Interface IProjectionBuilder<TProjection>
- Namespace
- Excalibur.EventSourcing.Projections
- Assembly
- Excalibur.EventSourcing.dll
Fluent builder for configuring a projection's mode, event handlers, and optional caching.
public interface IProjectionBuilder<TProjection> where TProjection : class, new()
Type Parameters
TProjectionThe projection state type.
Remarks
Use this builder within AddProjection<T> to configure how a projection
processes events:
builder.AddProjection<OrderSummary>(p => p
.Async()
.When<OrderPlaced>((proj, e) => { proj.Total = e.Amount; })
.When<OrderShipped>((proj, e) => { proj.ShippedAt = e.ShippedAt; }));
If no mode is selected, the projection defaults to Async.
A second registration for the same projection type replaces the first.
This builder says what a projection FOLDS, not where it is stored. A stored projection also
needs a store registration — a provider's Add<T>, or
AddInMemoryProjectionStore<T> for development — and the host refuses to start, naming the
projection, when one is registered with no store. A projection declared Ephemeral() is
rebuilt on demand and needs none.
Methods
AddProjectionHandlersFromAssembly(Assembly)
Scans the specified assembly for all implementations of IProjectionEventHandler<TProjection, TEvent> and registers them as handlers for this projection.
[RequiresUnreferencedCode("Assembly scanning uses reflection to discover IProjectionEventHandler<T, TEvent> implementations.")]
IProjectionBuilder<TProjection> AddProjectionHandlersFromAssembly(Assembly assembly)
Parameters
assemblyAssemblyThe assembly to scan.
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Remarks
If the assembly contains no matching handler implementations, this is a no-op (D7).
Assembly scanning discovers handlers at startup. For AOT scenarios,
prefer explicit WhenHandledBy registration instead.
Exceptions
- InvalidOperationException
Thrown if two handler classes handle the same (TProjection, TEvent) pair.
Async()
Configures the projection to be applied asynchronously by the projection host. This is the default mode. Register an explicit background host or processor for Async projections.
IProjectionBuilder<TProjection> Async()
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Remarks
Cooperating processors apply events in position order using conditional positioned writes. A save returns a session token; pass it to a read that must observe its own write. Read-after-write is therefore available on request rather than implicit, which is what makes a lost fold inexpressible instead of merely unlikely.
Ephemeral()
Configures the projection as ephemeral — built on-demand without persistence.
Ephemeral projections are never stored; they are rebuilt from events each time
they are requested via IEphemeralProjectionEngine.
IProjectionBuilder<TProjection> Ephemeral()
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Inline()
Applies the committed event prefix before the save returns, with automatic durable recovery.
IProjectionBuilder<TProjection> Inline()
Returns
- IProjectionBuilder<TProjection>
This builder.
Remarks
A committed save whose projections cannot be confirmed reports BoundExpired on Projections rather than throwing: the events ARE durable and only the read model is behind. Do not repeat the command -- answer from the stale read model, or wait on the session token.
KeyedBy<TEvent>(Func<TEvent, string>)
Registers a key derivation function for the specified event type. When a projection processes an event of this type, the projection instance is loaded and stored using the derived key instead of the aggregate ID. This enables multi-stream projections keyed by event data (e.g., category, tenant, date).
IProjectionBuilder<TProjection> KeyedBy<TEvent>(Func<TEvent, string> keySelector) where TEvent : IDomainEvent
Parameters
keySelectorFunc<TEvent, string>A function that extracts the projection key from the event. Must return a non-null, non-empty string.
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Type Parameters
TEventThe domain event type to extract the key from.
TransactionalInline(string)
Updates this model atomically with saves of one aggregate type.
IProjectionBuilder<TProjection> TransactionalInline(string aggregateType)
Parameters
aggregateTypestringThe exact aggregate type name used by the repository.
Returns
- IProjectionBuilder<TProjection>
This builder.
Remarks
Requires transactional event and projection capabilities. Keyed and DI handlers are not supported. Handlers must be deterministic and free of external effects; the complete stream is replayed on each save. Support is optional for custom builders; the default implementation rejects this mode.
Exceptions
- NotSupportedException
This builder does not support transactional projections.
WhenDeleted(Func<string, CancellationToken, Task>)
Registers a deletion handler that is invoked when the associated aggregate is deleted. The handler receives the projection ID and a cancellation token, and is responsible for removing the projection from its store.
IProjectionBuilder<TProjection> WhenDeleted(Func<string, CancellationToken, Task> deleteAction)
Parameters
deleteActionFunc<string, CancellationToken, Task>An async function that deletes the projection by its ID.
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Remarks
Only one deletion handler may be registered per projection. If called multiple times, the last handler wins.
builder.AddProjection<OrderSummary>(p => p
.Async()
.When<OrderPlaced>((proj, e) => { /* ... */ })
.WhenDeleted((projectionId, ct) => store.DeleteAsync(projectionId, ct)));
WhenHandledBy<TEvent, THandler>()
Registers a DI-resolved typed event handler for the specified domain event type.
IProjectionBuilder<TProjection> WhenHandledBy<TEvent, THandler>() where TEvent : IDomainEvent where THandler : IProjectionEventHandler<TProjection, TEvent>
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Type Parameters
TEventThe domain event type to handle.
THandlerThe handler type implementing IProjectionEventHandler<TProjection, TEvent>.
Remarks
The handler is resolved from DI per invocation, enabling constructor injection for cross-aggregate lookups, logging, and other services.
A second registration for the same event type replaces the first.
When<TEvent>(Action<TProjection, TEvent, ProjectionContext>)
Registers an event handler for the specified domain event type that receives a ProjectionContext with replay/position awareness.
IProjectionBuilder<TProjection> When<TEvent>(Action<TProjection, TEvent, ProjectionContext> handler) where TEvent : IDomainEvent
Parameters
handlerAction<TProjection, TEvent, ProjectionContext>An action that applies the event to the projection state, with access to the projection processing context (e.g., IsReplay, GlobalPosition).
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Type Parameters
TEventThe domain event type to handle.
Remarks
Use this overload when handlers need to distinguish between live event processing and projection rebuild/replay scenarios. For example, skip sending notifications during replay:
builder.When<OrderPlaced>((proj, e, ctx) =>
{
proj.Total = e.Amount;
if (!ctx.IsReplay)
{
// send notification
}
});
When<TEvent>(Action<TProjection, TEvent>)
Registers an event handler for the specified domain event type.
IProjectionBuilder<TProjection> When<TEvent>(Action<TProjection, TEvent> handler) where TEvent : IDomainEvent
Parameters
handlerAction<TProjection, TEvent>An action that applies the event to the projection state.
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Type Parameters
TEventThe domain event type to handle.
WithCacheTtl(TimeSpan)
Configures optional caching for ephemeral projection results.
Only applies when the projection is used via IEphemeralProjectionEngine.
IProjectionBuilder<TProjection> WithCacheTtl(TimeSpan ttl)
Parameters
ttlTimeSpanThe cache time-to-live.
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
WithOptions(Action<ProjectionOptions>)
Configures per-projection options such as warning thresholds.
IProjectionBuilder<TProjection> WithOptions(Action<ProjectionOptions> configure)
Parameters
configureAction<ProjectionOptions>An action that configures ProjectionOptions.
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Remarks
builder.AddProjection<OrderSummary>(p => p
.Async()
.WithOptions(o => o.WarningThreshold = TimeSpan.FromMilliseconds(200))
.When<OrderPlaced>((proj, e) => { /* ... */ }));
WithSearchText(Func<TProjection, string>, Action<TProjection, string>)
Configures automatic computed search text for this projection.
After all events in a batch are applied to a projection instance,
the engine computes the search text via computeSearchText
and writes it back via setSearchText.
IProjectionBuilder<TProjection> WithSearchText(Func<TProjection, string> computeSearchText, Action<TProjection, string> setSearchText)
Parameters
computeSearchTextFunc<TProjection, string>A function that computes the search text from the current projection state. Called once per upsert (after all events in the batch are applied), not per event.
setSearchTextAction<TProjection, string>An action that sets the computed search text on the projection instance. Typically assigns to a
SearchTextproperty on the projection type.
Returns
- IProjectionBuilder<TProjection>
This builder for fluent chaining.
Remarks
This is opt-in — projections without WithSearchText do not invoke these search-text delegates.
The delegates provide explicit member access without requiring reflection-based member discovery.
Delegate implementations and their dependencies still require NativeAOT verification.
builder.AddProjection<OrderSummary>(p => p
.Async()
.WithSearchText(
proj => $"{proj.CustomerName} {proj.OrderNumber} {proj.Status}",
(proj, text) => proj.SearchText = text)
.When<OrderPlaced>((proj, e) => { proj.CustomerName = e.CustomerName; }));