DKNet.AspCore.Extensions 13.1.2

DKNet.AspCore.Extensions

The minimal-API glue for DKNet-based ASP.NET Core web APIs: claim-backed request binding, versioned endpoint-group discovery, one-line SlimMessageBus mapping helpers, a shared paging envelope, and FluentResults-to-IResult/ProblemDetails conversion.

Installation

dotnet add package DKNet.AspCore.Extensions

Features

• Contextual request binding — [FromClaim] (and any custom IContextualSource) populates a request property from the authenticated caller before validation and before the handler runs, so it can never be forged through the request body or querystring; automatically excluded from the published OpenAPI description.
• Header-sourced request members — [FromRequestHeader("Idempotency-Key")] fills a request property from a named HTTP request header through that same mechanism and the same AddContextualRequestPopulation() registration. The header is published as an in: header operation parameter (a claim-filled member is hidden instead), a missing header is never a refusal, and — unlike a claim — a header is supplied by the caller, so it is a binding convenience, never an authorization signal.
• Endpoint group discovery — implement IEndpointConfig per feature area and let UseEndpointConfigs() discover, version, tag, and authorize every group across your assemblies.
• Fluent minimal-API mappers — MapPost/MapPut/MapPatch/MapDelete/MapGet/MapGetPage wire a verb straight onto a SlimMessageBus fluent command/query, plus generic MapGetById/ MapGetList/MapDeleteById backed by DKNet.EfCore.Specifications.
• PagedResponse<T> — a shared paging envelope (PageNumber, PageSize, PageCount, TotalItemCount, Items, HasNextPage, HasPreviousPage) used by every paged endpoint.
• Result/ProblemDetails conversion — Response()/Response<T>() turn a FluentResults outcome into the right minimal-API IResult, and are the only public path onto the standard error body. They resolve the host's registered error-response setting themselves, so an endpoint never has to name it — and cannot skip it.
• One error-response setting — AddErrorResponses() registers a single ErrorResponseOptions that shapes all three ways a request can fail: a failed command handler, input a validator refused, and an unhandled exception. One body shape for all three, one status rule set, and no second registration — the call wires the exception handling for you.

Quick Start

Register the pieces you need and let UseEndpointConfigs do the mapping:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorization();
builder.Services.AddApiVersioning();
builder.Services.AddContextualRequestPopulation(); // powers [FromClaim] and friends

var app = builder.Build();
app.UseEndpointConfigs(); // discovers every IEndpointConfig across the loaded assemblies
app.Run();

using System.Security.Claims;
using DKNet.AspCore.Extensions;
using DKNet.AspCore.Extensions.ModelBinding;
using DKNet.SlimBus.Extensions;

public sealed record CreateProductCommand : Fluents.Requests.IWitResponse<ProductModel>
{
    public string Name { get; init; } = string.Empty;

    [FromClaim(ClaimTypes.NameIdentifier)]
    public string? CreatedBy { get; set; } // always resolved from the caller's claim, never from the body

    [FromRequestHeader("Idempotency-Key")]
    public string? IdempotencyKey { get; set; } // always resolved from the request header, never from the body
}

public sealed class ProductsEndpointConfig : IEndpointConfig
{
    public string GroupEndpoint => "/products";

    public void Map(RouteGroupBuilder group) =>
        group.MapPost<CreateProductCommand, ProductModel>("/");
}

POST /v1/products now dispatches CreateProductCommand through IMessageBus, resolves CreatedBy from the caller's claim before the handler runs, and returns 201 Created (the mapper infers "Created" from the command's type name) with a FluentResults-derived ProblemDetails body on failure.

IdempotencyKey is filled the same way, from the Idempotency-Key request header — the same registration, no route-level code. Header-name matching is case-insensitive, and a header sent more than once fills the member with the first value sent. Three things to know before you rely on it:

• A missing header is not a refusal. The member holds its type's default and the request is still dispatched. Requiring a header stays the job of a filter or a validator.
• There is no built-in fallback value. An absent header always leaves the member's type default. CanResolve keys on the attribute type, and population consults only the first matching resolver — never more than one. A host that wants a value of its own instead must register a resolver that performs the header lookup itself and substitutes only when it comes back empty (httpContext.Request.Headers.TryGetValue(...) ... ?? "system-account"); registering one ahead of AddContextualRequestPopulation() replaces the built-in resolver for that attribute entirely, for every request declaring it, not only the ones missing the header. If the constant it substitutes is the same for every caller who omits the header, that matters if you use the member as an idempotency key.
• A header is never an authorization signal. Unlike a claim, a header is supplied by the caller. The declaration is a binding convenience; a service that treated it as proof of identity would be trusting the caller.

Unlike [FromClaim], the header is advertised in the published OpenAPI operation as an in: header parameter — the caller has to know to send it — while the member itself stays absent from the published request body.

MapDeleteById<TEntity> hard-deletes an IEntity<Guid> by id without a command or handler:

