BumpyClock/agent-templates / skills_archive/merged-into-parent/winui-wpf-migration
winui-wpf-migration
UnverifiedMigrate WPF applications to WinUI 3 — namespace replacement (System.Windows → Microsoft.UI.Xaml), control mapping (DataGrid→ListView, WrapPanel→ItemsRepeater, TabControl→TabView), threading (Dispatcher→DispatcherQueue), imaging (System.Drawing→BitmapImage), MVVM conversion to CommunityToolkit.Mvvm, and DynamicResource→ThemeResource. Use when converting WPF code, replacing WPF namespaces, or fixing migration build errors.
Migration Process
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. Build to verify before porting any code.
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- Custom
RelayCommand→[RelayCommand]attribute {Binding}→{x:Bind Mode=OneWay}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>or<WindowsPackageType>None</WindowsPackageType> - ❌ NEVER delete
Package.appxmanifest - ❌ NEVER overwrite
App.xaml/App.xaml.cs— merge WPF code into the WinUI 3 boilerplate - ✅ Always use
winapp runto launch — never run 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 and run with the bundled analyzer
.\BuildAndRun.ps1
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |