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
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):
csharpCopy
After (.NET 10):
csharpCopy
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].
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):
csharpCopy
After (.NET 10):
csharpCopy
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):
csharpCopy
After (.NET 10):
csharpCopy
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.
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):
csharpCopy
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.
Upgrading Larkfield.Claims.Api surfaces several deprecation warnings that you should resolve during the migration rather than suppress.
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):
csharpCopy
After (.NET 10):
csharpCopy
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.The customer portal, Larkfield.Portal, benefits from runtime performance improvements and simplified state management in .NET 10.
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):
csharpCopy
After (.NET 10):
csharpCopy
When reviewing your project file for Larkfield.Portal, check for these project configuration updates:
BlazorCacheBootResources MSBuild property is removed. If present in your .csproj file, delete it.blazor.boot.json is now inlined directly into dotnet.js to eliminate an extra network roundtrip during startup.<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName> property.Update the service configuration in Larkfield.Claims.Api to use modern ASP.NET Core 10 conventions.
Microsoft.AspNetCore.OpenApi, and replace its Program.cs with the code below:bashCopy
csharpCopy
bashCopy
curl:bashCopy
Confirm that the application returns an HTTP 400 Bad Request status code containing problem details with validation errors for both fields.
Query the OpenAPI endpoint to verify the generated schema format:
bashCopy
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?