dotnet-modernizer — A Claude Code Plugin That Scores Your .NET Framework to .NET 10 Migration

Why this exists

.NET 8 and .NET 9 both leave support in November 2026, which makes .NET 10 LTS (supported through November 2028) the only sensible landing zone for a migration that starts now. Most teams with a .NET Framework estate don't have a current-state assessment, and producing one by hand takes weeks of reading .csproj files, grepping for System.Web and checking NuGet packages one by one.

dotnet-modernizer turns that into a single command inside Claude Code. Point it at a legacy solution and it returns a scored, prioritised migration backlog in minutes — then drafts the first fixes on request.

What it does

1. Inventories every project in the solution — SDK-style vs legacy .csproj, target framework, project type and dependency graph.
2. Detects removed and incompatible APIs with Roslyn semantic analysis: System.Web, WCF contracts, BinaryFormatter, .NET Remoting, EnterpriseServices, AppDomain.CreateDomain and more.
3. Checks every NuGet reference for .NET 10 compatibility.
4. Scores and orders the work into a migration backlog with quick-win, moderate and complex tiers.
5. Writes the report — executive summary, migration order, per-project findings with file:line references, and the decision points that need human judgment.

Architecture

The plugin has two layers. Inside Claude Code, the /analyze-migration command hands off to a read-only migration-analyst subagent, while a separate codemod-writer subagent applies fixes. Underneath, a C# MCP server on net10.0 — built on the official ModelContextProtocol package — does the analysis.

Four narrow MCP tools, not one big one

• scan_project_structure — parses .sln and .csproj files.
• find_breaking_apis — runs a Roslyn semantic model over the source.
• analyze_nuget_compat — checks packages against an offline catalog and the NuGet flat-container API.
• estimate_migration_effort — applies the scoring model to the combined results.

Each tool returns a structured, JSON-serialisable record, never free-form prose, so the agent composes them: scan first, then per-project API and package analysis, then scoring. Narrow tools keep each output small enough to reason over, let the agent skip work that doesn't apply, and keep failures local — a malformed .csproj fails one call, not the whole assessment.

Semantic analysis, not regex

Regex over source text can't tell the System.Web.HttpContext API from the string literal "System.Web", misses using-aliases and false-positives on comments. Detection is two-level: semantic matching on the full metadata name where the symbol resolves, and a syntactic fallback (qualified names and using-directives, aliases expanded) where it can't — legacy net472 code rarely compiles on the analysis machine because its reference assemblies are missing. Both levels work on syntax and symbol nodes only, so strings and comments can never produce findings.

Honest about uncertainty

NuGet compatibility is decided in layers: an offline catalog of the usual legacy suspects first, then live package metadata (a package whose latest version targets netstandard2.x or net5.0+ is consumable from net10.0), and finally unknown. It never guesses when the network is down and the catalog is silent.

Subagents with opposite tool grants

migration-analyst runs the full assessment in its own context window, so scanning a 40-project solution doesn't flood the main conversation — only the finished report comes back. It is read-only by construction: the four MCP tools plus Read, with no Write, Edit or Bash. codemod-writer is the inverse — Read, Edit, Write and dotnet build/dotnet test, but none of the analysis tools. Analysis can't mutate; mutation can't wander.

Hooks as a hard safety boundary

A PreToolUse hook blocks any Write or Edit that resolves outside the project root — path-normalised and traversal-resolved, so ..\..\ tricks don't work. A PostToolUse hook runs dotnet format whitespace on touched .cs files, so formatting never depends on the model remembering to do it.

The scoring model

Each project gets a score and a tier: quick-win (≤ 4), moderate (≤ 12) or complex (above 12).

• Base score by project type — class library or test project 1, console app 2, System.Web app 8, WCF service 10.
• +3 per blocker API family — 40 usages of System.Web.Mvc are one problem, not forty.
• +1 per warning API family — a known mechanical replacement exists.
• +2 per incompatible package and +0.5 per package that needs an upgrade.
• +1 flat for a legacy-style .csproj — SDK-style conversion is real but bounded.
• × (1 + 0.1 per dependent project) — churn in a widely referenced project ripples into every dependent's build.

The weights live in a single ScoringWeights.cs file as pure data, so the model can be tuned without touching estimation code. Call-site counts deliberately don't multiply the score: the number of distinct problem families predicts calendar time, not the amount of typing.

Sample result

Against the bundled test-fixtures/LegacyShop solution — four synthetic .NET Framework 4.7.2 projects — the analyst returns a total effort score of 44.5 and this order:

1. LegacyShop.Utils — quick-win (2.1). No breaking APIs, no package issues.
2. LegacyShop.Core — moderate (6.4). .NET Remoting is gone on .NET 10; the order channel needs IPC or gRPC.
3. LegacyShop.Web — complex (19). System.Web / ASP.NET MVC 5 doesn't exist on .NET 10; the web layer moves to ASP.NET Core.
4. LegacyShop.Services — complex (17). The WCF server stack needs CoreWCF or a gRPC/REST rewrite.

Recommended approach: modernise the two libraries first to build confidence, then tackle the website and the service, each of which needs a technology decision before work begins.

Quick start

Prerequisites: Claude Code and the .NET 10 SDK.

# Add the repo as a marketplace and install the plugin
/plugin marketplace add pravinharchandani/dotnet-modernizer
/plugin install dotnet-modernizer

# Assess your own solution...
/analyze-migration C:\src\YourLegacyApp\YourLegacyApp.sln

# ...or try it on the bundled fixture
/analyze-migration test-fixtures/LegacyShop

Roadmap

• Config-file transforms — web.config to appsettings.json and Program.cs equivalents, as a codemod the writer agent can apply.
• Solution-wide codemod batches — apply one finding family, such as every BinaryFormatter usage, across the whole solution in one reviewed batch.
• CI mode — run the analysis headless in a pipeline and fail the build when new Framework-only API usage appears, so a migration in progress can't regress.