Many line-of-business systems still run on .NET Framework 4.8. They work, and Microsoft still supports them. This article is about deciding whether to move them to .NET 10, and how to do it without a long feature freeze or a risky big-bang release.
There is no deadline, so be clear about the reason
.NET Framework 4.8 and 4.8.1 are Windows components. Microsoft's lifecycle policy ties their support to the lifecycle of the Windows version they are installed on, so there is no fixed end-of-support date. Microsoft has also said 4.8 is the last major version of .NET Framework: it receives security and reliability fixes, not new features.
That means the case for migrating is a business case, not a compliance one. The usual reasons are:
- Hosting cost and options. .NET Framework applications need Windows servers and IIS. Modern .NET runs on Linux and in containers, which widens the choice of hosting.
- Hiring and retention. Fewer engineers want to work on Web Forms, WCF services and
packages.configprojects. - New libraries. A growing number of SDKs, including those for AI services, target modern .NET only.
- Performance and tooling. Modern .NET receives runtime and ASP.NET Core performance work every year; .NET Framework does not.
If an application changes rarely, is due for replacement, or none of these reasons apply, leaving it on .NET Framework can be the right decision. Write that decision down and revisit it yearly.
Phase 0: assessment
Start by listing every project in the solution and its type: ASP.NET MVC 5, Web API 2, Web Forms, WCF service, Windows service, WinForms or WPF, class library. Each type has a different path:
- MVC and Web API controllers port to ASP.NET Core with moderate changes.
- Web Forms has no equivalent in ASP.NET Core; those pages are rebuilt in Razor Pages, MVC or Blazor.
- WCF services need a decision of their own; see WCF in 2026: CoreWCF, gRPC or REST.
- Windows services become worker services using the generic host.
Then look for technologies that are not available on modern .NET, such as creating additional AppDomains, .NET Remoting and Code Access Security. Code that depends on them needs redesign, not porting.
For tooling, Microsoft now points to the GitHub Copilot app modernization agent, which analyses a solution, proposes an upgrade plan and automates some code changes. The older .NET Upgrade Assistant is deprecated but still documented for teams without Copilot access. Treat any tool's output as a starting point: it finds the mechanical changes well, and it cannot tell you which behaviour your users rely on.
Dependency analysis
For each NuGet package, record whether a version exists that targets .NET Standard 2.0 or modern .NET, and what replaces it if not. Also record COM components, native DLLs, third-party UI control suites and anything installed in the GAC. These are the items most likely to change an estimate significantly, so find them early.
Phase 1: build a test harness before changing code
Most legacy applications have little automated test coverage. Unit tests written now would test the code you are about to change, so start one level up: characterisation tests over HTTP. Record what the current application returns for a representative set of requests (pages, API calls, file downloads, error cases) and assert that the migrated application returns the same thing.
Because these tests talk HTTP, the same suite runs against the old and the new application. Add a database reset step so each run starts from known data. This harness is what makes the later phases safe.
Phase 2: move shared libraries first
Convert class libraries to SDK-style projects and make them multi-target, or target .NET Standard 2.0, so both the old application and the new one can use them. Microsoft's migration guide recommends upgrading libraries in dependency order: the libraries nothing else depends on come first.
<PropertyGroup>
<TargetFrameworks>net48;net10.0</TargetFrameworks>
</PropertyGroup>
Where a library uses System.Web types such as HttpContext, the System.Web adapters described below let it compile against both frameworks with fewer changes.
Phase 3: strangler fig with YARP
For a production web application, Microsoft recommends incremental migration, an implementation of the strangler fig pattern. A new ASP.NET Core application is deployed in front of the existing one. It serves the routes that have been migrated and forwards everything else to the old application using YARP, Microsoft's reverse proxy library. Users see one site throughout.
The System.Web adapters (Microsoft.AspNetCore.SystemWebAdapters) fill the gaps during the transition. They provide System.Web-style APIs on ASP.NET Core and can share session state and authentication with the old application through a "remote app" connection. A minimal front-end setup looks like this:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddSystemWebAdapters(); // add remote session/auth here as needed
builder.Services.AddHttpForwarder();
var app = builder.Build();
app.UseRouting();
app.UseAuthorization();
app.UseSystemWebAdapters();
app.MapDefaultControllerRoute();
// Anything not handled above goes to the legacy ASP.NET application.
app.MapForwarder("/{**catch-all}", app.Configuration["LegacyAppUrl"]!)
.Add(static b => ((RouteEndpointBuilder)b).Order = int.MaxValue);
app.Run();
Minimal illustrative example. Follow Microsoft's incremental migration guide for remote session and authentication configuration.
Migrate in vertical slices: one feature area at a time, including its controllers, views and data access. Run the characterisation tests for that area against the new application before switching its routes. Low-risk, read-heavy areas make good first slices because they let the team learn the pattern before touching anything that writes data.
Phase 4: data access, from EF6 to EF Core
Entity Framework 6 runs on modern .NET (from EF 6.3 onwards), so you do not have to change the runtime and the data access layer in the same release. A sensible order is:
- Run the existing EF6 code on .NET 10 behind the new application.
- Port the model to EF Core one bounded area at a time.
- Remove EF6 once nothing references it.
EF Core is not a drop-in replacement. EDMX designer models are not supported, lazy loading is opt-in, and some LINQ queries translate differently or fail if they cannot be translated to SQL. Microsoft's porting guide lists the differences. Write query-level tests against a real database for the areas you port, and compare generated SQL for the queries that matter most for performance.
Phase 5: authentication
During the transition, a signed-in user must stay signed in when a request moves between the old and new applications. There are two common approaches:
- Remote authentication through the System.Web adapters, where the new application asks the old one who the user is.
- Shared cookies, where both applications read the same authentication cookie using compatible data protection settings. See sharing authentication cookies among ASP.NET apps.
Avoid changing identity provider (for example moving from Forms authentication to Microsoft Entra ID) in the same release as the runtime migration, unless you have to. Two simultaneous changes to sign-in make faults much harder to diagnose.
Phase 6: deployment
- Side by side. On IIS, the new application runs in its own application pool set to "No Managed Code", with the .NET 10 Hosting Bundle installed. The legacy application stays where it is.
- Configuration. Move settings from
web.configtoappsettings.json, environment variables or a secret store. Do not copy secrets into the new configuration files. - Observability. Use the same correlation ID across both applications and the proxy, so a single user request can be traced end to end.
Rollback at every step
The strangler fig approach makes rollback a routing change. If a migrated area misbehaves, point its routes back at the legacy application and redeploy the front end; no data moves. To keep that option open:
- Keep the legacy code for an area until the new version has run in production for an agreed period.
- Use an expand-and-contract approach for database changes: add new columns and tables first, remove old ones only after both applications have stopped using them.
- Put route switching behind configuration or feature flags so it does not require a code change.
When you are done
The migration is finished when the forwarder no longer receives traffic. Log forwarded requests throughout the project; when the count reaches zero for a sustained period, remove the forwarder, the System.Web adapters and the legacy application, then decommission the Windows servers that only existed to host it.
Planning a .NET Framework migration?
We assess .NET Framework estates and carry out staged migrations to modern .NET, keeping the application in production throughout.