Workik.

.NET 8 to .NET 10 Migration: An Enterprise Upgrade Guide

Upgrade ASP.NET Core 8 to ASP.NET Core 10

Upgrade ASP.NET Core 8 apps to ASP.NET Core 10: built-in OpenAPI 3.1, MapStaticAssets, minimal API validation, cookie auth and Blazor.

Upgrading your web applications from ASP.NET Core 8 to ASP.NET Core 10 involves modernizing your API documentation, streamlining static asset delivery, and adjusting to stricter security defaults. In Larkfield Insurance, Larkfield.Claims.Api handles both controller endpoints and minimal APIs, while Larkfield.Portal serves customer interactions using Blazor. Migrating these services requires replacing outdated patterns like Swashbuckle and unconstrained forwarded headers with first-party alternatives.

Previous lesson: .NET 9 and .NET 10 Breaking Changes in Core Libraries | Next lesson: Upgrade EF Core 8 to EF Core 10


Replace Swashbuckle with Built-in OpenAPI

ASP.NET Core now provides built-in OpenAPI support through the Microsoft.AspNetCore.OpenApi package. In .NET 8, many services relied on the third-party Swashbuckle package, which is no longer included in the official web API templates.

In ASP.NET Core 10, the built-in OpenAPI generator emits OpenAPI specification version 3.1 by default. This enables native support for JSON Schema features like type unions and nullable keywords. If your downstream tooling, code generators, or API gateways only support OpenAPI 3.0, you can explicitly configure the specification version.

Before (.NET 8):

csharp
Copy

After (.NET 10):

csharp
Copy

Because Microsoft.AspNetCore.OpenApi only generates the raw specification document at /openapi/v1.json, it does not ship with an interactive user interface out of the box. If your developers depend on an interactive testing page, you can keep Swashbuckle for the UI only, or adopt an alternative UI provider such as Scalar.

Pro Tip: The WithOpenApi extension method used on minimal API endpoints in .NET 8 is deprecated in .NET 10. Describe endpoints with .WithSummary(), .WithDescription(), and .WithTags(), or with attributes such as [EndpointSummary] and [EndpointDescription].


Cookie Authentication Redirects for API Endpoints

A frequent issue in mixed applications like Larkfield.Claims.Api is handling unauthorized access. In ASP.NET Core 8, when an unauthenticated request reached an endpoint protected by cookie authentication, the default behavior redirected the caller to a login path with an HTTP 302 status code. This redirect caused confusion for API clients, single-page applications, and mobile frontends that expected an HTTP 401 Unauthorized or HTTP 403 Forbidden status code.

ASP.NET Core 10 changes this behavior. For endpoints that ASP.NET Core recognizes as API endpoints, such as controllers marked [ApiController], minimal API endpoints that return JSON or TypedResults, and SignalR hubs, cookie authentication no longer redirects. It returns HTTP 401 or HTTP 403 directly.

Common Mistake: Assuming browser-based login workflows will continue redirecting API requests automatically. If your admin dashboard relies on browser redirects when an API fetch call fails, you must update your frontend logic to handle 401 status codes.

If you maintain legacy endpoints that strictly require the redirect behavior, you can override the cookie authentication events explicitly.

Before (.NET 8):

csharp
Copy

After (.NET 10):

csharp
Copy

Deliver Static Content with MapStaticAssets

ASP.NET Core 9 introduced MapStaticAssets, which replaces app.UseStaticFiles() as the recommended approach for serving web assets. While UseStaticFiles served files directly from disk at runtime, MapStaticAssets optimizes your static assets during build and publish time.

At build and publish time, it compresses files with gzip and Brotli and calculates content hashes, so each asset gets a fingerprinted URL. This enables aggressive caching policies because browsers can cache fingerprinted files indefinitely without serving stale assets when you deploy updates.

Before (.NET 8):

csharp
Copy

After (.NET 10):

csharp
Copy

