Skip to content

React to Chronicle Read Model Changes

A Chronicle read model reactor runs application code when a read model instance is added, modified, or removed. Use one when a change to derived state should trigger a notification or downstream update, without managing a watch subscription yourself.

In .NET, name a handler Added, Modified, or Removed and Chronicle dispatches matching changes to it. This convenience uses the watch stream; it does not add transactional delivery. Choose your client tab for its handler and registration syntax.

For .NET, implement the IReadModelReactor marker interface and add a method named Added, Modified, or Removed. The method name selects the change, and the first parameter selects the read model to watch:

using Cratis.Chronicle.ReadModels;
public class AccountNotifier : IReadModelReactor
{
public Task Added(Account account) => SendWelcome(account);
public Task Modified(Account account) => SendUpdated(account);
public Task Removed(Account account) => SendClosed(account);
Task SendWelcome(Account account) => Task.CompletedTask;
Task SendUpdated(Account account) => Task.CompletedTask;
Task SendClosed(Account account) => Task.CompletedTask;
}

View C# snippet source on GitHub

The .NET client discovers and starts these reactors automatically, then closes their subscriptions when the client is disposed. To handle another model or change type, add a matching method.

A .NET handler can return void, Task, or Task<T>. Its first parameter accepts either a single read model or a collection. The collection form contains the changed instance, or is empty when a removal has no instance. It does not batch several changes:

using Cratis.Chronicle.ReadModels;
public class AccountBatchProjector : IReadModelReactor
{
public async Task Modified(IEnumerable<Account> accounts)
{
foreach (var account in accounts)
{
await Sync(account);
}
}
Task Sync(Account account) => Task.CompletedTask;
}

View C# snippet source on GitHub

In .NET, parameters after the read model are resolved from the service container, with EventContext supplied separately by the dispatcher. For a projection-backed watch, that context identifies the causing event’s sequence number, occurrence time, and correlation ID. Reducer and materialized observations have less context, as described below.

Use constructor injection, method parameters, or both for your services:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.ReadModels;
public interface IAccountNotifications
{
Task Notify(string accountId);
}
public interface IAccountAuditLog
{
void Record(string accountId, EventSequenceNumber sequenceNumber);
}
public class AccountAuditor(IAccountNotifications notifications) : IReadModelReactor
{
public Task Modified(Account account, EventContext context, IAccountAuditLog audit)
{
audit.Record(account.Id, context.SequenceNumber);
return notifications.Notify(account.Id);
}
}

View C# snippet source on GitHub

A .NET handler can return events for Chronicle to append, using the same return shapes as a reactor side effect: a single event, a collection, an EventForEventSourceId, or a mix. The dispatcher honors [EventStreamType] and [EventSourceType] on the reactor. These appends are best-effort, not part of a transaction with the read model change.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.ReadModels;
[EventType]
public record AccountFlagged(string AccountId);
public class AccountReviewer : IReadModelReactor
{
public Task<AccountFlagged> Modified(Account account) =>
Task.FromResult(new AccountFlagged(account.Id));
}

View C# snippet source on GitHub

Method Reacts to
Added The watched instance was added, or first seen by an observation that infers changes locally.
Modified The read model instance changed.
Removed The read model instance was removed.

For projection-backed read models watched through the change stream, the server supplies the change type and causing event context. This distinguishes an addition from a modification. Reducer-backed and materialized observations infer changes locally instead.

In .NET, apply [Materialized] to observe stored state instead of the projection change stream. Chronicle observes the complete materialized collection, without the API’s default 50-instance page limit, and compares successive snapshots to infer changes.

using Cratis.Chronicle.ReadModels;
[Materialized]
public class AccountSnapshotReactor : IReadModelReactor
{
public Task Added(Account account) => Task.CompletedTask;
}

View C# snippet source on GitHub

Use this when the reaction should follow what is stored in the sink. It cannot preserve every intermediate state: SQL polling and snapshot delivery can combine several writes into one observed change.

The .NET dispatcher logs handler and append failures without pausing a partition or retrying the failed dispatch. Rapid changes can run handlers concurrently, so completion order is not guaranteed.

Materialized comparison uses serialized values keyed by id, _id, or Id. Its EventContext carries the model key but no causing event sequence number. Existing instances in the first snapshot are reported as Added; that does not mean they were just created.

For reducer-backed models, the .NET reactor tracks keys locally to infer additions. The first observed non-removal for a key is Added; later ones are Modified, and removals remain Removed. This does not supply the original event context.

If ordered, replayable processing is a requirement, react to the domain event rather than the derived read model. That page explains event-reactor delivery and partition handling so you can choose the appropriate processing model.