{"id":"c0b8c32f-6e73-48ac-95ad-17144e82d982","shortId":"6GfyGa","kind":"skill","title":"winui3-migration-guide","tagline":"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, back","description":"# WinUI 3 Migration Guide\n\nUse 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.\n\n---\n\n## Namespace Changes\n\nAll `Windows.UI.Xaml.*` namespaces move to `Microsoft.UI.Xaml.*`:\n\n| UWP Namespace | WinUI 3 Namespace |\n|--------------|-------------------|\n| `Windows.UI.Xaml` | `Microsoft.UI.Xaml` |\n| `Windows.UI.Xaml.Controls` | `Microsoft.UI.Xaml.Controls` |\n| `Windows.UI.Xaml.Media` | `Microsoft.UI.Xaml.Media` |\n| `Windows.UI.Xaml.Input` | `Microsoft.UI.Xaml.Input` |\n| `Windows.UI.Xaml.Data` | `Microsoft.UI.Xaml.Data` |\n| `Windows.UI.Xaml.Navigation` | `Microsoft.UI.Xaml.Navigation` |\n| `Windows.UI.Xaml.Shapes` | `Microsoft.UI.Xaml.Shapes` |\n| `Windows.UI.Composition` | `Microsoft.UI.Composition` |\n| `Windows.UI.Input` | `Microsoft.UI.Input` |\n| `Windows.UI.Colors` | `Microsoft.UI.Colors` |\n| `Windows.UI.Text` | `Microsoft.UI.Text` |\n| `Windows.UI.Core` | `Microsoft.UI.Dispatching` (for dispatcher) |\n\n---\n\n## Top 3 Most Common Copilot Mistakes\n\n### 1. ContentDialog Without XamlRoot\n\n```csharp\n// ❌ WRONG — Throws InvalidOperationException in WinUI 3\nvar dialog = new ContentDialog\n{\n    Title = \"Error\",\n    Content = \"Something went wrong.\",\n    CloseButtonText = \"OK\"\n};\nawait dialog.ShowAsync();\n```\n\n```csharp\n// ✅ CORRECT — Set XamlRoot before showing\nvar dialog = new ContentDialog\n{\n    Title = \"Error\",\n    Content = \"Something went wrong.\",\n    CloseButtonText = \"OK\",\n    XamlRoot = this.Content.XamlRoot  // Required in WinUI 3\n};\nawait dialog.ShowAsync();\n```\n\n### 2. MessageDialog Instead of ContentDialog\n\n```csharp\n// ❌ WRONG — UWP API, not available in WinUI 3 desktop\nvar dialog = new Windows.UI.Popups.MessageDialog(\"Are you sure?\", \"Confirm\");\nawait dialog.ShowAsync();\n```\n\n```csharp\n// ✅ CORRECT — Use ContentDialog\nvar dialog = new ContentDialog\n{\n    Title = \"Confirm\",\n    Content = \"Are you sure?\",\n    PrimaryButtonText = \"Yes\",\n    CloseButtonText = \"No\",\n    XamlRoot = this.Content.XamlRoot\n};\nvar result = await dialog.ShowAsync();\nif (result == ContentDialogResult.Primary)\n{\n    // User confirmed\n}\n```\n\n### 3. CoreDispatcher Instead of DispatcherQueue\n\n```csharp\n// ❌ WRONG — CoreDispatcher does not exist in WinUI 3\nawait Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>\n{\n    StatusText.Text = \"Done\";\n});\n```\n\n```csharp\n// ✅ CORRECT — Use DispatcherQueue\nDispatcherQueue.TryEnqueue(() =>\n{\n    StatusText.Text = \"Done\";\n});\n\n// With priority:\nDispatcherQueue.TryEnqueue(DispatcherQueuePriority.High, () =>\n{\n    ProgressBar.Value = 100;\n});\n```\n\n---\n\n## Windowing Migration\n\n### Window Reference\n\n```csharp\n// ❌ WRONG — Window.Current does not exist in WinUI 3\nvar currentWindow = Window.Current;\n```\n\n```csharp\n// ✅ CORRECT — Use a static property in App\npublic partial class App : Application\n{\n    public static Window MainWindow { get; private set; }\n\n    protected override void OnLaunched(LaunchActivatedEventArgs args)\n    {\n        MainWindow = new MainWindow();\n        MainWindow.Activate();\n    }\n}\n// Access anywhere: App.MainWindow\n```\n\n### Window Management\n\n| UWP API | WinUI 3 API |\n|---------|-------------|\n| `ApplicationView.TryResizeView()` | `AppWindow.Resize()` |\n| `AppWindow.TryCreateAsync()` | `AppWindow.Create()` |\n| `AppWindow.TryShowAsync()` | `AppWindow.Show()` |\n| `AppWindow.TryConsolidateAsync()` | `AppWindow.Destroy()` |\n| `AppWindow.RequestMoveXxx()` | `AppWindow.Move()` |\n| `AppWindow.GetPlacement()` | `AppWindow.Position` property |\n| `AppWindow.RequestPresentation()` | `AppWindow.SetPresenter()` |\n\n### Title Bar\n\n| UWP API | WinUI 3 API |\n|---------|-------------|\n| `CoreApplicationViewTitleBar` | `AppWindowTitleBar` |\n| `CoreApplicationView.TitleBar.ExtendViewIntoTitleBar` | `AppWindow.TitleBar.ExtendsContentIntoTitleBar` |\n\n---\n\n## Dialogs and Pickers Migration\n\n### File/Folder Pickers\n\n```csharp\n// ❌ WRONG — UWP style, no window handle\nvar picker = new FileOpenPicker();\npicker.FileTypeFilter.Add(\".txt\");\nvar file = await picker.PickSingleFileAsync();\n```\n\n```csharp\n// ✅ CORRECT — Initialize with window handle\nvar picker = new FileOpenPicker();\nvar hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);\nWinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);\npicker.FileTypeFilter.Add(\".txt\");\nvar file = await picker.PickSingleFileAsync();\n```\n\n## Threading Migration\n\n| UWP Pattern | WinUI 3 Equivalent |\n|-------------|-------------------|\n| `CoreDispatcher.RunAsync(priority, callback)` | `DispatcherQueue.TryEnqueue(priority, callback)` |\n| `Dispatcher.HasThreadAccess` | `DispatcherQueue.HasThreadAccess` |\n| `CoreDispatcher.ProcessEvents()` | No equivalent — restructure async code |\n| `CoreWindow.GetForCurrentThread()` | Not available — use `DispatcherQueue.GetForCurrentThread()` |\n\n**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.\n\n---\n\n## Background Tasks Migration\n\n```csharp\n// ❌ WRONG — UWP IBackgroundTask\npublic sealed class MyTask : IBackgroundTask\n{\n    public void Run(IBackgroundTaskInstance taskInstance) { }\n}\n```\n\n```csharp\n// ✅ CORRECT — Windows App SDK AppLifecycle\nusing Microsoft.Windows.AppLifecycle;\n\n// Register for activation\nvar args = AppInstance.GetCurrent().GetActivatedEventArgs();\nif (args.Kind == ExtendedActivationKind.AppNotification)\n{\n    // Handle background activation\n}\n```\n\n---\n\n## App Settings Migration\n\n| Scenario | Packaged App | Unpackaged App |\n|----------|-------------|----------------|\n| Simple settings | `ApplicationData.Current.LocalSettings` | JSON file in `LocalApplicationData` |\n| Local file storage | `ApplicationData.Current.LocalFolder` | `Environment.GetFolderPath(SpecialFolder.LocalApplicationData)` |\n\n---\n\n## GetForCurrentView() Replacements\n\nAll `GetForCurrentView()` patterns are unavailable in WinUI 3 desktop apps:\n\n| UWP API | WinUI 3 Replacement |\n|---------|-------------------|\n| `UIViewSettings.GetForCurrentView()` | Use `AppWindow` properties |\n| `ApplicationView.GetForCurrentView()` | `AppWindow.GetFromWindowId(windowId)` |\n| `DisplayInformation.GetForCurrentView()` | Win32 `GetDpiForWindow()` or `XamlRoot.RasterizationScale` |\n| `CoreApplication.GetCurrentView()` | Not available — track windows manually |\n| `SystemNavigationManager.GetForCurrentView()` | Handle back navigation in `NavigationView` directly |\n\n---\n\n## Testing Migration\n\nUWP unit test projects do not work with WinUI 3. You must migrate to the WinUI 3 test project templates.\n\n| UWP | WinUI 3 |\n|-----|---------|\n| Unit Test App (Universal Windows) | **Unit Test App (WinUI in Desktop)** |\n| Standard MSTest project with UWP types | Must use WinUI test app for Xaml runtime |\n| `[TestMethod]` for all tests | `[TestMethod]` for logic, `[UITestMethod]` for XAML/UI tests |\n| Class Library (Universal Windows) | **Class Library (WinUI in Desktop)** |\n\n```csharp\n// ✅ WinUI 3 unit test — use [UITestMethod] for any XAML interaction\n[UITestMethod]\npublic void TestMyControl()\n{\n    var control = new MyLibrary.MyUserControl();\n    Assert.AreEqual(expected, control.MyProperty);\n}\n```\n\n**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.\n\n---\n\n## Migration Checklist\n\n1. [ ] Replace all `Windows.UI.Xaml.*` using directives with `Microsoft.UI.Xaml.*`\n2. [ ] Replace `Windows.UI.Colors` with `Microsoft.UI.Colors`\n3. [ ] Replace `CoreDispatcher.RunAsync` with `DispatcherQueue.TryEnqueue`\n4. [ ] Replace `Window.Current` with `App.MainWindow` static property\n5. [ ] Add `XamlRoot` to all `ContentDialog` instances\n6. [ ] Initialize all pickers with `InitializeWithWindow.Initialize(picker, hwnd)`\n7. [ ] Replace `MessageDialog` with `ContentDialog`\n8. [ ] Replace `ApplicationView`/`CoreWindow` with `AppWindow`\n9. [ ] Replace `CoreApplicationViewTitleBar` with `AppWindowTitleBar`\n10. [ ] Replace all `GetForCurrentView()` calls with `AppWindow` equivalents\n11. [ ] Update interop for Share and Print managers\n12. [ ] Replace `IBackgroundTask` with `AppLifecycle` activation\n13. [ ] Update project file: TFM to `net10.0-windows10.0.22621.0`, add `<UseWinUI>true</UseWinUI>`\n14. [ ] Migrate unit tests to **Unit Test App (WinUI in Desktop)** project; use `[UITestMethod]` for XAML tests\n15. [ ] Test both packaged and unpackaged configurations","tags":["winui3","migration","guide","awesome","copilot","github","agent-skills","agents","custom-agents","github-copilot","hacktoberfest","prompt-engineering"],"capabilities":["skill","source-github","skill-winui3-migration-guide","topic-agent-skills","topic-agents","topic-awesome","topic-custom-agents","topic-github-copilot","topic-hacktoberfest","topic-prompt-engineering"],"categories":["awesome-copilot"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/github/awesome-copilot/winui3-migration-guide","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add github/awesome-copilot","source_repo":"https://github.com/github/awesome-copilot","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 30784 github stars · SKILL.md body (8,501 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T06:52:34.283Z","embedding":null,"createdAt":"2026-04-18T20:26:51.902Z","updatedAt":"2026-04-22T06:52:34.283Z","lastSeenAt":"2026-04-22T06:52:34.283Z","tsv":"'1':120,661 '10':717 '100':256 '11':725 '12':733 '13':739 '14':748 '15':765 '2':171,669 '3':9,43,55,68,86,115,130,168,184,225,238,269,311,333,390,425,509,515,553,560,566,614,674 '4':679 '5':686 '6':693 '7':701 '8':706 '9':712 'access':303 'activ':468,478,738 'add':687,746 'anywher':304 'api':15,69,179,309,312,331,334,513 'app':19,52,57,280,284,461,479,484,486,511,569,574,588,755 'app.mainwindow':305,375,683 'appinstance.getcurrent':471 'applic':285,416 'applicationdata.current.localfolder':497 'applicationdata.current.localsettings':489 'applicationview':708 'applicationview.getforcurrentview':521 'applicationview.tryresizeview':313 'applifecycl':463,737 'appwindow':36,519,711,723 'appwindow.create':316 'appwindow.destroy':320 'appwindow.getfromwindowid':522 'appwindow.getplacement':323 'appwindow.move':322 'appwindow.position':324 'appwindow.requestmovexxx':321 'appwindow.requestpresentation':326 'appwindow.resize':314 'appwindow.setpresenter':327 'appwindow.show':318 'appwindow.titlebar.extendscontentintotitlebar':338 'appwindow.tryconsolidateasync':319 'appwindow.trycreateasync':315 'appwindow.tryshowasync':317 'appwindowtitlebar':336,716 'arg':298,470 'args.kind':474 'assert.areequal':631 'asta':415 'async':404,437 'attribut':637 'avail':181,408,531 'await':143,169,194,218,239,360,383 'back':41,537 'background':441,477 'bar':329 'before/after':23 'block':423 'built':420 'built-in':419 'call':721 'callback':394,397 'chang':28,76 'checklist':660 'class':283,450,603,607 'closebuttontext':141,161,212 'code':24,64,405,438 'common':117 'configur':771 'confirm':193,205,224 'content':137,157,206 'contentdialog':121,134,154,175,199,203,691,705 'contentdialogresult.primary':222 'control':628 'control.myproperty':633 'copilot':118 'coreapplication.getcurrentview':529 'coreapplicationview.titlebar.extendviewintotitlebar':337 'coreapplicationviewtitlebar':335,714 'coredispatch':30,226,232 'coredispatcher.processevents':400 'coredispatcher.runasync':392,676 'coredispatcherpriority.normal':241 'corewindow':34,709 'corewindow.getforcurrentthread':406 'correct':17,66,146,197,245,274,363,459 'cover':26 'csharp':124,145,176,196,230,244,261,273,345,362,444,458,612 'currentwindow':271 'desktop':185,510,577,611,758 'dialog':37,132,152,187,201,339 'dialog.showasync':144,170,195,219 'differ':412 'direct':541,666 'dispatch':113 'dispatcher.hasthreadaccess':398 'dispatcher.runasync':240 'dispatcherqueu':32,229,247 'dispatcherqueue.getforcurrentthread':410 'dispatcherqueue.hasthreadaccess':399 'dispatcherqueue.tryenqueue':248,253,395,678 'dispatcherqueuepriority.high':254 'displayinformation.getforcurrentview':524 'done':243,250 'environment.getfolderpath':498 'equival':21,391,402,724 'error':136,156 'execut':643 'exist':235,266 'expect':632 'extendedactivationkind.appnotification':475 'file':359,382,491,495,742 'file/folder':343 'fileopenpick':355,371 'generat':63 'get':290 'getactivatedeventarg':472 'getdpiforwindow':526 'getforcurrentview':500,503,720 'guid':4,45 'handl':351,367,476,536 'hwnd':373,378,700 'ibackgroundtask':447,452,735 'ibackgroundtaskinst':456 'initi':364,694 'initializewithwindow.initialize':698 'instanc':692 'instanti':655 'instead':70,173,227 'interact':622 'interop':727 'invalidoperationexcept':127 'issu':435 'json':490 'key':411,634 'launchactivatedeventarg':297 'legaci':13,72 'librari':604,608 'local':494 'localapplicationdata':493 'logic':598 'mainwindow':289,299,301 'mainwindow.activate':302 'manag':307,732 'manual':534 'map':12 'messag':440 'messagedialog':172,703 'microsoft.ui.colors':107,673 'microsoft.ui.composition':103 'microsoft.ui.dispatching':111 'microsoft.ui.input':105 'microsoft.ui.text':109 'microsoft.ui.xaml':82,89,657,668 'microsoft.ui.xaml.controls':91 'microsoft.ui.xaml.data':97 'microsoft.ui.xaml.input':95 'microsoft.ui.xaml.media':93 'microsoft.ui.xaml.navigation':99 'microsoft.ui.xaml.shapes':101 'microsoft.windows.applifecycle':465 'migrat':3,10,44,50,258,342,386,443,481,543,556,659,749 'mistak':119 'move':80 'mstest':579 'must':555,584 'mylibrary.myusercontrol':630 'mytask':451 'namespac':27,75,79,84,87 'navig':538 'navigationview':540 'net10.0-windows10.0.22621.0':745 'new':133,153,188,202,300,354,370,629 'ok':142,162 'onlaunch':296 'overrid':294 'packag':483,768 'partial':282 'pattern':74,388,504 'picker':38,341,344,353,369,377,696,699 'picker.filetypefilter.add':356,379 'picker.picksinglefileasync':361,384 'primarybuttontext':210 'print':40,731 'prioriti':252,393,396 'privat':291 'progressbar.value':255 'project':547,562,580,741,759 'properti':278,325,520,685 'protect':293,431 'public':281,286,448,453,624 'pump':439 'reentranc':422,434 'refer':11,260 'regist':466 'replac':501,516,662,670,675,680,702,707,713,718,734 'requir':165,653 'restructur':403 'result':217,221 'run':455 'runner':641 'runtim':591 'scenario':482 'sdk':20,58,462 'seal':449 'set':147,292,480,488 'share':39,729 'show':150 'simpl':487 'skill':48 'skill-winui3-migration-guide' 'snippet':25 'someth':138,158 'source-github' 'specialfolder.localapplicationdata':499 'sta':417,428 'standard':427,578 'static':277,287,684 'statustext.text':242,249 'storag':496 'style':348 'sure':192,209 'systemnavigationmanager.getforcurrentview':535 'task':442 'taskinst':457 'tell':638 'templat':563 'test':542,546,561,568,573,587,595,602,616,640,645,751,754,764,766 'testmethod':592,596 'testmycontrol':626 'tfm':743 'this.content.xamlroot':164,215 'thread':29,385,650 'throw':126 'titl':135,155,204,328 'top':114 'topic-agent-skills' 'topic-agents' 'topic-awesome' 'topic-custom-agents' 'topic-github-copilot' 'topic-hacktoberfest' 'topic-prompt-engineering' 'track':532 'true':747 'txt':357,380 'type':583,658 'ui':649 'uitestmethod':599,618,623,636,761 'uiviewsettings.getforcurrentview':517 'unavail':506 'unit':545,567,572,615,750,753 'univers':570,605 'unpackag':485,770 'updat':726,740 'use':46,65,198,246,275,409,414,426,464,518,585,617,665,760 'user':223 'uwp':6,14,51,73,83,178,308,330,347,387,413,446,512,544,564,582 'uwp-to-winui':5 'var':131,151,186,200,216,270,352,358,368,372,381,469,627 'verifi':61 'void':295,454,625 'watch':432 'went':139,159 'win32':525 'window':18,33,56,257,259,288,306,350,366,460,533,571,606 'window.current':263,272,681 'windowid':523 'windows.ui.colors':106,671 'windows.ui.composition':102 'windows.ui.core':110 'windows.ui.input':104 'windows.ui.popups.messagedialog':189 'windows.ui.text':108 'windows.ui.xaml':78,88,664 'windows.ui.xaml.controls':90 'windows.ui.xaml.data':96 'windows.ui.xaml.input':94 'windows.ui.xaml.media':92 'windows.ui.xaml.navigation':98 'windows.ui.xaml.shapes':100 'winrt.interop.initializewithwindow.initialize':376 'winrt.interop.windownative.getwindowhandle':374 'winui':8,42,54,67,85,129,167,183,237,268,310,332,389,424,508,514,552,559,565,575,586,609,613,756 'winui3':2 'winui3-migration-guide':1 'without':122,429 'work':550 'wrong':125,140,160,177,231,262,346,445 'xaml':590,621,648,763 'xaml/ui':601 'xamlroot':123,148,163,214,688 'xamlroot.rasterizationscale':528 'yes':211","prices":[{"id":"58b7432c-df92-499f-886e-83d005fc2648","listingId":"c0b8c32f-6e73-48ac-95ad-17144e82d982","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"github","category":"awesome-copilot","install_from":"skills.sh"},"createdAt":"2026-04-18T20:26:51.902Z"}],"sources":[{"listingId":"c0b8c32f-6e73-48ac-95ad-17144e82d982","source":"github","sourceId":"github/awesome-copilot/winui3-migration-guide","sourceUrl":"https://github.com/github/awesome-copilot/tree/main/skills/winui3-migration-guide","isPrimary":false,"firstSeenAt":"2026-04-18T21:51:41.237Z","lastSeenAt":"2026-04-22T06:52:34.283Z"},{"listingId":"c0b8c32f-6e73-48ac-95ad-17144e82d982","source":"skills_sh","sourceId":"github/awesome-copilot/winui3-migration-guide","sourceUrl":"https://skills.sh/github/awesome-copilot/winui3-migration-guide","isPrimary":true,"firstSeenAt":"2026-04-18T20:26:51.902Z","lastSeenAt":"2026-04-22T06:40:17.896Z"}],"details":{"listingId":"c0b8c32f-6e73-48ac-95ad-17144e82d982","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"github","slug":"winui3-migration-guide","github":{"repo":"github/awesome-copilot","stars":30784,"topics":["agent-skills","agents","ai","awesome","custom-agents","github-copilot","hacktoberfest","prompt-engineering"],"license":"mit","html_url":"https://github.com/github/awesome-copilot","pushed_at":"2026-04-21T22:20:21Z","description":"Community-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.","skill_md_sha":"23969d1b631eb1a86301adfbdce915ea6d441e04","skill_md_path":"skills/winui3-migration-guide/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/github/awesome-copilot/tree/main/skills/winui3-migration-guide"},"layout":"multi","source":"github","category":"awesome-copilot","frontmatter":{"name":"winui3-migration-guide","description":"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."},"skills_sh_url":"https://skills.sh/github/awesome-copilot/winui3-migration-guide"},"updatedAt":"2026-04-22T06:52:34.283Z"}}