ASP.NET Core 11 cheat sheet

A PR merged into dotnet/aspnetcore main on August 19, 2026 makes ExceptionHandlerMiddleware honour BadHttpRequestException.StatusCode instead of overwriting it with 500.

A [FromForm] Dictionary in a minimal API binds with an empty prefix: the form keys must be [key], not metadata[key]. Wrap it in a class to keep readable names.

Swashbuckle 8 and later emit openapi 3.0.4, not 3.0.1, and there is no OpenApiSpecVersion for a patch version. Why it changed, and four ways to pin the string your tooling expects.

ASP.NET Core 11 emits openapi 3.2.0 by default and Swagger UI below 10.1.5 rejects it. Upgrade Swashbuckle.AspNetCore.SwaggerUI, or pin OpenApiVersion back to OpenApi3_1.

Skip the downloadFileFromStream JS module entirely. Render an anchor with the download attribute pointing at a minimal API endpoint that returns TypedResults.File, or POST a plain HTML form with an AntiforgeryToken. Covers why the download attribute is what stops Blazor's enhanced navigation from swallowing the click, why data-enhance silently discards the file, and the cookie-vs-bearer auth trap.

Scalar ships 1.02 MiB of gzipped JavaScript and a far better request builder. Swagger UI ships 514 KiB and renders OpenAPI 3.2, which is what .NET 11 now emits by default. Measured payloads, the 3.2 gap, endpoint routing on both sides, and the auth details that decide it.

Zstandard is the right default for dynamic API responses in .NET 11, but not at the quality the ASP.NET Core provider ships with. Benchmarks on real JSON payloads showing why quality 1 beats the default quality 3 on both size and CPU, when Brotli still wins, and why Gzip survives only as a fallback.

.NET 11 Preview 7 adds an opt-in package that pauses interactive Server circuits when the browser tab is hidden, freeing memory and SignalR connections held by users who are not actually there.

blazor.server.js 404s on .NET 10 because the script stopped being an embedded resource. Add RequiresAspNetWebAssets to the host project, or make sure it has a .razor file.

CS9137 comes from the Microsoft.AspNetCore.OpenApi source generator. Add InterceptorsNamespaces to every project that calls AddOpenApi, not just the one holding the PackageReference.

OpenApiReference was deleted in Microsoft.OpenApi 2.0. Changing the using to Microsoft.OpenApi is not enough: replace each usage with a typed reference such as OpenApiSchemaReference.

Replace UseSwaggerUI with MapScalarApiReference in ASP.NET Core 11: routing, multiple documents, pre-filled auth, production gating, offline assets, and the Scalar-only OpenAPI extensions that mark endpoints stable or hidden.

They are not alternatives. WebApplicationFactory boots your app, Testcontainers boots your dependencies. Measured on .NET SDK 10.0.201: a container fixture costs 1.7 s per class against 10 ms for SQLite, and a HasMaxLength(16) violation that Postgres rejects with 22001 is silently accepted by SQLite.

The reconnect modal means the SignalR circuit dropped, not that your app crashed. Decide whether the retry ended in failed or rejected, then fix sticky sessions, the 3-minute retention window, the 32 KB message limit, or persist circuit state with [PersistentState].

For internal service-to-service calls in .NET 11, default to gRPC when you own both ends of the contract and the call is point-to-point. Use REST with JSON when anything you do not control has to call the service. SignalR is not an RPC transport between services: reach for it only when one producer has to fan a message out to many long-lived consumers.

500.30 means your app threw during startup inside w3wp.exe. The real exception is already in the Windows Application event log under IIS AspNetCore Module V2. Read that first, then rank the fix: missing shared framework, x86/x64 app pool mismatch, missing config, or app pool permissions.

Implement IValidateOptions<T>, register it in DI, and chain ValidateOnStart so a bad appsettings.json kills the process instead of the first request that touches it. Covers the .NET 11 Validate<TValidator>() overload, async validation through IAsyncValidateOptions<T>, and the three places ValidateOnStart silently does nothing.

A complete guide to enabling HTTP/3 on Kestrel in ASP.NET Core 11: the HttpProtocols.Http1AndHttp2AndHttp3 endpoint config, MsQuic platform requirements on Windows, Linux, and macOS, why the first request is never HTTP/3, how to verify with HttpClient and middleware, QuicTransportOptions tuning, and the firewall and proxy gotchas that make it silently fall back.

