.NET Version Migration Assistant

Guides incremental migration between .NET versions with breaking change detection and verification.

Stack: C#/.NET (ASP.NET Core, EF Core, NuGet)

When to Use

• Planning a .NET version upgrade (8→9, 9→10, 10→11)
• Adopting nullable reference types across a codebase
• Preparing a project for Native AOT compilation
• Assessing migration risk before committing to an upgrade

Core Principle

Migrate incrementally. One project at a time, verify at each step. Never upgrade the entire solution in one commit. Build confidence through small, verified steps.

Argument Routing

Universal Migration Steps

These apply to every .NET version upgrade:

Pre-Migration Checklist

[ ] All tests passing on current version
[ ] Dependencies checked for target version support
[ ] Binlog baseline captured (dotnet build /bl:baseline.binlog)
[ ] Git branch created for migration
[ ] CI pipeline supports new SDK version

Step-by-Step Upgrade

1. UPDATE SDK        → global.json → new SDK version
2. TARGET FRAMEWORK  → <TargetFramework>net{version}</TargetFramework> in csproj
3. PACKAGES          → Update all Microsoft.* packages to matching version
4. BUILD             → dotnet build 2>&1 | tee build-output.txt
5. FIX ERRORS        → Address compiler errors from breaking changes
6. TEST              → dotnet test — fix behavioral changes
7. INFRASTRUCTURE    → Update Dockerfile, CI/CD pipeline SDK versions
8. DEPRECATED APIS   → dotnet build /p:TreatWarningsAsErrors=true — catch obsolete usage

Upgrade Order (multi-project solutions)

1. Shared libraries (no project dependencies)
2. Domain / Core projects
3. Infrastructure / Data access
4. Application / Service layer
5. API / Web host
6. Test projects (last — they depend on everything)

After each project: dotnet build the entire solution to catch cross-project breaks.

Version Detection

# Current SDK
dotnet --version

# Current target frameworks
grep -rh '<TargetFramework>' --include="*.csproj" . | sort -u

# Global.json SDK pin
cat global.json 2>/dev/null || echo "No global.json (using latest installed SDK)"

# Installed SDKs
dotnet --list-sdks

Post-Migration Verification

After completing the migration, run the full verification loop:

1. dotnet build — clean compile
2. dotnet test — all tests pass
3. dotnet build /bl:post-migration.binlog — capture for comparison
4. Invoke dev-verification-backend --full for comprehensive checks

Rollback

If migration fails and can't be fixed in reasonable time:

# Revert all migration changes
git checkout -- .

# Or selectively revert
git checkout -- global.json
git checkout -- '*.csproj'
dotnet restore

Reference Docs

• migrate-dotnet8-to-9.md — .NET 8 → 9 breaking changes and new features
• migrate-dotnet9-to-10.md — .NET 9 → 10 breaking changes and new features
• migrate-dotnet10-to-11.md — .NET 10 → 11 (preview guidance)
• nullable-references.md — Nullable reference type adoption strategy
• aot-compatibility.md — Native AOT preparation guide