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.md

GitHub

ASP.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+json HttpValidationProblemDetails, 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 in AddProblemDetails(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 skips Validate, 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; set JsonSerializerOptions.UnmappedMemberHandling = Disallow if 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 calls AddValidation() (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.Validation package for the generator (docs).

DataAnnotations gotchas

  • [Required] int Quantity never fails: a missing JSON number binds to 0. Use [Range(1, ...)], or int? 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.TryValidateObject is 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 TypedResults over Results. TypedResults.Ok(x) is Ok<T>; Results.Ok(x) is an opaque IResult. 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) and TypedResults.Problem(...) write problem details.
  • Don't return bare strings from JSON APIs: they are text/plain and 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() without AddProblemDetails() (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 IExceptionHandler that returns true after writing a problem (IProblemDetailsService.TryWriteAsync), or StatusCodeSelector (.NET 9+) for status only. Only put ex.Message in detail for exceptions you wrote for clients.
  • .NET 10 no longer logs exceptions that an IExceptionHandler handled; use ExceptionHandlerOptions.SuppressDiagnosticsCallback if 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() (with AddProblemDetails()) runs before authentication, or you write a problem yourself.
  • .AllowCookieRedirect() or [AllowCookieRedirect] opts an endpoint back into redirects.
  • Requests with X-Requested-With: XMLHttpRequest always 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 Program class 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 test only drives in MTP mode: add "test": { "runner": "Microsoft.Testing.Platform" } to global.json, or dotnet test fails with "Testing with VSTest target is no longer supported" (measured). Then run dotnet test --project tests/Foo.Tests.
  • Assert status, Content-Type (application/problem+json) and the errors keys, 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 in IValidatableObject.
  • 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 (DisableCookieRedirect on the API group or path-based events), and pages still redirect.
  • Handlers return TypedResults (unions when branching), not bare strings or Results.*.
  • Form endpoints have antiforgery middleware.
  • No new packages for features the framework has.

More