Chronicle projections — register a read model explicitly
Register a Chronicle read model and its projection explicitly when assembly discovery cannot find them, such as a library outside the scanned assemblies or a projection generated at runtime. In the .NET client, explicit registration uses the same projection builder and kernel registration path as discovered definitions.
Only the way the client learns about the definition changes. Reads still follow the model’s materialized or passive behavior, and a materialized projection still catches up asynchronously. Registration does not make existing history appear in the sink before it returns.
Register a projection defined in code
Section titled “Register a projection defined in code”Define the projection with the same builder an IProjectionFor<T> class receives:
using Cratis.Chronicle.Events;using Cratis.Chronicle.Projections;
[EventType]public record StockReceived(string Sku, int Quantity);
[EventType]public record StockPicked(string Sku, int Quantity);
public record WarehouseStock(string Sku, int Quantity);
public class WarehouseStockRegistration{ public async Task<WarehouseStock?> Register(IEventStore eventStore, string sku) { await eventStore.Projections.Register<WarehouseStock>(projection => projection .From<StockReceived>(from => from.Add(model => model.Quantity).With(@event => @event.Quantity)) .From<StockPicked>(from => from.Subtract(model => model.Quantity).With(@event => @event.Quantity)));
// The read model is now an ordinary read model - read it like any other. return await eventStore.ReadModels.GetInstanceById<WarehouseStock>(sku); }}By default the projection is identified by the read model’s full type name, the same identity a model-bound projection for that read model would have. Pass an identifier when the projection’s identity has to survive renaming the read model. Keep it stable: Chronicle tracks the projection’s position under that identifier.
A stable projection ID does not preserve every storage identity. Renaming the model can still change its read-model identifier and default container. Plan that separately using the read-model migration checklist.
Register a passive projection
Section titled “Register a passive projection”A projection defined with Passive() is not materialized. Chronicle registers its read model without
a sink, so each read computes the instance from its events on demand:
using Cratis.Chronicle.Events;using Cratis.Chronicle.Projections;
[EventType]public record ShipmentDispatched(string Carrier);
public record ShipmentState(string Carrier);
public class ShipmentStateRegistration{ public async Task<ShipmentState?> Current(IEventStore eventStore, string shipmentId) { await eventStore.Projections.Register<ShipmentState>( projection => projection.Passive().From<ShipmentDispatched>(), id: "shipment-state");
// A passive projection is never materialized - each read computes the instance from its events. return await eventStore.ReadModels.GetInstanceById<ShipmentState>(shipmentId); }}A passive by-ID read selects one event source. Keep a view with cross-source joins or custom aggregation keys materialized when that history is needed to reconstruct it. See passive projections before changing an existing model’s consistency behavior.
Register a model-bound read model
Section titled “Register a model-bound read model”A read model whose projection is declared by model-bound attributes but is not in a scanned assembly can be registered by type:
using Cratis.Chronicle.Events;using Cratis.Chronicle.Projections.ModelBound;
[EventType]public record SupplierOnboarded(string Name);
[FromEvent<SupplierOnboarded>]public record Supplier(string Name);
public class SupplierRegistration{ public Task Register(IEventStore eventStore) => eventStore.ReadModels.Register<Supplier>();}ReadModels.Register<T>() recognizes a read model that no projection or reducer maintains yet, but that carries model-bound attributes, and registers its projection. Projections.Register<T>() does the same thing without the read model detour. A read model that discovery already found is not registered twice.
Register while configuring the client
Section titled “Register while configuring the client”Registrations made on an event store are sent to Chronicle immediately when the client is connected. Anything registered before the connection is established, or re-established, is included in the next registration pass instead.
To declare registrations before the client exists, from hosting or dependency injection setup, add them to the client options. Every event store the client creates builds them when it discovers its artifacts. It includes them in its normal registration pass and registers them again after every reconnect:
using Microsoft.Extensions.Hosting;
public static class ExplicitProjectionsAtStartup{ public static void Configure(string[] args) { var builder = Host.CreateApplicationBuilder(args);
builder.AddCratisChronicle(configureOptions: options => options.ExplicitArtifacts .RegisterProjection<WarehouseStock>(projection => projection .From<StockReceived>(from => from.Add(model => model.Quantity).With(@event => @event.Quantity)) .From<StockPicked>(from => from.Subtract(model => model.Quantity).With(@event => @event.Quantity))) .RegisterReadModel<Supplier>()); }}Registrations on the options are captured when the store is constructed and built during discovery, which is on by default (AutoDiscoverAndRegister). Later options changes apply only to new stores; reconnect retains the original recipes. A projection that cannot be built is reported through the event store’s registration outcome, like a discovered one.
Event types and the other artifact kinds can also be nominated without marker interfaces or attributes. See explicit artifact registration for the .NET composition APIs, peer conflicts and lifetime rules.
- A read model has one builder: a projection or a reducer. Registering a second projection with a different identifier for the same read model is rejected. Registering the same identifier again replaces the definition.
- An explicit projection cannot claim a read model that a discovered projection already maintains.
- Variants are wired together with their siblings during discovery, so a variant read model cannot be registered on its own.
After registering, inspect the registration outcome for failed definitions. If you replace a definition under the same ID, the registration lifecycle determines whether historical data needs replay; re-registering alone is not a storage migration.