For Larkfield.Portal, switching to MapStaticAssets reduces payload sizes and lets browsers cache assets safely. If you use traditional controllers with views or Razor Pages, chain .WithStaticAssets() to the endpoint mapping so that tag helpers automatically resolve the fingerprinted asset paths.


Minimal API Validation

In ASP.NET Core 8, minimal APIs lacked native, declarative model validation. Developers either implemented manual validation routines inside their endpoint handlers or installed third-party libraries.

ASP.NET Core 10 introduces builder.Services.AddValidation(). This method validates request bodies, query string values, and headers using standard DataAnnotations attributes. When a request fails validation, the endpoint returns HTTP 400 Bad Request with problem details listing each error.

After (.NET 10):

csharp
Copy

If a client sends a payload where Amount is zero or PolicyNumber does not match the pattern, the endpoint rejects the call immediately. You no longer need to write boilerplate checks or inject custom validation filters for basic constraint checking.


Obsolete Hosting and Networking APIs

Upgrading Larkfield.Claims.Api surfaces several deprecation warnings that you should resolve during the migration rather than suppress.

Forwarded Headers and Reverse Proxies

Larkfield.Claims.Api runs behind a reverse proxy. ASP.NET Core enforces stricter checks on forwarded headers like X-Forwarded-For and X-Forwarded-Proto. The middleware ignores headers coming from unknown proxies by default.

In .NET 10, ForwardedHeadersOptions.KnownNetworks and the IPNetwork class in Microsoft.AspNetCore.HttpOverrides are obsolete (warning ASPDEPR005). Use KnownIPNetworks with System.Net.IPNetwork instead.

Before (.NET 8):

csharp
Copy

After (.NET 10):

csharp
Copy

Hosting Types and Context Accessors

Legacy bootstrapping constructs are marked as obsolete in .NET 10:

  • WebHostBuilder, IWebHost, and WebHost are obsolete. Move entirely to WebApplicationBuilder and WebApplication.
  • IActionContextAccessor and ActionContextAccessor are obsolete. If you used these accessors to inspect route values or action descriptors inside service classes, pass the required data explicitly as method parameters or access IHttpContextAccessor instead.
  • Razor runtime compilation packages are obsolete. Build-time compilation is the standard model.

Blazor Updates for Larkfield.Portal

The customer portal, Larkfield.Portal, benefits from runtime performance improvements and simplified state management in .NET 10.

Simplified State Persistence

In Blazor Web Apps running interactive server and WebAssembly modes, preserving state during prerendering previously required injecting PersistentComponentState and managing callback registrations manually. In .NET 10, the [PersistentState] attribute automates this process.

Before (.NET 8):

csharp
Copy

After (.NET 10):

csharp
Copy

Blazor Configuration Adjustments

When reviewing your project file for Larkfield.Portal, check for these project configuration updates:

  • The BlazorCacheBootResources MSBuild property is removed. If present in your .csproj file, delete it.
  • In standalone WebAssembly deployments, the manifest file blazor.boot.json is now inlined directly into dotnet.js to eliminate an extra network roundtrip during startup.
  • You can specify the environment name for standalone WebAssembly applications directly in the project file using the <WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName> property.

Try It Yourself

Update the service configuration in Larkfield.Claims.Api to use modern ASP.NET Core 10 conventions.

  1. Create a test web API project, which already references Microsoft.AspNetCore.OpenApi, and replace its Program.cs with the code below:
bash
Copy
csharp
Copy
  1. Run the application on a fixed port:
bash
Copy
  1. In a separate terminal, test the validation rules by submitting an invalid payload using curl:
bash
Copy
  1. Confirm that the application returns an HTTP 400 Bad Request status code containing problem details with validation errors for both fields.

  2. Query the OpenAPI endpoint to verify the generated schema format:

bash
Copy

In the next lesson, Upgrade EF Core 8 to EF Core 10, you will upgrade your data layer, handle pending model change exceptions, and configure isolated database migrations.

Was this lesson helpful?