Winui3 Migration Guide

WinUI 3 migration guide

Migrate UWP code to WinUI 3 / Windows App SDK by replacing legacy APIs with desktop-safe equivalents. Review generated code for UWP-only patterns and produce concrete before/after guidance.

When to invoke

• "Migrate this UWP app to WinUI 3."
• "Replace Windows.UI.Xaml APIs with Microsoft.UI.Xaml."
• "Fix this ContentDialog for WinUI 3."
• "Review this generated code for UWP patterns."
• "Convert CoreDispatcher, CoreWindow, and GetForCurrentView usage."

Namespace changes

All Windows.UI.Xaml.* namespaces move to Microsoft.UI.Xaml.*.

High-risk GitHub Copilot mistakes

Use WRONG/CORRECT examples for subtle migrations, especially File/Folder picker ownership and dialog threading issues.

// Correct ContentDialog pattern
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
}

// Correct DispatcherQueue pattern
DispatcherQueue.TryEnqueue(() =>
{
    StatusText.Text = "Done";
});

DispatcherQueue.TryEnqueue(DispatcherQueuePriority.High, () =>
{
    ProgressBar.Value = 100;
});

// Correct picker pattern
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();

Windowing migration

public partial class App : Application
{
    public static Window MainWindow { get; private set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        MainWindow = new MainWindow();
        MainWindow.Activate();
    }
}

Threading and view APIs

Key difference: UWP uses ASTA (Application STA) with built-in reentrancy blocking. WinUI 3 uses standard STA without that protection, so review async code for reentrancy when messages are pumped.

Dialogs, pickers, background work, and settings

using Microsoft.Windows.AppLifecycle;

var args = AppInstance.GetCurrent().GetActivatedEventArgs();
if (args.Kind == ExtendedActivationKind.AppNotification)
{
    // Handle background activation
}

Testing and project migration

[UITestMethod]
public void TestMyControl()
{
    var control = new MyLibrary.MyUserControl();
    Assert.AreEqual(expected, control.MyProperty);
}

[UITestMethod] runs the test on the XAML UI thread, which is required for instantiating any Microsoft.UI.Xaml type. Update the project file to target net10.0-windows10.0.22621.0 and set <UseWinUI>true</UseWinUI> when that target framework is appropriate for the app.

Migration checklist

• Replace 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 or explicit window references.
• Add XamlRoot to all ContentDialog instances.
• Initialize pickers with InitializeWithWindow.Initialize(picker, hwnd).
• Replace MessageDialog with ContentDialog.
• Replace ApplicationView and CoreWindow with AppWindow patterns.
• Replace CoreApplicationViewTitleBar with AppWindowTitleBar.
• Replace GetForCurrentView() calls with AppWindow or explicit window equivalents.
• Update interop for Share and Print managers.
• Replace IBackgroundTask with AppLifecycle activation where applicable.
• Update TFM and WinUI project settings: net10.0-windows10.0.22621.0, <UseWinUI>true</UseWinUI>.
• Migrate unit tests to Unit Test App (WinUI in Desktop) and use [UITestMethod] for XAML tests.
• Test packaged and unpackaged configurations.

Gotchas

• Do not keep UWP singleton assumptions: desktop WinUI 3 can have different window ownership and requires explicit HWND/XamlRoot handling.
• Do not use CoreDispatcher.ProcessEvents(): there is no equivalent; change the async design instead of forcing reentrancy.
• Do not assume packaged APIs work unpackaged: settings and file storage differ for unpackaged apps.

Output template

## WinUI 3 migration review — <file, feature, or project>

**Status:** ready | changes required | blocked
**Scope:** <UWP APIs or files reviewed>

| Area | UWP pattern found | WinUI 3 replacement | Evidence | Action |
| --- | --- | --- | --- | --- |
| Dialogs | `MessageDialog` | `ContentDialog` with `XamlRoot` | `<file:line>` | Replace dialog construction |

### Code changes
```csharp
<before/after or corrected WinUI 3 snippet>
```

### Validation
- Packaged configuration: pass | not run | blocked
- Unpackaged configuration: pass | not run | blocked
- XAML/UI tests using `[UITestMethod]`: pass | not run | blocked

Quality gate

• Every Windows.UI.Xaml.* namespace is migrated to Microsoft.UI.Xaml.*.
• Dialogs set XamlRoot and avoid MessageDialog.
• Pickers are initialized with an owner HWND.
• CoreDispatcher, CoreWindow, ApplicationView, and GetForCurrentView() usages are replaced or explicitly justified.
• Window state uses AppWindow, explicit Window references, or App.MainWindow rather than Window.Current.
• Background activation uses Microsoft.Windows.AppLifecycle where UWP IBackgroundTask no longer applies.
• Test projects use WinUI 3 desktop test templates and [UITestMethod] for XAML interaction.