Trellis.ServiceDefaults API Reference

Package: Trellis.ServiceDefaults
Namespace: Trellis.ServiceDefaults
Purpose: Opinionated composition builder for API/composition-root projects that want Trellis integration modules applied in the canonical order.

See also: trellis-api-cookbook.md — composition-root recipe.

Use this file when

You are wiring a composition root and want Trellis modules applied in the canonical order.
You want one fluent builder for ASP, Mediator, FluentValidation, resource authorization, actor provider, and EF unit-of-work registration.
You need to know what AddTrellis(...) deliberately does not register.

Patterns Index

Goal	Canonical API / pattern	See
Enable ASP Result-to-HTTP mapping	`services.AddTrellis(o => o.UseAsp())`	`TrellisServiceBuilder`, ASP
Add standard mediator behaviors	`.UseMediator()`	`TrellisServiceBuilder`, Mediator
Add FluentValidation adapter/scanning	`.UseFluentValidation(typeof(Program).Assembly)` or `.UseFluentValidation()`	`TrellisServiceBuilder`, FluentValidation
Add resource authorization	`.UseResourceAuthorization(...)`	`TrellisServiceBuilder`, Mediator resource authorization
Register an actor provider	`.UseClaimsActorProvider()`, `.UseEntraActorProvider()`, or `.UseDevelopmentActorProvider()`	`TrellisServiceBuilder`, ASP actor providers
Add EF unit-of-work behavior	`.UseEntityFrameworkUnitOfWork<TContext>()`	`TrellisServiceBuilder`, Mediator UoW

Common traps

AddTrellis(...) does not register DbContext, Mediator handlers, route constraints, or app-specific validators.
UseEntityFrameworkUnitOfWork<TContext>() is applied last so transaction commit remains innermost in the mediator pipeline.
If you only need one module, direct package-specific registration remains valid; the builder is for composition-root clarity.

Types

`TrellisServiceCollectionExtensions`

public static class TrellisServiceCollectionExtensions

Signature	Returns	Description
`public static IServiceCollection AddTrellis(this IServiceCollection services, Action<TrellisServiceBuilder> configure)`	`IServiceCollection`	Creates a `TrellisServiceBuilder`, lets the caller select modules, then applies the selected modules in canonical order. Does not register `DbContext` or Mediator handlers.

`TrellisServiceBuilder`

public sealed class TrellisServiceBuilder

Signature	Returns	Description
`public TrellisServiceBuilder UseAsp(Action<TrellisAspOptions>? configure = null)`	`TrellisServiceBuilder`	Registers `Trellis.Asp` integration via `AddTrellisAsp(...)`.
`public TrellisServiceBuilder UseMediator(Action<TrellisMediatorTelemetryOptions>? configureTelemetry = null)`	`TrellisServiceBuilder`	Registers Trellis Mediator behaviors via `AddTrellisBehaviors(...)`.
`public TrellisServiceBuilder UseFluentValidation(params Assembly[] assemblies)`	`TrellisServiceBuilder`	Registers the FluentValidation adapter. When assemblies are supplied, also scans them for validators. Implies `UseMediator()`.
`public TrellisServiceBuilder UseResourceAuthorization(params Assembly[] assemblies)`	`TrellisServiceBuilder`	Registers resource authorization behaviors/loaders discovered in assemblies. With no assemblies, enables the mediator pipeline for explicit resource-authorization registrations without scanning. Implies `UseMediator()`.
`public TrellisServiceBuilder UseClaimsActorProvider(Action<ClaimsActorOptions>? configure = null)`	`TrellisServiceBuilder`	Registers `ClaimsActorProvider` as `IActorProvider`.
`public TrellisServiceBuilder UseEntraActorProvider(Action<EntraActorOptions>? configure = null)`	`TrellisServiceBuilder`	Registers `EntraActorProvider` as `IActorProvider`.
`public TrellisServiceBuilder UseDevelopmentActorProvider(Action<DevelopmentActorOptions>? configure = null)`	`TrellisServiceBuilder`	Registers `DevelopmentActorProvider` as `IActorProvider`. Use only in development/testing hosts.
`public TrellisServiceBuilder UseEntityFrameworkUnitOfWork<TContext>() where TContext : DbContext`	`TrellisServiceBuilder`	Registers `EfUnitOfWork<TContext>` and `TransactionalCommandBehavior<,>` via `AddTrellisUnitOfWork<TContext>()`. Implies `UseMediator()` and is applied last.

Behavior

AddTrellis(...) records selected modules first and then applies them in this order:

ASP integration.
Actor provider.
Mediator behaviors.
Resource authorization.
FluentValidation adapter/scanning when selected.
EF Core Unit of Work.

That order preserves the important pipeline invariant: TransactionalCommandBehavior<,> is the innermost behavior, closest to the handler, so commit failures remain visible to outer logging/tracing/exception behaviors.

AddTrellis(...) deliberately does not register:

AddDbContext<TContext>(...) — provider, connection string, pooling, migrations, and interceptors are application-owned.
AddMediator(...) — handler discovery/source-generator configuration is application-owned.
route constraints — route parameter names are application-owned.

Examples

services.AddTrellis(options => options.UseAsp());

services.AddTrellis(options => options
    .UseAsp()
    .UseMediator()
    .UseFluentValidation(typeof(Program).Assembly));

// Adapter only; validators are registered explicitly elsewhere.
services.AddTrellis(options => options
    .UseMediator()
    .UseFluentValidation());

// No assembly scanning; resource authorization registrations are explicit elsewhere.
services.AddTrellis(options => options
    .UseMediator()
    .UseResourceAuthorization());

services.AddTrellis(options => options
    .UseAsp()
    .UseMediator()
    .UseClaimsActorProvider()
    .UseResourceAuthorization(typeof(Program).Assembly)
    .UseEntityFrameworkUnitOfWork<AppDbContext>());