Skip to content

BumpyClock/agent-templates / skills_archive/merged-into-parent/winui-wpf-migration

winui-wpf-migration

Unverified

Migrate 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

WPFWinUI 3
System.WindowsMicrosoft.UI.Xaml
System.Windows.ControlsMicrosoft.UI.Xaml.Controls
System.Windows.MediaMicrosoft.UI.Xaml.Media
System.Windows.InputMicrosoft.UI.Xaml.Input
System.Windows.DataMicrosoft.UI.Xaml.Data
System.Windows.Threading.DispatcherMicrosoft.UI.Dispatching.DispatcherQueue
PresentationCore / PresentationFrameworkRemove entirely

Step 4: Replace Controls

WPF ControlWinUI 3 Equivalent
DataGridListView with Grid column headers
WrapPanelItemsRepeater + UniformGridLayout
TabControlTabView
StatusBarGrid row at bottom with TextBlock elements
Menu / MenuItemMenuBar / MenuBarItem / MenuFlyoutItem
ToolBarCommandBar
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
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: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall