| name | source-migration-wpf-winui-uno |
| description | Use when an agent needs to migrate, analyze, plan, stage, or compose WPF source code toward WinUI 3 or Uno using MigrateToWinUI. Triggers on WPF .xaml, System.Windows, UseWPF, ApplicationDefinition, WP2U diagnostics, WPF-to-WinUI rule packs, WPF safe rewrites, and WPF migration reports. |
WPF Source Migration to WinUI/Uno
Use this skill for source-available WPF projects, directories, solutions, or files. The WPF lane reuses the same migration report, rewrite plan, rule-pack, validation, and target-composition models as the Avalonia lane, but diagnostics use WP2U ids and must not reuse or renumber AW2U ids.
For agent-run analyzer/code-fix loops, prefer:
python3 plugins/migrate-to-winui-agent/scripts/analyzer_codefix_workflow.py <input> --source wpf --target both --mode preview --bundle
python3 plugins/migrate-to-winui-agent/scripts/analyzer_codefix_workflow.py <input> --source wpf --target uno --mode apply --rules WP2U0101 --rounds 2 --bundle
Repo Entry Points
- CLI project:
src/MigrateToWinUI.Cli/MigrateToWinUI.Cli.csproj
- WPF analyzer rules:
src/MigrateToWinUI.Analyzers/AvaloniaMigrationAnalyzer.cs
- WPF C# rules:
src/MigrateToWinUI.CSharp/CSharpMigrationEngine.cs
- WPF XAML rules:
src/MigrateToWinUI.Xaml/XamlMigrationEngine.cs
- Project rules:
src/MigrateToWinUI.Core/Projects/ProjectMigrationRules.cs
- Default WPF rule pack:
rulepacks/wpf-to-winui.v1.json
- CLI contract:
specs/001-migration-core/contracts/cli.md
- WPF diagnostic families:
specs/001-migration-core/spec.md
- Rule taxonomy and coverage semantics:
specs/001-migration-core/remaining-work.md
- Fixtures:
samples/WpfInput, samples/WpfNetFrameworkInput, samples/MixedSourceInput
Workflow
-
Confirm source evidence.
- Prefer
--source wpf for known WPF projects.
- Use
--source auto only to classify unknown workspaces; mixed Avalonia/WPF evidence must become a diagnostic, not an implicit choice.
- For mixed-source samples or monorepos, analyze each project with explicit
--source.
-
Generate reports.
dotnet run --project src/MigrateToWinUI.Cli -- analyze <input> --source wpf --target both --format json --report artifacts/wpf-migration-report.json
dotnet run --project src/MigrateToWinUI.Cli -- detail <input> --source wpf --target both --format md --out artifacts/wpf-dashboard.md
dotnet run --project src/MigrateToWinUI.Cli -- plan <input> --source wpf --target both --format md --out artifacts/wpf-plan.md
Expected outputs:
WP2U findings for project bootstrap, WPF namespaces, bindings, dependency properties, routed events, triggers/resources, windowing/dialogs, commands/input, rendering, documents/media, interop, and unsupported/manual review.- Safe rewrite plans only where the rule is explicitly marked
Safe.
- Manual-review blockers for behaviors that require target design.
-
Inspect WPF rules before deciding what to automate.
dotnet run --project src/MigrateToWinUI.Cli -- rules list
dotnet run --project src/MigrateToWinUI.Cli -- rules explain WP2U0101
dotnet run --project src/MigrateToWinUI.Cli -- rules catalog rulepacks --format md
-
Preview rewrites.
dotnet run --project src/MigrateToWinUI.Cli -- convert <input> --source wpf --target both --dry-run --preview artifacts/wpf-rewrite-preview.txt --report artifacts/wpf-preview-report.json
Review the preview for namespace/base-type substitutions and verify that no manual-review diagnostic is being presented as an automated edit.
-
Compose target project output when the goal is a migrated tree.
dotnet run --project src/MigrateToWinUI.Cli -- compose <input> --source wpf --target uno --out artifacts/wpf-target-projects --project-name MigratedWpfApp --clean --validate
dotnet run --project src/MigrateToWinUI.Cli -- compose <input> --source wpf --target winui3 --out artifacts/wpf-winui --project-name MigratedWpfApp --clean --validate
Composition copies converted source into generated shells, preserves manual-review gates, maps assets/resources only when the tool has explicit entries, and runs static or target validation as available.
-
Mutate original source only when explicitly requested.
dotnet run --project src/MigrateToWinUI.Cli -- apply <input> --source wpf --target both --rules WP2U0101 WP2U0601
dotnet run --project src/MigrateToWinUI.Cli -- verify <input> --source wpf --target both
WPF Diagnostic Families
- Project, SDK, target framework, app bootstrap:
WP2U0001-WP2U0099
- XAML controls/layout and namespace/type mappings:
WP2U0101-WP2U0199
- Bindings, converters, validation, templates:
WP2U0201-WP2U0299
- Dependency properties, metadata, routed events:
WP2U0301-WP2U0399
- Styles, templates, triggers, resources, visual states:
WP2U0401-WP2U0599
- Platform services, windowing, dialogs, navigation:
WP2U0601-WP2U0669
- Commands, input bindings, gestures, focus:
WP2U0670-WP2U0699
- Rendering, drawing, media, animation, composition:
WP2U0701-WP2U0799
- Documents, printing, media, imaging, interop:
WP2U0801-WP2U0899
- Unsupported/manual/out-of-scope:
WP2U0901-WP2U0999
Guardrails
- Preserve WPF-specific semantics.
System.Windows.DependencyProperty, FrameworkPropertyMetadata, coercion, inheritance, routed events, command routing, resources, triggers, HwndHost, WindowsFormsHost, printing, media, and documents need explicit target review unless the rule marks a narrow safe rewrite.
- Do not translate WPF triggers or resource precedence mechanically into WinUI visual states without a pattern and validation.
- Do not assume Uno support equals WinUI 3 support for interop, windowing, media, documents, or platform APIs.
- Do not run
apply against a broad solution until a preview has been reviewed and rule ids have been selected.
- Do not remove
WP2U findings from reports just because the code compiles; findings are migration decisions, not only compiler errors.
Validation
Run focused tests when changing WPF migration behavior:
dotnet test --filter "FullyQualifiedName~Wpf"
dotnet test --filter "FullyQualifiedName~AnalyzerTests|FullyQualifiedName~AnalyzerCodeFixTests|FullyQualifiedName~ProjectMigrationEngineTests"
Exit code expectations:
0: no error-level findings.1: CLI usage, IO, bad image, or rule-pack failure.2: verification/validation failed or error-level findings exist.3: API coverage failed because scanned source APIs remain unclassified.