Default to IOptions<T>. Use IOptionsMonitor<T> when a singleton has to see config reloads, and IOptionsSnapshot<T> only when a scoped consumer wants a value that is stable for one request. The deciding axis is the lifetime of the consumer, not the shape of the settings.

Prerendering runs your component on the server with no browser attached, so IJSRuntime throws. Move the call into OnAfterRenderAsync, gate it on RendererInfo.IsInteractive, or disable prerendering.

Add Aspire 13.4 to a brownfield ASP.NET Core solution by adding two new projects and three lines per service: aspire init, AppHost wiring with AddProject and WithReference, keeping your existing launchSettings.json and connection strings, and the resilience, health-endpoint, and proxy gotchas that bite on day one.

A complete guide to WebApplicationFactory<TEntryPoint> in ASP.NET Core 11: making the Program entry point reachable, ConfigureTestServices vs ConfigureWebHost, replacing the EF Core registration through IDbContextOptionsConfiguration, the new ConfigureHostApplicationBuilder hook in .NET 11 preview 6, faking authentication, WebApplicationFactoryClientOptions, and UseKestrel when you need a real port.

A decision guide for ASP.NET Core 11: middleware runs for every request before your handler binds, endpoint filters run only for the matched endpoint after binding and can see the typed arguments. Includes a feature matrix, when-to-pick-each scenarios, the ordering rules, and the gotchas that force the choice.

Cancelling the CancellationToken you pass to InvokeAsync now reaches the server and cancels the hub method. This closes a SignalR request open since 2019.

In ASP.NET Core 11, return Results<T1, TN> with TypedResults for minimal APIs and ActionResult<T> for controllers. Treat bare IResult and bare IActionResult as escape hatches: they compile for any response but describe nothing to OpenAPI, so you pay for them in hand-written ProducesResponseType attributes.

Use CreateBuilder for a normal app, CreateSlimBuilder when you publish trimmed or Native AOT behind a TLS proxy, and CreateEmptyBuilder only when you want to register every service yourself. Here is the feature matrix and the gotchas that force the call.

Output caching is the right default for almost every server-side app in ASP.NET Core 11. Response caching only wins when your goal is to steer browser and proxy caches through HTTP headers. Here is the decision, with a feature matrix and the gotchas that force the call.

Preview 6 adds AsyncValidationAttribute and IAsyncValidatableObject so DataAnnotations rules can hit the database before your endpoint runs, without blocking a thread.

A complete, working guide to health checks in an ASP.NET Core 11 minimal API: AddHealthChecks and MapHealthChecks, custom IHealthCheck classes returning Healthy/Degraded/Unhealthy, the AddDbContextCheck EF Core probe, tag-based liveness and readiness endpoints for Kubernetes, a JSON ResponseWriter, ResultStatusCodes, securing the endpoint with RequireAuthorization and RequireHost, and pushing results with IHealthCheckPublisher.

A complete, working guide to endpoint filters in an ASP.NET Core 11 minimal API: AddEndpointFilter with an inline delegate, IEndpointFilter classes with DI, GetArgument and the Arguments list, short-circuiting with Results.Problem, FIFO/FILO ordering across multiple filters, group-level filters on MapGroup, and AddEndpointFilterFactory for signature-aware filters.

Preview 6 rejects unsafe cross-origin browser requests by default, reading the Sec-Fetch-Site header instead of an antiforgery token. Here is what it blocks and how to opt out.

Kestrel caps request bodies at 30,000,000 bytes by default and returns 413 when you exceed it. Raise MaxRequestBodySize globally, per endpoint, or in web.config behind IIS.

You set a header, status code, or content type after the body was already flushed. Set all headers before the first write, or guard with HttpResponse.HasStarted and OnStarting.

A complete guide to response compression in ASP.NET Core 11: AddResponseCompression and UseResponseCompression, the new built-in Zstandard provider alongside Brotli and Gzip, compression levels, EnableForHttps and the CRIME/BREACH risk, custom MIME types, middleware ordering, and when to let the reverse proxy do it instead.

