Loading...
Loading...
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.
npx skill4agent add github/awesome-copilot winui3-migration-guideWindows.UI.Xaml.*Microsoft.UI.Xaml.*| UWP Namespace | WinUI 3 Namespace |
|---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
// ❌ 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();// ❌ 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
}// ❌ 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;
});// ❌ 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| UWP API | WinUI 3 API |
|---|---|
| |
| |
| |
| |
| |
| |
| |
| UWP API | WinUI 3 API |
|---|---|
| |
| |
// ❌ 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();| UWP Pattern | WinUI 3 Equivalent |
|---|---|
| |
| |
| No equivalent — restructure async code |
| Not available — use |
// ❌ 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
}| Scenario | Packaged App | Unpackaged App |
|---|---|---|
| Simple settings | | JSON file in |
| Local file storage | | |
GetForCurrentView()| UWP API | WinUI 3 Replacement |
|---|---|
| Use |
| |
| Win32 |
| Not available — track windows manually |
| Handle back navigation in |
| 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 |
| |
| 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);
}[UITestMethod]Microsoft.UI.XamlWindows.UI.Xaml.*Microsoft.UI.Xaml.*Windows.UI.ColorsMicrosoft.UI.ColorsCoreDispatcher.RunAsyncDispatcherQueue.TryEnqueueWindow.CurrentApp.MainWindowXamlRootContentDialogInitializeWithWindow.Initialize(picker, hwnd)MessageDialogContentDialogApplicationViewCoreWindowAppWindowCoreApplicationViewTitleBarAppWindowTitleBarGetForCurrentView()AppWindowIBackgroundTaskAppLifecyclenet10.0-windows10.0.22621.0<UseWinUI>true</UseWinUI>[UITestMethod]