Trellis.ServiceDefaults 3.0.0-alpha.342

Trellis.ServiceDefaults

Opinionated composition defaults for Trellis web services.

Installation

dotnet add package Trellis.ServiceDefaults

Quick Example

using Trellis.ServiceDefaults;

builder.Services.AddTrellis(options => options
    .UseAsp()
    .UseScalarValueValidation()
    .UseProblemDetails()
    .UseMediator()
    .UseFluentValidation(typeof(Program).Assembly)
    .UseClaimsActorProvider()
    .UseResourceAuthorization(typeof(Program).Assembly)
    .UseEntityFrameworkUnitOfWork<AppDbContext>());

UseEntityFrameworkUnitOfWork<TContext>() is always applied last so the transactional command behavior runs innermost. AddDbContext<TContext>(...) and AddMediator(...) remain application-owned registrations.

UseFluentValidation() and UseResourceAuthorization() both support no-assembly calls for explicit, no-scanning composition; pass assemblies only when you want Trellis to discover validators/resource loaders automatically.

UseScalarValueValidation() is independent of UseAsp() — it registers the scalar-value model binders, JSON converters, and SuppressModelStateInvalidFilter toggle that mutate global MvcOptions / JsonOptions for both MVC and Minimal API JSON pipelines. Hosts that only need error-to-status mapping (e.g. an MVC site that does not bind value-object DTOs) can call UseAsp() alone and skip the binder / converter wiring. Minimal API hosts must still call app.UseScalarValueValidation() middleware and chain .WithScalarValueValidation() per endpoint.

UseProblemDetails() is independent of UseAsp() — it registers Trellis ProblemDetails customization (traceId on every error, 405 Allow header projected as extensions.allow, 500 detail rewrite) without pulling in Trellis MVC/result-mapping infrastructure. Composing it with a direct services.AddTrellisProblemDetails() call is idempotent — exactly one Trellis post-configure layer ends up registered.

UseIdempotency(opt => ...) wires the opt-in IETF Idempotency-Key middleware (options + scope resolver + marker). Composition is explicit — the slot does not register a store, so callers add services.AddInMemoryIdempotencyStore() (dev / tests) or an EF-backed store (production) and mount the middleware with app.UseTrellisIdempotency(). Endpoints opt in with [Idempotent].

UseWorkerActor(systemActor) composes the previously selected actor provider with a worker/system fallback for background scopes that have no HttpContext. It applies after the actor-provider selection and caching wrap, so HTTP requests still resolve through the inner provider (and its cache) and BackgroundService ticks short-circuit to the supplied system actor.

AOT compatibility

Trellis.ServiceDefaults is AOT- and trim-compatible. The package enables the AOT and trim analyzers (IsAotCompatible, IsTrimmable, EnableAotAnalyzer, EnableTrimAnalyzer) and keeps the default composition slots safe when you choose explicit overloads.

AOT-safe builder shapes are UseFluentValidation() plus UseFluentValidation<TValidator, TMessage>() per validator, UseResourceAuthorization() plus UseResourceAuthorization<TMessage, TResource, TResponse>() per command, and UseDomainEvents() or UseTrackedAggregateDomainEvents() plus their <TEvent, THandler>() per-handler overloads.

The assembly-scanning overloads (UseFluentValidation(asm), UseResourceAuthorization(asm), UseDomainEvents(asm), UseTrackedAggregateDomainEvents(asm)) remain convenience APIs for non-AOT consumers. They are annotated with [RequiresUnreferencedCode] and [RequiresDynamicCode], so trimmed/AOT applications must either switch to explicit registrations or make that choice visible at the consumer call site, for example by annotating the composition method or suppressing the analyzer warning.

UseEntityFrameworkUnitOfWork<TContext>() is also annotated [RequiresUnreferencedCode] / [RequiresDynamicCode] because the EF Core integration depends on runtime reflection and is excluded from the Trellis AOT publish gate. AOT consumers can still use the ASP, Mediator, FluentValidation, and authorization slots through this builder, but should compose data access separately.

Part of Trellis

This package is part of the Trellis framework.