winui3-migration-guide

SKILL.md

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

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
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

UWP API
WinUI 3 API

ApplicationView.TryResizeView()
AppWindow.Resize()

AppWindow.TryCreateAsync()
AppWindow.Create()

AppWindow.TryShowAsync()
AppWindow.Show()

AppWindow.TryConsolidateAsync()
AppWindow.Destroy()

AppWindow.RequestMoveXxx()
AppWindow.Move()

AppWindow.GetPlacement()
AppWindow.Position property

AppWindow.RequestPresentation()
AppWindow.SetPresenter()

Title Bar

UWP API
WinUI 3 API

CoreApplicationViewTitleBar
AppWindowTitleBar

CoreApplicationView.TitleBar.ExtendViewIntoTitleBar
AppWindow.TitleBar.ExtendsContentIntoTitleBar

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

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
}

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 <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