version: "1.0.0" name: wpf-to-winui3-migration description: 'Guide for migrating PowerToys modules from WPF to WinUI 3 (Windows App SDK). Use when asked to migrate WPF code, convert WPF XAML to WinUI, replace System.Windows namespaces with Microsoft.UI.Xaml, update Dispatcher to DispatcherQueue, replace DynamicResource with ThemeResource, migrate imaging APIs from System.Windows.Media.Imaging to Windows.Graphics.Imaging, convert WPF Window to WinUI Window, migrate .resx to .resw resources, migrate custom Observable/RelayCommand to CommunityToolkit.Mvvm source generators, handle WPF-UI (Lepo) to WinUI native control migration, or fix installer/build pipeline issues after migration. Keywords: WPF, WinUI, WinUI3, migration, porting, convert, namespace, XAML, Dispatcher, DispatcherQueue, imaging, BitmapImage, Window, ContentDialog, ThemeResource, DynamicResource, ResourceLoader, resw, resx, CommunityToolkit, ObservableProperty, WPF-UI, SizeToContent, AppWindow, SoftwareBitmap.' license: Complete terms in LICENSE.txt

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.

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 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