.NET Framework to .NET Upgrade Checklist
A readiness checklist for moving from .NET Framework to modern .NET. It addresses API gaps, project and config formats, WebForms re-architecture, EF Core, and staged cutover.
When to Use This Checklist
Use this checklist when moving an application from .NET Framework to modern .NET (.NET 8 or 9). The two runtimes differ in project format, configuration, hosting model, and available APIs. Some components, notably WebForms and parts of System.Web, have no direct port and require re-architecture. A structured readiness pass prevents mid-migration surprises.
How to Use This Checklist
Begin with the .NET Upgrade Assistant and Portability Analyzer to get an API gap report. Convert to SDK-style projects early because the rest of the tooling assumes it. Catalog NuGet packages that lack compatible versions and decide on replacements. Migrate configuration to appsettings.json and rebuild the middleware and dependency-injection pipeline on ASP.NET Core. Keep a green baseline test run for comparison and ship the cutover behind blue-green with a clear rollback.
EF Core and containerization items are optional but common companions to this migration.
What Good Looks Like
A finished migration runs on modern .NET with SDK-style projects, JSON configuration, and an ASP.NET Core hosting pipeline. Every dependency has a compatible version, Windows-only APIs are removed or shimmed, and the test suite is green. Dependency scans are clean and the app can run cross-platform in a container if desired. Cutover is staged with a documented rollback.
Common Pitfalls
The biggest trap is assuming WebForms has a port; it does not, and that work is often the critical path. Teams also miss transitive NuGet packages that block the upgrade, or keep web.config patterns that no longer apply. Migrating without a baseline test run hides regressions, and a big-bang cutover removes the ability to recover quickly.
Related Resources
See the twelve-factor app for configuration and the test pyramid for your safety net. Blue-green deployment supports safe cutover and static application security testing in CI covers the dependency scan.