Declare the handler's return type as Results<Ok<T>, NotFound> and return TypedResults.Ok / TypedResults.NotFound: the union gives compile-time checking that the handler only returns what it declares, and it self-describes to OpenAPI so you never write .Produces by hand. Covers async handlers, the six-type limit, and testing in ASP.NET Core 11.

A complete, working guide to output caching in an ASP.NET Core 11 minimal API: AddOutputCache and UseOutputCache, CacheOutput on endpoints and MapGroup, named and base policies, Expire, VaryByQuery and VaryByHeader, tag-based eviction with EvictByTagAsync, cache stampede protection, ETag revalidation, and a Redis backing store.

A deep dive into the built-in OpenAPI transformer pipeline in .NET 11: operation vs schema transformers, the context objects, execution order, DI-activated transformers, and recipes for headers, responses, examples, and per-property tweaks.

IHostedService is the two-method interface (StartAsync/StopAsync) the .NET generic host calls on startup and graceful shutdown. Here is exactly what the contract promises, when to implement it directly, and the .NET 10 and 11 behavior changes that catch people out.

A step-by-step migration guide for replacing hand-rolled if-checks in ASP.NET Core 11 minimal API handlers with the built-in source-generated DataAnnotations validator: what breaks, which manual rules do and do not port, and how to verify the 400 ProblemDetails contract stays identical.

A minimal API returns 415 when the request Content-Type does not match what the endpoint binds. Send Content-Type: application/json for a body-bound type, or use [FromForm] for form and file uploads.

Call AddProblemDetails with a CustomizeProblemDetails callback to reshape the 400 that built-in minimal API validation returns in ASP.NET Core 11: add a traceId, rewrite the title, switch 400 to 422, or take full control with a custom IProblemDetailsWriter.

A complete, working setup for JWT bearer authentication in an ASP.NET Core 11 minimal API: install the package, wire up AddAuthentication().AddJwtBearer(), issue a token, protect endpoints with RequireAuthorization, add role and claim policies, and test the whole thing with dotnet user-jwts.

Use cookie authentication for any app where the browser is the only client, and reserve JWT bearer tokens for APIs called by mobile apps, other services, or third parties. Here is the full decision matrix.

A protected endpoint returning 405 instead of 401 almost always means routing rejected the HTTP verb before auth ran, or a cookie scheme stole the challenge. Here is how to tell which.

A valid token that still 401s almost always means the bearer handler never ran or ran under the wrong scheme. Check middleware order, the default scheme, the scheme name, and whether the header even reached the handler.

Register more than one implementation of the same interface under a key with AddKeyedSingleton/Scoped/Transient, then resolve them with [FromKeyedServices], GetRequiredKeyedService, or KeyedService.AnyKey. The keyed and non-keyed registries are separate, which is the gotcha that bites most people.

A complete guide to TokenValidationParameters in ASP.NET Core 11: how ValidateIssuer, ValidateAudience, and ValidateLifetime work, what the defaults actually are, why Authority auto-configures the issuer and signing keys, the 5-minute ClockSkew trap, and how to read the IDX error codes when a valid-looking token is rejected.

A complete guide to CORS for a bearer-token API in ASP.NET Core 11: the correct UseCors ordering relative to authentication, why a bearer token in the Authorization header is not a CORS credential, why AllowAnyHeader works but a manual wildcard does not cover Authorization, and how to keep preflight from failing.

Reading session state in static server-rendered Blazor meant reaching into HttpContext.Session and serializing by hand. .NET 11 Preview 5 adds [SupplyParameterFromSession] so a component property binds to a session key directly.

Use the built-in source-generated validation for synchronous, attribute-expressible rules in ASP.NET Core 11; reach for FluentValidation when you need async rules, complex cross-field logic, or validation kept out of your domain models.

Default to HybridCache for new caching code in .NET 11. Reach for IMemoryCache only when you need raw single-server speed with no serialization, and IDistributedCache only as a backing store. Here is the decision matrix.

The error means Data Protection lost the key that signed the token. Persist keys to a shared, durable store and call SetApplicationName so every instance reads the same key ring.

Static server-rendered Blazor forms could only validate after a full POST round-trip. .NET 11 Preview 5 renders validation metadata so the Blazor JS enforces DataAnnotations rules in the browser, no circuit required.

