Dotnet WebApi Util

Architecture

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Architecture

This page shows how the pieces of ArturRios.Util.WebApi fit together: the request pipeline, the security model, the response envelope, and the design principles that hold them together.

Request pipeline

The library is a thin layer around the standard ASP.NET Core pipeline. WebApiStartup builds the WebApplicationBuilder/WebApplication and exposes AddMiddlewares(Type[]), which registers each given middleware type on the app in the order supplied, skipping any type that isn’t a WebApiMiddleware. A typical setup registers the three built-in middlewares in this order:

flowchart LR
Client["Client request"] --> Trace["TraceActivityMiddleware<br/><i>assigns/propagates W3C traceparent</i>"]
Trace --> Exception["ExceptionMiddleware<br/><i>catches unhandled exceptions</i>"]
Exception --> Auth["AuthenticationMiddleware<br/><i>validates token, attaches AuthenticatedUser</i>"]
Auth --> Endpoint["Controller / endpoint"]
Endpoint --> Resolver["ResponseResolver<br/><i>Output envelope → ActionResult</i>"]
Resolver --> Client

WebApiMiddleware is an abstract marker base class with no members — its only job is to let AddMiddlewares recognize which types are safe to register with App.UseMiddleware(...):

AddMiddlewares([
 typeof(TraceActivityMiddleware),
 typeof(ExceptionMiddleware),
 typeof(AuthenticationMiddleware)
]);

Because registration order is registration order, TraceActivityMiddleware runs first so the trace id is available to everything downstream (including exception logging), ExceptionMiddleware runs next so it can catch exceptions thrown by authentication or the endpoint itself, and AuthenticationMiddleware runs last of the three so only requests that pass tracing/exception setup pay for token validation.

See Middleware & Diagnostics for what TraceActivityMiddleware and ExceptionMiddleware do in detail, and Configuration for the full WebApiStartup lifecycle.

Security model

AuthenticationMiddleware extracts a token (from the header, a cookie, or either, per AuthenticationOptions.Source) and validates it on every request that isn’t a Swagger route or an [AllowAnonymous] endpoint. Which token schemes are tried, and how, depends on AuthenticationOptions (registered via AddTokenAuthentication):

flowchart TB
Token["Extracted token"] --> Jwt{"EnableJwt?"}
Jwt -- "yes" --> JwtValid{"Signature valid?"}
JwtValid -- "no" --> Google
JwtValid -- "yes" --> Mode{"JwtMode"}
Mode -- "ClaimsOnly (default)" --> Claims["AuthenticatedUserFactory.FromToken<br/><i>id + role claims, no lookup</i>"]
Mode -- "Revalidate" --> ProviderId["IAuthenticationProvider.GetAuthenticatedUserById<br/><i>resolved per-request from RequestServices</i>"]
Jwt -- "no" --> Google{"EnableGoogle?"}
Google -- "yes" --> GoogleValid{"Google ID token valid?"}
GoogleValid -- "yes" --> ProviderEmail["IAuthenticationProvider.GetAuthenticatedUserByEmail"]
GoogleValid -- "no" --> R401["401 Unauthorized"]
Google -- "no" --> R401
ProviderId -.-> Cached["CachedAuthenticationProvider<br/><i>IMemoryCache, Ttl / CacheMisses</i>"]
ProviderEmail -.-> Cached
Cached -.-> ProviderId
Cached -.-> ProviderEmail
Claims --> Items["HttpContext.Items[User]"]
ProviderId --> Items
ProviderEmail --> Items
Items --> Authorize["AuthorizeAttribute<br/><i>401 if no user</i>"]
Authorize --> RoleReq["RoleRequirementFilter<br/><i>403 if role not authorized</i>"]
RoleReq --> Endpoint["Controller action"]

For the app JWT scheme, ClaimsOnly (the default) never touches a data store — the user is rebuilt straight from the token’s id and role claims, so authentication costs nothing beyond the signature check. Revalidate instead resolves IAuthenticationProvider from the current request’s HttpContext.RequestServices and calls GetAuthenticatedUserById on every request, trading a lookup for freshness. The Google scheme always resolves the user via IAuthenticationProvider.GetAuthenticatedUserByEmail after verifying the token, so an IAuthenticationProvider is required whenever Google authentication is enabled, just as it is for JWT Revalidate. CachedAuthenticationProvider sits transparently in front of any IAuthenticationProvider (registered via AddCachedAuthenticationProvider<T>) to absorb repeated lookups of the same user within a short TTL, without any mode needing to know it’s there.

AuthorizeAttribute and RoleRequirementFilter both read the same HttpContext.Items["User"] slot that AuthenticationMiddleware populates, and both honor [AllowAnonymous] by short-circuiting before checking it.

See Security for the full authentication and authorization reference.

Response envelopes

Endpoints return an ArturRios.Output envelope rather than throwing on failure. ProcessOutput carries success/error/message state; DataOutput<T> adds a typed payload on top of it:

classDiagram
class ProcessOutput {
+bool Success
+List~string~ Messages
+List~string~ Errors
+WithError(string) ProcessOutput
}
class DataOutput~T~ {
+T Data
+WithData(T) DataOutput~T~
}
class PaginatedOutput~T~ {
+int Page
+int PageSize
+int TotalCount
}
ProcessOutput <|-- DataOutput
DataOutput <|-- PaginatedOutput

ResponseResolver.Resolve(...) maps any of ProcessOutput, DataOutput<T> or PaginatedOutput<T> onto an ActionResult, defaulting the HTTP status to 200 when Success is true and 400 otherwise, unless an explicit statusCode is supplied:

