.NET Framework 4.x to .NET 10 Migration Runbook
Upgrade a .NET Framework estate one project at a time: .NET Standard 2.0 bridges, YARP side-by-side hosting, CoreWCF, EF Core and Linux containers.
By the Ryz Labs team · Updated November 2026
Moving from .NET Framework 4.x to .NET 10 means porting a solution project by project, from the leaf class libraries up to the web and service hosts, and then running the new ASP.NET Core app side by side with the old one until every route has moved. Use the incremental approach: shared libraries first through .NET Standard 2.0, then a YARP proxy in front of the old app so endpoints move one at a time. What decides success is how early you find the hard blockers, mainly System.Web, Web Forms, WCF server code, AppDomains, .NET Remoting and Windows-only APIs, because each one needs a redesign, not a recompile.
Why teams migrate now
.NET Framework is not on a countdown in the way most legacy stacks are, so be precise about what is and isn't ending:
- Microsoft's .NET Framework lifecycle FAQ says 4.5.2 and later are Windows components that follow the lifecycle policy of the underlying Windows OS. That includes 4.8 and 4.8.1, which have no fixed end date of their own.
- The .NET Framework lifecycle page shows 4.5.2, 4.6 and 4.6.1 retired on April 26, 2022, and lists 4.6.2 ending on January 12, 2027 (Pacific time). If any app still targets 4.6.2, that is your nearest hard date.
- On the modern side, the .NET support policy shows .NET 8 (LTS) and .NET 9 (STS) both reached end of support on November 10, 2026. Teams that half-migrated to .NET 8 are now on an unsupported runtime too.
- .NET 10 is the LTS release: released November 11, 2025, supported until November 14, 2028. .NET 11 (STS) shipped on November 10, 2026 and is also supported until November 14, 2028, so it buys no extra time. For a migration you start today, target .NET 10.
So the reason to move off Framework 4.8 is less about a deadline and more about what the platform keeps you tied to: Windows Server and IIS for every host, no Linux containers, package updates that increasingly need a modern target, and Web Forms and WCF code that fewer people on your team can safely change. Those turn into real costs: Windows licensing on every node, audit findings on old dependencies that can't be upgraded without the runtime, and slower delivery. Moving straight to .NET 10 means one migration lands you on the current LTS, instead of a stop on .NET 8 that is already out of support.
Before you start: inventory and baseline
- Project graph. Every csproj in every solution, its target framework, whether it is old-style or SDK-style, and whether it uses packages.config or PackageReference. Draw the dependency graph; the leaves are your first ports.
- App models. Mark each host as ASP.NET MVC 5, Web API 2, Web Forms, WCF service, Windows Service, WinForms or WPF, console or scheduled job. Web Forms and WCF server projects go on the blocker list immediately.
- Blocker scan. Search for System.Web and HttpContext.Current, HttpModules and HttpHandlers in web.config, Global.asax events, AppDomain.CreateDomain, MarshalByRefObject and .NET Remoting channels, Code Access Security attributes, BinaryFormatter, System.Messaging (MSMQ), COM interop, System.EnterpriseServices, and System.Web.Caching.
- Windows-only APIs. Registry access, EventLog, WMI through System.Management, System.Drawing in server code, Windows authentication and impersonation, performance counters, and file paths with drive letters or backslashes. Turn on the platform compatibility analyzer (CA1416) once projects are SDK-style so the compiler lists them for you.
- NuGet audit. For every package, find whether a version targets .NET Standard 2.0 or modern .NET, and which ones are abandoned. Unsupported packages are often the real critical path.
- Data access. EF6 with EDMX or Code First, raw ADO.NET, stored procedures, distributed transactions through TransactionScope across databases.
- Baseline metrics. p95 and p99 latency per endpoint, error rate, memory per worker process, request throughput per server, build time, and test coverage per project. Record them from production so the .NET 10 host has numbers to match.
- Tests to write first. Characterization tests that pin current behavior: HTTP-level tests that record request and response pairs for every route you'll move, golden-file tests for serialized output (JSON and XML casing, date formats, null handling), and integration tests against a copy of the database for the heaviest EF queries.
- Owners. One owner per solution, a platform owner for build and hosting, and a named owner for each blocker on the list.
The strangler-fig plan, phase by phase
Phase 0: Tooling and SDK-style projects
Convert every csproj to the SDK-style format while it still targets net48, and move packages.config to PackageReference. Nothing changes at runtime, but builds now run on the dotnet CLI, central package management becomes possible, and later multi-targeting is a one-line change. Microsoft's GitHub Copilot upgrade agent (available in Visual Studio, VS Code, the Copilot CLI and GitHub.com) lists .NET Framework of any version to .NET 8 or later among its supported paths and can draft these changes; review its output like any other pull request. Exit criteria: whole solution builds and passes tests on net48 with SDK-style projects, from CI, without Visual Studio.
Phase 1: Shared libraries as the bridge
Retarget leaf class libraries to netstandard2.0, or multi-target them with TargetFrameworks set to net48 and net10.0 when they need APIs .NET Standard doesn't have. .NET Framework 4.8 hosts can consume .NET Standard 2.0 libraries, so the domain model, validation and service clients can run on both runtimes at once. Replace Windows-only calls with abstractions, or isolate them behind an interface with a Windows implementation for now. Use the Microsoft.Windows.Compatibility package only as a temporary bridge, since it pulls in Windows-only APIs that block Linux later. Exit criteria: all shared libraries build for both targets and their tests pass on both.
Phase 2: Side-by-side web hosting with YARP
Create a new ASP.NET Core app on .NET 10 and put it in front of the existing ASP.NET app with YARP as a reverse proxy, which is Microsoft's documented incremental ASP.NET to ASP.NET Core pattern. Every request hits the new app first. Routes it handles stay there; the rest fall through to the Framework app. The System.Web adapters (Microsoft.AspNetCore.SystemWebAdapters) give ported code a System.Web-shaped HttpContext so you don't rewrite every controller at once, and their remote app features let the two apps share session state and authentication during the transition. Move routes in order of risk, starting with read-only Web API endpoints. Exit criteria per route: characterization tests pass against the new host, and shadow comparison shows matching responses.
Phase 3: The hard blockers
These are design work, not porting:
- Web Forms. There is no Web Forms on ASP.NET Core. Rebuild pages as Razor Pages, MVC views or Blazor. The Copilot upgrade agent lists Web Forms to Blazor as a supported path, which helps with the first draft of markup and code-behind; ViewState-dependent logic still needs redesign.
- WCF services. For SOAP clients you can't change, host the service on CoreWCF, the community port of the WCF server model to modern .NET, and keep the contracts and bindings it supports. Where you control the clients, move to gRPC or HTTP APIs. WCF client proxies move to the System.ServiceModel client packages.
- AppDomains and .NET Remoting. Modern .NET supports one AppDomain per process. Plugin isolation and unloading move to AssemblyLoadContext; true isolation moves to separate processes. Remoting calls become gRPC, named pipes or HTTP.
- Windows Services. Rehost as .NET Worker Services with the Generic Host, which can still run as a Windows service, or later in a Linux container.
- Serialization. Inventory BinaryFormatter and NetDataContractSerializer payloads, especially anything persisted in a database or cache, and plan the replacement format and the data conversion.
Exit criteria: every blocker has shipped its replacement behind the proxy or as a separate service.
Phase 4: EF6 to EF Core
EF6 can run on modern .NET, so you may move the runtime first and the ORM second, which keeps the two risks apart. When you move to EF Core, reverse-engineer a model from the database with scaffolding if you used EDMX, since EF Core has no EDMX designer. Check the known behavior differences query by query: lazy loading is opt-in, queries that can't be translated to SQL throw instead of silently evaluating on the client, GroupBy and complex Include chains translate differently, and ObjectContext APIs are gone. Compare the generated SQL and row counts for your heaviest queries against EF6. Exit criteria: integration tests and SQL comparison pass, and p95 query latency holds.
Phase 5: Linux containers and decommission
Once a host has no Windows-only dependencies, build it as a Linux container image. Move configuration from web.config transforms to appsettings.json and environment variables, persist ASP.NET Core Data Protection keys to shared storage so every replica can read auth cookies, and check globalization (ICU) settings, case-sensitive file paths and time zone IDs. Hosts that still need Windows can run on Windows containers or VMs while their last dependency is removed. When the proxy no longer forwards any route to the Framework app, retire the IIS site. Exit criteria: no traffic to the Framework app, IIS hosts removed, all services on .NET 10.
| Phase | Goal | Key technique | Exit criteria |
|---|
| 0. Projects | Modern build without runtime change | SDK-style csproj, PackageReference, Copilot upgrade agent drafts | Solution builds and tests on net48 from CI |
| 1. Bridge | Shared code runs on both runtimes | netstandard2.0 or net48;net10.0 multi-targeting | Libraries pass tests on both targets |
| 2. Side by side | Move web routes one at a time | YARP proxy in a .NET 10 app, System.Web adapters, shared session and auth | Per-route characterization and shadow match |
| 3. Blockers | Replace what can't be ported | Razor/Blazor for Web Forms, CoreWCF or gRPC, AssemblyLoadContext, Worker Services | Every blocker shipped behind the proxy |
| 4. Data | ORM on supported stack | EF6 on .NET 10 first, then EF Core with scaffolded model | SQL and latency comparison pass |
| 5. Hosting | Retire IIS and Windows-only hosts | Linux containers, Data Protection key ring, config to env vars | Zero traffic to Framework app |
Cutover and rollback
The YARP proxy is the control point. Route configuration decides which app serves each path, and changing it does not need a code deploy of either app.
- Routing by path. Move one route or route prefix at a time. Keep the route table in configuration so the move and the revert are both a config change.
- Shadow traffic. Before switching a route, mirror a sample of production requests to the new handler, discard its responses, and diff them against the Framework app's responses: status codes, JSON field names and casing, date formats, and headers. JSON serializer defaults differ between Newtonsoft.Json and System.Text.Json, and that is the most common diff.
- Shared auth and session. Users must not notice which app answered. Use the System.Web adapters' remote session and remote authentication, or share the auth cookie with matching Data Protection settings, and test sign-in and sign-out on both sides.
- Data. Both apps talk to the same database during the migration, so schema changes must be backward compatible: add columns, don't rename or drop them until the Framework app is gone.
- Feature flags for behavior changes inside a moved route, so a route can move first and change later.
Go/no-go checklist per route: characterization tests pass; shadow diff clean over a full business cycle (month-end jobs included where relevant); p95 latency and error rate at or better than baseline; auth and session verified across both apps; logs and traces flowing to the same observability stack; rollback tested in staging.
Rollback path by phase:
- Phase 0 and 1: revert the project file changes; runtime behavior never changed. Multi-targeted libraries keep working for net48 hosts.
- Phase 2 and 3: point the route back to the Framework app in the YARP config. Keep the old code path deployed until the route has been stable on .NET 10 for at least one full release cycle.
- Phase 4: because EF6 stays usable on .NET 10, a problem query can fall back to the EF6 context while you fix it. Never ship an EF Core migration that the EF6 model can't read until the switch is final.
- Phase 5: keep the Windows hosts and IIS site warm, with the proxy able to send traffic back, until the Linux deployment has run through your peak load.
Risk matrix
| Risk | Likelihood | Impact | Mitigation | Early warning signal |
|---|
| Hidden HttpContext.Current use deep in shared libraries | High | Medium | Scan in Phase 1; pass context explicitly; System.Web adapters for the rest | Null reference errors on moved routes in shadow runs |
| Web Forms rebuild grows larger than planned | High | High | Inventory pages by traffic; retire unused pages before porting | Pages per release below plan; ViewState logic found late |
| WCF binding or security mode not supported on CoreWCF | Medium | High | Spike each binding early; offer clients a gRPC or HTTP alternative | Client integration tests fail on handshake or message security |
| JSON output changes break API consumers | High | Medium | Golden-file tests; match serializer settings or keep Newtonsoft.Json | Shadow diffs on casing, dates and nulls |
| EF Core generates different SQL and slows key queries | Medium | High | SQL capture and comparison; split queries; keep EF6 path until verified | p95 database time rising in traces for moved endpoints |
| Abandoned NuGet package with no modern .NET target | Medium | Medium | Replace or fork during Phase 1; wrap behind an interface | Package shows no .NET Standard 2.0 or net10.0 build |
| Windows-only API found after containerizing | Medium | Medium | CA1416 analyzer as error; run tests in Linux containers in CI | PlatformNotSupportedException in Linux test runs |
| Auth cookies or sessions not shared, users signed out between apps | Medium | High | Remote auth via System.Web adapters or shared Data Protection keys | Login rate spike after a route switch |
| Persisted BinaryFormatter data can't be read by the new code | Low | High | Convert data in a one-off job with the old runtime; dual-read during switch | Deserialization errors in cache or queue consumers |
Typical team shape
This migration rewards engineers who have shipped on both runtimes and know where ASP.NET Core differs from System.Web. A working shape:
- .NET tech lead who owns the project graph, the blocker list and the YARP route plan.
- Two or three senior .NET developers on library retargeting, route moves, CoreWCF and EF Core.
- QA and test automation for characterization tests, golden files and shadow diffs.
- Part-time platform or DevOps engineer for CI, container images and hosting, with a PM if several teams own parts of the estate.
Many teams begin with a pod of 3 to 5 senior engineers (a tech lead plus engineers), and a full pod is about seven. Ryz engineers on your team start from $7,000 per month (our published range is $7,000–$15,000 per engineer per month, mostly mid-level to senior), quoted per team. You can budget with project cost = team size × months × monthly rate; we don't give fixed project quotes before the inventory. Ryz engineers work on your team, reporting to your leads. Once you say go, engineers can typically start in under two weeks. See our .NET developer rates for detail, or scope your team with us.
Where an AI pod helps (and where it doesn't)
A Framework estate has a lot of mechanical change: hundreds of csproj files, namespace swaps, controller base classes, config moves, and test scaffolding. Our AI pod uses Microsoft's GitHub Copilot upgrade agent where it supports the path, plus coding assistants for the rest: drafting characterization tests from recorded traffic, proposing SDK-style project conversions, generating Razor or Blazor drafts from Web Forms pages, opening dependency upgrade pull requests, and triaging shadow diffs and logs so engineers look only at real differences.
The judgment calls stay human. Choosing between CoreWCF and a gRPC rewrite, designing AppDomain replacements, reading EF Core's SQL against EF6's, and deciding when a route is ready all depend on context a tool doesn't have. Every change goes through code review, passes the characterization tests, and moves through the proxy with a rollback ready.
When not to migrate (yet)
- Stable, low-change apps on 4.8 or 4.8.1 that run on a supported Windows Server and have no blocked dependencies. Their Framework support follows the OS, so a careful plan can wait for a business reason. Apps on 4.6.2 should at least move to 4.8.1 before January 12, 2027.
- Apps you plan to retire or replace with SaaS. Don't port a Web Forms back office that a purchased product will replace.
- Desktop WinForms or WPF apps with heavy third-party control suites. They can move to .NET 10 on Windows, but check every vendor control first; sometimes staying put until the vendor ships is cheaper.
- Regulatory freeze windows such as audit periods. Do Phase 0 and the inventory, then move routes after the window.
Ryz isn't the right fit if what you need is a management-consulting or strategy engagement rather than engineers shipping the migration.
Related
FAQ
How long does a .NET Framework to .NET 10 migration take?
It depends on the number of projects, how many Web Forms pages and WCF services you have, how much code touches System.Web directly, how many NuGet packages lack a modern target, and test coverage. The Phase 1 blocker scan is where an estimate becomes reliable, because it shows which projects recompile and which need redesign.
Can the old and new apps run in parallel?
Yes. A .NET 10 ASP.NET Core app with a YARP proxy sits in front of the Framework app and forwards any route it doesn't handle yet. With the System.Web adapters, both apps can share session state and authentication, so users don't notice which one answered.
Should we go to .NET 8 first since it's more familiar?
No. .NET 8 and .NET 9 both reached end of support on November 10, 2026. .NET 10 is the current LTS and is supported until November 14, 2028, so target it directly.
Do we need to freeze feature work?
Not across the board. Build new endpoints in the .NET 10 app from the start, and freeze only the routes being moved during their switch. Shared libraries that multi-target let both apps pick up fixes during the transition.
What does a .NET Framework migration cost?
Cost is team size multiplied by months multiplied by the monthly rate per engineer. The drivers are the blocker list (Web Forms, WCF, AppDomains), data access changes and how much characterization testing exists. We quote per team after the inventory, with a plan and named engineers, rather than a fixed project price.
Questions we didn't answer? Email info@ryzlabs.com.