Repository navigation
Extend the Pipeline
Last verified against v3.0.0
The MediatR pipeline is the extension point. Add your own commands, queries, pipeline behaviours, and validators in a consumer assembly, then hand that assembly to AddConsumerHandlers so the framework discovers them.
using System.Reflection;
using FluentResults;
using IntegratoR.Abstractions.Common.Results;
using IntegratoR.Abstractions.Interfaces.Commands;
using MediatR;
// 1. Define a custom command — a record implementing ICommand<TResponse>.
public record PostLedgerJournalCommand(string DataAreaId, string JournalBatchNumber)
: ICommand<Result<PostedJournalReceipt>>
{
// ICommand carries IContext; override GetLoggingContext to enrich the structured log scope.
public IReadOnlyDictionary<string, object> GetLoggingContext() => new Dictionary<string, object>
{
["EntityType"] = nameof(LedgerJournalHeader),
["DataAreaId"] = DataAreaId,
["JournalBatchNumber"] = JournalBatchNumber,
};
}
public sealed record PostedJournalReceipt(string Voucher, DateTime PostedAt);
// 2. Implement the handler — return Result<T>, never throw for a business failure.
public sealed class PostLedgerJournalCommandHandler
: IRequestHandler<PostLedgerJournalCommand, Result<PostedJournalReceipt>>
{
public async Task<Result<PostedJournalReceipt>> Handle(
PostLedgerJournalCommand request,
CancellationToken cancellationToken)
{
Result<PostedJournalReceipt> action = await CallBoundActionAsync(request, cancellationToken)
.ConfigureAwait(false);
return action;
}
}
// 3. Register the assembly in the AddIntegratoR builder.
services.AddIntegratoR(configuration, integrator =>
integrator.AddConsumerHandlers(Assembly.GetExecutingAssembly()));
// 4. Send it through IMediator like any other command.
Result<PostedJournalReceipt> result = await mediator.Send(
new PostLedgerJournalCommand("USMF", "B0001"),
cancellationToken).ConfigureAwait(false);ICommand<TResponse> is IRequest<TResponse> plus IContext. Use the non-generic ICommand for a command that reports only success or failure; its handler returns Task<Result>.
AddConsumerHandlers folds the assembly into AddIntegratoR's single combined MediatR scan, so the framework's generic CreateCommand<T>/UpdateCommand<T>/DeleteCommand<T>/GetByKeyQuery<T>/GetByFilterQuery<T> handlers also close over any entity you declare there — including subclasses of framework entities — with no extra registration.
A custom handler surfaces a D365 rejection as a failed Result<T> — it does not throw. Branch on result.IsFailed and read result.GetError().
if (result.IsFailed)
{
IntegrationError? error = result.GetError();
// e.g. Code "OData.RequestFailed", Type ErrorType.Failure when the bound action returns HTTP 400.
return Results.Problem(error?.Message);
}
PostedJournalReceipt receipt = result.Value;Inside the handler, wrap a rejected downstream call in an IntegrationError rather than letting an exception escape:
if (action.IsFailed)
{
return Result.Fail(new IntegrationError(
"OData.RequestFailed",
"The bound action returned HTTP 400.",
ErrorType.Failure));
}ErrorType has four members: Failure, Validation, NotFound, Conflict. See Handle Errors for the full mapping.
Queries follow the same shape with IQuery<TResponse>:
public record GetOpenJournalCountQuery(string DataAreaId) : IQuery<Result<int>>
{
public IReadOnlyDictionary<string, object> GetLoggingContext() =>
new Dictionary<string, object> { ["DataAreaId"] = DataAreaId };
}Pair it with IRequestHandler<GetOpenJournalCountQuery, Result<int>> in the consumer assembly. To cache the response, implement ICacheableQuery<TResponse> instead and set CacheKey — see Cache Query Results.
Write an AbstractValidator<T> for your command or query in the consumer assembly. AddConsumerHandlers registers it, and the ValidationBehaviour runs it before the handler.
using FluentValidation;
public sealed class PostLedgerJournalCommandValidator
: AbstractValidator<PostLedgerJournalCommand>
{
public PostLedgerJournalCommandValidator()
{
RuleFor(command => command.DataAreaId).NotEmpty().Length(1, 4);
RuleFor(command => command.JournalBatchNumber).NotEmpty();
}
}A validation failure short-circuits the pipeline with a failed Result carrying IntegrationError code Validation.Error and ErrorType.Validation. See Add Validation.
Register an IPipelineBehavior<TRequest, TResponse> after AddIntegratoR and it runs after the three built-in behaviours.
using MediatR;
public sealed class IdempotencyBehaviour<TRequest, TResponse>
: IPipelineBehavior<TRequest, TResponse>
where TRequest : IRequest<TResponse>
{
private readonly IIdempotencyStore _store; // consumer-defined; not shipped by the framework
public IdempotencyBehaviour(IIdempotencyStore store) => _store = store;
public async Task<TResponse> Handle(
TRequest request,
RequestHandlerDelegate<TResponse> next,
CancellationToken cancellationToken)
{
// Cross-cutting concern — record the idempotency token, then call the next step.
return await next().ConfigureAwait(false);
}
}Register it in the same IServiceCollection:
services.AddIntegratoR(configuration, integrator =>
integrator.AddConsumerHandlers(Assembly.GetExecutingAssembly()));
services.AddTransient(typeof(IPipelineBehavior<,>), typeof(IdempotencyBehaviour<,>));AddIntegratoR registers the three built-in behaviours in this order:
Logging → Validation → Caching → Handler.
Registration is onion-nested: the first behaviour registered wraps every later one. So Logging is outermost (it times and records the whole request), Validation short-circuits before Caching and the handler, and Caching serves a cached hit without invoking the handler.
Because AddIntegratoR registers all three first, a behaviour you register after it runs inside the built-ins — after Caching, immediately around the handler:
Logging → Validation → Caching → YourBehaviour → Handler
Caution
Registration order fixes execution order, and getting it wrong fails silently. Register a behaviour that must reject a request (an auth or idempotency gate) after AddIntegratoR and it runs after Caching — a cached response is returned before your gate ever executes, so the gate looks wired but never fires. To run a behaviour before Validation, register it on the IServiceCollection before calling AddIntegratoR.
-
Send Commands — when the generic
CreateCommand<T>/UpdateCommand<T>/DeleteCommand<T>shape is enough -
Add Validation — validator authoring and the
Validation.Errorfailure - Cache Query Results — opt a custom query into the caching behaviour
- Understand the Architecture — the pipeline model and dependency direction
Get Started
Use Cases
- Handle Errors
- Configure Resilience
- Add Validation
- Cache Query Results
- Work with Dimensions
- Run Smoke Tests
- Extend the Pipeline
- Test with TestKit
Reference