Ryz Labs/Migrations/.NET Framework to .NET 10
Migrations

.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.

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:

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

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:

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.

PhaseGoalKey techniqueExit criteria
0. ProjectsModern build without runtime changeSDK-style csproj, PackageReference, Copilot upgrade agent draftsSolution builds and tests on net48 from CI
1. BridgeShared code runs on both runtimesnetstandard2.0 or net48;net10.0 multi-targetingLibraries pass tests on both targets
2. Side by sideMove web routes one at a timeYARP proxy in a .NET 10 app, System.Web adapters, shared session and authPer-route characterization and shadow match
3. BlockersReplace what can't be portedRazor/Blazor for Web Forms, CoreWCF or gRPC, AssemblyLoadContext, Worker ServicesEvery blocker shipped behind the proxy
4. DataORM on supported stackEF6 on .NET 10 first, then EF Core with scaffolded modelSQL and latency comparison pass
5. HostingRetire IIS and Windows-only hostsLinux containers, Data Protection key ring, config to env varsZero 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.

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:

Risk matrix

RiskLikelihoodImpactMitigationEarly warning signal
Hidden HttpContext.Current use deep in shared librariesHighMediumScan in Phase 1; pass context explicitly; System.Web adapters for the restNull reference errors on moved routes in shadow runs
Web Forms rebuild grows larger than plannedHighHighInventory pages by traffic; retire unused pages before portingPages per release below plan; ViewState logic found late
WCF binding or security mode not supported on CoreWCFMediumHighSpike each binding early; offer clients a gRPC or HTTP alternativeClient integration tests fail on handshake or message security
JSON output changes break API consumersHighMediumGolden-file tests; match serializer settings or keep Newtonsoft.JsonShadow diffs on casing, dates and nulls
EF Core generates different SQL and slows key queriesMediumHighSQL capture and comparison; split queries; keep EF6 path until verifiedp95 database time rising in traces for moved endpoints
Abandoned NuGet package with no modern .NET targetMediumMediumReplace or fork during Phase 1; wrap behind an interfacePackage shows no .NET Standard 2.0 or net10.0 build
Windows-only API found after containerizingMediumMediumCA1416 analyzer as error; run tests in Linux containers in CIPlatformNotSupportedException in Linux test runs
Auth cookies or sessions not shared, users signed out between appsMediumHighRemote auth via System.Web adapters or shared Data Protection keysLogin rate spike after a route switch
Persisted BinaryFormatter data can't be read by the new codeLowHighConvert data in a one-off job with the old runtime; dual-read during switchDeserialization 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:

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)

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.

Thanks — your message has been sent. We’ll get back to you soon.

Something went wrong while sending your message. Please try again or email info@ryzlabs.com.

Explore Ryz Labs

Software development servicesAI development companyIndustriesStaff augmentationAI pod teamsNearshore software developmentHire engineers by roleEngineer ratesGuidesBuyer guidesCase studiesHow we vet engineers

Ryz Labs

Senior engineers on your team. AI pod teams that ship.

Tell us what you're building. You get a scoped plan, a price and the names of the people who would do the work.

  • Only the top 1% of tens of thousands interviewed make it
  • On US business hours, including New York hours
  • Trusted by Fortune 500 engineering teams

Tell us who you need

A Ryz partner replies with a scoped team plan.

Start a conversation →

Prefer to talk? Book a 15-min call →