TCIS.Mediator.Keyed 1.0.0-rc.35

TCIS.Mediator.Keyed

Routes mediator handlers by site code, so a port-specific plugin can override or extend the standard business without the Platform knowing it exists.

Core mediator behaviour — pipeline, validation, notifications — is documented in TCIS.Mediator.

1. Registration

dotnet add package TCIS.Mediator.Keyed

builder.Services.AddTKeyedMediator(options =>
{
    options.Assemblies = [typeof(Program).Assembly];
    options.AddTEcosystem();
});

One call does four things:

AddTKeyedMediator and AddTMediator may be called in either order — the core registers IMediator with TryAdd, so it never overwrites the keyed one.

2. Send overrides · Publish adds

This is the distinction to keep in mind:

// Send — CATLAI's handler wins if it exists, otherwise the platform's runs
var result = await mediator.Send(new CalculateGateFee(transactionId), ct);

// Publish — BOTH the platform reaction and CATLAI's reaction run
await mediator.Publish(new GateInCompleted(transactionId), ct);

That asymmetry is the point of the 80/20 model: a port overrides the parts it needs to change, and adds the parts that are extra.

3. The key is read per resolution

KeyedMediator calls IMediatorKeyProvider.GetCurrentKey() each time a service is resolved, not once when it is constructed.

That matters for anything holding an IMediator longer than one request — a background worker that resolves once and then processes messages for several tenants, or any field-injected mediator. Freezing the key at construction would have run the wrong site's business with no signal at all.

Keys are normalised (Trim().ToUpperInvariant()) before lookup, so a custom key provider returning "catlai" still matches handlers registered as CATLAI instead of silently falling back to the platform handler.

4. Writing a plugin handler

Plugin assemblies are registered by the Pluggable engine's discovery pass, keyed by the module's SiteCode:

// In the CATLAI plugin assembly
public sealed class CatLaiCalculateGateFeeHandler : IRequestHandler<CalculateGateFee, decimal>
{
    public Task<decimal> Handle(CalculateGateFee request, CancellationToken ct) { … }
}

Nothing else is needed — no attribute, no manual registration. The handler is discovered because the assembly was passed to AddSitePlugins, and it wins over the platform handler for that site only.

5. Custom key source

The default provider reads the site code from IWorkContext. Replace it when the key comes from somewhere else:

public sealed class HeaderMediatorKeyProvider(IHttpContextAccessor accessor) : IMediatorKeyProvider
{
    public string GetCurrentKey()
        => accessor.HttpContext?.Request.Headers["X-Site-Code"].FirstOrDefault() ?? Sites.Default;
}

builder.Services.AddScoped<IMediatorKeyProvider, HeaderMediatorKeyProvider>();   // before AddTKeyedMediator

Prefer the default. WorkContext is the single source of truth for the site code across every ingress — HTTP, gRPC, Hangfire and EventBus all restore it through context propagation. A second source is how one site's steps end up running with another site's rules.

6. Pitfalls