winui-wpf-migration

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.Imaging references at migration start
• Replace with Windows.Graphics.Imaging (WinRT) or Microsoft.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:

• INotifyPropertyChanged base → ObservableObject with [ObservableProperty] partial properties
• Custom RelayCommand → [RelayCommand] attribute
• {Binding} → {x:Bind Mode=OneWay}
• DynamicResource → {ThemeResource}

Step 8: Replace Resources

• .resx → .resw (copy + rename to Strings\en-us\)
• {x:Static} → x:Uid for localized strings
• Properties.Resources.Key → ResourceLoader.GetString("Key")

Critical Rules

• ❌ NEVER reference PresentationCore, PresentationFramework, or System.Windows.Controls assemblies
• ❌ 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 run to 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