TailoredApps.Shared.Mediator¶
Description¶
This library provides a ready-made set of pipeline behaviors for the mediator that cover the most common enterprise application needs: logging, validation, caching, fallback, and retry. Instead of manually implementing these cross-cutting concerns in every handler, register them once via PipelineRegistration and they apply to all requests.
Behaviors execute in order: Logging → Validation → Caching → Fallback → Retry → Handler.
The library supports auto-discovery (via Scrutor) — cache policies, fallback handlers, and retry configurations are automatically scanned and registered from the specified assembly.
Installation¶
DI registration¶
// Program.cs
using TailoredApps.Shared.Mediator.DI;
// Register the mediator
builder.Services.AddMediator(cfg =>
cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));
var pipeline = new PipelineRegistration(builder.Services);
// 1. The five pipeline behaviors + HybridCache
pipeline.RegisterPipelineBehaviors();
// 2. Scan the assembly for ICachePolicy<,>, IFallbackHandler<,> and IRetryableRequest<,> implementations
pipeline.RegisterPipelineBehaviors(typeof(Program).Assembly);
// Validators are not scanned by the library - register the ones you have
builder.Services.AddTransient<IValidator<GetProductQuery>, GetProductQueryValidator>();
Both RegisterPipelineBehaviors calls are needed. The parameterless overload registers the behaviors (and HybridCache) but no policies; the overload that takes an assembly only scans it and does not add the behaviors. Without the first call nothing runs in the pipeline; without the second no request is cached, retried or answered by a fallback, because the behaviors find no policy for it.
RegisterPipelineBehaviors() also registers the HybridCache in which CachingBehavior keeps responses. On its own it is an in-process cache; when an IDistributedCache (for example Redis) is registered, HybridCache uses it automatically as the level shared between instances:
Changes in 3.0 (test phase)
The TailoredApps.Shared.Mediator* libraries use ForkForward.Mediator - a fork of MediatR 12.5.0 under the Apache-2.0 licence - instead of the MediatR package. In 2.x they were named TailoredApps.Shared.MediatR*. The types and the behaviour are the same; in the application replace using MediatR; with using ForkForward.Mediator; and AddMediatR(...) with AddMediator(...). Details: Upgrading to 3.0. From ForkForward.Mediator 13 the library also works in an application published with NativeAOT - see Trimming and NativeAOT.
Changes in 2.0
CachingBehavior uses HybridCache. The ICache interface and the Cache class are removed together with the Newtonsoft.Json dependency — delete your own ICache registration. Responses are serialized with System.Text.Json, and ICachePolicy.SlidingExpiration is no longer supported (an entry lives until it expires). After upgrading, clear the shared cache or change the key prefix: entries written by 1.x have a different format.
When the host registers an IDistributedCache (Redis, for example), responses are shared between application instances: an instance without the entry in memory reads it from the distributed cache without calling the handler. When the distributed cache cannot be reached, the handler answers the request - a cache outage does not stop requests.
Usage example¶
Request + Handler¶
// Request
public class GetProductQuery : IRequest<ProductDto>
{
public int ProductId { get; set; }
}
// Validator (run by ValidationBehavior once it is registered in DI as IValidator<GetProductQuery>)
public class GetProductQueryValidator : AbstractValidator<GetProductQuery>
{
public GetProductQueryValidator()
{
RuleFor(x => x.ProductId).GreaterThan(0);
}
}
// Handler
public class GetProductQueryHandler : IRequestHandler<GetProductQuery, ProductDto>
{
private readonly IProductRepository _repo;
public GetProductQueryHandler(IProductRepository repo) => _repo = repo;
public async Task<ProductDto> Handle(GetProductQuery request, CancellationToken ct)
{
var product = await _repo.GetByIdAsync(request.ProductId, ct);
return product?.ToDto() ?? throw new NotFoundException($"Product {request.ProductId} not found");
}
}
Cache Policy for a request¶
public class GetProductQueryCachePolicy : ICachePolicy<GetProductQuery, ProductDto>
{
public string GetCacheKey(GetProductQuery request)
=> $"product:{request.ProductId}";
public TimeSpan? AbsoluteExpirationRelativeToNow => TimeSpan.FromHours(1);
public TimeSpan? LocalCacheExpiration => TimeSpan.FromMinutes(5);
public IReadOnlyCollection<string>? Tags => ["products"];
}
Fallback Handler¶
public class GetProductQueryFallback : IFallbackHandler<GetProductQuery, ProductDto>
{
public Task<ProductDto> HandleFallback(GetProductQuery request, CancellationToken cancellationToken)
{
// Return a default value when the handler throws (the exception is not passed in)
return Task.FromResult(ProductDto.Empty);
}
}
Retry configuration¶
public class GetProductQueryRetry : IRetryableRequest<GetProductQuery, ProductDto>
{
public int RetryAttempts => 3; // retries after the first failure; default 1
public int RetryDelay => 200; // milliseconds; default 250
public bool RetryWithExponentialBackoff => true; // default false
public int ExceptionsAllowedBeforeCircuitTrip => 5; // default 1
}
Trimming and NativeAOT¶
From version 3.0 the library declares that it is safe for trimming and NativeAOT (on ForkForward.Mediator 13). In an application
published with <PublishAot>true</PublishAot> or <PublishTrimmed>true</PublishTrimmed> nothing can be found by scanning an assembly, so
handlers, behaviors and policies are registered by name:
// Program.cs
builder.Services.AddMediator(cfg =>
{
cfg.AddRequestHandler<GetProductQuery, ProductDto, GetProductQueryHandler>();
cfg.AddRequestHandler<CountProductsQuery, int, CountProductsQueryHandler>();
});
new PipelineRegistration(builder.Services)
.AddPipelineBehaviors<GetProductQuery, ProductDto>() // the five behaviors, closed for this request
.AddPipelineBehaviorsWithoutCaching<CountProductsQuery, int>() // four of them, no cache
.AddCachePolicy<GetProductQuery, ProductDto, GetProductQueryCachePolicy>()
.AddFallbackHandler<GetProductQuery, ProductDto, GetProductQueryFallback>()
.AddRetryPolicy<GetProductQuery, ProductDto, GetProductQueryRetry>()
.AddCacheSerialization(AppJsonContext.Default);
builder.Services.AddTransient<IValidator<GetProductQuery>, GetProductQueryValidator>();
[JsonSerializable(typeof(ProductDto))] // the responses kept in the cache
[JsonSerializable(typeof(GetProductQuery))] // the requests a cache key is computed from
internal sealed partial class AppJsonContext : JsonSerializerContext;
| Ordinary application (JIT) | Trimmed or NativeAOT application |
|---|---|
cfg.RegisterServicesFromAssembly(...) |
cfg.AddRequestHandler<TRequest, TResponse, THandler>() for every handler |
RegisterPipelineBehaviors() |
AddPipelineBehaviors<TRequest, TResponse>() for every request; AddPipelineBehaviorsWithoutCaching<,>() for a request that is never cached |
RegisterPipelineBehaviors(assembly) |
AddCachePolicy<,,>(), AddFallbackHandler<,,>(), AddRetryPolicy<,,>() |
| The default cache key (a hash of the request JSON, built by reflection) | Your own GetCacheKey in the policy, or CacheKeyGenerator.Generate(request, AppJsonContext.Default.GetProductQuery) |
| Cached responses serialized by reflection | AddCacheSerialization(AppJsonContext.Default), with the response types in [JsonSerializable] |
- Open behaviors and value types.
RegisterPipelineBehaviors()works natively for requests whose response is a reference type. For a response that is a value type (int,bool,Guid, a struct) the container throwsInvalidOperationExceptionnatively: *Unable to create a generic service for type 'IPipelineBehavior2[…,System.Int32]' because 'System.Int32' is a ValueType*. That is why such an application registers the behaviors closed, per request. Pick one form for the whole application:RegisterPipelineBehaviors()together withAddPipelineBehaviors<,>()` would run the behaviors twice. - Scanning is marked.
RegisterPipelineBehaviors(assembly)carriesRequiresUnreferencedCodeandRequiresDynamicCode: the analyzer reportsIL2026/IL3050at the call instead of letting policies disappear silently when the application is trimmed. - The cache key. The default key serializes the request by reflection. When reflection-based JSON is switched off,
CacheKeyGenerator.Generate(Type, object)throwsInvalidOperationExceptioninstead of building a key from whatever survived trimming. OverrideGetCacheKeyin the policy or use the overload that takes aJsonTypeInfo. Do not assume that the two overloads give the same key for the same request. - HybridCache. Publishing an application that caches responses prints
IL2026/IL3050warnings from theMicrosoft.Extensions.Caching.Hybridassembly: they are about its fallback JSON serializer, which is not used for the types covered byAddCacheSerialization. The cache itself works natively - an application of its own checks that in CI (tests/TailoredApps.Shared.AotSmoke.Caching). An application that caches nothing and registers every request withAddPipelineBehaviorsWithoutCaching<,>()publishes without warnings. - A request without a response (
IRequest) does not go through the behaviors of this library (they requireIRequest<TResponse>); only its handler is registered:cfg.AddRequestHandler<TRequest, THandler>().
API Reference¶
| Type | Kind | Description |
|---|---|---|
LoggingBehavior<TRequest, TResponse> |
Pipeline Behavior | Logs the execution time (Debug), handler failures (Error), validation refusals and cancellations (Information); correlation ID per request |
ValidationBehavior<TRequest, TResponse> |
Pipeline Behavior | Runs every IValidator<TRequest> (FluentValidation) |
CachingBehavior<TRequest, TResponse> |
Pipeline Behavior | Caches the response in HybridCache according to ICachePolicy<TRequest, TResponse>; concurrent identical requests run the handler once |
FallbackBehavior<TRequest, TResponse> |
Pipeline Behavior | On an exception calls IFallbackHandler<TRequest, TResponse> |
RetryBehavior<TRequest, TResponse> |
Pipeline Behavior | Retries the request per IRetryableRequest<TRequest, TResponse>; after ExceptionsAllowedBeforeCircuitTrip consecutive failed requests it opens a circuit breaker (shared per request type) and rejects calls with CircuitBreakerOpenException (RequestType, RetryAfter) for 5 s; then a single trial request closes or re-opens the circuit. No third-party library involved |
PipelineRegistration |
Class | RegisterPipelineBehaviors() registers the five behaviors and HybridCache; RegisterPipelineBehaviors(assembly) only scans the assembly for cache policies, fallback handlers and retry configurations |
IPipelineRegistration |
Interface | PipelineRegistration contract |
PipelineRegistration - registration without scanning |
Class | AddPipelineBehaviors<TRequest, TResponse>() - the five behaviors closed for one request (and HybridCache); AddPipelineBehaviorsWithoutCaching<,>() - four of them, no cache; AddCachePolicy<,,>(), AddFallbackHandler<,,>(), AddRetryPolicy<,,>() - policies by name; AddCacheSerialization(JsonSerializerContext) - cached responses serialized with generated metadata. Each returns PipelineRegistration, so the calls chain |
JsonContextCacheSerializerFactory |
Class | An IHybridCacheSerializerFactory on the metadata of a JsonSerializerContext; it answers for the types the context knows and leaves the rest to the other factories. Registered by AddCacheSerialization |
CacheKeyGenerator |
Static class | Generate(Type, object) - the key {type}:{SHA-256 of the request JSON} built by reflection (throws InvalidOperationException in a trimmed application); Generate<TRequest>(request, JsonTypeInfo<TRequest>) - the same on generated metadata |
ICachePolicy<TRequest, TResponse> |
Interface | Cache configuration: key, lifetime (AbsoluteExpirationRelativeToNow, 5 minutes by default, or AbsoluteExpiration), LocalCacheExpiration, Tags |
IFallbackHandler<TRequest, TResponse> |
Interface | Fallback handler for an exception: HandleFallback(request, cancellationToken) |
IRetryableRequest<TRequest, TResponse> |
Interface | Retry configuration for a request: RetryAttempts (1), RetryDelay in ms (250), RetryWithExponentialBackoff (false), ExceptionsAllowedBeforeCircuitTrip (1) |
HybridCache |
Class (.NET) | Response store used by CachingBehavior; registered by RegisterPipelineBehaviors(). Invalidation: RemoveAsync(key), RemoveByTagAsync(tag) |
🔒 Security¶
- The cache key carries no request data. The default
ICachePolicy.GetCacheKeybuilds{RequestType.FullName}:{SHA-256 of the request JSON}(CacheKeyGenerator.Generate). The previousProp:ToString()format gave requests that differed only in collection contents (CustomerIds = [1]vs[2]) the same key, returning another caller's data. - The key does not include the caller's identity. For per-user or per-tenant data override
GetCacheKeyand prefix the key with the caller id, otherwise one user's response is served to another. LoggingBehaviordoes not serialize the request. Only the request type name and a correlation id go into the logging scope; passwords, tokens and binary payloads never reach the logs.- A validation refusal is not an error. A
ValidationExceptionis logged at Information level (rejected by validation …; invalid: Id) with the property names only - validation messages can quote the values the client sent. A request cancelled by its caller is logged as Information too; every other handler exception as Error. The exception is always rethrown.
🤖 AI Agent Prompt¶
## TailoredApps.Shared.Mediator - instructions for an AI agent
You are using the TailoredApps.Shared.Mediator library with pipeline behaviors in a .NET project.
### Registration
```csharp
builder.Services.AddMediator(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));
var pipeline = new PipelineRegistration(builder.Services);
pipeline.RegisterPipelineBehaviors(); // the five behaviors + HybridCache
pipeline.RegisterPipelineBehaviors(typeof(Program).Assembly); // scans for ICachePolicy<,>, IFallbackHandler<,>, IRetryableRequest<,>
builder.Services.AddTransient<IValidator<MyQuery>, MyQueryValidator>(); // validators are not scanned
```
### Order of behaviors
Logging → Validation → Caching → Fallback → Retry → Handler
### Validation
```csharp
// Runs for every IValidator<MyQuery> registered in DI — throws ValidationException on an error
public class MyQueryValidator : AbstractValidator<MyQuery>
{
public MyQueryValidator() { RuleFor(x => x.Id).GreaterThan(0); }
}
```
### Cache Policy
```csharp
public class MyCachePolicy : ICachePolicy<MyQuery, MyResponse>
{
public string GetCacheKey(MyQuery r) => $"my:{r.Id}";
public TimeSpan? AbsoluteExpirationRelativeToNow => TimeSpan.FromHours(1);
public TimeSpan? LocalCacheExpiration => TimeSpan.FromMinutes(5);
public IReadOnlyCollection<string>? Tags => ["products"];
}
```
### Fallback and retry
```csharp
public class MyFallback : IFallbackHandler<MyQuery, MyResponse>
{
public Task<MyResponse> HandleFallback(MyQuery request, CancellationToken cancellationToken)
=> Task.FromResult(MyResponse.Empty);
}
public class MyRetry : IRetryableRequest<MyQuery, MyResponse>
{
public int RetryAttempts => 3; // default 1
public int ExceptionsAllowedBeforeCircuitTrip => 5; // default 1
}
```
### Rules
- Call both RegisterPipelineBehaviors() and RegisterPipelineBehaviors(assembly): the first adds the behaviors, the second only scans for policies
- ValidationBehavior runs the IValidator<TRequest> instances registered in DI - the library does not register validators, do it yourself
- For the cache to work, implement ICachePolicy<TRequest, TResponse> in the scanned assembly (or register it yourself)
- IFallbackHandler has one method: HandleFallback(request, cancellationToken) - the exception is not passed to it
- LoggingBehavior: start and finish at Debug, validation refusals and cancellations at Information, handler failures at Error - do not count validation failures from Error entries
- Every request has a unique correlation ID in the logs
- The default cache key is a hash of the request content; for per-user data override GetCacheKey and add the user/tenant id
- LoggingBehavior logs only the request name and correlation id - log request fields explicitly in the handler, never whole objects with secrets
- Caching is built on HybridCache (registered by RegisterPipelineBehaviors): do not register ICache - that interface does not exist in 2.0
- Every response is cached as returned - including null, 0 and false; concurrent identical requests run the handler once
- Set an entry's lifetime with AbsoluteExpirationRelativeToNow (5 minutes by default) or AbsoluteExpiration; SlidingExpiration is not supported
- A cached response type must be serializable with System.Text.Json; register an IHybridCacheSerializer<T> for other types
- To share the cache between instances register an IDistributedCache (for example Redis) - HybridCache uses it automatically
- A request cancelled by its caller is not retried, does not open the circuit breaker and is not sent to the fallback
- An open circuit throws CircuitBreakerOpenException (in 1.x: Polly's BrokenCircuitException); answer 503 with a Retry-After header taken from its RetryAfter property
- The library depends on neither Polly nor Newtonsoft.Json - do not add them to configure retries or caching
- An application with PublishAot or PublishTrimmed: scan nothing - cfg.AddRequestHandler<TRequest, TResponse, THandler>() for handlers, AddPipelineBehaviors<TRequest, TResponse>() (or AddPipelineBehaviorsWithoutCaching) for every request instead of RegisterPipelineBehaviors(), AddCachePolicy / AddFallbackHandler / AddRetryPolicy instead of RegisterPipelineBehaviors(assembly)
- In such an application override GetCacheKey (or use CacheKeyGenerator.Generate(request, jsonTypeInfo)) and call AddCacheSerialization(context) with the response types in [JsonSerializable]; the default key throws InvalidOperationException there
- Do not combine RegisterPipelineBehaviors() with AddPipelineBehaviors<,>() in one application - the behaviors would run twice