Migrate WPF to WinUI 3 with an Agent Skill

Where this fits

You're modernizing a WPF line-of-business app to WinUI 3. Your codebase has System.Windows namespaces, DataGrid, Dispatcher, and a hand-rolled MVVM framework. The manual migration checklist is long: project creation, namespace alignment, control mapping, threading updates, image handling. This skill encodes that checklist so an agent can do the audit and mechanical rewrite.

Why agents benefit

• Agents can inventory WPF-specific APIs before editing, using the PowerShell audit command, so changes are targeted.
• It maps controls correctly (DataGrid→ListView, WrapPanel→ItemsRepeater, TabControl→TabView), avoiding design regressions.
• It handles threading translation (Dispatcher→DispatcherQueue) and imaging (System.Drawing→BitmapImage) which are common build blockers.
• It converts MVVM patterns to CommunityToolkit.Mvvm, reducing manual view-model rewrites.
• It keeps migration build errors in context, letting agents fix issues iteratively instead of guessing.

Practical scenarios

Automating the initial WPF namespace audit

You ask your agent to "prepare a migration plan for the WPF app." It runs the Select-String inventory, groups results by namespace and control, and produces a report of affected files. You can review the list before any code changes.

Rewiring threading and image calls after project creation

After scaffolding a WinUI 3 project, the agent updates Dispatcher.Invoke calls to DispatcherQueue.TryEnqueue, replaces System.Drawing.Bitmap with BitmapImage, and adjusts the XAML resource lookups from DynamicResource to ThemeResource. These are the edits that often cause runtime exceptions if done piecemeal.

Fixing build errors during a namespace migration

Your migration is halfway done and the build fails on System.Windows remnants. The agent reads the errors, identifies the WPF-specific types, and applies the skill's replacement table. It also updates x:Class and RootNamespace so the output matches the existing application structure.

Add it to your agent workflow

Install the skill with:

npx skills add microsoft/win-dev-skills --skill winui-wpf-migration

Then have your agent audit the source:

Select-String -Path (Get-ChildItem -Recurse -Filter "*.cs" | Where-Object { $_.FullName -notlike "*\obj\*" }) -Pattern "System\.Windows\." | Select-Object -Property Filename, LineNumber, Line

You can also point the agent to the skill's repository for the full migration process: the skill's README documents the exact winapp new template and step-by-step alignment.

Compare before adopting

Before adding this skill, compare it with other migration approaches: check whether the GitHub repo (microsoft/win-dev-skills) has recent commits and issue activity—a stale skill may miss WinUI 3 API changes. Compare its control mapping list against your actual control usage; your app may use third-party WPF controls that need manual mapping. Also evaluate if the skill's MVVM conversion matches your existing pattern or if you are already on CommunityToolkit.Mvvm.

Why it is worth tracking

The skill is maintained by Microsoft and part of the win-dev-skills repo (407 stars), which signals community interest and a better chance of staying current with WinUI 3 releases. Track it when your team starts a WPF-to-WinUI project, and re-evaluate it after each WinUI 3 service release to see if the skill's mappings have been updated. Even if you only use the audit step, it saves time and gives your agent a precise starting point.