[HttpGet("{id:int}")]
public ActionResult<DataOutput<UserDto?>> GetById(int id)
{
 DataOutput<UserDto?> output = _userService.GetById(id);

 return ResponseResolver.Resolve(output);
}

See Responses for the full mapping reference.

Design principles

Envelopes, not exceptions. Endpoints report failure through ProcessOutput/DataOutput<T> and let ResponseResolver pick the status code; ExceptionMiddleware is the safety net for anything that still escapes as a thrown exception, not the primary error-reporting path.
Stateless by default, revalidating when you need it. JwtValidationMode.ClaimsOnly is the default because most requests don’t need a fresh database read on every call; Revalidate (optionally cached) is there for the cases where staleness — instead of an expired token — is the risk you can’t accept.
Small, focused middlewares. Each of TraceActivityMiddleware, ExceptionMiddleware and AuthenticationMiddleware does exactly one thing and derives from the WebApiMiddleware marker so it can be composed via AddMiddlewares in whatever order a given host needs.
Consistent InvokeAsync. Every middleware follows the standard ASP.NET Core convention — a constructor capturing RequestDelegate next plus other dependencies, and a single InvokeAsync(HttpContext) method — so custom middlewares slot into AddMiddlewares the same way the built-in ones do.
DI-first. Dependencies such as IAuthenticationProvider, AuthenticationOptions, the ITokenValidators and SettingsProvider are resolved through the container (constructor injection or, for per-request freshness, HttpContext.RequestServices) rather than passed around manually.

Where to next

Configuration — the WebApiStartup lifecycle and WebApiParameters.
Security — JWT validation modes, caching, and role-based authorization in depth.
Middleware & Diagnostics — exception handling and distributed tracing.
HTTP Client — building typed clients on top of BaseWebApiClient.
Responses — the full ResponseResolver mapping reference.
Endpoint Toggling — enabling or disabling individual endpoints from code or configuration.

Configuration

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Configuration

WebApiStartup is the abstract base class you derive from to bootstrap an ASP.NET Core host: configuration loading, Swagger, the middleware pipeline and the invalid-model-state response all go through a small set of methods on it, some of which you must implement and some of which are optional hooks.

The lifecycle

flowchart TB
New["new Startup(args)<br/><i>builds WebApplicationBuilder + WebApiParameters</i>"] --> Build["Build() — abstract, you implement it"]
Build --> LoadConfig["LoadConfiguration()"]
Build --> InvalidModel["AddCustomInvalidModelStateResponse()"]
Build --> SwaggerGen["UseSwaggerGen(...)"]
Build --> Deps["AddDependencies() — virtual hook"]
Build --> BuildApp["BuildApp() — builds App from Builder"]
Build --> ConfigureApp["ConfigureApp() — abstract, you implement it"]
ConfigureApp --> Middlewares["AddMiddlewares([...])"]
ConfigureApp --> Swagger["UseSwagger(...)"]
ConfigureApp --> Map["App.MapControllers() / endpoints"]
New --> Run["Run() or BuildAndRun()"]

Build() and ConfigureApp() are abstract — you must implement both. Everything else on WebApiStartup is either a plain helper method you call from inside them, or a virtual no-op hook you can override:

Member	Kind	Purpose
`Build()`	abstract	The full startup sequence: configuration, services, `BuildApp()`, then `ConfigureApp()`.
`ConfigureApp()`	abstract	Configures the built `App`’s request pipeline (middlewares, Swagger UI, endpoint mapping).
`AddDependencies()`	virtual hook	Override to register your own services. No-op by default.
`ConfigureCors()`	virtual hook	Override to enable and configure CORS. No-op by default.
`ConfigureSecurity()`	virtual hook	Override to configure authentication/authorization services. No-op by default.
`ConfigureWebApi()`	virtual hook	Override to configure web-API-specific services (controllers, filters, etc). No-op by default.
`StartServices()`	virtual hook	Override to start background/hosted services. No-op by default.
`LoadConfiguration()`	helper	Loads `appsettings`/env file per `WebApiParameters` and registers `SettingsProvider`/`EnvironmentProvider`.
`AddMiddlewares(Type[])`	helper	Registers each given middleware type on `App`, in order, skipping any type that isn’t a `WebApiMiddleware`.
`AddCustomInvalidModelStateResponse()`	helper	Replaces ASP.NET Core’s default invalid-model-state response with a `DataOutput<string>`-shaped 400.
`UseSwaggerGen(...)`	helper	Registers the Swagger generator, conditionally on the current environment.
`UseSwagger(...)`	helper	Enables the Swagger middleware (JSON + UI), conditionally on the current environment.
`BuildApp()`	helper	Builds `App` from `Builder`. Must run before `ConfigureApp()` touches `App`.
`Run()` / `BuildAndRun()`	helper	Runs the built app, or calls `Build()` then `Run()` in one call.

A minimal `Startup`

public class Startup(string[] args) : WebApiStartup(args)
{
 public override void Build()
 {
 LoadConfiguration();
 AddCustomInvalidModelStateResponse();
 UseSwaggerGen(jwtAuthentication: true);
 Builder.Services.AddControllers();

 AddDependencies();

 BuildApp();
 ConfigureApp();
 }

 public override void ConfigureApp()
 {
 AddMiddlewares([
 typeof(TraceActivityMiddleware),
 typeof(ExceptionMiddleware),
 typeof(AuthenticationMiddleware)
 ]);

 UseSwagger();
 App.MapControllers();
 }
}

new Startup(args).BuildAndRun();

BuildApp() must run before ConfigureApp(), since the pipeline configuration in ConfigureApp() (AddMiddlewares, UseSwagger, endpoint mapping) operates on the built App, not the Builder.

