minimal-apis
Builds, reviews and fixes ASP.NET Core minimal APIs on .NET 10 (current LTS, checked on 10.0.14). Covers built-in request validation (AddValidation, DataAnnotations on records and parameters, nested p
SKILL.mdcatalog/skills/aspnet-core/minimal-apis/SKILL.md
GitHubASP.NET Core minimal APIs on .NET 10
.NET 10 is the current LTS (10.0.14, SDK 10.0.403, November 2026); .NET 11 is at RC and not GA.
Most minimal API examples on the web, and in model training data, are .NET 6 to 8. Several .NET 8
habits still compile on .NET 10 and quietly do something else. Everything marked measured below
was run on 10.0.14 in mcr.microsoft.com/dotnet/sdk:10.0.403.
1. Know what you are on
dotnet --version # SDK; global.json may pin it
grep -h "<TargetFramework" -r --include=*.csproj --include=*.props .
| You see | It means |
|---|---|
net10.0 |
Built-in validation, cookie 401/403 for API endpoints, TypedResults.ServerSentEvents, OpenAPI 3.1 by default. |
net9.0 |
No built-in validation. ExceptionHandlerOptions.StatusCodeSelector and built-in OpenAPI exist. |
net8.0 |
No built-in validation. IExceptionHandler, antiforgery for form binding, [AllowedValues]/[Length]. |
Microsoft.NET.Sdk.Web |
Web project. A plain Microsoft.NET.Sdk library needs <FrameworkReference Include="Microsoft.AspNetCore.App" /> to map endpoints. |
Don't add NuGet packages for things the framework now does (FluentValidation or MiniValidation just for request validation, a problem-details library). Follow the repo if it already uses one.
2. Request validation (.NET 10)
builder.Services.AddValidation(); // without this, DataAnnotations on minimal API parameters do nothing
public record CreateEventRequest(
[Required, MaxLength(120)] string? Title,
[Required] Venue? Venue,
[Required, Length(1, 10)] List<TicketTier>? Tiers,
SaleWindow? Sales);
public record TicketTier([Required] string? Name, [Range(0, 1_000_000)] int PriceCents);
public record SaleWindow([Required] DateTimeOffset? Opens, [Required] DateTimeOffset? Closes) : IValidatableObject
{
public IEnumerable<ValidationResult> Validate(ValidationContext context)
{
if (Closes <= Opens) yield return new("Sales must close after they open.", [nameof(Closes)]);
}
}
app.MapPost("/api/events", (CreateEventRequest request, EventStore store) => { /* only valid requests get here */ });
app.MapGet("/api/events", ([Range(1, 50)] int limit = 10) => /* ... */);
What it does (measured):
- Validates query, header and body parameters before the handler runs, recursing into nested objects and collection items. Attributes on positional record parameters work.
- A failure is a 400
application/problem+jsonHttpValidationProblemDetails, all errors at once:{"title":"One or more validation errors occurred.","status":400,"errors":{"Venue.Capacity":[...],"Tiers[1].PriceCents":[...]}}. - Keys are C# member paths in PascalCase (
Tiers[1].PriceCents), or the parameter name for a top-level parameter (limit). They ignore the JSON naming policy and[JsonPropertyName], so a camelCase body produces PascalCase keys. If clients need JSON names, say so in the contract, match case-insensitively, or rewrite the keys inAddProblemDetails(o => o.CustomizeProblemDetails = ...), which also runs for validation responses. - Order inside an object: property attributes, then type-level attributes, then
IValidatableObject.Validate. Any property error skipsValidate, so a cross-field error only appears once the fields themselves are valid. .DisableValidation()turns it off for one endpoint. Unknown JSON properties are not rejected; setJsonSerializerOptions.UnmappedMemberHandling = Disallowif you need that.
The trap: the generator only sees its own assembly
AddValidation() is backed by a source generator that emits metadata for the endpoints and types in
the assembly that calls it. Endpoints mapped from a class library (a feature module with its own
MapVenuesModule()) are not validated when only the host calls AddValidation(), with no
error, warning or log (measured). Fix it in the library:
// Ticketing.Venues (class library with <FrameworkReference Include="Microsoft.AspNetCore.App" />)
public static IServiceCollection AddVenuesModule(this IServiceCollection services)
{
services.AddValidation(); // generator runs for this assembly's endpoints and types
services.AddSingleton<VenueDirectory>();
return services;
}
- Keep the host's own
AddValidation()too: the registrations compose, and removing the host call stops validation of the host's endpoints (measured). [ValidatableType]on the library type does not help while the library never callsAddValidation()(measured); it is also experimental in .NET 10 (ASP0029).- Attributes directly on simple handler parameters (
[Range] int seats) are still checked in that case; complex types are what silently go unvalidated. Always prove it with a test that posts an invalid body to the module's endpoint. - A library without the ASP.NET Core framework reference needs the
Microsoft.Extensions.Validationpackage for the generator (docs).
DataAnnotations gotchas
[Required] int Quantitynever fails: a missing JSON number binds to 0. Use[Range(1, ...)], orint?with[Required].- .NET 10 known issue: attributes on a nullable value-type handler parameter
(
[Range(1, 50)] int? limit) are not checked when the value is null (dotnet/aspnetcore#67033). Validator.TryValidateObjectis not a substitute. It reads property attributes only, so it ignores attributes on positional record parameters, and it never recurses into nested objects or lists (measured: every rule on a record request silently passed).[EmailAddress]only checks for one@that is neither first nor last.[Phone]is loose too.[RegularExpression]must match the whole value.[AllowedValues("a", "b")],[DeniedValues]and[Length(min, max)](strings and collections) exist since .NET 8;[MaxLength]/[MinLength]also count collection items.
On .NET 8 or 9 there is no built-in validation: validate in the handler or an endpoint filter and
return TypedResults.ValidationProblem(errors), walking nested objects yourself. Details and the
error-key rewrite: references/validation.md.
3. Results: return types are API surface
- Prefer
TypedResultsoverResults.TypedResults.Ok(x)isOk<T>;Results.Ok(x)is an opaqueIResult. Typed results feed OpenAPI and, on .NET 10, mark the endpoint as an API for cookie auth (section 5). - Branching handlers declare a union:
Results<Ok<Ticket>, NotFound, Conflict<ProblemDetails>> (...) =>. A lambda whose branches return different typed results needs that explicit return type. TypedResults.ValidationProblem(dict)andTypedResults.Problem(...)write problem details.- Don't return bare strings from JSON APIs: they are
text/plainand are not treated as API endpoints.
4. Errors: problem details, never internals
builder.Services.AddProblemDetails(); // IProblemDetailsService: RFC 9457 bodies with traceId
builder.Services.AddExceptionHandler<DomainExceptionHandler>(); // optional: map known exceptions
var app = builder.Build();
app.UseExceptionHandler(); // 500 problem details, no exception text
app.UseStatusCodePages(); // bodies for empty 4xx/5xx responses (401, 403, 404)
UseExceptionHandler()withoutAddProblemDetails()(or a handler path) throws at startup (measured).- With
UseExceptionHandler(), an unexpected exception gives a generic 500 in every environment. Without it, the Development environment's developer exception page returns the exception message and stack trace as problem details (measured). Never run production as Development. - Map expected failures explicitly: an
IExceptionHandlerthat returnstrueafter writing a problem (IProblemDetailsService.TryWriteAsync), orStatusCodeSelector(.NET 9+) for status only. Only putex.Messageindetailfor exceptions you wrote for clients. - .NET 10 no longer logs exceptions that an
IExceptionHandlerhandled; useExceptionHandlerOptions.SuppressDiagnosticsCallbackif you want those logs.
More in references/errors-and-results.md.
5. Authorization and cookies
Deny by default. An endpoint without authorization metadata is anonymous unless a fallback policy exists:
builder.Services.AddAuthorizationBuilder()
.AddPolicy("finance", p => p.RequireRole("finance"))
.SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build());
app.MapGet("/healthz", () => TypedResults.Ok()).AllowAnonymous();
payouts.MapPost("/{id}/approve", ApprovePayout).RequireAuthorization("finance");
FallbackPolicy applies to endpoints with no [Authorize]/RequireAuthorization/AllowAnonymous;
DefaultPolicy is what a bare RequireAuthorization() means. Group-level RequireAuthorization()
protects only that group, not endpoints mapped elsewhere later.
Cookie authentication on .NET 10 answers 401/403 instead of redirecting only for endpoints
carrying IDisableCookieRedirectMetadata. Measured on 10.0.14 with a signed-out request:
| Handler returns | Response |
|---|---|
TypedResults.Ok/Created/NoContent/NotFound, Results<...>, a POCO, or reads a JSON body |
401 |
Results.Ok(...), Results.NoContent() and other IResult |
302 to the login page |
string, TypedResults.Text(...), TypedResults.Content(...) |
302 to the login page |
So "it's .NET 10, APIs get 401 now" is wrong for half a typical codebase. Make it explicit for the whole API surface, and keep redirects for HTML pages:
var api = app.MapGroup("/api").DisableCookieRedirect(); // .NET 10: 401/403 for everything under it
// or, independent of how endpoints are mapped:
options.Events.OnRedirectToLogin = ctx => RejectOrRedirect(ctx, StatusCodes.Status401Unauthorized);
options.Events.OnRedirectToAccessDenied = ctx => RejectOrRedirect(ctx, StatusCodes.Status403Forbidden);
static Task RejectOrRedirect(RedirectContext<CookieAuthenticationOptions> ctx, int status)
{
if (ctx.Request.Path.StartsWithSegments("/api")) ctx.Response.StatusCode = status;
else ctx.Response.Redirect(ctx.RedirectUri);
return Task.CompletedTask;
}
- The 401/403 body is empty unless
UseStatusCodePages()(withAddProblemDetails()) runs before authentication, or you write a problem yourself. .AllowCookieRedirect()or[AllowCookieRedirect]opts an endpoint back into redirects.- Requests with
X-Requested-With: XMLHttpRequestalways got 401/403;fetch()doesn't send it.
Forms. An endpoint that binds [FromForm], IFormFile or IFormCollection requires
AddAntiforgery() and app.UseAntiforgery() (after authentication and authorization); without
the middleware it fails with a 500 InvalidOperationException (measured). Don't DisableAntiforgery()
on cookie-authenticated forms. Details: references/auth.md.
6. Test it through HTTP
public sealed class ApiFactory : WebApplicationFactory<Program>
{
protected override void ConfigureWebHost(IWebHostBuilder b) => b.UseEnvironment("Production");
}
var client = factory.CreateClient(new() { AllowAutoRedirect = false }); // see 302s as 302s
- On .NET 10 the top-level
Programclass is public;public partial class Program;is only needed for older target frameworks. - xunit.v3 4.x runs on Microsoft.Testing.Platform v2, which the .NET 10 SDK's
dotnet testonly drives in MTP mode: add"test": { "runner": "Microsoft.Testing.Platform" }toglobal.json, ordotnet testfails with "Testing with VSTest target is no longer supported" (measured). Then rundotnet test --project tests/Foo.Tests. - Assert status,
Content-Type(application/problem+json) and theerrorskeys, and test the module endpoints too, not only the host's. See references/testing.md.
Review checklist
-
AddValidation()is called in every assembly that maps endpoints or declares request types; a test posts an invalid body to each module. - Rules are attributes on the bound records/parameters, nested types included; no
[Required]on non-nullable value types; cross-field rules inIValidatableObject. - Error keys match what clients expect (PascalCase member paths by default).
-
AddProblemDetails+UseExceptionHandler+UseStatusCodePages; no exception text for unexpected errors; expected errors mapped to 4xx problems. - A fallback policy requires an authenticated user; public endpoints say
AllowAnonymous. - Cookie-authenticated APIs return 401/403 for every endpoint (
DisableCookieRedirecton the API group or path-based events), and pages still redirect. - Handlers return
TypedResults(unions when branching), not bare strings orResults.*. - Form endpoints have antiforgery middleware.
- No new packages for features the framework has.
More
- references/validation.md: rules, keys, multi-assembly setup, .NET 8/9 fallback.
- references/errors-and-results.md: problem details, exception handlers, typed results.
- references/auth.md: fallback policies, cookie redirects, JWT, antiforgery.
- references/testing.md: WebApplicationFactory, xunit v3 on MTP, offline restore.
- references/sources.md: documentation and experiments behind every claim.