winui3-migration-guide

Name: winui3-migration-guide
Author: github

5.6kinstalls4.6kforks

How to install winui3-migration-guide?

github/awesome-copilot/winui3-migration-guide

$npx -y skills add github/awesome-copilot --skill winui3-migration-guide

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# WinUI 3 Migration Guide
2
3	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.
4
5	---
6
7	## Namespace Changes
8
9	All `Windows.UI.Xaml.` namespaces move to `Microsoft.UI.Xaml.`:
10
11	\| UWP Namespace \| WinUI 3 Namespace \|
12	\|--------------\|-------------------\|
13	\| `Windows.UI.Xaml` \| `Microsoft.UI.Xaml` \|
14	\| `Windows.UI.Xaml.Controls` \| `Microsoft.UI.Xaml.Controls` \|
15	\| `Windows.UI.Xaml.Media` \| `Microsoft.UI.Xaml.Media` \|
16	\| `Windows.UI.Xaml.Input` \| `Microsoft.UI.Xaml.Input` \|
17	\| `Windows.UI.Xaml.Data` \| `Microsoft.UI.Xaml.Data` \|
18	\| `Windows.UI.Xaml.Navigation` \| `Microsoft.UI.Xaml.Navigation` \|
19	\| `Windows.UI.Xaml.Shapes` \| `Microsoft.UI.Xaml.Shapes` \|
20	\| `Windows.UI.Composition` \| `Microsoft.UI.Composition` \|
21	\| `Windows.UI.Input` \| `Microsoft.UI.Input` \|
22	\| `Windows.UI.Colors` \| `Microsoft.UI.Colors` \|
23	\| `Windows.UI.Text` \| `Microsoft.UI.Text` \|
24	\| `Windows.UI.Core` \| `Microsoft.UI.Dispatching` (for dispatcher) \|
25
26	---
27
28	## Top 3 Most Common Copilot Mistakes
29
30	### 1. ContentDialog Without XamlRoot
31
32	```csharp
33	// ❌ WRONG — Throws InvalidOperationException in WinUI 3
34	var dialog = new ContentDialog
35	{
36	Title = "Error",
37	Content = "Something went wrong.",
38	CloseButtonText = "OK"
39	};
40	await dialog.ShowAsync();
41	```
42
43	```csharp
44	// ✅ CORRECT — Set XamlRoot before showing
45	var dialog = new ContentDialog
46	{
47	Title = "Error",
48	Content = "Something went wrong.",
49	CloseButtonText = "OK",
50	XamlRoot = this.Content.XamlRoot // Required in WinUI 3
51	};
52	await dialog.ShowAsync();
53	```
54
55	### 2. MessageDialog Instead of ContentDialog
56
57	```csharp
58	// ❌ WRONG — UWP API, not available in WinUI 3 desktop
59	var dialog = new Windows.UI.Popups.MessageDialog("Are you sure?", "Confirm");
60	await dialog.ShowAsync();
61	```
62
63	```csharp
64	// ✅ CORRECT — Use ContentDialog
65	var dialog = new ContentDialog
66	{
67	Title = "Confirm",
68	Content = "Are you sure?",
69	PrimaryButtonText = "Yes",
70	CloseButtonText = "No",
71	XamlRoot = this.Content.XamlRoot
72	};
73	var result = await dialog.ShowAsync();
74	if (result == ContentDialogResult.Primary)
75	{
76	// User confirmed
77	}
78	```
79
80	### 3. CoreDispatcher Instead of DispatcherQueue
81
82	```csharp
83	// ❌ WRONG — CoreDispatcher does not exist in WinUI 3
84	await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
85	{
86	StatusText.Text = "Done";
87	});
88	```
89
90	```csharp
91	// ✅ CORRECT — Use DispatcherQueue
92	DispatcherQueue.TryEnqueue(() =>
93	{
94	StatusText.Text = "Done";
95	});
96
97	// With priority:
98	DispatcherQueue.TryEnqueue(DispatcherQueuePriority.High, () =>
99	{
100	ProgressBar.Value = 100;
101	});
102	```
103
104	---
105
106	## Windowing Migration
107
108	### Window Reference
109
110	```csharp
111	// ❌ WRONG — Window.Current does not exist in WinUI 3
112	var currentWindow = Window.Current;
113	```
114
115	```csharp
116	// ✅ CORRECT — Use a static property in App
117	public partial class App : Application
118	{
119	public static Window MainWindow { get; private set; }
120
121	protected override void OnLaunched(LaunchActivatedEventArgs args)
122	{
123	MainWindow = new MainWindow();
124	MainWindow.Activate();
125	}
126	}
127	// Access anywhere: App.MainWindow
128	```
129
130	### Window Management
131
132	\| UWP API \| WinUI 3 API \|
133	\|---------\|-------------\|
134	\| `ApplicationView.TryResizeView()` \| `AppWindow.Resize()` \|
135	\| `AppWindow.TryCreateAsync()` \| `AppWindow.Create()` \|
136	\| `AppWindow.TryShowAsync()` \| `AppWindow.Show()` \|
137	\| `AppWindow.TryConsolidateAsync()` \| `AppWindow.Destroy()` \|
138	\| `AppWindow.RequestMoveXxx()` \| `AppWindow.Move()` \|
139	\| `AppWindow.GetPlacement()` \| `AppWindow.Position` property \|
140	\| `AppWindow.RequestPresentation()` \| `AppWindow.SetPresenter()` \|
141
142	### Title Bar
143
144	\| UWP API \| WinUI 3 API \|
145	\|---------\|-------------\|
146	\| `CoreApplicationViewTitleBar` \| `AppWindowTitleBar` \|
147	\| `CoreApplicationView.TitleBar.ExtendViewIntoTitleBar` \| `AppWindow.TitleBar.ExtendsContentIntoTitleBar` \|
148
149	---
150
151	## Dialogs and Pickers Migration
152
153	### File/Folder Pickers
154
155	```csharp
156	// ❌ WRONG — UWP style, no window handle
157	var picker = new FileOpenPicker();
158	picker.FileTypeFilter.Add(".txt");
159	var file = await picker.PickSingleFileAsync();
160	```
161
162	```csharp
163	// ✅ CORRECT — Initialize with window handle
164	var picker = new FileOpenPicker();
165	var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
166	WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);
167	picker.FileTypeFilter.Add(".txt");
168	var file = await picker.PickSingleFileAsync();
169	```
170
171	## Threading Migration
172
173	\| UWP Pattern \| WinUI 3 Equivalent \|
174	\|-------------\|-------------------\|
175	\| `CoreDispatcher.RunAsync(priority, callback)` \| `DispatcherQueue.TryEnqueue(priority, callback)` \|
176	\| `Dispatcher.H

People who liked this also viewed

6 picks

Type

winui3-migration-guide

5.6kinstalls4.6kforks

View on GitHub

How to install winui3-migration-guide?

github/awesome-copilot/winui3-migration-guide

$npx -y skills add github/awesome-copilot --skill winui3-migration-guide

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# WinUI 3 Migration Guide
2
3	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.
4
5	---
6
7	## Namespace Changes
8
9	All `Windows.UI.Xaml.` namespaces move to `Microsoft.UI.Xaml.`:
10
11	\| UWP Namespace \| WinUI 3 Namespace \|
12	\|--------------\|-------------------\|
13	\| `Windows.UI.Xaml` \| `Microsoft.UI.Xaml` \|
14	\| `Windows.UI.Xaml.Controls` \| `Microsoft.UI.Xaml.Controls` \|
15	\| `Windows.UI.Xaml.Media` \| `Microsoft.UI.Xaml.Media` \|
16	\| `Windows.UI.Xaml.Input` \| `Microsoft.UI.Xaml.Input` \|
17	\| `Windows.UI.Xaml.Data` \| `Microsoft.UI.Xaml.Data` \|
18	\| `Windows.UI.Xaml.Navigation` \| `Microsoft.UI.Xaml.Navigation` \|
19	\| `Windows.UI.Xaml.Shapes` \| `Microsoft.UI.Xaml.Shapes` \|
20	\| `Windows.UI.Composition` \| `Microsoft.UI.Composition` \|
21	\| `Windows.UI.Input` \| `Microsoft.UI.Input` \|
22	\| `Windows.UI.Colors` \| `Microsoft.UI.Colors` \|
23	\| `Windows.UI.Text` \| `Microsoft.UI.Text` \|
24	\| `Windows.UI.Core` \| `Microsoft.UI.Dispatching` (for dispatcher) \|
25
26	---
27
28	## Top 3 Most Common Copilot Mistakes
29
30	### 1. ContentDialog Without XamlRoot
31
32	```csharp
33	// ❌ WRONG — Throws InvalidOperationException in WinUI 3
34	var dialog = new ContentDialog
35	{
36	Title = "Error",
37	Content = "Something went wrong.",
38	CloseButtonText = "OK"
39	};
40	await dialog.ShowAsync();
41	```
42
43	```csharp
44	// ✅ CORRECT — Set XamlRoot before showing
45	var dialog = new ContentDialog
46	{
47	Title = "Error",
48	Content = "Something went wrong.",
49	CloseButtonText = "OK",
50	XamlRoot = this.Content.XamlRoot // Required in WinUI 3
51	};
52	await dialog.ShowAsync();
53	```
54
55	### 2. MessageDialog Instead of ContentDialog
56
57	```csharp
58	// ❌ WRONG — UWP API, not available in WinUI 3 desktop
59	var dialog = new Windows.UI.Popups.MessageDialog("Are you sure?", "Confirm");
60	await dialog.ShowAsync();
61	```
62
63	```csharp
64	// ✅ CORRECT — Use ContentDialog
65	var dialog = new ContentDialog
66	{
67	Title = "Confirm",
68	Content = "Are you sure?",
69	PrimaryButtonText = "Yes",
70	CloseButtonText = "No",
71	XamlRoot = this.Content.XamlRoot
72	};
73	var result = await dialog.ShowAsync();
74	if (result == ContentDialogResult.Primary)
75	{
76	// User confirmed
77	}
78	```
79
80	### 3. CoreDispatcher Instead of DispatcherQueue
81
82	```csharp
83	// ❌ WRONG — CoreDispatcher does not exist in WinUI 3
84	await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
85	{
86	StatusText.Text = "Done";
87	});
88	```
89
90	```csharp
91	// ✅ CORRECT — Use DispatcherQueue
92	DispatcherQueue.TryEnqueue(() =>
93	{
94	StatusText.Text = "Done";
95	});
96
97	// With priority:
98	DispatcherQueue.TryEnqueue(DispatcherQueuePriority.High, () =>
99	{
100	ProgressBar.Value = 100;
101	});
102	```
103
104	---
105
106	## Windowing Migration
107
108	### Window Reference
109
110	```csharp
111	// ❌ WRONG — Window.Current does not exist in WinUI 3
112	var currentWindow = Window.Current;
113	```
114
115	```csharp
116	// ✅ CORRECT — Use a static property in App
117	public partial class App : Application
118	{
119	public static Window MainWindow { get; private set; }
120
121	protected override void OnLaunched(LaunchActivatedEventArgs args)
122	{
123	MainWindow = new MainWindow();
124	MainWindow.Activate();
125	}
126	}
127	// Access anywhere: App.MainWindow
128	```
129
130	### Window Management
131
132	\| UWP API \| WinUI 3 API \|
133	\|---------\|-------------\|
134	\| `ApplicationView.TryResizeView()` \| `AppWindow.Resize()` \|
135	\| `AppWindow.TryCreateAsync()` \| `AppWindow.Create()` \|
136	\| `AppWindow.TryShowAsync()` \| `AppWindow.Show()` \|
137	\| `AppWindow.TryConsolidateAsync()` \| `AppWindow.Destroy()` \|
138	\| `AppWindow.RequestMoveXxx()` \| `AppWindow.Move()` \|
139	\| `AppWindow.GetPlacement()` \| `AppWindow.Position` property \|
140	\| `AppWindow.RequestPresentation()` \| `AppWindow.SetPresenter()` \|
141
142	### Title Bar
143
144	\| UWP API \| WinUI 3 API \|
145	\|---------\|-------------\|
146	\| `CoreApplicationViewTitleBar` \| `AppWindowTitleBar` \|
147	\| `CoreApplicationView.TitleBar.ExtendViewIntoTitleBar` \| `AppWindow.TitleBar.ExtendsContentIntoTitleBar` \|
148
149	---
150
151	## Dialogs and Pickers Migration
152
153	### File/Folder Pickers
154
155	```csharp
156	// ❌ WRONG — UWP style, no window handle
157	var picker = new FileOpenPicker();
158	picker.FileTypeFilter.Add(".txt");
159	var file = await picker.PickSingleFileAsync();
160	```
161
162	```csharp
163	// ✅ CORRECT — Initialize with window handle
164	var picker = new FileOpenPicker();
165	var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
166	WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);
167	picker.FileTypeFilter.Add(".txt");
168	var file = await picker.PickSingleFileAsync();
169	```
170
171	## Threading Migration
172
173	\| UWP Pattern \| WinUI 3 Equivalent \|
174	\|-------------\|-------------------\|
175	\| `CoreDispatcher.RunAsync(priority, callback)` \| `DispatcherQueue.TryEnqueue(priority, callback)` \|
176	\| `Dispatcher.H

People who liked this also viewed

6 picks

Type