`WebApiParameters` — command-line startup args

WebApiParameters parses the process’s args into a small set of properties, without any code changes required at the call site. Each argument is a Key:Value pair; unrecognized or malformed entries are silently ignored, leaving the default in place:

Argument	Property	Default	Effect
`Environment:<name>`	`EnvironmentName`	`""`	Sets the environment name, if it’s a valid `EnvironmentType` value.
`UseAppSetting:<bool>`	`UseAppSettings`	`true`	Whether `LoadConfiguration()` loads `appsettings.json`.
`UseEnvFile:<bool>`	`UseEnvFile`	`true`	Whether `LoadConfiguration()` loads a `.env` file.
`SwaggerEnvironments:[A,B]`	`SwaggerEnvironments`	`[]`	The environment names in which Swagger is served (see below).

For example:

Environment:Production UseAppSetting:false UseEnvFile:false SwaggerEnvironments:[Development,Staging]

Swagger — enabled per environment

Swagger is gated by environment name, not by a simple on/off flag. UseSwagger(allowedEnvironments) and UseSwaggerGen(allowedEnvironments, ...) each decide whether to activate using this precedence:

The allowedEnvironments parameter passed directly to the call, if non-empty.
Otherwise, WebApiParameters.GetSwaggerEnvironments() — the SwaggerEnvironments:[...] CLI arg, if it parsed to at least one valid environment name.
Otherwise, the built-in default: Development and Local.

UseSwaggerGen(jwtAuthentication: true); // uses the default/CLI-configured environments
UseSwagger([EnvironmentType.Development, EnvironmentType.Staging]); // explicit override

Because GetSwaggerEnvironments() always falls back to [Development, Local] rather than returning an empty list, in practice Swagger’s on/off state is always decided by one of the first two rules — there is no separate appsettings.json toggle you need to flip to turn Swagger on or off.

AppSettingsKeys.SwaggerEnabled ("Swagger:Enabled") is a separate internal marker, and it is set only when you pass an explicit SwaggerEnvironments:[...] argument that includes the current environment (the marker uses the raw argument, not the [Development, Local] fallback). AuthenticationMiddleware reads this marker to recognize /swagger routes and skip authentication on them. This means Swagger can be served by default in Development/Local without the marker being set — in that case the /swagger authentication bypass is not active unless you also pass the matching SwaggerEnvironments:[...] argument.

Logging

WebApiStartup no longer configures logging — that is the derived class’s responsibility. Because the library’s logging types depend only on Microsoft.Extensions.Logging.ILogger<T>, any backend works: the default ASP.NET Core providers (already registered by WebApplication.CreateBuilder), Serilog (Builder.Host.UseSerilog(...)), or a custom ILogger. Configure whichever you prefer inside your Build() override before calling BuildApp().

Invalid model state

AddCustomInvalidModelStateResponse() replaces ASP.NET Core’s built-in [ApiController] validation response with a DataOutput<string>-shaped 400: each invalid model-binding parameter is turned into an error message of the form Parameter: <name> | Error: <message>, collected on the envelope’s Errors list, so validation failures come back in the same shape as any other failed ResponseResolver.Resolve call.

Where to next

Architecture — how the pipeline, security model and response envelopes fit together.
Security — ConfigureSecurity(), JWT validation modes, and role-based authorization.
Middleware & Diagnostics — the built-in middlewares registered via AddMiddlewares.
Responses — ResponseResolver and the invalid-model-state envelope shape.
Endpoint Toggling — reading appsettings.json/environment values to enable or disable individual endpoints.

Endpoint Toggling

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Endpoint Toggling

[EndpointToggle] is an action filter attribute that turns a single endpoint on or off. When the endpoint is disabled, the request is short-circuited before the action runs and a response is returned in one of several shapes. The toggle can be fixed in code or resolved from configuration on every request, so an endpoint can be disabled without a redeploy.

The two forms

The attribute has two constructors — pick one per endpoint:

Form	Constructor	Toggle source
Compile-time	`[EndpointToggle(bool isEnabled = true, ...)]`	The `isEnabled` flag, fixed at build time.
Configuration	`[EndpointToggle(ConfigurationSourceType configurationSource, ...)]`	A configuration value re-read on every request.

public class ReportsController : ControllerBase
{
 // Compile-time: always disabled until the code changes.
 [EndpointToggle(isEnabled: false)]
 [HttpGet("legacy")]
 public IActionResult Legacy() { /* ... */ }

 // Configuration: re-read from "Endpoints:Reports:Export" on every request.
 [EndpointToggle(ConfigurationSourceType.AppSettings)]
 [HttpGet("export")]
 public IActionResult Export() { /* ... */ }
}

Request flow

flowchart TB
Request["Request reaches action"] --> Source{"Configuration form?"}
Source -- "no" --> Static["Use isEnabled flag"]
Source -- "yes" --> Config["Read toggle from configuration"]
Static --> Enabled{"Enabled?"}
Config --> Enabled
Enabled -- "yes" --> Action["Action runs normally"]
Enabled -- "no" --> Shape["Shape disabled response by OutputType"]
Shape --> Void["Void → empty status code"]
Shape --> Default["Default → action's default return value"]
Shape --> Object["Object → ProcessOutput envelope"]
Shape --> Exception["Exception → throw EndpointDisabledException"]

Resolving the toggle from configuration

The configuration form reads its value from the source given by ConfigurationSourceType:

`ConfigurationSourceType`	Read from	Key separator
`AppSettings`	`IConfiguration` (resolved from the request’s services)	`:`
`EnvFile` / `EnvironmentVariables`	Process environment variables (`Environment.GetEnvironmentVariable`)	`_`