You put @rendermode on a child whose parent is already interactive. A subtree has exactly one render mode. Remove the child directive or move it to the boundary.

A prerendered Blazor component runs its initialization twice and loses state at the interactive handoff. Fix it with the [PersistentState] attribute or the PersistentComponentState service in .NET 11.

Swashbuckle is gone from the ASP.NET Core templates. Here is how to generate and serve an OpenAPI document in .NET 11 with the built-in Microsoft.AspNetCore.OpenApi package: AddOpenApi, MapOpenApi, transformers, multiple documents, build-time generation, and a UI on top.

A complete guide to structuring minimal APIs in ASP.NET Core 11 with MapGroup: per-resource endpoint modules as extension methods, nested groups, shared filters and auth, route-parameter prefixes, OpenAPI tags, and the filter-ordering rules that surprise people.

Wire HybridCache to a Redis L2 in ASP.NET Core 11: register the service, add the StackExchange Redis distributed cache, and let GetOrCreateAsync give you a two-tier cache with built-in stampede protection and tag invalidation.

ASP.NET Core 11 has built-in validation for minimal APIs: call AddValidation, annotate your request record with DataAnnotations, and a source generator validates the bound model and returns 400 ProblemDetails before your handler runs. No controllers, no FluentValidation, no manual checks.

A step-by-step checklist to move a standalone Blazor Server app to the unified Blazor Web App template on .NET 11, keeping every page on InteractiveServer with zero behaviour change.

Pick BackgroundService for in-process loops, raw IHostedService when you need fine lifecycle control, and Hangfire when jobs must survive a restart. A decision matrix with code and the one gotcha that picks for you.

Calling Task.Run from a controller loses work on shutdown, swallows exceptions, and captures disposed scoped services. The safe pattern is a bounded Channel queue drained by a BackgroundService that opens a fresh scope per work item and drains in-flight work on StopAsync.

A BackgroundService is a singleton, so it cannot inject a scoped service like a DbContext directly. Take IServiceScopeFactory, open one scope per unit of work with CreateAsyncScope, resolve inside it, and dispose it when the work is done.

A version-pinned migration playbook for moving a .NET Framework 4.8 codebase to .NET 11 LTS in 2026, covering the SDK-style csproj rewrite, System.Web to ASP.NET Core, WCF, EF6 to EF Core 11, BinaryFormatter removal, AppDomain replacements, and a realistic rollback plan.

For any new Blazor app on .NET 11, scaffold a Blazor Web App (the template formerly nicknamed Blazor United) and pick render modes per page. Server-only and WebAssembly-only templates only still make sense in narrow cases.

.NET 11 Preview 4 makes ASP.NET Core OpenAPI generation recognize HTTP QUERY as a first-class operation in OpenAPI 3.2, with a graceful fallback for 3.0 and 3.1 documents.

Pick minimal APIs by default in ASP.NET Core 11. Use controllers only when you need MVC features that minimal APIs still do not match: convention-based routing across many actions, MVC-style filters, or Razor views.

Replace the Stream.Read or Write call with ReadAsync/WriteAsync. As a last resort, set AllowSynchronousIO on Kestrel, IIS, or per-request via IHttpBodyControlFeature.

ASP.NET Core's scope validation throws this when a singleton would capture a scoped dependency for the rest of the process. Make the consumer scoped, or take IServiceScopeFactory and create a scope on demand.

ASP.NET Core throws this when a constructor asks for a type that was never registered, was registered on the wrong container, or was added after the host was built. Three concrete fixes cover almost every case.

If GetConnectionString returns null in .NET 11, your appsettings.json is missing the key, not copied to the build output, or the wrong environment file is being selected. Three checks fix 95% of cases.

A complete guide to wiring Serilog 4.x and Seq 2025.2 into a .NET 11 ASP.NET Core app: AddSerilog vs UseSerilog, two-stage bootstrap logging, JSON configuration, enrichers, request logging, OpenTelemetry trace correlation, API keys, and the production gotchas around buffering, retention, and signal level.

Wire OpenTelemetry traces, metrics, and logs into a .NET 11 ASP.NET Core app with the OTLP exporter, then ship them to a free, self-hosted backend: the standalone Aspire Dashboard for local dev, Jaeger and SigNoz for self-hosted production, and the OpenTelemetry Collector when you need both.

