Skip to main content

Aggregate Handlers & Cascading

Excalibur.EventSourcing.Handlers provides a Decider registration that wires a dispatched command straight to an event-sourced aggregate — load, decide, save with optimistic concurrency — without hand-writing a handler class. An optional cascading convention lets a handler return follow-up messages that UseOutbox() stages to the outbox.

Before You Start​

The Decider​

AddAggregateHandler registers a handler that, for a given command type, resolves the target aggregate's identity, loads it, applies a domain decision, and saves it back with optimistic concurrency:

using Microsoft.Extensions.DependencyInjection;

services.AddAggregateHandler<Order, OrderId, ShipOrder>(
resolveId: command => command.OrderId,
decide: (order, command, cancellationToken) =>
{
order.Ship(command.Carrier, command.TrackingNumber);
return Task.CompletedTask;
});
  • resolveId extracts the aggregate identifier from the command.
  • decide invokes the aggregate's own domain methods, which raise the aggregate's events. It does not persist directly — the handler saves the aggregate after the decision.

The command type must implement IDispatchAction, and the aggregate must be an IAggregateRoot<TKey> with snapshot support. The handler resolves its IEventSourcedRepository<TAggregate, TKey> from the container.

The identity resolver and decision are supplied explicitly (not reflected off the message), so the registration is AOT-safe — no runtime code generation.

Error semantics​

SituationSurfaces as
Command targets a missing aggregateResourceNotFoundException
A concurrent write raced the saveConcurrencyException

Cascading follow-up messages​

A handler can emit follow-up messages that are staged to the outbox by returning a result that implements ICascade. Two conditions must both hold, and the return type is only one of them:

  1. The handler's result implements ICascade — a result that does not produces no cascade.
  2. The pipeline includes the cascade step, which UseOutbox() adds.

The cascade step is not part of any shipped pipeline profile. A host that configures its pipeline from a profile alone stages no cascades, even though those profiles do stage the handler's own outbox messages — so the follow-up messages are silently dropped rather than reported as an error. Call UseOutbox() explicitly:

services.AddDispatch(dispatch =>
{
dispatch.UseOutbox(); // outbox staging and the cascade step
});

This call also states that the host stages, so it requires an IOutboxStore — register one for your provider alongside it, or the host refuses to start and names the registration it is missing. An event-sourced host that cascades needs a store in any case, since that is where the follow-up messages go.

The cascade step costs nothing when you are not using it: it returns immediately for any result that does not implement ICascade.

How to tell whether cascading is live. Dispatch a message whose handler returns a non-empty ICascade result and read the logs:

what you seewhat it means
Cascade: staged N follow-up message(s) (Debug)working
Cascade: handler ... returned N cascaded message(s) but no outbox is staged (Warning)the cascade step is in the pipeline but no outbox staging is — the messages were not dispatched
neither linethe cascade step is not in your pipeline at all — call UseOutbox()

The third row is the silent case, and it is the one to check first: nothing is logged because the middleware never runs.

using Excalibur.Dispatch;

public sealed record OrderShipped(IReadOnlyList<IDispatchMessage> Messages) : ICascade;

Cascaded messages are enqueued to the same outbox the handler already writes to, so they inherit its delivery semantics: atomic when a transactional writer participates in the handler's unit of work, otherwise eventually-consistent at-least-once (handlers must be idempotent). An empty Messages list produces no cascade.

Because the signal is the return type — not an attribute or reflection — cascading composes with the compile-time dispatch pipeline and stays AOT-safe.

What's Next​