The key

Pass an explicit key to read a specific configuration entry. When key is empty, the key is derived from the key prefix, the current controller name, the action name, and the optional suffix:

<keyPrefix with [Controller] replaced><sep><ActionName>[<sep><keySuffix>]

When keyPrefix is empty, a default is used — Endpoints:[Controller] for app settings, or Endpoints_[Controller] for environment variables — with [Controller] replaced by the current controller name. So [EndpointToggle(ConfigurationSourceType.AppSettings)] on Export in ReportsController reads Endpoints:Reports:Export, while the environment-variable form reads Endpoints_Reports_Export.

Missing values default to enabled

If the toggle can’t be resolved to an explicit boolean, the endpoint stays enabled, so a misconfigured toggle never silently hides a working endpoint. Both sources behave the same way: only a value that parses as false disables the endpoint; an absent, empty, or non-boolean value leaves it enabled.

Situation	Result
Key set to `true`	Enabled
Key set to `false`	Disabled
Key absent, empty, or non-boolean	Enabled (fallback)
App-settings `IConfiguration` not registered	Enabled (fallback)

Shaping the disabled response

When an endpoint is disabled, disabledOutputType (an OutputType) decides what the caller receives:

`OutputType`	Disabled response	Status code
`Void`	Empty result, no body.	`disabledStatusCode` (default `404`)
`Default`	The action’s default return value — `default(T)` for value types, `null` for reference types, or an empty result for `void`.	`disabledStatusCode` (default `404`)
`Object` (default)	A `ProcessOutput` envelope carrying `disabledMessage`.	`disabledStatusCode` (default `404`)
`Exception`	Throws `EndpointDisabledException`, handled by the exception pipeline (e.g. `ExceptionMiddleware`).	Decided by the exception handler

A few details worth knowing:

disabledStatusCode defaults to 404 Not Found and is honored by the Void, Default and Object shapes whenever the caller provides it.
disabledMessage (default "This endpoint is currently disabled") is only included by the Object shape. The Exception shape always carries the default message.
EndpointToggleAttribute.DefaultDisabledStatusCode and DefaultDisabledMessage expose those defaults.

// Disabled requests get a 503 with a ProcessOutput explaining why.
[EndpointToggle(
 ConfigurationSourceType.AppSettings,
 disabledStatusCode: HttpStatusCode.ServiceUnavailable,
 disabledOutputType: OutputType.Object,
 disabledMessage: "Reporting is paused for maintenance")]
[HttpGet("export")]
public IActionResult Export() { /* ... */ }

Where to next

Configuration — how appsettings.json and environment values are loaded into the host that [EndpointToggle] reads from.
Middleware & Diagnostics — ExceptionMiddleware, which handles the EndpointDisabledException thrown by the Exception output type.
Responses — the ProcessOutput envelope used by the Object output type.

HTTP Client

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

HTTP Client

ArturRios.Util.WebApi gives you a thin base for typed clients that call another web API: BaseWebApiClient owns a shared HttpGateway, and BaseWebApiClientRoute groups related endpoints under a base URL with helpers for authenticating and carrying the resulting bearer token.

`BaseWebApiClient`

BaseWebApiClient is abstract and exposes a protected HttpGateway Gateway that every route object uses to issue requests. It has two constructors:

BaseWebApiClient(HttpClient httpClient) — wraps an existing HttpClient. Prefer this one: it lets the client be created through IHttpClientFactory (via AddHttpClient<T>()), which manages the underlying HttpClient’s lifetime and connection pooling for you and is what lets you attach message handlers like TracePropagationHandler.
BaseWebApiClient(string baseUrl) — constructs its own HttpClient with BaseAddress = baseUrl. Simpler for quick/manual use, but you lose IHttpClientFactory’s pooling and the ability to attach handlers through DI.

Both constructors call the abstract SetRoutes() method before returning, so a derived class implements it to instantiate its route objects against the shared Gateway:

public class MyApiClient : BaseWebApiClient
{
 public AccountsRoute Accounts { get; private set; } = null!;

 public MyApiClient(HttpClient httpClient) : base(httpClient) { }

 protected override void SetRoutes()
 {
 Accounts = new AccountsRoute(Gateway);
 }
}

`BaseWebApiClientRoute`

BaseWebApiClientRoute(HttpGateway gateway) is the base for a group of related routes on the remote API. It exposes:

abstract string BaseUrl — the base path this route group is mounted under (e.g. /accounts).
AuthenticateAsync(Credentials credentials, string authRoute) — posts credentials to authRoute via the shared Gateway and returns the resulting Authentication. Throws WebApiClientException if the response comes back with no body.
Authorize(string authToken) — sets Gateway.Client.DefaultRequestHeaders.Authorization to a Bearer header carrying authToken. This is a plain assignment, so it’s idempotent — calling it again (e.g. after re-authenticating) simply replaces the previous header rather than accumulating anything.
AuthenticateAndAuthorizeAsync(Credentials credentials, string authRoute) — calls AuthenticateAsync then Authorize with the returned token, in one call.

public class AccountsRoute(HttpGateway gateway) : BaseWebApiClientRoute(gateway)
{
 public override string BaseUrl => "/accounts";

 public Task LoginAsync(Credentials credentials) =>
 AuthenticateAndAuthorizeAsync(credentials, $"{BaseUrl}/login");
}

After LoginAsync completes, every subsequent call made through the shared Gateway — from Accounts or any other route object on the same client — carries the Authorization: Bearer header, since they all share the same underlying HttpClient.

`WebApiClientException`