group.MapDeleteById<ProductEntity>("/{id}");

DELETE /v1/products/{id} loads the entity via IRepositorySpec, removes it through Delete/SaveChangesAsync (so audit-log and domain-event hooks fire as usual), and returns 204 No Content, 404 when no entity matches, or 409 when a referencing row blocks the removal. Authorization is inherited from the route group the endpoint is registered into — the handler performs no ownership or tenancy check of its own.

Migration — namespace changes in this release

Root types were grouped into concern folders; the namespace of each moved type now ends with its folder name. This is an import-only source break: no type was renamed, removed, resignatured, or had its behaviour changed — update the using line and you're done.

IEndpointConfig — the package's entry surface — stays at DKNet.AspCore.Extensions.

FromRequestHeaderAttribute is new in this release rather than moved, and ships in DKNet.AspCore.Extensions.ModelBinding alongside FromClaimAttribute.

Customisation reference

Three options types, plus the type parameters and attributes that make up the rest of the public surface. Defaults are the ones the code applies when you pass nothing.

AddContextualRequestPopulation() takes no configure delegate and has no options of its own — a declared member the registered resolvers cannot resolve always holds its type's default. Supply a value of your own by registering a custom IContextualValueResolver before AddContextualRequestPopulation() (see Quick Start above).

EndpointRegistrationOptions — app.UseEndpointConfigs(Action<EndpointRegistrationOptions>?, params Assembly[]):

ErrorResponseOptions — services.AddErrorResponses(Action<ErrorResponseOptions>?). The one place a host shapes error responses, covering all three failure kinds: a failed command handler, refused validation input, and an unhandled exception. It is the host's only step — do not add a UseExceptionHandler() line or an AddProblemDetails() call of your own; AddErrorResponses makes both for you, and calling it twice is a no-op (the first call's configure wins). Every knob is host-wide, applying to every route:

Each callback receives an ErrorResponseContext: Source (Command, Validation or Unhandled), Errors — a list of ErrorItem(Message, Code?, Field?) — and Exception, the raised exception for Unhandled only. Code is the FluentResults error's "Code" metadata entry for a command failure and the validation failure's ErrorCode for refused input; Field names the refused input member and is always null otherwise.

All three failure kinds answer with the same body:

{
  "title": "Error",
  "status": 409,
  "type": "Conflict",
  "traceId": "00-...-00",
  "errors": [ { "message": "...", "code": "precondition", "field": null } ]
}

type is always the final response status' name, recomputed after StatusCode runs — it never names an exception type. There is no detail member. Outside the Development environment an unhandled exception's errors carries one fixed message and nothing the exception itself carried; inside Development that entry carries the exception's own message.

An exception raised inside an endpoint one of the fluent mappers registered is caught by the endpoint filter ProducesCommons() adds; every other unhandled exception is caught by the IExceptionHandler AddErrorResponses registers. An endpoint registered without ProducesCommons() is covered in Production, but in Development still answers with ASP.NET Core's developer exception page — chain .ProducesCommons() onto it to put it on the same path.

Mapping a failure code to a status, and supplying your own body for an unhandled exception:

using DKNet.AspCore.Extensions.Responses;
using Microsoft.AspNetCore.Mvc;

builder.Services.AddErrorResponses(o =>
{
    o.StatusCode = ctx => ctx.Errors.Any(e => e.Code == "precondition") ? 409 : null;

    o.UnhandledError = ctx => new ProblemDetails
    {
        Status = StatusCodes.Status503ServiceUnavailable,
        Title = "Error",
        Extensions = { ["retryDelaySeconds"] = 30 }
    };
});

IEndpointConfig — what each implementation supplies:

ListQueryOptions — services.AddListQueryOptions(Action<ListQueryOptions>?), or bind the DKNet:ListQuery configuration section with services.Configure<ListQueryOptions>(…). Global to the host, not per endpoint:

AddListQueryOptions binds no configuration itself — it adds ValidateDataAnnotations().ValidateOnStart(), so a value below 1 fails the host at start-up. Both calls are optional: with neither, the defaults above apply.

ListQueryRequest — the query string every MapGetList endpoint accepts:

Only fields the returned model declares can be filtered, searched or sorted; anything else is rejected with 400 rather than silently ignored.

fromDate/toDate bound the listing by activity: a record is in range when either its CreatedOn or its UpdatedOn moment falls inside the bounds, so a record edited recently stays listed however old it is, and a record never updated is matched on CreatedOn alone. Naming either bound replaces the default window entirely and is open-ended on the side left out — fromDate=0001-01-01T00:00:00Z is how a caller asks for all history. fromDate later than toDate is a 400. Listed types that carry no audit timestamps ignore both bounds rather than rejecting them.

Attributes and other extension points:

Full Documentation

See the full feature guide for contextual-source resolvers, EndpointRegistrationOptions, all fluent mappers, paging details, and gotchas.

License

MIT — see LICENSE.

About

Developed by Steven Hoang.