Table of Contents

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

TProjection

The 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

assembly Assembly

The 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

keySelector Func<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

TEvent

The 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

aggregateType string

The 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

deleteAction Func<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

TEvent

The domain event type to handle.

THandler

The 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

handler Action<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

TEvent

The 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

handler Action<TProjection, TEvent>

An action that applies the event to the projection state.

Returns

IProjectionBuilder<TProjection>

This builder for fluent chaining.

Type Parameters

TEvent

The 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

ttl TimeSpan

The 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

configure Action<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

computeSearchText Func<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.

setSearchText Action<TProjection, string>

An action that sets the computed search text on the projection instance. Typically assigns to a SearchText property 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; }));