A plain Exception subclass raised when a BaseWebApiClientRoute operation can’t complete — currently, only when AuthenticateAsync gets a response with no body. Catch it around login calls if you want to distinguish “the remote API is unreachable/malformed” from a normal authentication failure surfaced through the Authentication.Valid flag.

Pairing with `TracePropagationHandler`

Because the HttpClient-based constructor is built for IHttpClientFactory, you can attach TracePropagationHandler (see Middleware & Diagnostics) so every outgoing call from the client carries the current request’s W3C trace id:

builder.Services.AddTransient<TracePropagationHandler>();
builder.Services.AddHttpClient<MyApiClient>()
 .AddHttpMessageHandler<TracePropagationHandler>();

flowchart LR
Ctor["MyApiClient(HttpClient)"] --> SetRoutes["SetRoutes()"]
SetRoutes --> Accounts["AccountsRoute(Gateway)"]
Accounts -- "AuthenticateAndAuthorizeAsync" --> Login["POST /accounts/login"]
Login -- "Authentication.Token" --> Authorize["Authorize(token)"]
Authorize --> Header["Gateway.Client default Authorization header"]
Header --> Calls["Subsequent calls via Gateway"]
Calls -- "TracePropagationHandler" --> Downstream["Downstream API"]

Where to next

Middleware & Diagnostics — TracePropagationHandler and the trace id it propagates.
Security — Credentials, Authentication and the login flow this client typically calls into.
Responses — the ArturRios.Output envelopes returned by the APIs these clients call.

Middleware & Diagnostics

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Middleware & Diagnostics

ArturRios.Util.WebApi ships two request-pipeline middlewares — TraceActivityMiddleware and ExceptionMiddleware — plus TracePropagationHandler, a DelegatingHandler that carries the same trace id onto outgoing HttpClient calls. (The third pipeline middleware, AuthenticationMiddleware, is covered on the Security page.) The middlewares are registered through AddMiddlewares, as referenced in Architecture and Configuration.

`WebApiMiddleware` and registration order

WebApiMiddleware is an abstract marker base class with no members. Its only job is letting WebApiStartup.AddMiddlewares(Type[]) recognize which types it’s safe to register with App.UseMiddleware(...) — any type in the array that isn’t a subclass of WebApiMiddleware is silently skipped. Registration happens in the order given:

AddMiddlewares([
 typeof(TraceActivityMiddleware), // assigns/propagates a W3C trace id
 typeof(ExceptionMiddleware), // turns unhandled exceptions into a JSON error envelope
 typeof(AuthenticationMiddleware)
]);

TraceActivityMiddleware runs first so the trace id is available to everything downstream, including exception logging; ExceptionMiddleware runs next so it can catch exceptions thrown by authentication or the endpoint itself; AuthenticationMiddleware (see Security) runs last of the three.

`ExceptionMiddleware`

ExceptionMiddleware.InvokeAsync wraps the rest of the pipeline in a try/catch:

Client-initiated cancellations — an OperationCanceledException or TaskCanceledException caught while httpContext.RequestAborted.IsCancellationRequested is true is logged at Debug level ("Request was canceled by the client...") and swallowed. No response is written, since there’s no client left to receive one.
Everything else falls through to a single structured logger.LogError(exception, "Unhandled exception while processing the request.") call, followed by an HTTP 500 response — unless the response has already started or the request was aborted, in which case it logs at Debug and returns without writing anything.

The 500 response body is a JSON DataOutput<string> envelope. By default its Messages carry a single generic message — "Internal server error, please try again later" — so internal exception details are never leaked to the client. The one exception: if the thrown exception is a CustomException, its own Messages are returned instead, letting application code surface a deliberate, safe-to-show error through the same envelope shape ResponseResolver uses everywhere else (see Responses).

The response body is serialized with JsonConvert.SerializeObject(output) (Newtonsoft, default casing), so a generic 500 looks like:

{
 "Success": false,
 "Data": "",
 "Messages": ["Internal server error, please try again later"],
 "Errors": []
}

`TraceActivityMiddleware`

TraceActivityMiddleware ensures every request is associated with a W3C-format Activity. The W3C Activity.DefaultIdFormat/Activity.ForceDefaultIdFormat configuration is set once, in a static constructor — not on every request.

For each request, InvokeAsync:

Reuses Activity.Current if one already exists, or starts a new "ServerReceive" activity otherwise.
Sets context.TraceIdentifier and context.Items["TraceId"] to the activity’s trace id.
Writes a traceparent response header formatted as 00-{traceId}-{spanId}-{flags} (the standard W3C trace-context format), so callers can correlate their request with the server-side trace even if they didn’t originate it.

flowchart LR
Req["Incoming request"] --> Check{"Activity.Current?"}
Check -- "exists" --> Reuse["Reuse it"]
Check -- "none" --> New["Start new ServerReceive activity"]
Reuse --> Set["context.TraceIdentifier / Items[TraceId]"]
New --> Set
Set --> Header["Response header: traceparent"]
Header --> Next["Next middleware / endpoint"]

`TracePropagationHandler`

TracePropagationHandler is a DelegatingHandler for outgoing typed/named HttpClients. When Activity.Current is set (typically because TraceActivityMiddleware is running the current request) and the outgoing request doesn’t already carry a traceparent header, it adds one built from the same 00-{traceId}-{spanId}-{flags} format — so a call your service makes to another service continues the same distributed trace instead of starting a new one.

builder.Services.AddTransient<TracePropagationHandler>();
builder.Services.AddHttpClient<MyApiClient>()
 .AddHttpMessageHandler<TracePropagationHandler>();

See HTTP Client for how BaseWebApiClient fits into that registration.

