winui3-migration-guide

WinUI 3 Migration Guide

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.*:

---

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();

This form applies inside a Window. Inside a Page or UserControl, use the XamlRoot of that element instead.

2. MessageDialog Instead of ContentDialog

// ❌ WRONG — UWP API, needs window handle setup in WinUI 3 desktop, prefer ContentDialog
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 — Dispatcher returns null for WinUI 3 windows, use DispatcherQueue
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;
});

The enqueue call returns false when the work could not be queued, for example while the queue is shutting down. Check the result and log or handle that case.

---

Windowing Migration

Window Reference

// ❌ WRONG — Window.Current returns null in WinUI 3 desktop apps
var currentWindow = Window.Current;

// ✅ CORRECT — Use a static property in App
public partial class App : Application
{
    public static Window MainWindow { get; private set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        MainWindow = new MainWindow();
        MainWindow.Activate();
    }
}
// Access anywhere: App.MainWindow

Window Management

Title Bar

---

Dialogs and Pickers Migration

File/Folder Pickers

// ❌ 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();

Share and Print

Like pickers, the Share and Print managers in desktop apps must be obtained for a specific window using its window handle through their interop interfaces. Follow the official Microsoft documentation for this interop code rather than writing it from memory.

Threading Migration

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 notification activation
}

This sample covers notification activation only. It is not a full replacement for timer, push or maintenance background work. Check the official Microsoft documentation for the supported background task path before migrating those triggers.

---

App Settings Migration

The JSON settings file is plain text. Keep it to settings that are not sensitive, store secrets such as passwords or tokens in the Windows credential store or with data protection, and place the file in a folder for your app.

---

GetForCurrentView() Replacements

All GetForCurrentView() patterns are unavailable in WinUI 3 desktop apps:

---

Testing Migration

UWP unit test projects do not work with WinUI 3. You must migrate to the WinUI 3 test project templates.

// ✅ WinUI 3 unit test — use [UITestMethod] for any XAML interaction
[UITestMethod]
public void TestMyControl()
{
    var control = new MyLibrary.MyUserControl();
    Assert.AreEqual(expected, control.MyProperty);
}

Declare expected with the known value of the property before the assertion.

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

1. Replace all Windows.UI.Xaml.* using directives with Microsoft.UI.Xaml.*
2. Replace Windows.UI.Colors with Microsoft.UI.Colors
3. Replace CoreDispatcher.RunAsync with DispatcherQueue.TryEnqueue
4. Replace Window.Current with App.MainWindow static property
5. Add XamlRoot to all ContentDialog instances
6. Initialize all pickers with InitializeWithWindow.Initialize(picker, hwnd)
7. Replace MessageDialog with ContentDialog
8. Replace ApplicationView/CoreWindow with AppWindow
9. Replace CoreApplicationViewTitleBar with AppWindowTitleBar
10. Replace all GetForCurrentView() calls with AppWindow equivalents
11. Update interop for Share and Print managers
12. Review each IBackgroundTask trigger and use AppLifecycle activation only for notification activation
13. Update project file: TFM to net10.0-windows10.0.22621.0, add <UseWinUI>true</UseWinUI> (the TFM shown is an example, so match it to your installed SDKs), and reference the Windows App SDK package from the official NuGet feed with an explicit pinned version and a lock file
14. Migrate unit tests to Unit Test App (WinUI in Desktop) project; use [UITestMethod] for XAML tests
15. Test both packaged and unpackaged configurations