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
builderIEventSourcingBuilderThe event sourcing builder.
configureAction<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
builderIEventSourcingBuilderThe builder.
Returns
- IEventSourcingBuilder
The builder for fluent configuration.
Type Parameters
TStrategyThe 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
builderIEventSourcingBuilderThe builder.
configureAction<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
builderIEventSourcingBuilderThe builder.
configureAction<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
builderIEventSourcingBuilderThe event sourcing builder.
configureAction<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
builderIEventSourcingBuilderThe 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
builderIEventSourcingBuilderThe builder.
configureAction<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
builderIEventSourcingBuilderThe builder.
Returns
- IEventSourcingBuilder
The builder for fluent configuration.
Type Parameters
TSerializerThe 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
builderIEventSourcingBuilderThe builder.
Returns
- IEventSourcingBuilder
The builder for fluent configuration.
Type Parameters
TMappingThe 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
builderIEventSourcingBuilderThe builder.
eventIntervalintThe 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
builderIEventSourcingBuilderThe 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
builderIEventSourcingBuilderThe builder.
maxSizeInByteslongThe 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
builderIEventSourcingBuilderThe builder.
Returns
- IEventSourcingBuilder
The builder for fluent configuration.
Type Parameters
TManagerThe snapshot manager implementation type.
UseTimeBasedSnapshots(IEventSourcingBuilder, TimeSpan)
Configures a time-based snapshot strategy.
public static IEventSourcingBuilder UseTimeBasedSnapshots(this IEventSourcingBuilder builder, TimeSpan timeInterval)
Parameters
builderIEventSourcingBuilderThe builder.
timeIntervalTimeSpanThe 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
builderIEventSourcingBuilderThe builder.
Returns
- IEventSourcingBuilder
The builder for fluent configuration.
Type Parameters
TOutboxWriterThe 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.