Where to next

Architecture — how these middlewares sit relative to AuthenticationMiddleware and ResponseResolver in the full pipeline.
Configuration — registering middlewares via AddMiddlewares as part of WebApiStartup.
HTTP Client — pairing TracePropagationHandler with BaseWebApiClient.
Responses — the DataOutput<T>/ProcessOutput envelopes ExceptionMiddleware and ResponseResolver both use.

Responses

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Responses

ResponseResolver is a static class that converts ArturRios.Output envelopes — DataOutput<T>, ProcessOutput, and PaginatedOutput<T> — into ASP.NET Core ActionResults, so a controller action never has to hand-pick a status code for the happy and unhappy paths itself.

`Resolve` overloads

ResponseResolver.Resolve has three overloads, one per envelope type:

Overload	Returns
`Resolve<T>(DataOutput<T?> dataOutput, int? statusCode = null)`	`ActionResult<DataOutput<T?>>`
`Resolve(ProcessOutput processOutput, int? statusCode = null)`	`ActionResult<ProcessOutput>`
`Resolve<T>(PaginatedOutput<T> paginatedOutput, int? statusCode = null)`	`ActionResult<PaginatedOutput<T>>`

Each wraps the envelope in an ObjectResult whose StatusCode is set from the resolved status code — none of the three re-shape or otherwise touch the envelope itself; the body returned to the client is the same object you passed in.

Status resolution order

Every overload also accepts an optional statusMap — an IReadOnlyDictionary<string, int> from an envelope message to an HTTP status code — and resolves its status the same way:

statusCode supplied — used as-is, regardless of the envelope’s Success value or the map.
statusMap supplied — the lookup key is the first Errors entry when Success is false, or the first Messages entry when Success is true. If that key is present in the map, its value is used.
Otherwise — no map, an empty list, or a key not found — defaults to 200 when Success is true and 400 otherwise.

The caller owns the dictionary, so its key comparer controls matching — build it with StringComparer.OrdinalIgnoreCase for case-insensitive keys.

flowchart LR
Output["DataOutput / ProcessOutput / PaginatedOutput"] --> Resolve["ResponseResolver.Resolve(output, statusCode?, statusMap?)"]
Resolve --> HasCode{"statusCode supplied?"}
HasCode -- "yes" --> UseCode["Use statusCode as-is"]
HasCode -- "no" --> HasMap{"statusMap supplied?"}
HasMap -- "yes" --> Lookup{"first error/message in map?"}
Lookup -- "yes" --> UseMapped["Use mapped status"]
Lookup -- "no" --> Success{"output.Success?"}
HasMap -- "no" --> Success
Success -- "true" --> Ok["200"]
Success -- "false" --> Bad["400"]
UseCode --> Result["ObjectResult"]
UseMapped --> Result
Ok --> Result
Bad --> Result

To map specific errors to specific statuses without branching in the action, pass a statusMap keyed on the envelope’s first error:

var statusMap = new Dictionary<string, int>
{
 ["User not found"] = 404,
 ["Email already registered"] = 409,
};

return ResponseResolver.Resolve(output, statusMap: statusMap);

This means a failed operation that should still return, say, a 404 or 409 rather than a generic 400 just needs an explicit statusCode:

return ResponseResolver.Resolve(output, statusCode: 404);

Pairing with the envelopes

ResponseResolver is the last stop for the “envelopes, not exceptions” pattern the rest of the library follows (see Architecture): application code builds a ProcessOutput or DataOutput<T> (WithData, WithError, etc.) to describe what happened, and ResponseResolver is the single place that decides how that maps onto the HTTP response — so success and failure both flow through the same, predictable shape instead of being scattered across Ok(...)/BadRequest(...)/NotFound(...) calls in every action. It pairs naturally with AddCustomInvalidModelStateResponse() (see Configuration), which shapes ASP.NET Core’s own model-validation 400 as a DataOutput<string> so it looks identical to a Resolved failure.

Controller-action example

[HttpGet("{id:int}")]
public ActionResult<DataOutput<UserDto?>> GetById(int id)
{
 DataOutput<UserDto?> output = _userService.GetById(id);

 return ResponseResolver.Resolve(output);
}

_userService.GetById returns a DataOutput<UserDto?> whose Success reflects whether the user was found; ResponseResolver.Resolve turns that straight into a 200 with the user payload or a 400 with the service’s error messages, with no branching in the action itself.

Where to next

Architecture — where ResponseResolver sits at the end of the request pipeline, and the envelope class hierarchy (ProcessOutput → DataOutput<T> → PaginatedOutput<T>).
Configuration — AddCustomInvalidModelStateResponse(), which shapes validation failures the same way.
Middleware & Diagnostics — ExceptionMiddleware, which returns the same DataOutput<string> shape for unhandled exceptions that never reach a Resolve call.

Security

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Security

ArturRios.Util.WebApi ships token authentication and role-based authorization as a small, composable set of pieces: AuthenticationMiddleware extracts and validates the token and attaches the user, a pair of attributes/filters declare access rules, and Credentials/Authentication give you the record types for a login flow.

Two token schemes are supported side by side — the app’s own HMAC JWT and Google ID tokens — and either can be accepted on a given request. Which scheme(s) are enabled, where the token is read from, and how the user is resolved are all controlled by one AuthenticationOptions instance, registered via AddTokenAuthentication.

Registering authentication — `AddTokenAuthentication`

builder.Services.AddTokenAuthentication(options =>
{
 options.Source = TokenSource.Either; // Header | Cookie | Either — default: Header
 options.CookieName = "access_token"; // default
 options.EnableJwt = true; // default
 options.EnableGoogle = true; // default: false
 options.GoogleClientIds = ["your-google-oauth-client-id"];
 options.JwtMode = JwtValidationMode.ClaimsOnly; // or Revalidate — default: ClaimsOnly
});

