Upgrade .NET 8 to .NET 10 Without Breaking Your API Contract

If I need to upgrade .NET 8 to .NET 10, I treat the work as an API contract migration, not a project-file edit. A service can compile, pass unit tests, and still surprise consumers with a changed JSON shape, status code, authentication response, or OpenAPI document.

That risk matters now because Microsoft has confirmed that .NET 8 and .NET 9 reach end of support on November 10, 2026. .NET 10 and C# 14 are the current stable releases, and .NET 10 is the supported LTS destination.

Why the deadline changes my upgrade order

My first step is inventory, not retargeting. I list every deployable project, test project, global.json, container base image, CI SDK pin, and Microsoft package reference. dotnet --list-sdks shows what a machine can build; dotnet --info shows what the current environment actually resolves.

If that inventory needs more detail, my older guide to dotnet sdk check is a useful starting point. For APIs still on .NET 8, the broader Web API setup and security checklist can help identify behavior worth protecting before the move.

I then separate the migration into three changes: SDK and target framework, NuGet dependencies, and runtime infrastructure. Keeping those changes visible makes a failure easier to locate. A giant dependency-refresh commit may be quick to create, but it is hard to diagnose.

Upgrade .NET 8 to .NET 10 behind contract tests

Before changing net8.0, I add a small set of tests around the endpoints consumers cannot tolerate changing. I care about observable behavior: status codes, content types, required JSON names, and authentication boundaries. I avoid asserting an entire serialized string because harmless property ordering can make that test noisy.

Here is a focused xUnit test for a Minimal API:

using System.Net;
using System.Text.Json;
using Microsoft.AspNetCore.Mvc.Testing;
using Xunit;

public sealed class ProductContractTests(
    WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    [Fact]
    public async Task GetProduct_keeps_the_public_contract()
    {
        using var client = factory.CreateClient(new()
        {
            BaseAddress = new Uri("https://localhost")
        });

        using var response = await client.GetAsync("https://dev.to/products/42");

        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
        Assert.Equal(
            "application/json",
            response.Content.Headers.ContentType?.MediaType);

        await using var stream =
            await response.Content.ReadAsStreamAsync();
        using var json = await JsonDocument.ParseAsync(stream);

        Assert.Equal(
            42,
            json.RootElement.GetProperty("id").GetInt32());
        Assert.True(json.RootElement.TryGetProperty("name", out _));
    }
}

The test project references Microsoft.AspNetCore.Mvc.Testing in the same 10.0 servicing line as the application. This one test is not a complete compatibility suite. It is a template for the small number of contracts that matter most: a successful read, a validation failure, an unauthorized request, and a not-found response. Those checks catch behavioral changes that a unit test below the HTTP pipeline cannot see.

For a top-level Minimal API, I also expose the entry point to the test project:

app.Run();

public partial class Program
{
}

Microsoft maintains a complete .NET 10 WebApplicationFactory sample. I use that as the reference for test-host setup rather than creating custom server plumbing.

Move the runtime, packages, and pipeline together

With the baseline green, I change the application and test projects to net10.0. I update Microsoft.AspNetCore, Microsoft.Extensions, and EF Core packages to compatible 10.0 servicing releases, then inspect the official .NET 10 breaking-change catalog instead of guessing from compiler errors alone.

  net10.0

I run the same short sequence locally and in CI:

dotnet package list --outdated
dotnet restore
dotnet build --warnaserror
dotnet test
dotnet publish -c Release

The pipeline must install a .NET 10 SDK, and containerized services must use matching 10.0 build and runtime images. Updating only the developer machine proves very little about the artifact that reaches production.

OpenAPI deserves an explicit decision. ASP.NET Core 10’s built-in generator emits OpenAPI 3.1 by default. If an existing client generator only understands 3.0, I temporarily pin the format and schedule that contract change separately:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion =
        Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
});

That pin is a compatibility tool, not a reason to avoid OpenAPI 3.1 forever. I keep it only until consumers have been tested and upgraded.

When I would not use this direct path

A direct retarget is the wrong move when a database provider, authentication component, hosting platform, or commercial dependency does not support .NET 10. In that case, I isolate the blocker first. Moving through .NET 9 can help expose changes in smaller steps, but .NET 9 has the same November 2026 support deadline, so it is not the final destination.

I also avoid combining the runtime upgrade with an EF model redesign, authentication rewrite, or OpenAPI generator replacement. Those may all be worthwhile, but separate commits and deployments preserve a useful rollback boundary.

For shared libraries, temporary net8.0;net10.0 multi-targeting can let applications migrate independently. For a deployable API, multi-targeting is not a substitute for choosing and validating the runtime that production will execute.

Which API contract would you pin down before moving your service to .NET 10?

Thanks for reading ? see you next time.