TCIS.Mediator 1.0.0-rc.37

TCIS.Mediator

A small CQRS mediator for the TCIS ecosystem: requests, notifications, streams, and a deliberately minimal pipeline.

Per-site handler routing lives in TCIS.Mediator.Keyed.

Table of contents

1. Registration

dotnet add package TCIS.Mediator

builder.Services.AddTMediator(options =>
{
    options.Assemblies = [typeof(Program).Assembly];   // scans handlers + validators
    options.AddTEcosystem();                            // tracing, then validation
});

Assembly scanning registers IRequestHandler<,>, INotificationHandler<>, IStreamRequestHandler<,> and FluentValidation IValidator<>.

IMediator is registered with TryAdd, so AddTMediator and AddTKeyedMediator may be called in either order without one silently overriding the other.

2. Requests and handlers

public sealed record CreateOrder(string OrderNo, string CustomerCode) : IRequest<Guid>;

public sealed class CreateOrderHandler(IUnitOfWork uow) : IRequestHandler<CreateOrder, Guid>
{
    public async Task<Guid> Handle(CreateOrder request, CancellationToken ct)
    {
        var order = new Order { OrderNo = request.OrderNo };
        uow.Repository<Order>().Add(order);
        await uow.SaveChangesAsync(ct);
        return order.Id;
    }
}

// Call site
Guid id = await mediator.Send(new CreateOrder("ORD-001", "CUST-01"), ct);

Use IRequest (no type argument) for commands with no return value — it is IRequest<Unit>.

3. The pipeline

Registration order IS execution order, outer to inner. The behavior registered first ends up outermost.

AddTEcosystem() registers exactly two:

TracingBehavior      ← outermost: the span covers the whole request
ValidationBehavior
handler              ← innermost

Add your own with options.AddBehavior(typeof(MyBehavior<,>)) — placed according to where you register it.

Why the standard pipeline is this small

Four behaviors were removed after an audit found that nothing in the repository — including all three templates and the sample — had ever implemented them:

• ExceptionHandlerBehavior could turn an infrastructure failure into a fake success, violating the business/infrastructure boundary. TExceptionMiddleware already maps exceptions by taxonomy.
• LoggingBehavior logged the whole request object at Information level — a login or change-password command would have written credentials to the log. Duration is already on the tracing span; 5xx logging is already in the middleware.
• PreProcessorBehavior / PostProcessorBehavior ran on every request to iterate an empty collection. Work that belongs before or after a handler reads better inside the handler.

Validation

ValidationBehavior runs every registered IValidator<TRequest>. On failure it throws TValidationException with code VALIDATION_ERROR (HTTP 400) and per-field detail:

{
  "isSuccess": false,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed: Name is required.",
  "data": [ { "field": "name", "message": "Name is required." } ]
}

It stays in the pipeline — rather than relying on the MVC validation filter — because it is the only place covering every ingress: MVC controllers, Minimal APIs, gRPC services, EventBus consumers and Hangfire jobs all reach the same handler (ARC-050). The MVC filter only runs for controller actions.

4. Notifications

public sealed record ContainerWeighed(Guid VisitId, string ContainerNo, int WeightKg) : INotification;

public sealed class UpdateVisitTotalHandler : INotificationHandler<ContainerWeighed> { … }
public sealed class WriteWeighAuditHandler  : INotificationHandler<ContainerWeighed> { … }

await mediator.Publish(new ContainerWeighed(visitId, "TCIU1234567", 28400), ct);

Every registered handler runs, sequentially, in DI registration order.

Publish is not fire-and-forget. The correct mental model is:

await mediator.Publish(evt, ct);
// ≡
foreach (var h in handlers) await h.Handle(evt, ct);

No queue, no separate scope, no retry. Handlers run on the caller's thread, in the caller's DI scope, sharing the caller's DbContext and transaction. A handler that throws fails the caller, and later handlers do not run.

Sequential is not a limitation to work around: handlers share one DbContext, which is not thread-safe. Dispatching them concurrently produces "A second operation was started on this context".

5. ⚠️ Publish vs EventBus — read before using either

One question decides it:

If this handler fails, SHOULD the original command fail too?

Yes → mediator.Publish · No → EventBus + Outbox

All four conditions must hold to use Publish. Break one and you need the EventBus:

Where Publish genuinely earns its place

Several same-module reactions that must be atomic. The command does not need to know how many pieces of logic react.

An in-transaction extension point for plugins — the strongest reason in this stack. Platform publishes, a site plugin adds its own reaction, and both live or die together:

await mediator.Publish(new GateInCompleted(transactionId), ct);   // Platform

[/* plugin assembly */]
public sealed class CatLaiSurchargeHandler : INotificationHandler<GateInCompleted> { … }

With TCIS.Mediator.Keyed, Platform and plugin handlers both react. The EventBus cannot do this — it is eventual by design, so the plugin's reaction would land outside the transaction and change the business meaning.

Where it does not

Do not reach for Publish merely to "decouple". If there is exactly one handler and it must run, call the service directly: you get a compile-time contract, a readable call flow, and a debugger that steps straight through.

Publish earns its keep through plurality and openness — an unknown, extensible set of reactors. Without that, it is a method call hidden behind indirection.

Decision table

6. Streams

public sealed record ExportOrders(DateOnly From) : IStreamRequest<OrderRow>;

await foreach (var row in mediator.CreateStream(new ExportOrders(from), ct))
{
    await writer.WriteAsync(row);
}

Use for large exports where materialising the whole result would blow memory.

7. Pitfalls