Table of Contents

Class EventSourcingBuilderExtensions

Namespace
Microsoft.Extensions.DependencyInjection
Assembly
Excalibur.EventSourcing.dll

Extension methods for IEventSourcingBuilder.

public static class EventSourcingBuilderExtensions
Inheritance
EventSourcingBuilderExtensions
Inherited Members

Methods

AddProjectionProcessor(IEventSourcingBuilder, Action<GlobalStreamProjectionOptions>?)

Registers projection processing WITHOUT a background service, for a host that drives it itself.

public static IEventSourcingBuilder AddProjectionProcessor(this IEventSourcingBuilder builder, Action<GlobalStreamProjectionOptions>? configure = null)

Parameters

builder IEventSourcingBuilder

The event sourcing builder.

configure Action<GlobalStreamProjectionOptions>

Configures the stable subscription identity and page size. SubscriptionScope is required; SubscriptionRevision defaults to "1". IdlePollingInterval is used only by a background worker.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

Examples

services.AddExcalibur(x => x.AddEventSourcing(es =>
{
    es.UseSqlServer(sql => sql.ConnectionString(connStr));
    es.AddProjection<OrderSummary>(p => p
        .Async()
        .When<OrderCreated>((proj, e) => { proj.Total++; }));

    es.AddProjectionProcessor(opts => opts.SubscriptionScope = "orders/sql-events/order-summaries");
}));

// then, where the work happens:
await repository.SaveAsync(order, ct);
var result = await processor.ProcessPendingAsync(ct); // inspect Outcome before claiming freshness

Remarks

Resolve IProjectionProcessor and call ProcessPendingAsync(CancellationToken) when you want projections advanced. It processes through the stream head captured at invocation entry and returns. A halt or cancellation returns its own outcome; callers must inspect it before claiming a read model is current.

Two cases need this rather than EnableProjectionProcessing(IEventSourcingBuilder, Action<GlobalStreamProjectionOptions>?). A host that cannot run a background service at all — a Function, a Lambda — drives it from its trigger. And a host that wants its read models current by the time a request returns drives it immediately after saving, which costs one read of the stream and makes the projection visible to the next read with no session token and no waiting.

Manual processing and background polling may run together. They share a FIFO gate for one finite page, released before idle polling. Across processes, positioned projection writes and a checkpoint compare-and-set reconcile competing readers. All participants sharing a subscription name must use identical projection types, SubscriptionScope and SubscriptionRevision. A different definition is refused before effects; external effects remain at-least-once and must be idempotent.

This mirrors how the outbox is composed: its registration supplies the manually-driven processor, and the background drain is a separate explicit opt-in.

AddSnapshotStrategy<TStrategy>(IEventSourcingBuilder)

Configures a custom snapshot strategy.

public static IEventSourcingBuilder AddSnapshotStrategy<TStrategy>(this IEventSourcingBuilder builder) where TStrategy : class, ISnapshotStrategy

Parameters

builder IEventSourcingBuilder

The builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

Type Parameters

TStrategy

The snapshot strategy implementation type.

AddSnapshotUpgrading(IEventSourcingBuilder, Action<SnapshotUpgradingBuilder>)

Configures snapshot upgrading for automatic snapshot version migration.

public static IEventSourcingBuilder AddSnapshotUpgrading(this IEventSourcingBuilder builder, Action<SnapshotUpgradingBuilder> configure)

Parameters

builder IEventSourcingBuilder

The builder.

configure Action<SnapshotUpgradingBuilder>

Action to configure the snapshot upgrading builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

AddUpcastingPipeline(IEventSourcingBuilder, Action<UpcastingBuilder>)

Configures the upcasting pipeline for event versioning.

public static IEventSourcingBuilder AddUpcastingPipeline(this IEventSourcingBuilder builder, Action<UpcastingBuilder> configure)

Parameters

builder IEventSourcingBuilder

The builder.

configure Action<UpcastingBuilder>

Action to configure the upcasting builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

EnableProjectionProcessing(IEventSourcingBuilder, Action<GlobalStreamProjectionOptions>?)

Enables background processing for Async projections.

public static IEventSourcingBuilder EnableProjectionProcessing(this IEventSourcingBuilder builder, Action<GlobalStreamProjectionOptions>? configure = null)

Parameters

builder IEventSourcingBuilder

The event sourcing builder.

configure Action<GlobalStreamProjectionOptions>

Configures subscription identity, polling and page size. SubscriptionScope must be supplied here or through options configuration. SubscriptionRevision defaults to "1". The built-in processor checkpoints every page; CheckpointInterval applies only to custom global-stream hosts.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

Examples

services.AddExcalibur(x => x.AddEventSourcing(es =>
{
    es.UseSqlServer(sql => sql.ConnectionString(connStr));

    es.AddProjection<OrderSummary>(p => p
        .Async()
        .When<OrderCreated>((proj, e) => { proj.Total++; }));

    // Start the background host that processes async projections
    es.EnableProjectionProcessing(opts =>
    {
        opts.SubscriptionScope = "orders/sql-events/order-summaries";
        opts.SubscriptionRevision = "1";
        opts.IdlePollingInterval = TimeSpan.FromSeconds(2);
        opts.BatchSize = 200;
    });
}));

Remarks

THIS CALL IS REQUIRED, and omitting it fails silently. A projection registered with .Async() is applied by nothing unless a projection processor runs, so without this (or a manual IProjectionProcessor drive, which this also registers) the projection exists, the application starts clean, and no event is ever folded into it. There is no error to notice. Nothing else in the registration hints that it is outstanding — which is why this extension lives in the same namespace as AddProjection rather than one a consumer has to discover.