AddTokenAuthentication registers the AuthenticationOptions instance plus one ITokenValidator per enabled scheme (app JWT first, then Google, so that’s the order AuthenticationMiddleware tries them in). It throws an ArgumentException if:

neither EnableJwt nor EnableGoogle is true — at least one scheme must be enabled; or
EnableGoogle is true but GoogleClientIds is empty.

The app must still separately register JwtConfiguration/JwtHandler (for the JWT scheme) and, when required (see below), an IAuthenticationProvider.

`TokenSource` — where the token is read from

AuthenticationOptions.Source controls how AuthenticationMiddleware extracts the raw token from the request, via TokenExtractor:

Header (default) — the Authorization header only. The scheme must be Bearer (case-insensitive) with a non-empty parameter; any other or malformed scheme is treated as no token.
Cookie — the cookie named CookieName (default "access_token") only.
Either — the header first, falling back to the cookie if the header carries no token.

`AuthenticationMiddleware`

AuthenticationMiddleware runs once per request (see Architecture for where it sits in the pipeline). For each request it:

Skips validation entirely for Swagger routes and for endpoints marked [AllowAnonymous].
Extracts the token per AuthenticationOptions.Source, as above.
Runs the token through the enabled validators, in registration order (app JWT, then Google). The first validator that resolves an AuthenticatedUser wins: it’s attached to HttpContext.Items["User"] and the next middleware runs.
If no validator resolves a user, the request gets a 401 with the last validator’s error (e.g. "Invalid token", "Invalid Google token", "User not found").

The app JWT scheme — `ClaimsOnly` vs `Revalidate`

When EnableJwt is true, JwtTokenValidator first checks the token’s signature via JwtHandler.IsTokenValidAsync; an invalid or missing token fails with "Invalid token". How the user is then resolved is controlled by AuthenticationOptions.JwtMode:

ClaimsOnly (default) — AuthenticatedUserFactory.FromToken rebuilds the user from the token’s id and role claims. No data store is queried, so authentication costs nothing beyond the signature check. The trade-off: because nothing is re-checked server-side, role changes and revocations only take effect once the token expires. Keep access-token lifetimes short and pair this mode with refresh tokens.
Revalidate — the user id is read from the token, and IAuthenticationProvider is resolved per-request from HttpContext.RequestServices (so it can be a scoped service) and its GetAuthenticatedUserById is called. This guarantees freshness — a deleted or role-changed user is rejected or updated on the very next request — at the cost of one lookup per request. An IAuthenticationProvider must be registered for this mode.

Google authentication

When EnableGoogle is true, GoogleTokenValidator verifies the token via IGoogleTokenVerifier — by default GoogleTokenVerifier, backed by Google.Apis.Auth’s GoogleJsonWebSignature, which checks signature, issuer, expiry and audience against GoogleClientIds. On success, the token’s verified email is looked up through IAuthenticationProvider.GetAuthenticatedUserByEmail. An IAuthenticationProvider is therefore required whenever EnableGoogle is true — the same requirement as JWT Revalidate mode, above.

To accept Google sign-in:

Add the Google.Apis.Auth package (already a dependency of this library, so it resolves transitively — add it explicitly to your project only if you call its APIs directly).
Set EnableGoogle = true and GoogleClientIds to your app’s accepted OAuth client ID(s)/audiences in the AddTokenAuthentication callback.
Implement IAuthenticationProvider.GetAuthenticatedUserByEmail(string) on your provider (alongside GetAuthenticatedUserById if you also use the JWT scheme) and register it, optionally wrapped with AddCachedAuthenticationProvider<T> (below).

EnableJwt and EnableGoogle are independent — enable both to let a single endpoint accept either an app-issued JWT or a Google ID token on the same request path; AuthenticationMiddleware figures out which one it got by trying each enabled validator in turn.

Caching provider lookups

When using Revalidate, wrap your IAuthenticationProvider with CachedAuthenticationProvider so repeated lookups of the same user within a short window are served from an IMemoryCache instead of hitting the store on every request:

builder.Services.AddCachedAuthenticationProvider<MyAuthenticationProvider>(options =>
{
 options.Ttl = TimeSpan.FromSeconds(30); // default: 60s
 options.CacheMisses = true; // also cache "user not found" (default: false)
});

AddCachedAuthenticationProvider<TProvider> registers TProvider (your concrete IAuthenticationProvider implementation) as a scoped service, adds IMemoryCache, and registers IAuthenticationProvider itself as a CachedAuthenticationProvider decorating TProvider. Both provider methods are cached independently: GetAuthenticatedUserById checks the cache first (key "auth:user:" + id by default, via CacheKeyPrefix), and GetAuthenticatedUserByEmail does the same keyed by email ("auth:email:" + email by default, via EmailCacheKeyPrefix). On a miss, each delegates to the inner provider and caches the result for Ttl, but only caches a null result (a miss) when CacheMisses is true. This bounds staleness to the TTL while collapsing bursts of requests for the same user into a single store hit — AuthenticationMiddleware (for both the JWT Revalidate and Google schemes) and your own code both see it as a plain IAuthenticationProvider and don’t need to know caching is happening.

Identity types

