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";
});
// ❌ WRONG — UWP style, no window handle
var picker = new FileOpenPicker();
picker.FileTypeFilter.Add(".txt");
var file = await picker.PickSingleFileAsync();
// ✅ CORRECT — Initialize with window handle
var picker = new FileOpenPicker();
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);
picker.FileTypeFilter.Add(".txt");
var file = await picker.PickSingleFileAsync();
Threading Migration
UWP Pattern
WinUI 3 Equivalent
CoreDispatcher.RunAsync(priority, callback)
DispatcherQueue.TryEnqueue(priority, callback)
Dispatcher.HasThreadAccess
DispatcherQueue.HasThreadAccess
CoreDispatcher.ProcessEvents()
No equivalent — restructure async code
CoreWindow.GetForCurrentThread()
Not available — use DispatcherQueue.GetForCurrentThread()
Key difference: 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
}
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 <UseWinUI>true</UseWinUI>
Migrate unit tests to Unit Test App (WinUI in Desktop) project; use [UITestMethod] for XAML tests
Test both packaged and unpackaged configurations
1---2name: winui3-migration-guide3description: 'UWP-to-WinUI 3 migration reference. Maps legacy UWP APIs to correct Windows App SDK equivalents with before/after code snippets. Covers namespace changes, threading (CoreDispatcher to DispatcherQueue), windowing (CoreWindow to AppWindow), dialogs, pickers, sharing, printing, background tasks, and the most common Copilot code generation mistakes.'4metadata:5 source: https://skillmd.com/skills/github/winui3-migration-guide6---78# WinUI 3 Migration Guide910Use 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.1112---1314## Namespace Changes1516All `Windows.UI.Xaml.*` namespaces move to `Microsoft.UI.Xaml.*`:1718| UWP Namespace | WinUI 3 Namespace |19|--------------|-------------------|20| `Windows.UI.Xaml` | `Microsoft.UI.Xaml` |21| `Windows.UI.Xaml.Controls` | `Microsoft.UI.Xaml.Controls` |22| `Windows.UI.Xaml.Media` | `Microsoft.UI.Xaml.Media` |23| `Windows.UI.Xaml.Input` | `Microsoft.UI.Xaml.Input` |24| `Windows.UI.Xaml.Data` | `Microsoft.UI.Xaml.Data` |25| `Windows.UI.Xaml.Navigation` | `Microsoft.UI.Xaml.Navigation` |26| `Windows.UI.Xaml.Shapes` | `Microsoft.UI.Xaml.Shapes` |27| `Windows.UI.Composition` | `Microsoft.UI.Composition` |28| `Windows.UI.Input` | `Microsoft.UI.Input` |29| `Windows.UI.Colors` | `Microsoft.UI.Colors` |30| `Windows.UI.Text` | `Microsoft.UI.Text` |31| `Windows.UI.Core` | `Microsoft.UI.Dispatching` (for dispatcher) |3233---3435## Top 3 Most Common Copilot Mistakes3637### 1. ContentDialog Without XamlRoot3839```csharp40// ❌ WRONG — Throws InvalidOperationException in WinUI 341var dialog = new ContentDialog42{43 Title = "Error",44 Content = "Something went wrong.",45 CloseButtonText = "OK"46};47await dialog.ShowAsync();48```4950```csharp51// ✅ CORRECT — Set XamlRoot before showing52var dialog = new ContentDialog53{54 Title = "Error",55 Content = "Something went wrong.",56 CloseButtonText = "OK",57 XamlRoot = this.Content.XamlRoot // Required in WinUI 358};59await dialog.ShowAsync();60```6162### 2. MessageDialog Instead of ContentDialog6364```csharp65// ❌ WRONG — UWP API, not available in WinUI 3 desktop66var dialog = new Windows.UI.Popups.MessageDialog("Are you sure?", "Confirm");67await dialog.ShowAsync();68```6970```csharp71// ✅ CORRECT — Use ContentDialog72var dialog = new ContentDialog73{74 Title = "Confirm",75 Content = "Are you sure?",76 PrimaryButtonText = "Yes",77 CloseButtonText = "No",78 XamlRoot = this.Content.XamlRoot79};80var result = await dialog.ShowAsync();81if (result == ContentDialogResult.Primary)82{83 // User confirmed84}85```8687### 3. CoreDispatcher Instead of DispatcherQueue8889```csharp90// ❌ WRONG — CoreDispatcher does not exist in WinUI 391await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>92{93 StatusText.Text = "Done";94});95```9697```csharp98// ✅ CORRECT — Use DispatcherQueue99DispatcherQueue.TryEnqueue(() =>100{101 StatusText.Text = "Done";102});103104// With priority:105DispatcherQueue.TryEnqueue(DispatcherQueuePriority.High, () =>106{107 ProgressBar.Value = 100;108});109```110111---112113## Windowing Migration114115### Window Reference116117```csharp118// ❌ WRONG — Window.Current does not exist in WinUI 3119var currentWindow = Window.Current;120```121122```csharp123// ✅ CORRECT — Use a static property in App124public partial class App : Application125{126 public static Window MainWindow { get; private set; }127128 protected override void OnLaunched(LaunchActivatedEventArgs args)129 {130 MainWindow = new MainWindow();131 MainWindow.Activate();132 }133}134// Access anywhere: App.MainWindow135```136137### Window Management138139| UWP API | WinUI 3 API |140|---------|-------------|141| `ApplicationView.TryResizeView()` | `AppWindow.Resize()` |142| `AppWindow.TryCreateAsync()` | `AppWindow.Create()` |143| `AppWindow.TryShowAsync()` | `AppWindow.Show()` |144| `AppWindow.TryConsolidateAsync()` | `AppWindow.Destroy()` |145| `AppWindow.RequestMoveXxx()` | `AppWindow.Move()` |146| `AppWindow.GetPlacement()` | `AppWindow.Position` property |147| `AppWindow.RequestPresentation()` | `AppWindow.SetPresenter()` |148149### Title Bar150151| UWP API | WinUI 3 API |152|---------|-------------|153| `CoreApplicationViewTitleBar` | `AppWindowTitleBar` |154| `CoreApplicationView.TitleBar.ExtendViewIntoTitleBar` | `AppWindow.TitleBar.ExtendsContentIntoTitleBar` |155156---157158## Dialogs and Pickers Migration159160### File/Folder Pickers161162```csharp163// ❌ WRONG — UWP style, no window handle164var picker = new FileOpenPicker();165picker.FileTypeFilter.Add(".txt");166var file = await picker.PickSingleFileAsync();167```168169```csharp170// ✅ CORRECT — Initialize with window handle171var picker = new FileOpenPicker();172var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);173WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);174picker.FileTypeFilter.Add(".txt");175var file = await picker.PickSingleFileAsync();176```177178## Threading Migration179180| UWP Pattern | WinUI 3 Equivalent |181|-------------|-------------------|182| `CoreDispatcher.RunAsync(priority, callback)` | `DispatcherQueue.TryEnqueue(priority, callback)` |183| `Dispatcher.HasThreadAccess` | `DispatcherQueue.HasThreadAccess` |184| `CoreDispatcher.ProcessEvents()` | No equivalent — restructure async code |185| `CoreWindow.GetForCurrentThread()` | Not available — use `DispatcherQueue.GetForCurrentThread()` |186187**Key difference**: 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.188189---190191## Background Tasks Migration192193```csharp194// ❌ WRONG — UWP IBackgroundTask195public sealed class MyTask : IBackgroundTask196{197 public void Run(IBackgroundTaskInstance taskInstance) { }198}199```200201```csharp202// ✅ CORRECT — Windows App SDK AppLifecycle203using Microsoft.Windows.AppLifecycle;204205// Register for activation206var args = AppInstance.GetCurrent().GetActivatedEventArgs();207if (args.Kind == ExtendedActivationKind.AppNotification)208{209 // Handle background activation210}211```212213---214215## App Settings Migration216217| Scenario | Packaged App | Unpackaged App |218|----------|-------------|----------------|219| Simple settings | `ApplicationData.Current.LocalSettings` | JSON file in `LocalApplicationData` |220| Local file storage | `ApplicationData.Current.LocalFolder` | `Environment.GetFolderPath(SpecialFolder.LocalApplicationData)` |221222---223224## GetForCurrentView() Replacements225226All `GetForCurrentView()` patterns are unavailable in WinUI 3 desktop apps:227228| UWP API | WinUI 3 Replacement |229|---------|-------------------|230| `UIViewSettings.GetForCurrentView()` | Use `AppWindow` properties |231| `ApplicationView.GetForCurrentView()` | `AppWindow.GetFromWindowId(windowId)` |232| `DisplayInformation.GetForCurrentView()` | Win32 `GetDpiForWindow()` or `XamlRoot.RasterizationScale` |233| `CoreApplication.GetCurrentView()` | Not available — track windows manually |234| `SystemNavigationManager.GetForCurrentView()` | Handle back navigation in `NavigationView` directly |235236---237238## Testing Migration239240UWP unit test projects do not work with WinUI 3. You must migrate to the WinUI 3 test project templates.241242| UWP | WinUI 3 |243|-----|---------|244| Unit Test App (Universal Windows) | **Unit Test App (WinUI in Desktop)** |245| Standard MSTest project with UWP types | Must use WinUI test app for Xaml runtime |246| `[TestMethod]` for all tests | `[TestMethod]` for logic, `[UITestMethod]` for XAML/UI tests |247| Class Library (Universal Windows) | **Class Library (WinUI in Desktop)** |248249```csharp250// ✅ WinUI 3 unit test — use [UITestMethod] for any XAML interaction251[UITestMethod]252public void TestMyControl()253{254 var control = new MyLibrary.MyUserControl();255 Assert.AreEqual(expected, control.MyProperty);256}257```258259**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.260261---262263## Migration Checklist2642651. [ ] Replace all `Windows.UI.Xaml.*` using directives with `Microsoft.UI.Xaml.*`2662. [ ] Replace `Windows.UI.Colors` with `Microsoft.UI.Colors`2673. [ ] Replace `CoreDispatcher.RunAsync` with `DispatcherQueue.TryEnqueue`2684. [ ] Replace `Window.Current` with `App.MainWindow` static property2695. [ ] Add `XamlRoot` to all `ContentDialog` instances2706. [ ] Initialize all pickers with `InitializeWithWindow.Initialize(picker, hwnd)`2717. [ ] Replace `MessageDialog` with `ContentDialog`2728. [ ] Replace `ApplicationView`/`CoreWindow` with `AppWindow`2739. [ ] Replace `CoreApplicationViewTitleBar` with `AppWindowTitleBar`27410. [ ] Replace all `GetForCurrentView()` calls with `AppWindow` equivalents27511. [ ] Update interop for Share and Print managers27612. [ ] Replace `IBackgroundTask` with `AppLifecycle` activation27713. [ ] Update project file: TFM to `net10.0-windows10.0.22621.0`, add `<UseWinUI>true</UseWinUI>`27814. [ ] Migrate unit tests to **Unit Test App (WinUI in Desktop)** project; use `[UITestMethod]` for XAML tests27915. [ ] Test both packaged and unpackaged configurations
Run npx get-skill add github/winui3-migration-guide in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Maps legacy UWP APIs to correct Windows App SDK equivalents with before/after code snippets for migrating to WinUI 3. It is listed under Coding & Dev Tools, Refactoring on SkillMD.
SkillMD's automated safety review verdict for this skill is PASS. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
GitHub (Microsoft) (@github) published this skill as a verified publisher. Their other Agent Skills are listed on their SkillMD profile.