A complete guide to per-endpoint rate limiting in ASP.NET Core 11: when to pick fixed window vs sliding window vs token bucket vs concurrency, how RequireRateLimiting and [EnableRateLimiting] differ, partitioning by user or IP, the OnRejected handler, and the distributed deployment pitfall everyone hits.

Stream Claude responses from an ASP.NET Core 11 minimal API end-to-end: the official Anthropic .NET SDK, TypedResults.ServerSentEvents, SseItem, IAsyncEnumerable, cancellation flow, and the gotchas that buffer your tokens silently. With Claude Sonnet 4.6 and Opus 4.7 examples.

Asp.Versioning 10.0 is the first release that targets .NET 10 and the new Microsoft.AspNetCore.OpenApi pipeline. Sander ten Brinke's April 23 walkthrough shows how to register one OpenAPI document per API version with WithDocumentPerVersion().

In .NET 11 the OpenAPI document is generated by Microsoft.AspNetCore.OpenApi and Swagger UI is no longer in the template. Here is how to wire Bearer, OAuth2 with PKCE, and OpenID Connect so the Authorize button actually works.

Two working paths in .NET 11: the built-in MapIdentityApi /refresh endpoint, and a custom JWT setup with refresh token rotation, family tracking, and reuse detection.

Upload multi-GB files to Azure Blob Storage from .NET 11 without loading them into memory. BlockBlobClient.UploadAsync with StorageTransferOptions, MultipartReader for ASP.NET Core uploads, and the buffering traps that put your payload on the LOH.

A complete .NET 11 walkthrough for shipping an ASP.NET Core minimal API with Native AOT: PublishAot, CreateSlimBuilder, source-generated JSON, the AddControllers limitation, IL2026 / IL3050 warnings, and EnableRequestDelegateGenerator for library projects.

A complete guide to global exception handling in ASP.NET Core 11: why IExceptionFilter is the wrong tool, how IExceptionHandler and UseExceptionHandler work together, ProblemDetails responses, multi-handler chains, and the .NET 10 diagnostics suppression breaking change.

Use Kiota, Microsoft's official OpenAPI code generator, to produce a fluent, strongly typed C# client from any OpenAPI spec. Step-by-step: install, generate, wire into ASP.NET Core DI, and handle authentication.

Serve large files from ASP.NET Core 11 without loading them into memory. Three tiers: PhysicalFileResult for on-disk files, Results.Stream for arbitrary streams, and Response.BodyWriter for generated payloads -- with code for each.

A HMAC validation flaw in Microsoft.AspNetCore.DataProtection 10.0.0 through 10.0.6 lets attackers forge ciphertexts. .NET 10.0.7 is the mandatory fix.

.NET 11 Preview 3 lets Kestrel serve HTTP/3 requests before the peer's control stream and SETTINGS frame arrive, shaving handshake latency off the first request on every new QUIC connection.

ASP.NET Core in .NET 11 Preview 3 teaches the Virtualize component to measure items at runtime, fixing the spacing and scroll jitter that uniform-height assumptions caused.

ASP.NET Core in .NET 11 Preview 2 brings TempData to Blazor static server-side rendering, enabling flash messages and Post-Redirect-Get flows without workarounds.

ASP.NET Core in .NET 11 Preview 2 adds OpenTelemetry semantic attributes directly to HTTP server activity, removing the need for OpenTelemetry.Instrumentation.AspNetCore.

Kestrel's HTTP/1.1 request parser in .NET 11 replaces BadHttpRequestException with a result struct, cutting malformed-request overhead by up to 40%.

A new project template in .NET 11 Preview 2 scaffolds the JS plumbing, WebWorkerClient, and JSExport boilerplate needed to run .NET code in a browser Web Worker.

If your Bearer token works in Postman but not in Scalar, the problem is likely your OpenAPI document. Here is how to declare a proper security scheme in .NET 10.

Fix the 'dotnet-ef does not exist' / 'dotnet ef command not found' error by installing the EF Core CLI as a global or local .NET tool.

Fix the 'Microsoft.NetCore.App or Microsoft.AspNetCore.App was not found' error by updating your Azure App Service stack and .NET runtime version.