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

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