| name | legacy-migration-analyzer |
| audience | team |
| description | Analyze .NET Framework to .NET 10 migration paths. Use when assessing legacy codebases for modernization, identifying breaking changes, and planning incremental migration strategies. Also
|
Legacy Migration Analyzer
"The best migrations are the ones you don't notice. Incremental, tested, and invisible to the end user."
-- Immo Landwerth, .NET Platform Compatibility Lead
Core Philosophy
This skill analyzes legacy .NET Framework codebases and produces actionable migration plans to .NET 10. It does NOT perform the migration itself — it assesses, quantifies risk, and creates a phased plan that humans and other skills execute.
Non-negotiable constraints:
- Assess before acting — Scan the codebase, catalog dependencies, and score risk before recommending any approach.
- Incremental migration over big-bang rewrites — The strangler fig pattern and project-by-project migration succeed. Full rewrites fail.
- Preserve business logic unchanged — Migration changes infrastructure, not behavior.
- Dependencies are the real blockers — Third-party NuGet packages, COM interop, and Windows-specific APIs are where migrations stall. Identify these first.
- Every recommendation must cite evidence — Reference specific files, namespaces, NuGet packages, or API calls. Vague guidance is not actionable.
The full 10-row domain principle table, AI discipline rules, and the anti-pattern catalog live in
references/migration-decision-matrix.md.
Knowledge Base Lookups
| Query | When to Call |
|---|
search_knowledge(".NET Framework to .NET 8 10 migration breaking changes") | At SCAN phase — load authoritative breaking changes catalog |
search_knowledge(".NET Upgrade Assistant compatibility analyzer tool") | During ASSESS phase — confirms tooling commands and output |
search_knowledge("Entity Framework 6 EF Core migration differences lazy loading") | When assessing data access layer |
search_knowledge("ASP.NET MVC to ASP.NET Core migration web.config appsettings") | When analyzing web projects |
search_knowledge("NuGet package compatibility .NET Standard target framework") | During dependency audit |
search_knowledge("strangler fig pattern incremental migration legacy modernization") | During PLAN phase |
Search at the start of SCAN and ASSESS phases. Every risk finding must cite its authoritative source.
Workflow
Analysis proceeds through four phases: SCAN (codebase inventory) → ASSESS (risk scoring) → PLAN (migration roadmap) → VALIDATE (feasibility confirmation). Do not skip phases or reorder them.
Approach selection: Hard blockers (WCF duplex, COM-heavy, undocumented protocols) that can be isolated → strangler fig; that cannot be isolated → hybrid (keep blocked components on .NET Framework behind API gateway). Single monolith under 50K LOC → in-place upgrade. All NuGet dependencies compatible → project-by-project in-place. Incompatible packages with replacements → replace packages first, then upgrade. No clean path → strangler fig for affected projects.
Phase 1: SCAN — Codebase Inventory
- Run
upgrade-assistant analyze <SolutionPath> --target-tfm net10.0
- Catalog all projects (class libraries, ASP.NET MVC/Web API, WCF, Windows Services, Console, WinForms/WPF)
- Enumerate all NuGet package references and versions
- Identify
System.Web namespace usages, COM interop, and P/Invoke declarations
- Catalog all
web.config/app.config sections with custom configuration
- Catalog authentication mechanisms, IIS-specific features, and Windows-specific APIs
- Map project-to-project references and dependency graph
Analysis commands, upgrade tooling, complexity classification, and the SDK-style .csproj target
are in references/breaking-changes-catalog.md (.NET Framework Upgrade Specifics).
Phase 2: ASSESS — Risk Scoring
- Cross-reference each NuGet package against Breaking Changes Catalog and Breaking Changes 4.x to 10
- Score each project using the Migration Decision Matrix
- Consult Package Replacement Map for NuGet migration paths
- Consult API Replacement Patterns for code-level migration patterns
- For web projects, consult ASP.NET to Blazor Patterns
- Classify each breaking change: Blocker, High, Medium, Low
- Calculate effort estimates per project and aggregate into overall risk score
Phase 3: PLAN — Migration Roadmap
Order projects by dependency graph (leaf nodes first). Group into 2-4 week phases. Assign risk levels and rollback strategies. Define validation criteria per phase.
Standard phase order: Phase 0 (prerequisites: characterization tests, NuGet updates, extract interfaces) → Phase 1 (class libraries with no framework dependencies; multi-target if needed: net48;net10.0) → Phase 2 (data access layer; coordinate with ef-migration-manager) → Phase 3 (business logic layer) → Phase 4 (presentation/API layer; ASP.NET Core, gRPC) → Phase 5 (infrastructure; Worker Services, Kestrel, CI/CD).
Phase 4: VALIDATE — Feasibility Confirmation
- Walk the plan with the development team; verify effort estimates against capacity
- Confirm all hard blockers have mitigation strategies
- Validate rollback is possible at each phase boundary
- Confirm deployment constraints are respected
- Get stakeholder sign-off on timeline and risk acceptance
When the Upgrade Assistant, a NuGet package, WCF, or System.Web blocks progress, follow the
recovery procedures in references/api-replacement-patterns.md (Error Recovery).
State Block
<migration-analysis-state>
step: [SCAN | ASSESS | PLAN | VALIDATE]
source_framework: [e.g., ".NET Framework 4.8"]
target_framework: [e.g., ".NET 10"]
breaking_changes_found: [count]
risk_level: [low | medium | high | critical]
last_action: [what was just done]
next_action: [what should happen next]
blockers: [any issues]
</migration-analysis-state>
A worked example of a populated state block is in references/migration-decision-matrix.md.
Output Template
The Migration Inventory Report template (metrics, package compatibility, breaking changes by
category, hard blockers, risk score) is in references/migration-decision-matrix.md
(Output Report Template).
Integration with Other Skills
ef-migration-manager — When the analysis identifies EF6 usage, coordinate for the EF6→EF Core migration. The database schema migration is often the riskiest part and should be planned and tested independently.dotnet-vertical-slice — When the plan calls for decomposing a monolithic application, use this skill to structure new .NET 10 projects as vertical slices. Especially relevant in strangler fig migrations.nuget-package-scaffold — When shared libraries need to be extracted or multi-targeted (net48;net10.0) during the transition period.
Reference Files
