MCPInstall

winui3-migration-guide

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.

Installs
5.7K
Last 24h
—
Trending rank
—
Security
Pass

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/github/awesome-copilot --skill winui3-migration-guide
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads winui3-migration-guide automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·The skill is a legitimate documentation resource for migrating UWP applications to WinUI 3. It contains educational code snippets and API mapping tables with no evidence of malicious behavior, obfuscation, or security vulnerabilities.
Socket PassNo alerts
Snyk PassLOW ·Risk: LOW · No issues
Runlayer PassLOW ·1/1 file flagged
ZeroLeaks PassNONE ·Score: 93/100 · 2 sections analyzed

SKILL.md

The instructions your agent reads when the skill is triggered.

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 NamespaceWinUI 3 Namespace
Windows.UI.XamlMicrosoft.UI.Xaml
Windows.UI.Xaml.ControlsMicrosoft.UI.Xaml.Controls
Windows.UI.Xaml.MediaMicrosoft.UI.Xaml.Media
Windows.UI.Xaml.InputMicrosoft.UI.Xaml.Input
Windows.UI.Xaml.DataMicrosoft.UI.Xaml.Data
Windows.UI.Xaml.NavigationMicrosoft.UI.Xaml.Navigation
Windows.UI.Xaml.ShapesMicrosoft.UI.Xaml.Shapes
Windows.UI.CompositionMicrosoft.UI.Composition
Windows.UI.InputMicrosoft.UI.Input
Windows.UI.ColorsMicrosoft.UI.Colors
Windows.UI.TextMicrosoft.UI.Text
Windows.UI.CoreMicrosoft.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 APIWinUI 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 APIWinUI 3 API
CoreApplicationViewTitleBarAppWindowTitleBar
CoreApplicationView.TitleBar.ExtendViewIntoTitleBarAppWindow.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 PatternWinUI 3 Equivalent
CoreDispatcher.RunAsync(priority, callback)DispatcherQueue.TryEnqueue(priority, callback)
Dispatcher.HasThreadAccessDispatcherQueue.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

ScenarioPackaged AppUnpackaged App
Simple settingsApplicationData.Current.LocalSettingsJSON file in LocalApplicationData
Local file storageApplicationData.Current.LocalFolderEnvironment.GetFolderPath(SpecialFolder.LocalApplicationData)

GetForCurrentView() Replacements

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

UWP APIWinUI 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.

UWPWinUI 3
Unit Test App (Universal Windows)Unit Test App (WinUI in Desktop)
Standard MSTest project with UWP typesMust 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

  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. Replace IBackgroundTask with AppLifecycle activation
  13. Update project file: TFM to net10.0-windows10.0.22621.0, add <UseWinUI>true</UseWinUI>
  14. Migrate unit tests to Unit Test App (WinUI in Desktop) project; use [UITestMethod] for XAML tests
  15. Test both packaged and unpackaged configurations

FAQ

What does the winui3-migration-guide skill do?

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.

How do I install winui3-migration-guide?

Run npx skills add https://github.com/github/awesome-copilot --skill winui3-migration-guide in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/winui3-migration-guide/ (personal) or .claude/skills/winui3-migration-guide/ (project).

Which AI agents can use winui3-migration-guide?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is winui3-migration-guide safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains winui3-migration-guide?

It is published by github in github/awesome-copilot, and it is an official skill from the maker of the technology it covers. It has 5,703 recorded installs.

More from github/awesome-copilot

View all →

git-commit

github/awesome-copilot

Use this skill when the user wants to make a Git commit or split changes into more than one commit. Also use it when the user types "/commit" or asks for a conventional commit. The skill examines the diff, stages the related files, writes a Conventional Commits message, and runs git commit. Do not use it when the user wants only a commit message and no commit. Do not use it to push, open a pull request, rebase, or change the commit history.

OfficialCode Quality & Workflow47.4K installs

excalidraw-diagram-generator

github/awesome-copilot

Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw.

OfficialDocs & Writing31.9K installs

multi-stage-dockerfile

github/awesome-copilot

Create optimized multi-stage Dockerfiles for any language or framework

Official29.8K installs

documentation-writer

github/awesome-copilot

Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.

OfficialDocs & Writing27.9K installs

prd

github/awesome-copilot

Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis.

Official24.1K installs

refactor

github/awesome-copilot

Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

OfficialCode Quality & Workflow22.4K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.