This is the projection-side equivalent of CDC's EnableBackgroundProcessing(). It registers a hosted service that polls the global event stream via IGlobalStreamQuery and dispatches events to all projections registered with .Async() mode.

Requires an IGlobalStreamQuery implementation to be registered by the event store provider (e.g., UseSqlServer()), a positioned projection store, and an explicit checkpoint durability choice. Background startup refuses invalid composition or a different definition already bound to the subscription. Ambient leader election does not gate this worker.

RequirePositionedProjectionWrites(IEventSourcingBuilder)

Requires every registered projection to be written through a store that records how far the projection has been folded, so a re-delivered event cannot be applied twice.

public static IEventSourcingBuilder RequirePositionedProjectionWrites(this IEventSourcingBuilder builder)

Parameters

builder IEventSourcingBuilder

The event sourcing builder.

Returns

IEventSourcingBuilder

The builder, for chaining.

Remarks

What this buys. A projection is applied by loading it, mutating it and writing it back, and without a recorded position nothing can tell that an event is being applied a second time. A handler that assigns a value survives that; one that accumulates — incrementing a total, appending to a list — double-counts on every redelivery, silently and without bound. The framework cannot tell the two apart, which is why this is a choice the host makes rather than a default the framework guesses.

It fails at startup rather than degrading. A store without the capability is refused by name, with the projections that cannot be served. Falling back to the unconditional write would hand back exactly the defect this prevents, reported as success.

Requires the last-applied-position migration for your provider, shipped alongside its other schema scripts.

UseCompositeSnapshotStrategy(IEventSourcingBuilder, Action<CompositeSnapshotStrategyBuilder>)

Configures a composite snapshot strategy combining multiple strategies.

public static IEventSourcingBuilder UseCompositeSnapshotStrategy(this IEventSourcingBuilder builder, Action<CompositeSnapshotStrategyBuilder> configure)

Parameters

builder IEventSourcingBuilder

The builder.

configure Action<CompositeSnapshotStrategyBuilder>

Action to configure the composite strategy.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

UseEventSerializer<TSerializer>(IEventSourcingBuilder)

Configures a custom event serializer implementation.

public static IEventSourcingBuilder UseEventSerializer<TSerializer>(this IEventSourcingBuilder builder) where TSerializer : class, IEventSerializer

Parameters

builder IEventSourcingBuilder

The builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

Type Parameters

TSerializer

The serializer implementation type.

UseEventStoreErasure<TMapping>(IEventSourcingBuilder)

Registers event store erasure support for GDPR compliance.

public static IEventSourcingBuilder UseEventStoreErasure<TMapping>(this IEventSourcingBuilder builder) where TMapping : class, IAggregateDataSubjectMapping

Parameters

builder IEventSourcingBuilder

The builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

Type Parameters

TMapping

The IAggregateDataSubjectMapping implementation that maps data subjects to their aggregates.

UseIntervalSnapshots(IEventSourcingBuilder, int)

Configures an interval-based snapshot strategy.

public static IEventSourcingBuilder UseIntervalSnapshots(this IEventSourcingBuilder builder, int eventInterval = 100)

Parameters

builder IEventSourcingBuilder

The builder.

eventInterval int

The number of events between snapshots. Default: 100.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

UseNoSnapshots(IEventSourcingBuilder)

Configures a no-op snapshot strategy that never creates snapshots.

public static IEventSourcingBuilder UseNoSnapshots(this IEventSourcingBuilder builder)

Parameters

builder IEventSourcingBuilder

The builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

UseSizeBasedSnapshots(IEventSourcingBuilder, long)

Configures a size-based snapshot strategy.

public static IEventSourcingBuilder UseSizeBasedSnapshots(this IEventSourcingBuilder builder, long maxSizeInBytes)

Parameters

builder IEventSourcingBuilder

The builder.

maxSizeInBytes long

The maximum size in bytes before creating a snapshot.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

UseSnapshotManager<TManager>(IEventSourcingBuilder)

Configures a custom snapshot manager.

public static IEventSourcingBuilder UseSnapshotManager<TManager>(this IEventSourcingBuilder builder) where TManager : class, ISnapshotManager

Parameters

builder IEventSourcingBuilder

The builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

Type Parameters

TManager

The snapshot manager implementation type.

UseTimeBasedSnapshots(IEventSourcingBuilder, TimeSpan)

Configures a time-based snapshot strategy.

public static IEventSourcingBuilder UseTimeBasedSnapshots(this IEventSourcingBuilder builder, TimeSpan timeInterval)

Parameters

builder IEventSourcingBuilder

The builder.

timeInterval TimeSpan

The time interval between snapshots.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

UseTransactionalOutboxWriter<TOutboxWriter>(IEventSourcingBuilder)

Configures a custom transactional outbox writer for event sourcing.

public static IEventSourcingBuilder UseTransactionalOutboxWriter<TOutboxWriter>(this IEventSourcingBuilder builder) where TOutboxWriter : class, ITransactionalOutboxWriter

Parameters

builder IEventSourcingBuilder

The builder.

Returns

IEventSourcingBuilder

The builder for fluent configuration.

Type Parameters

TOutboxWriter

The transactional outbox writer implementation type.

Remarks

Most consumers should register the unified outbox via AddExcaliburOutbox(o => o.UseSqlServer(...)) which automatically registers ITransactionalOutboxWriter. Use this method only for custom implementations.