dotnet-upgrade-scan 0.1.2

dotnet-upgrade-scan

A free, open-source, deterministic assessment CLI for planning .NET Framework → modern .NET upgrades. Point it at a legacy solution; get a dependency-ordered upgrade plan with per-project effort estimates — without modifying a single file.

Why this exists. Microsoft deprecated the free .NET Upgrade Assistant in favor of a paid GitHub Copilot modernization agent. AWS closed its free Porting Assistant to new customers. The community lost every free, deterministic option for upgrade assessment. This project is the community continuation.

What it tells you

Scanning a solution produces a report that answers four questions:

1. Where are you? Target framework, project style (SDK vs. legacy), and language for every project — even ones that no longer build.
2. In what order? The dependency-ordered upgrade sequence (leaves first), with circular references reported as groups instead of crashes.
3. What will block you? NuGet packages incompatible with modern .NET (with known replacements), and blocker API usages per project — WCF, WebForms, System.Web, AppDomain, Remoting, COM interop, and more.
4. How much work is it? A rough S / M / L / XL effort score per project, computed from a documented, tunable heuristic.

Principles

• Deterministic. Same input + same tool version → byte-identical report. No AI in the core, no heuristic drift.
• Read-only. The scanner never writes into your source tree — enforced by an automated test, not a promise.
• No network, no telemetry. Ever. Scans run fully offline. Nothing is collected, phoned home, or updated behind your back.
• Every claim is traceable. Each finding cites a rule ID (PKG0042, API0117) backed by a YAML rule file you can read, dispute, and improve.
• Never dies mid-scan. Analysis degrades gracefully per project: full design-time build → syntax-only → raw manifest parsing. A broken project on disk still yields useful facts.
• Cross-platform. Windows, Linux, macOS. No Visual Studio or full MSBuild install required.

Status

The full v1 pipeline works end to end: load → tiered analysis → upgrade order → rules matching → effort scoring → report. The main open work is growing the rules database beyond its seed set.

Quick start

dotnet tool install -g dotnet-upgrade-scan
upgrade-scan path/to/YourSolution.sln --output report.md

Requires .NET 8 or later. To build from source instead:

git clone https://github.com/vericodex/dotnet-upgrade-scan.git
cd dotnet-upgrade-scan
dotnet run --project src/UpgradeScan.Cli -- path/to/YourSolution.sln --output report.md

Building from source requires the .NET 10 SDK.

The default report is Markdown: a summary table, the dependency-ordered upgrade sequence (with a Mermaid graph), and per-project findings with effort scores. An excerpt from scanning an MVC 5 fixture:

## Summary

| Project | Target framework | Style | Type | Tier | Blockers | Packages | Effort |
|---|---|---|---|---|---:|---:|---|
| Mvc5Web | net472 | Legacy | AspNetMvc | Syntactic | 2 | 2 | M |

## Mvc5Web

Effort: M (score 20)

### API findings

**web**

- [API0101] ~ System.Web — Controllers/HomeController.cs:1 — No modern equivalent; requires migration to ASP.NET Core.

For a quick look in the terminal, use --format console:

upgrade-scan — tests/fixtures/net472-two-proj
target net10.0 · rules 04f243e34a9b · 2 project(s)
╭─────────┬──────────────────┬────────┬─────────┬───────────┬──────────┬──────────┬────────╮
│ Project │ Target framework │ Style  │ Type    │ Tier      │ Blockers │ Packages │ Effort │
├─────────┼──────────────────┼────────┼─────────┼───────────┼──────────┼──────────┼────────┤
│ Lib     │ net472           │ Legacy │ Library │ Syntactic │ 0        │ 0        │ S      │
│ App     │ net472           │ Legacy │ Console │ Syntactic │ 0        │ 1        │ S      │
╰─────────┴──────────────────┴────────┴─────────┴───────────┴──────────┴──────────┴────────╯
Effort: 2×S · 0 blocker finding(s)

Options

There are also two rules subcommands: rules list enumerates every loaded rule with its ID, and rules validate [dir] checks a rules directory and exits non-zero on any error.

Exit code 0 means the scan completed (findings never affect the exit code — this is an assessment, not a gate); 1 means the scan could not run.

How it works

Each project is analyzed at the highest tier that succeeds, and the report tells you which tier produced each result:

Legacy solutions often fail design-time builds — that's the norm, not the exception, and it's why the tiered approach exists. A scan of 20 projects never dies on project 3.

VB.NET projects are detected and reported at manifest level with a "reduced analysis" note; C# gets the full tiered analysis.

Contributing

Contributions are welcome — especially to the rules database: each package/API rule is a small, self-contained YAML file in rules/, reviewable without knowing the analyzer internals. The authoring guide is docs/rules-authoring.md, and upgrade-scan rules validate checks your rule files before you open a PR.

Also valuable:

• Try it on your solution and open an issue for anything that crashes, misdetects, or surprises you — broken/exotic legacy projects are exactly the test cases this tool needs.
• Run dotnet test from the repo root; the suite must stay green and builds are warning-clean (TreatWarningsAsErrors).

Prior art & credits

This project continues ideas from tools the community lost — the .NET Upgrade Assistant (Microsoft, MIT, deprecated) and Porting Assistant for .NET (AWS, Apache-2.0, closed to new customers). See NOTICE for lineage and license provenance.

Who builds this

dotnet-upgrade-scan is built and maintained by Vericodex.

The tool tells you the shape of an upgrade: what's there, in what order, and what will block you. It deliberately stops short of telling you how long it takes or what it costs — those are judgement calls, not facts a scanner can derive. If you need a costed, sequenced migration plan with blockers triaged and a person accountable for the number, that's the work Vericodex does: vericodex.com/contact.

Bug reports and rule contributions belong in GitHub issues, not email — the tool stays free and community-supported regardless.

License

MIT © 2026 Nitin Mukherjee