Skip to content

Cratis Chronicle reactors: register typed delegates

Cratis Chronicle’s .NET fluent reactor API registers delegate handlers without a reactor class. Use it when a host builds behavior from configuration or a framework owns the handlers. Give the reactor a stable identifier, declare the event types it handles, and register the resulting definition.

Use a class-based reactor when convention-based method discovery already fits your application.

Use On<TEvent> when the handler needs a known .NET event type. It receives the deserialized event, optionally with its event context. The overloads accept synchronous handlers or handlers that return a Task:

using Cratis.Chronicle.Events;
[EventType]
public record InvoiceIssued(string Customer, decimal Amount);
[EventType]
public record InvoicePaid(decimal Amount);
public interface IInvoiceNotifications
{
Task Issued(string customer, decimal amount);
Task Paid(EventSourceId invoice, decimal amount);
}
public class InvoiceReactorRegistration
{
public async Task Register(IEventStore eventStore, IInvoiceNotifications notifications)
{
await eventStore.Reactors.Register(
"invoice-notifications",
reactor => reactor
.On<InvoiceIssued>(@event => notifications.Issued(@event.Customer, @event.Amount))
.On<InvoicePaid>((@event, context) => notifications.Paid(context.EventSourceId, @event.Amount)));
}
}

View C# snippet source on GitHub

Without a catch-all handler, the reactor subscribes only to the event types declared with On<TEvent>. The subscription uses the event type identity and generation registered for TEvent; it does not necessarily select the latest generation if that .NET type represents a historical generation.

Use Subscribe when one handler should receive every event type known to the client. It receives each deserialized event as an object, together with its context:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;
public interface IAuditTrail
{
Task Record(EventSourceId eventSourceId, object @event);
}
public class AuditReactorRegistration
{
public async Task<IReactorHandler> Register(IEventStore eventStore, IAuditTrail auditTrail)
{
var definition = eventStore.Reactors.Define(
"audit-trail",
reactor => reactor.Subscribe((@event, context) => auditTrail.Record(context.EventSourceId, @event)));
// The definition is inspectable before it is registered.
Console.WriteLine($"{definition.Id} subscribes to all events: {definition.SubscribesToAllEvents}");
Console.WriteLine($"Event types: {string.Join(", ", definition.EventTypes.Select(_ => _.Id))}");
return await eventStore.Reactors.Register(definition);
}
}

View C# snippet source on GitHub

The subscription is a snapshot, not a wildcard at the kernel. When the definition is built, Subscribe adds the latest known generation of each event type not already covered by a typed handler. Unknown types and types registered later are not included. Inspect EventTypes on the definition to see the exact subscription.

You can combine typed and catch-all handlers. Typed handlers for the delivered .NET type run first, in declaration order, followed by the catch-all handlers.

Call Reactors.Define to inspect a definition before registering it. Check EventTypes and ClrTypes for the subscribed identities and .NET types, EventSequenceId for the source sequence, and IsReplayable for the replay policy. Id and SubscribesToAllEvents identify the reactor and whether it has a catch-all handler.

Use Reactors.Register(definition) when that subscription is correct, or Reactors.Register(id, define) to define and register it in one call.

A fluently defined reactor keeps its own observation position under its identifier, just like a class-based reactor. Use GetHandlerById to inspect its state and failed partitions later. Keep the identifier stable across restarts so it remains connected to that stored position.

Chronicle awaits each handler. If one throws or its task fails, the partition fails without advancing past that event. Make external effects idempotent so a retry does not repeat the business outcome; an earlier handler may already have completed before a later one fails.

The definition reads the default event log unless you select another sequence with OnEventSequence. Use NotReplayable to disable replay when effects must not run through history again. That setting does not eliminate retries or initial catch-up. This API has no start-at-tail option, so a new observer still catches up on existing history.

Registering on an event store sends the subscription to Chronicle immediately and registers it again after reconnecting. If you need to declare it earlier, during hosting or dependency injection setup, add it to the client options:

using Microsoft.Extensions.Hosting;
public static class FluentReactorAtStartup
{
public static void Configure(string[] args)
{
var builder = Host.CreateApplicationBuilder(args);
builder.AddCratisChronicle(configureOptions: options => options.ExplicitArtifacts
.RegisterReactor(
"invoice-log",
reactor => reactor
.On<InvoiceIssued>(@event => Console.WriteLine($"Issued to {@event.Customer}"))
.NotReplayable()));
}
}

View C# snippet source on GitHub

Each event store created by the client builds the definition during its first artifact discovery, after event types are known. The callback runs once per event store. A catch-all subscription therefore covers the types known at that point; reconnecting reuses the definition rather than expanding it.

If the host knows event type identifiers but has no .NET event classes to deserialize, use Register at Runtime to receive JSON instead.