| name | source-migration-avalonia-winui-uno |
| description | Use when an agent needs to migrate, analyze, plan, stage, or compose Avalonia source code toward WinUI 3 or Uno using the MigrateToWinUI repository tooling. Triggers on Avalonia .axaml, Avalonia project files, AW2U diagnostics, WinUI/Uno target shell generation, Avalonia safe rewrites, or Avalonia migration reports. |
Avalonia Source Migration to WinUI/Uno
Use this skill for source-available Avalonia projects, directories, solutions, or single files. Keep the migration deterministic: analyze first, preview safe rewrites, preserve manual-review blockers, and stage or compose into a target project before changing source files.
For agent-run analyzer/code-fix loops, prefer:
python3 plugins/migrate-to-winui-agent/scripts/analyzer_codefix_workflow.py <input> --source avalonia --target both --mode preview --bundle
python3 plugins/migrate-to-winui-agent/scripts/analyzer_codefix_workflow.py <input> --source avalonia --target both --mode apply --rules AW2U0101 AW2U0102 --rounds 2 --bundle
Repo Entry Points
- CLI project:
src/MigrateToWinUI.Cli/MigrateToWinUI.Cli.csproj
- Core migration models:
src/MigrateToWinUI.Core/MigrationModels.cs
- C# rules:
src/MigrateToWinUI.CSharp/CSharpMigrationEngine.cs
- XAML rules:
src/MigrateToWinUI.Xaml/XamlMigrationEngine.cs
- Avalonia analyzer/code fix:
src/MigrateToWinUI.Analyzers/AvaloniaMigrationAnalyzer.cs, src/MigrateToWinUI.Analyzers/AvaloniaMigrationCodeFixProvider.cs
- Default rule pack:
rulepacks/avalonia-to-winui.v1.json
- CLI contract:
specs/001-migration-core/contracts/cli.md
- Report schema:
specs/001-migration-core/contracts/report.schema.json
- Rule taxonomy and coverage semantics:
specs/001-migration-core/remaining-work.md
- Fixtures:
samples/AvaloniaInput, samples/FeatureCorpusInput
Workflow
-
Confirm scope and source framework.
- Use
--source avalonia when the source is known Avalonia.
- Use
--source auto only for discovery; if MTW0001 or mixed evidence appears, rerun per project or pass an explicit source.
- Pick
--target winui3, --target uno, or --target both before interpreting target-specific findings.
-
Inventory and report findings.
dotnet run --project src/MigrateToWinUI.Cli -- analyze <input> --source avalonia --target both --format json --report artifacts/migration-report.json
dotnet run --project src/MigrateToWinUI.Cli -- detail <input> --source avalonia --target both --format md --out artifacts/migration-dashboard.md
dotnet run --project src/MigrateToWinUI.Cli -- plan <input> --source avalonia --target both --format md --out artifacts/migration-plan.md
Expected outputs:
analyze: report JSON or stdout with inventory, findings, and rewritePlans.detail: dashboard rollups by severity, category, rule, file, manual blockers, safe rewrites, and asset mappings.plan: phased summary with safe rewrite groups, manual-review families, target notes, validation steps, and remediation links.
-
Inspect rule impact before editing.
dotnet run --project src/MigrateToWinUI.Cli -- rules list
dotnet run --project src/MigrateToWinUI.Cli -- rules explain AW2U0301
dotnet run --project src/MigrateToWinUI.Cli -- rules catalog rulepacks --format md
-
Preview safe rewrites.
dotnet run --project src/MigrateToWinUI.Cli -- convert <input> --source avalonia --target both --dry-run --preview artifacts/rewrite-preview.txt --report artifacts/preview-report.json
Treat only safety: Safe rewrite plans as mechanically applicable. Review and Manual findings must remain visible for explicit target design.
-
Stage or compose instead of mutating source when the goal is a target project.
dotnet run --project src/MigrateToWinUI.Cli -- compose <input> --source avalonia --target both --out artifacts/target-projects --project-name MigratedApp --clean --validate
Expected outputs include generated Uno/WinUI shell files, copied converted source, .axaml to .xaml target renames, copied assets, skipped manual-review rewrites, and optional validation results. If manual-review blockers are expected and approved, add --allow-manual-review; otherwise let composition fail.
-
Apply to the original workspace only when the user explicitly wants source mutation.
dotnet run --project src/MigrateToWinUI.Cli -- apply <input> --source avalonia --target both --rules AW2U0101 AW2U0102 AW2U0201
dotnet run --project src/MigrateToWinUI.Cli -- verify <input> --source avalonia --target both
Common Avalonia Rule Families
- Project/bootstrap:
AW2U0001-AW2U0005
- XAML and namespace rewrites:
AW2U0101, AW2U0102
- Bindings:
AW2U0201, AW2U0202
- Property system and custom controls:
AW2U0301-AW2U0305
- Styles/resources/templates:
AW2U0401, AW2U0501
- Platform, lifetime, command/input:
AW2U0601, AW2U0602
- Rendering:
AW2U0701
- Unsupported/manual umbrella:
AW2U0901
Guardrails
- Do not infer a target service abstraction for storage, launcher, clipboard, dialogs, windows, drag/drop, screens, native menus, rendering, or custom controls. Keep these as manual-review findings unless a target design exists.
- Do not treat diagnostic-only JSON rule packs as safe rewrite automation.
- Do not apply rewrites from a report generated against a different input, source framework, target profile, or rule-pack set.
- Do not hide manual-review diagnostics after safe rewrites; rerun
analyze or verify after any mutation.
- Do not overwrite generated target shells unless the command includes
--overwrite or composition uses an approved clean output directory.
- On non-Windows hosts,
verify performs static verification; WinUI-only build validation is Windows-only.
Validation
Run focused tests when changing the tooling or rules:
dotnet test --filter "FullyQualifiedName~Avalonia"
dotnet test --filter "FullyQualifiedName~XamlMigrationEngineTests|FullyQualifiedName~CSharpMigrationEngineTests|FullyQualifiedName~TargetProjectStagingServiceTests"
Before delivering a migration result, report the command exit code meaning:
0: no error-level findings.1: usage, IO, bad image, or rule-pack failure.2: verification/validation failures or error-level findings.3: API coverage failure due to unclassified source APIs.
