wpf-to-winui3-migration

WPF to WinUI 3 Migration Skill

Migrate PowerToys modules from WPF (System.Windows.*) to WinUI 3 (Microsoft.UI.Xaml.* / Windows App SDK). Based on patterns validated in the ImageResizer module migration.

When to Use This Skill

• Migrate a PowerToys module from WPF to WinUI 3
• Convert WPF XAML files to WinUI 3 XAML
• Replace System.Windows namespaces with Microsoft.UI.Xaml
• Migrate Dispatcher usage to DispatcherQueue
• Migrate custom Observable/RelayCommand to CommunityToolkit.Mvvm source generators
• Replace WPF-UI (Lepo) controls with native WinUI 3 controls
• Convert imaging code from System.Windows.Media.Imaging to Windows.Graphics.Imaging
• Handle WPF Window vs WinUI Window differences (sizing, positioning, SizeToContent)
• Migrate resource files from .resx to .resw with ResourceLoader
• Fix installer/build pipeline issues after WinUI 3 migration
• Update project files, NuGet packages, and signing config

Prerequisites

• Visual Studio 2022 17.4+
• Windows App SDK NuGet package (Microsoft.WindowsAppSDK)
• .NET 8+ with net8.0-windows10.0.19041.0 TFM
• Windows 10 1803+ (April 2018 Update or newer)

Migration Strategy

Phase-by-Phase Scope

Work on bounded problems, not the entire codebase at once. Each phase should compile before moving to the next.

1. Project file — Update TFM, NuGet packages, set <UseWinUI>true</UseWinUI>
2. Data models and business logic — No UI dependencies, migrate first
3. MVVM framework — Replace custom Observable/RelayCommand with CommunityToolkit.Mvvm
4. Resource strings — Migrate .resx → .resw, introduce ResourceLoaderInstance
5. Services and utilities — Replace System.Windows types, async-ify imaging code
6. ViewModels — Update Dispatcher usage, binding patterns
7. Views/Pages — Starting from leaf pages with fewest dependencies
8. Main page / shell — Last, since it depends on everything
9. App.xaml / startup code — Merge carefully (do NOT overwrite WinUI 3 boilerplate)
10. Installer & build pipeline — Update WiX, signing, build events
11. Tests — Adapt for WinUI 3 runtime, async patterns

Migration Contract: Prohibited Patterns

These rules capture human judgment and must be applied consistently across every file. Do NOT deviate.

Architecture prohibitions:

• Do NOT overwrite App.xaml / App.xaml.cs — WinUI 3 has different lifecycle boilerplate. Merge resources and init code into the generated WinUI 3 App class.
• Do NOT create Exe→WinExe ProjectReference — Extract shared code to a Library project. Causes phantom build artifacts.
• Do NOT instantiate services directly — Use DI and CommunityToolkit.Mvvm patterns.
• Do NOT create a Window subclass for every dialog or sub-page — use ContentDialog for in-app dialogs and Frame/Page navigation for sub-views. Separate Window classes are reserved for distinct top-level surfaces (e.g., FancyZones editor, OOBE).
• Do NOT omit WindowsPackageType=None and WindowsAppSDKSelfContained=true — Both are mandatory in the csproj for every WinUI 3 module in PowerToys. Without them the app crashes at startup with COMException: ClassFactory cannot supply requested class because the WinUI 3 runtime DLLs are not found.
• Do NOT default to a bare Window, and do NOT hand-write code-behind for windowing that XAML can express — For a top-level window in a WinUI 3 module, use WinUIEx.WindowEx or an existing PowerToys base derived from it (for example, TransparentWindow for transient overlays). WindowEx restores WPF-like Window members as XAML properties (MinWidth/MinHeight, Width/Height, IsResizable, IsMaximizable/IsMinimizable, IsTitleBarVisible, IsAlwaysOnTop, IsShownInSwitchers, WindowState, SystemBackdrop) plus helpers (CenterOnScreen(), PersistenceId), so windowing is declared in XAML instead of manual AppWindow/OverlappedPresenter code-behind. This is the established PowerToys convention across ImageResizer, PowerDisplay, Peek, AdvancedPaste, MeasureTool, ShortcutGuide, Settings, Hosts, FileLocksmith, QuickAccess, and other WinUI 3 modules. Only drop to raw AppWindow/presenter code for behavior WindowEx does not expose. See Threading and Window Management → WindowEx.

