winui-wpf-migration
Migrate or port a WPF app to WinUI 3: namespaces (System.Windows to Microsoft.UI.Xaml), control mapping (DataGrid, WrapPanel, TabControl), Dispatcher to DispatcherQueue, imaging, MVVM with CommunityToolkit.Mvvm, ThemeResource. Use when converting WPF code or fixing migration build errors.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.4k
- Forks
- 96
01 前言 Front Matter
- name
- winui-wpf-migration
- description
- Migrate or port a WPF app to WinUI 3: namespaces (System.Windows to Microsoft.UI.Xaml), control mapping (DataGrid, WrapPanel, TabControl), Dispatcher to DispatcherQueue, imaging, MVVM with CommunityToolkit.Mvvm, ThemeResource. Use when converting WPF code or fixing migration build errors.
03 SKILL.md 正文
Migration Process
Use the WinApp CLI 0.7+ prerequisites and per-app analyzer setup in winui-dev-workflow. The normal SDK path needs .NET 8.0.100 or later and the SDK required by the target TFM; Native AOT additionally needs MSVC/Desktop C++ tools. Handle missing prerequisites as described there.
Step 1: Audit the WPF Source
Before writing code, inventory WPF-specific APIs:
# Find all WPF namespace usage
Select-String -Path (Get-ChildItem -Recurse -Filter "*.cs" | Where-Object { $_.FullName -notlike "*\obj\*" }) -Pattern "System\.Windows\." | Select-Object -Property Filename, LineNumber, Line
List: WPF controls used, custom MVVM framework, imaging APIs, threading patterns, Win32 interop.
Step 2: Create WinUI 3 Project and Align Namespaces
winapp new --name <AppName> --template winui-mvvm --template-version latest --use-defaults
Immediately set <RootNamespace> in .csproj to match the WPF namespace. Update x:Class in App.xaml, MainWindow.xaml and their code-behind files. Add the analyzer per winui-dev-workflow. Build to verify before porting any code.
Before implementing API replacements, restore the app project and check its exact references from the WinUI project directory, not the old WPF project or machine SDK:
winapp find-api DispatcherQueue --json --project-dir .
winapp find-api members DispatcherQueue --filter TryEnqueue --json --project-dir .
winapp find-api check-property ListView ItemsSource SelectionMode --json --project-dir .
Use winapp find-ui "<intent>" for usage samples; see winui-design for project selection and batch API checks.
Step 3: Replace Namespaces
| WPF | WinUI 3 |
|---|---|
System.Windows |
Microsoft.UI.Xaml |
System.Windows.Controls |
Microsoft.UI.Xaml.Controls |
System.Windows.Media |
Microsoft.UI.Xaml.Media |
System.Windows.Input |
Microsoft.UI.Xaml.Input |
System.Windows.Data |
Microsoft.UI.Xaml.Data |
System.Windows.Threading.Dispatcher |
Microsoft.UI.Dispatching.DispatcherQueue |
PresentationCore / PresentationFramework |
Remove entirely |
Step 4: Replace Controls
| WPF Control | WinUI 3 Equivalent |
|---|---|
DataGrid |
ListView with Grid column headers |
WrapPanel |
ItemsRepeater + UniformGridLayout |
TabControl |
TabView |
StatusBar |
Grid row at bottom with TextBlock elements |
Menu / MenuItem |
MenuBar / MenuBarItem / MenuFlyoutItem |
ToolBar |
CommandBar |
Expander (custom) |
Expander (built-in) |
Step 5: Replace Threading
// WPF
Application.Current.Dispatcher.Invoke(() => { /* UI work */ });
// WinUI 3
dispatcherQueue.TryEnqueue(() => { /* UI work */ });
Get via DispatcherQueue.GetForCurrentThread(). No Application.Current.Dispatcher in WinUI 3.
Step 6: Replace Imaging
Critical: PresentationCore.dll and System.Windows.Media.Imaging crash the WinUI XAML compiler. This is an architectural incompatibility — no workaround exists.
- Remove ALL
System.Windows.Media.Imagingreferences at migration start - Replace with
Windows.Graphics.Imaging(WinRT) orMicrosoft.UI.Xaml.Media.Imaging.BitmapImage - Do NOT add
<UseWPF>true</UseWPF>— it silently corrupts the build - If heavy imaging code exists, migrate it early (step 2, not step 7)
Step 7: Replace MVVM Framework
Delete custom ObservableObject/RelayCommand/DelegateCommand. Use CommunityToolkit.Mvvm:
INotifyPropertyChangedbase →ObservableObjectwith[ObservableProperty]partial properties (fix MVVMTK0045; don't keep fields)- Custom
RelayCommand→[RelayCommand]attribute - Prefer
{x:Bind}for known types; keep runtime{Binding}/DisplayMemberPathwhere needed. Seewinui-packaging'sreferences/sourcegen-patterns.mdfor binding modes,x:DataType, and AOT-safe runtime binding. DynamicResource→{ThemeResource}
Step 8: Replace Resources
.resx→.resw(copy + rename toStrings\en-us\){x:Static}→x:Uidfor localized stringsProperties.Resources.Key→ResourceLoader.GetString("Key")
Critical Rules
- ❌ NEVER reference
PresentationCore,PresentationFramework, orSystem.Windows.Controlsassemblies - ❌ NEVER add
<UseWPF>true</UseWPF> - Keep packaged as the default; see
winui-dev-workflowCritical Rules for unpackaged experiments. - ❌ NEVER delete
Package.appxmanifest - ❌ NEVER overwrite
App.xaml/App.xaml.cs— merge WPF code into the WinUI 3 boilerplate - ✅ Launch with project-mode
winapp run, not the .exe directly. - ✅ Break migration into file-level tasks — not one massive rewrite
Post-Migration Validation
# Check for remaining WPF references (should return nothing)
Select-String -Path (Get-ChildItem -Recurse -Filter "*.cs" | Where-Object { $_.FullName -notlike "*\obj\*" }) -Pattern "System\.Windows\."
# Verify packaging preserved
Test-Path "Package.appxmanifest" # should be True
# Build (the analyzer participates when installed)
dotnet build .\MyApp.csproj -p:Platform=x64
# Run the migrated app
winapp run .\MyApp.csproj --detach --json
For UI validation, see winui-ui-testing; for crash diagnostics, see winui-dev-workflow. If AOT is intended, also test the published artifact via the workflow's AOT path; the run above is JIT, even in Release.
04 同仓库更多 Skills
winui-ui-testing
Write and run automated UI tests for Windows desktop apps (WinUI 3, WPF, WinForms, Win32) with the winapp ui harness: one batch script, assertions, input, file pickers, dialogs, screenshots, locally or in Windows Sandbox. Use when asked for UI tests or to verify a feature end to end.
winui-setup
Install and verify WinUI 3 prerequisites — .NET SDK 8.0.100+, WinApp CLI 0.7+, and Developer Mode; identify additional Native AOT and Windows Sandbox requirements. Use when the user asks to set up or repair the toolchain, or when another WinUI skill finds a missing or outdated prerequisite.
winui-packaging
MSIX packaging, signing, and Microsoft Store publishing for WinUI 3 apps with WinApp CLI 0.7+: project packaging, Native AOT, certificates, self-contained deployment, CI/CD. Use when releasing or publishing a WinUI app. Not for WPF, WinForms, or Electron apps that only reference the Windows App SDK.
winui-dev-workflow
Create, build, run, and fix build errors in WinUI 3 apps (C# or C++) with WinApp CLI 0.7+: winapp new, winapp run, Native AOT, crash diagnosis. Use for a new WinUI app or a WinUI project that fails to build or crashes. Not for WPF, WinForms, or Electron apps that only reference the Windows App SDK.
winui-design
Read before writing or changing WinUI 3 XAML: choosing controls, pages and navigation, layout, Fluent Design, theming, accessibility, x:Bind, real samples, and checking that APIs exist with winapp find-api. Not for WPF or WinForms UI, even if the app uses the Windows App SDK.
winui-code-review
Review WinUI 3 code or changes for quality: MVVM, x:Bind correctness, accessibility, theming, security, performance, and WinUI analyzer findings. Use when asked to review or audit a WinUI app or its pending changes, or before committing. Catches issues the compiler and UI tests miss.