From 7051b8939b864f6f1b125834d9c895ef3d1d8bff Mon Sep 17 00:00:00 2001 From: moooyo <42196638+moooyo@users.noreply.github.com> Date: Tue, 24 Mar 2026 17:40:33 +0800 Subject: [PATCH] [Skills] Add WPF to WinUI 3 migration agent skill (#46462) ## Summary of the Pull Request With this skills, we can easily enable AI to complete most of the tasks involved in migrating from WPF to WinUI3. ## PR Checklist - [x] Closes: #46464 - [ ] **Communication:** I've discussed this with core contributors already. If the work hasn't been agreed, this work might be rejected - [ ] **Tests:** Added/updated and all pass - [ ] **Localization:** All end-user-facing strings can be localized - [ ] **Dev docs:** Added/updated - [ ] **New binaries:** Added on the required places - [ ] [JSON for signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json) for new binaries - [ ] [WXS for installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs) for new binaries and localization folder - [ ] [YML for CI pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml) for new test projects - [ ] [YML for signed pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml) - [ ] **Documentation updated:** If checked, please file a pull request on [our docs repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys) and link it here: #xxx ## Detailed Description of the Pull Request / Additional comments ## Validation Steps Performed --------- Co-authored-by: Yu Leng Co-authored-by: Claude Opus 4.6 (1M context) --- .github/actions/spell-check/allow/code.txt | 5 + .../skills/wpf-to-winui3-migration/SKILL.md | 165 ++++++ .../references/imaging-migration.md | 287 ++++++++++ .../references/namespace-api-mapping.md | 226 ++++++++ .../references/powertoys-patterns.md | 516 ++++++++++++++++++ .../references/threading-and-windowing.md | 314 +++++++++++ .../references/xaml-migration.md | 365 +++++++++++++ 7 files changed, 1878 insertions(+) create mode 100644 .github/skills/wpf-to-winui3-migration/SKILL.md create mode 100644 .github/skills/wpf-to-winui3-migration/references/imaging-migration.md create mode 100644 .github/skills/wpf-to-winui3-migration/references/namespace-api-mapping.md create mode 100644 .github/skills/wpf-to-winui3-migration/references/powertoys-patterns.md create mode 100644 .github/skills/wpf-to-winui3-migration/references/threading-and-windowing.md create mode 100644 .github/skills/wpf-to-winui3-migration/references/xaml-migration.md diff --git a/.github/actions/spell-check/allow/code.txt b/.github/actions/spell-check/allow/code.txt index 50a4b55e5b..f8b3fb3677 100644 --- a/.github/actions/spell-check/allow/code.txt +++ b/.github/actions/spell-check/allow/code.txt @@ -1,6 +1,7 @@ # COLORS argb +Bgr bgra BLACKONWHITE BLUEGRAY @@ -28,6 +29,7 @@ RUS AYUV bak +HDP Bcl bgcode Deflatealgorithm @@ -46,6 +48,7 @@ nupkg petabyte resw resx +runtimeconfig srt Stereolithography terabyte @@ -297,6 +300,8 @@ pwa AOT Aot +ify +TFM # YML onefuzz diff --git a/.github/skills/wpf-to-winui3-migration/SKILL.md b/.github/skills/wpf-to-winui3-migration/SKILL.md new file mode 100644 index 0000000000..89f7325c4f --- /dev/null +++ b/.github/skills/wpf-to-winui3-migration/SKILL.md @@ -0,0 +1,165 @@ +--- +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 + +### Recommended Order + +1. **Project file** — Update TFM, NuGet packages, set `true` +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 + +### Key Principles + +- **Do NOT overwrite `App.xaml` / `App.xaml.cs`** — WinUI 3 has different application lifecycle boilerplate. Merge your resources and initialization code into the generated WinUI 3 App class. +- **Do NOT create Exe→WinExe `ProjectReference`** — Extract shared code to a Library project. This causes phantom build artifacts. +- **Use `Lazy` for resource-dependent statics** — `ResourceLoader` is not available at class-load time in all contexts. + +## Quick Reference Tables + +### Namespace Mapping + +| WPF | WinUI 3 | +|-----|---------| +| `System.Windows` | `Microsoft.UI.Xaml` | +| `System.Windows.Controls` | `Microsoft.UI.Xaml.Controls` | +| `System.Windows.Media` | `Microsoft.UI.Xaml.Media` | +| `System.Windows.Media.Imaging` | `Microsoft.UI.Xaml.Media.Imaging` (UI) / `Windows.Graphics.Imaging` (processing) | +| `System.Windows.Input` | `Microsoft.UI.Xaml.Input` | +| `System.Windows.Data` | `Microsoft.UI.Xaml.Data` | +| `System.Windows.Threading` | `Microsoft.UI.Dispatching` | +| `System.Windows.Interop` | `WinRT.Interop` | + +### Critical API Replacements + +| WPF | WinUI 3 | Notes | +|-----|---------|-------| +| `Dispatcher.Invoke()` | `DispatcherQueue.TryEnqueue()` | Different return type (`bool`) | +| `Dispatcher.CheckAccess()` | `DispatcherQueue.HasThreadAccess` | Property vs method | +| `Application.Current.Dispatcher` | Store `DispatcherQueue` in static field | See [Threading](./references/threading-and-windowing.md) | +| `MessageBox.Show()` | `ContentDialog` | Must set `XamlRoot` | +| `DynamicResource` | `ThemeResource` | Theme-reactive only | +| `clr-namespace:` | `using:` | XAML namespace prefix | +| `{x:Static props:Resources.Key}` | `x:Uid` or `ResourceLoader.GetString()` | .resx → .resw | +| `DataType="{x:Type m:Foo}"` | Remove or use code-behind | `x:Type` not supported | +| `Properties.Resources.MyString` | `ResourceLoaderInstance.ResourceLoader.GetString("MyString")` | Lazy-init pattern | +| `Application.Current.MainWindow` | Custom `App.Window` static property | Must track manually | +| `SizeToContent="Height"` | Custom `SizeToContent()` via `AppWindow.Resize()` | See [Windowing](./references/threading-and-windowing.md) | +| `MouseLeftButtonDown` | `PointerPressed` | Mouse → Pointer events | +| `Pack URI (pack://...)` | `ms-appx:///` | Resource URI scheme | +| `Observable` (custom base) | `ObservableObject` + `[ObservableProperty]` | CommunityToolkit.Mvvm | +| `RelayCommand` (custom) | `[RelayCommand]` source generator | CommunityToolkit.Mvvm | +| `JpegBitmapEncoder` | `BitmapEncoder.CreateAsync(JpegEncoderId, stream)` | Async, unified API | +| `encoder.QualityLevel = 85` | `BitmapPropertySet { "ImageQuality", 0.85f }` | int 1-100 → float 0-1 | + +### NuGet Package Migration + +| WPF | WinUI 3 | +|-----|---------| +| `Microsoft.Xaml.Behaviors.Wpf` | `Microsoft.Xaml.Behaviors.WinUI.Managed` | +| `WPF-UI` (Lepo) | Remove — use native WinUI 3 controls | +| `CommunityToolkit.Mvvm` | `CommunityToolkit.Mvvm` (same) | +| `Microsoft.Toolkit.Wpf.*` | `CommunityToolkit.WinUI.*` | +| (none) | `Microsoft.WindowsAppSDK` | +| (none) | `Microsoft.Windows.SDK.BuildTools` | +| (none) | `WinUIEx` (optional, for window helpers) | +| (none) | `CommunityToolkit.WinUI.Converters` | + +### XAML Syntax Changes + +| WPF | WinUI 3 | +|-----|---------| +| `xmlns:local="clr-namespace:MyApp"` | `xmlns:local="using:MyApp"` | +| `{DynamicResource Key}` | `{ThemeResource Key}` | +| `{x:Static Type.Member}` | `{x:Bind}` or code-behind | +| `{x:Type local:MyType}` | Not supported | +| `` / `` | `VisualStateManager` | +| `{Binding}` in `Setter.Value` | Not supported — use `StaticResource` | +| `Content="{x:Static p:Resources.Cancel}"` | `x:Uid="Cancel"` with `.Content` in `.resw` | +| `` / `` (WPF-UI) | Native `` / `