XAML prohibitions:

• Do NOT use {DynamicResource} — Replace with {ThemeResource} (theme-reactive) or {StaticResource}.
• Do NOT use {Binding} in Setter.Value — Not supported in WinUI 3. Use {StaticResource}.
• Do NOT use {x:Static} — Replace with {x:Bind}, x:Uid, or code-behind.
• Do NOT use {x:Type} — Not supported. Use x:DataType for DataTemplate, or code-behind.
• Do NOT use clr-namespace: — Replace with using: in all xmlns declarations.
• Do NOT use Style.Triggers / DataTrigger / EventTrigger — Replace with VisualStateManager.
• Do NOT use MultiBinding — Replace with x:Bind function binding or computed ViewModel property.
• Do NOT mechanically port WPF IValueConverter classes — Prefer control VisualStates, direct {x:Bind} Boolean-to-Visibility conversion, resources supplied by XamlControlsResources, or CommunityToolkit.WinUI.Converters. Reuse converter instances and invert them with ConverterParameter=True when supported; write a custom converter only for app-specific conversion logic. See Value Converter Decision Guide.
• Do NOT use Visibility="Hidden" — WinUI only has Visible and Collapsed. Use Opacity="0" if layout must be preserved.
• Do NOT use IsDefault / IsCancel — Use AccentButtonStyle for primary button; handle Enter/Escape in code-behind.
• Do NOT omit BasedOn when overriding default styles — Without it, your style replaces the entire default. Always use BasedOn="{StaticResource DefaultButtonStyle}" etc.
• Do NOT omit XamlControlsResources as first merged dictionary — It provides default Fluent styles. Without it, controls have no visual appearance.

Code-behind prohibitions:

• Do NOT use Application.Current.Dispatcher — Store DispatcherQueue in a static field explicitly.
• Do NOT use Window.Current — Not supported. Use a custom App.Window static property.
• Do NOT put DataContext, Resources, or VisualStateManager on Window — WinUI 3 Window is NOT a DependencyObject. Use a root Page/UserControl/Grid.
• Do NOT use tunneling/preview events (PreviewMouseDown, PreviewKeyDown) — WinUI has no tunneling. Use bubbling equivalents with Handled property or AddHandler(handledEventsToo: true).

Resource prohibitions:

• Do NOT use Properties.Resources.MyString — Replace with ResourceLoaderInstance.ResourceLoader.GetString("MyString").
• Do NOT initialize ResourceLoader-dependent values as static fields — Wrap in Lazy<T> or null-coalescing property.
• Do NOT use pack:// URIs — Replace with ms-appx:/// scheme.

Quick Reference Tables

Namespace Mapping

Control Replacements (No 1:1 Mapping)

These WPF controls have no direct counterpart and require a different control or third-party package:

Layout & Header Controls from CommunityToolkit.WinUI

These WPF controls have no built-in WinUI 3 equivalent — install the corresponding CommunityToolkit package. The NuGet package id and the XAML namespace differ intentionally: package names end in .Primitives / .HeaderedControls, but the registered XAML namespace is the shorter CommunityToolkit.WinUI.Controls (confirmed in the official Microsoft Q&A).

No Equivalent — Requires Architectural Rework

These WPF features have no WinUI counterpart and require redesign, not find-and-replace:

Critical API Replacements

Event Replacements (Mouse → Pointer)

Property Replacements

NuGet Package Migration

XAML Syntax Changes

Binding: {Binding} vs {x:Bind}

Both work in WinUI 3. Prefer {x:Bind} for new/migrated code.

Detailed Reference Docs

Read only the section relevant to your current task:

• Namespace and API Mapping — Full type mapping, NuGet changes, project file, CsWinRT interop
• XAML Migration Guide — XAML syntax, WPF-UI removal, markup extensions, styles, resources, data binding
• Threading and Window Management — Dispatcher, DispatcherQueue, SizeToContent, AppWindow, HWND interop, custom entry point
• Imaging API Migration — BitmapEncoder/Decoder, SoftwareBitmap, CodecHelper, async patterns, int→uint
• PowerToys-Specific Patterns — MVVM migration, ResourceLoader, Lazy init, installer, signing, test adaptation, build pipeline

Common Pitfalls (from ImageResizer migration)

Troubleshooting