AuthenticatedUser(int Id, int Role) — the record attached to HttpContext.Items["User"] after successful authentication, and returned by both IAuthenticationProvider.GetAuthenticatedUserById and IAuthenticationProvider.GetAuthenticatedUserByEmail.
TokenClaimKeys — the claim key constants used on both ends of the token: Id = "id", Role = "role".
AuthenticationExtensions.ToTokenClaims(this AuthenticatedUser) — converts an AuthenticatedUser into a Dictionary<string, string> keyed by TokenClaimKeys, ready to hand to your JWT-issuing code when you build the token at login time.
AuthenticatedUserFactory.FromToken(string token) — reads a token’s id/role claims (without validating its signature — callers must have already done that) and returns the reconstructed AuthenticatedUser, or null if the token can’t be read or is missing a numeric id or role claim. This is what JwtTokenValidator calls in ClaimsOnly mode.

flowchart LR
User["AuthenticatedUser"] -- "ToTokenClaims()" --> Claims["id / role claims"]
Claims -- "embedded in JWT at login" --> Token["Bearer token"]
Token -- "AuthenticatedUserFactory.FromToken()" --> User2["AuthenticatedUser"]

Declaring access rules

[Authorize]
[RoleRequirement(1, 2)] // e.g. Admin, Manager
public class AccountsController : ControllerBase
{
 [AllowAnonymous]
 [HttpPost("login")]
 public IActionResult Login(Credentials credentials) { /* ... */ }

 [HttpGet]
 public IActionResult GetAll() { /* only roles 1 and 2 reach here */ }
}

[Authorize] — an IAuthorizationFilter that checks HttpContext.Items["User"]; if it’s null, the request short-circuits with a 401 ({"message": "Unauthorized"}). It first checks the action for [AllowAnonymous] and returns immediately (no 401) if present.
[RoleRequirement(params int[] authorizedRoles)] — a TypeFilterAttribute around RoleRequirementFilter. It reads the same HttpContext.Items["User"]; if the user is present and its Role is one of authorizedRoles, the request proceeds, otherwise it short-circuits with a 403 (a ProcessOutput with the error "You do not have permission to access this resource"). It also honors [AllowAnonymous] — an anonymous-marked action returns immediately without a role check, even under [RoleRequirement(...)].
[AllowAnonymous] — a plain marker attribute; it doesn’t enforce anything itself, but AuthenticationMiddleware, AuthorizeAttribute and RoleRequirementFilter all check for it and skip their own enforcement when it’s present on the action.

Because both filters read HttpContext.Items["User"] rather than re-validating the token themselves, [Authorize]/[RoleRequirement] only make sense downstream of AuthenticationMiddleware — see Architecture for how the two fit together.

`Credentials` and validation

public record Credentials(string Email, string Password);

CredentialsValidator (FluentValidation) enforces:

Email — not empty, and a valid email address format.
Password — not empty, minimum length 8.

public class CredentialsValidator : AbstractValidator<Credentials>
{
 public CredentialsValidator()
 {
 RuleFor(credentials => credentials.Email).NotEmpty().EmailAddress();
 RuleFor(credentials => credentials.Password).NotEmpty().MinimumLength(8);
 }
}

`Authentication` — the login result

public record Authentication(string? Token, bool Valid, string CreatedAt, string Expiration);

The record your authentication route returns after checking Credentials: Token is the issued JWT (or null on failure), Valid indicates whether the attempt succeeded, and CreatedAt/Expiration describe the token’s lifetime — the values you’d typically use to size access-token lifetime and drive a refresh flow, especially under ClaimsOnly mode where a short expiration is what keeps role changes and revocations bounded.

Where to next

Architecture — the full token → AuthenticationMiddleware → Items["User"] → authorization-filter flow, alongside the rest of the pipeline.
Configuration — registering AuthenticationMiddleware via AddMiddlewares and wiring up ConfigureSecurity().
Middleware & Diagnostics — how ExceptionMiddleware and TraceActivityMiddleware relate to the rest of the pipeline AuthenticationMiddleware runs in.

Dotnet WebApi Util

Architecture

Architecture

Request pipeline

Security model

Response envelopes

Design principles

Where to next

Configuration

Configuration

The lifecycle

A minimal Startup

WebApiParameters — command-line startup args

Swagger — enabled per environment

Logging

Invalid model state

Where to next

Endpoint Toggling

Endpoint Toggling

The two forms

Request flow

Resolving the toggle from configuration

The key

Missing values default to enabled

Shaping the disabled response

Where to next

HTTP Client

HTTP Client

BaseWebApiClient

BaseWebApiClientRoute

WebApiClientException

Pairing with TracePropagationHandler

Where to next

Middleware & Diagnostics

Middleware & Diagnostics

WebApiMiddleware and registration order

ExceptionMiddleware

TraceActivityMiddleware

TracePropagationHandler

Where to next

Responses

Responses

Resolve overloads

Status resolution order

Pairing with the envelopes

Controller-action example

Where to next

Security

Security

Registering authentication — AddTokenAuthentication

TokenSource — where the token is read from

AuthenticationMiddleware

The app JWT scheme — ClaimsOnly vs Revalidate

Google authentication

Caching provider lookups

Identity types

Declaring access rules

Credentials and validation

Authentication — the login result

Where to next

A minimal `Startup`

`WebApiParameters` — command-line startup args

`BaseWebApiClient`

`BaseWebApiClientRoute`

`WebApiClientException`

Pairing with `TracePropagationHandler`

`WebApiMiddleware` and registration order

`ExceptionMiddleware`

`TraceActivityMiddleware`

`TracePropagationHandler`

`Resolve` overloads

Registering authentication — `AddTokenAuthentication`

`TokenSource` — where the token is read from

`AuthenticationMiddleware`

The app JWT scheme — `ClaimsOnly` vs `Revalidate`

`Credentials` and validation

`Authentication` — the login result