Skip to content
MERVENORBook a triage call

Checklist · .NET Framework migration

Upgrading .NET 8 or 9 to .NET 10: the checklist

By MervenorPublished Last reviewed 5 min read

In short

For most applications, moving from .NET 8 or .NET 9 to .NET 10 is a contained piece of work: new tools, a new target framework, updated packages and the breaking changes that touch your code. Support for .NET 8 and .NET 9 ended on 10 November 2026, and .NET 10 is supported until 14 November 2028. Do it on a branch, release through a test environment, and keep the previous build ready to restore.

Before you start

List every project in the solution with its target framework, every service, function and scheduled job, and where each one runs. Note the SDK version pinned in global.json, the images your containers start from, and the SDK on your build agents. Make sure the test suite runs green on .NET 8 first: an upgrade on top of failing tests hides its own breakages.

Step 1: Update the tools

Install the .NET 10 SDK on every developer machine and build agent, and update global.json if it pins the SDK. Use an IDE version whose release notes list .NET 10 support. Update the build pipeline's setup step and any dotnet tools the build installs.

Step 2: Change the target framework

Change the target framework in each project file, or once in Directory.Build.props if the solution sets it there:

<TargetFramework>net10.0</TargetFramework>

Libraries that other applications still consume on .NET 8 can multi-target for a while (<TargetFrameworks>net8.0;net10.0</TargetFrameworks>) and drop net8.0 when the last consumer has moved. C# 14 becomes the default language version with net10.0; you do not have to use its new features.

Step 3: Update the packages

Move the Microsoft packages (Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*) to their 10.0 versions together, then check each third-party package for a release that supports .NET 10. dotnet list package --outdated gives the starting list. In .NET 10, dotnet restore also audits transitive packages for known vulnerabilities, so expect new warnings the first time: treat each one as a finding, not as noise.

Step 4: Work through the breaking changes

Microsoft publishes the full lists for .NET 10, ASP.NET Core 10 and EF Core 10; read the entries that touch your code. The ones that most often affect web applications and APIs:

  • WebHostBuilder, IWebHost and WebHost are obsolete: move to WebApplication or the generic host.
  • Razor runtime compilation is obsolete.
  • IActionContextAccessor and ActionContextAccessor are obsolete.
  • Cookie login redirects are disabled for known API endpoints: an API that used to redirect an unauthenticated request to a sign-in page now answers with a status code, which clients may need to handle.
  • The WithOpenApi extension method is deprecated.
  • IPNetwork and ForwardedHeadersOptions.KnownNetworks are obsolete, which matters for applications behind a proxy or load balancer.
  • BackgroundService runs all of ExecuteAsync as a task, so startup code placed there behaves differently.
  • Null values are preserved in configuration, and System.Text.Json checks for property name conflicts.

"Obsolete" produces a warning, not an error, unless the build treats warnings as errors; plan to remove each one rather than suppress it.

Step 5: Containers and hosting

The default .NET 10 container images, such as mcr.microsoft.com/dotnet/aspnet:10.0, are based on Ubuntu 24.04 instead of Debian, and Microsoft no longer provides Debian images for .NET 10. Test any Dockerfile step that installs operating-system packages. On Linux, .NET 10 needs OpenSSL 1.1.1 or later. On a managed host such as Azure App Service, change the runtime stack to .NET 10 in a staging slot first.

Step 6: Test what the build does not catch

  • Sign-in: API endpoints that relied on cookie redirects, and anything behind a proxy that reads forwarded headers.
  • Background work: hosted services and scheduled jobs, including their behaviour at startup and shutdown.
  • Configuration and serialisation: settings that may now arrive as null, and JSON payloads with similar property names.
  • Telemetry: the default trace context propagator is now the W3C standard, so check traces still join up across services.
  • Speed: compare response times and memory before and after on a realistic load.

Step 7: Roll out safely

Deploy to a test environment that mirrors production and run the full test suite against it. Release to production at a quiet time with the previous build ready to restore in one step, then watch errors, response times and memory for a few days. Move internet-facing services and anything that handles payments or personal data first.

Questions people ask

  1. Can we go straight from .NET 6 or 7?

    Yes, with the same steps, but read the breaking changes for each version in between (.NET 8, 9 and 10), not only the last one.

  2. Should we go to .NET 11 instead?

    .NET 11 was released on 10 November 2026 as a standard-term release, supported until 14 November 2028, the same day as .NET 10. The steps are the same; for most business applications .NET 10, the long-term-support release, is the steadier target because libraries and hosts have supported it for a year.

  3. How long does the upgrade take?

    It depends on the number of projects and services, the third-party packages, and how much the tests cover. The lists in steps 3 to 5 are the best early estimate of the work.

If this is your application

Renascia, the upgrade and migration sprint, moves applications from .NET 8 or 9, or from .NET Framework, to .NET 10, at a fixed price set by a five-day Perlustra audit.

.NET Framework migration

01Start

Tell us about the application

Thirty minutes, no slides, no sales script. You leave with a view on what to check first.

Length
30 minutes
Cost
Free
You leave with
A view on what to check first