Use this skill when migrating UWP apps to WinUI 3 / Windows App SDK, or when verifying that generated code uses correct WinUI 3 APIs instead of legacy UWP patterns.
Namespace Changes
All
Windows.UI.Xaml.*
namespaces move to
Microsoft.UI.Xaml.*
:
UWP Namespace
WinUI 3 Namespace
Windows.UI.Xaml
Microsoft.UI.Xaml
Windows.UI.Xaml.Controls
Microsoft.UI.Xaml.Controls
Windows.UI.Xaml.Media
Microsoft.UI.Xaml.Media
Windows.UI.Xaml.Input
Microsoft.UI.Xaml.Input
Windows.UI.Xaml.Data
Microsoft.UI.Xaml.Data
Windows.UI.Xaml.Navigation
Microsoft.UI.Xaml.Navigation
Windows.UI.Xaml.Shapes
Microsoft.UI.Xaml.Shapes
Windows.UI.Composition
Microsoft.UI.Composition
Windows.UI.Input
Microsoft.UI.Input
Windows.UI.Colors
Microsoft.UI.Colors
Windows.UI.Text
Microsoft.UI.Text
Windows.UI.Core
Microsoft.UI.Dispatching
(for dispatcher)
Top 3 Most Common Copilot Mistakes
1. ContentDialog Without XamlRoot
// ❌ WRONG — Throws InvalidOperationException in WinUI 3
var
dialog
=
new
ContentDialog
{
Title
=
"Error"
,
Content
=
"Something went wrong."
,
CloseButtonText
=
"OK"
}
;
await
dialog
.
ShowAsync
(
)
;
// ✅ CORRECT — Set XamlRoot before showing
var
dialog
=
new
ContentDialog
{
Title
=
"Error"
,
Content
=
"Something went wrong."
,
CloseButtonText
=
"OK"
,
XamlRoot
=
this
.
Content
.
XamlRoot
// Required in WinUI 3
}
;
await
dialog
.
ShowAsync
(
)
;
2. MessageDialog Instead of ContentDialog
// ❌ WRONG — UWP API, not available in WinUI 3 desktop
var
dialog
=
new
Windows
.
UI
.
Popups
.
MessageDialog
(
"Are you sure?"
,
"Confirm"
)
;
await
dialog
.
ShowAsync
(
)
;
// ✅ CORRECT — Use ContentDialog
var
dialog
=
new
ContentDialog
{
Title
=
"Confirm"
,
Content
=
"Are you sure?"
,
PrimaryButtonText
=
"Yes"
,
CloseButtonText
=
"No"
,
XamlRoot
=
this
.
Content
.
XamlRoot
}
;
var
result
=
await
dialog
.
ShowAsync
(
)
;
if
(
result
==
ContentDialogResult
.
Primary
)
{
// User confirmed
}
3. CoreDispatcher Instead of DispatcherQueue
// ❌ WRONG — CoreDispatcher does not exist in WinUI 3
await
Dispatcher
.
RunAsync
(
CoreDispatcherPriority
.
Normal
,
(
)
=>
{
StatusText
.
Text
=
"Done"
;
}
)
;
// ✅ CORRECT — Use DispatcherQueue
DispatcherQueue
.
TryEnqueue
(
(
)
=>
{
StatusText
.
Text
=
"Done"
;
}
)
;
// With priority:
DispatcherQueue
.
TryEnqueue
(
DispatcherQueuePriority
.
High
,
(
)
=>
{
ProgressBar
.
Value
=
100
;
}
)
;
Windowing Migration
Window Reference
// ❌ WRONG — Window.Current does not exist in WinUI 3
UWP uses ASTA (Application STA) with built-in reentrancy blocking. WinUI 3 uses standard STA without this protection. Watch for reentrancy issues when async code pumps messages.
Background Tasks Migration
// ❌ WRONG — UWP IBackgroundTask
public
sealed
class
MyTask
:
IBackgroundTask
{
public
void
Run
(
IBackgroundTaskInstance
taskInstance
)
{
}
}
// ✅ CORRECT — Windows App SDK AppLifecycle
using
Microsoft
.
Windows
.
AppLifecycle
;
// Register for activation
var
args
=
AppInstance
.
GetCurrent
(
)
.
GetActivatedEventArgs
(
)
;
if
(
args
.
Kind
==
ExtendedActivationKind
.
AppNotification
)
{
// Handle background activation
}
App Settings Migration
Scenario
Packaged App
Unpackaged App
Simple settings
ApplicationData.Current.LocalSettings
JSON file in
LocalApplicationData
Local file storage
ApplicationData.Current.LocalFolder
Environment.GetFolderPath(SpecialFolder.LocalApplicationData)
GetForCurrentView() Replacements
All
GetForCurrentView()
patterns are unavailable in WinUI 3 desktop apps:
UWP API
WinUI 3 Replacement
UIViewSettings.GetForCurrentView()
Use
AppWindow
properties
ApplicationView.GetForCurrentView()
AppWindow.GetFromWindowId(windowId)
DisplayInformation.GetForCurrentView()
Win32
GetDpiForWindow()
or
XamlRoot.RasterizationScale
CoreApplication.GetCurrentView()
Not available — track windows manually
SystemNavigationManager.GetForCurrentView()
Handle back navigation in
NavigationView
directly
Testing Migration
UWP unit test projects do not work with WinUI 3. You must migrate to the WinUI 3 test project templates.
UWP
WinUI 3
Unit Test App (Universal Windows)
Unit Test App (WinUI in Desktop)
Standard MSTest project with UWP types
Must use WinUI test app for Xaml runtime
[TestMethod]
for all tests
[TestMethod]
for logic,
[UITestMethod]
for XAML/UI tests
Class Library (Universal Windows)
Class Library (WinUI in Desktop)
// ✅ WinUI 3 unit test — use [UITestMethod] for any XAML interaction
[
UITestMethod
]
public
void
TestMyControl
(
)
{
var
control
=
new
MyLibrary
.
MyUserControl
(
)
;
Assert
.
AreEqual
(
expected
,
control
.
MyProperty
)
;
}
Key:
The
[UITestMethod]
attribute tells the test runner to execute the test on the XAML UI thread, which is required for instantiating any
Microsoft.UI.Xaml
type.
Migration Checklist
Replace all
Windows.UI.Xaml.
using directives with
Microsoft.UI.Xaml.
Replace
Windows.UI.Colors
with
Microsoft.UI.Colors
Replace
CoreDispatcher.RunAsync
with
DispatcherQueue.TryEnqueue
Replace
Window.Current
with
App.MainWindow
static property
Add
XamlRoot
to all
ContentDialog
instances
Initialize all pickers with
InitializeWithWindow.Initialize(picker, hwnd)
Replace
MessageDialog
with
ContentDialog
Replace
ApplicationView
/
CoreWindow
with
AppWindow
Replace
CoreApplicationViewTitleBar
with
AppWindowTitleBar
Replace all
GetForCurrentView()
calls with
AppWindow
equivalents
Update interop for Share and Print managers
Replace
IBackgroundTask
with
AppLifecycle
activation
Update project file: TFM to
net10.0-windows10.0.22621.0
, add
true
Migrate unit tests to
Unit Test App (WinUI in Desktop)
project; use
[UITestMethod]
for XAML tests
Test both packaged and unpackaged configurations