Table of Contents

Class ProjectionHandlerContext

Namespace
Excalibur.EventSourcing
Assembly
Excalibur.EventSourcing.Abstractions.dll

Provides context about the aggregate whose events are being projected, passed to HandleAsync(TProjection, TEvent, ProjectionHandlerContext, CancellationToken).

public sealed class ProjectionHandlerContext
Inheritance
ProjectionHandlerContext
Inherited Members

Remarks

A new context is created for each event. For persisted events, aggregate identity, version and timestamp come from that event's stored envelope, even when a batch spans multiple streams. OverrideProjectionId starts as null and allows the handler to redirect the projection to a different ID.

Constructors

ProjectionHandlerContext(string, string, long, DateTimeOffset, bool)

Initializes a new instance of the ProjectionHandlerContext class.

public ProjectionHandlerContext(string aggregateId, string aggregateType, long committedVersion, DateTimeOffset timestamp, bool isReplay)

Parameters

aggregateId string

The aggregate identifier.

aggregateType string

The aggregate type name.

committedVersion long

The persisted event's zero-based stream version.

timestamp DateTimeOffset

The persisted event's timestamp.

isReplay bool

true when this event is being re-applied by a rebuild or a recovery rather than delivered live.

Properties

AggregateId

Gets the unique identifier of the aggregate that produced the events.

public string AggregateId { get; }

Property Value

string

The aggregate identifier.

AggregateType

Gets the type name of the aggregate.

public string AggregateType { get; }

Property Value

string

The aggregate type name.

CommittedVersion

Gets the persisted event's zero-based stream version.

public long CommittedVersion { get; }

Property Value

long

The committed version number.

IsReplay

Gets a value indicating whether this event is being RE-APPLIED rather than delivered live.

public bool IsReplay { get; }

Property Value

bool

true during a rebuild or recovery; otherwise false.

Remarks

It means a rebuild, recovery or on-demand replay is deliberately re-folding history — nothing more. It is a property of the OPERATION, set by the caller that asked for the re-fold, not a judgement about whether any particular effect already happened.

A rebuild or a recovery re-runs every handler over history. An asynchronous handler is arbitrary code with arbitrary side effects -- it may send mail, call a payment provider, or publish a message -- and a whole-history re-fold would perform all of them again.

It is a REQUIRED constructor parameter rather than an optional one with a default. A default of false is correct for the common case and wrong for the dangerous one, and the dangerous one is the path nobody is looking at when they add a call site.

This deliberately diverges from the sibling EventNotificationContext, which carries the same flag with a default of false. That type is a record with init-only members, where the default buys real ergonomics. This one is constructed only by the framework's own apply and replay paths, so the ergonomic saving is small and the safety is not. The divergence is a choice, not an oversight.

Consumer obligation: a handler with side effects outside the projection state MUST be idempotent, keyed on the event identifier. Delivery is at-least-once — an effect may be requested more than once for a single event after a process crash or an overlap between two readers of one subscription, and this flag is false on those deliveries, because they are not re-folds of history. The duplicate window is bounded by the events applied since the last durable checkpoint.

So use it to skip effects during a deliberate re-fold of the whole of history, where repeating them is certainly wrong. Never use it as the mechanism that makes a handler correct. No flag the framework computes can be that mechanism: the effect is performed by consumer code, in a process the framework does not control, against a resource it cannot name, so the effect and the record of it cannot commit together. Idempotency is the only thing that closes it.

Folding into the projection state itself is idempotent by construction and needs no guard.

OverrideProjectionId

Gets or sets an optional projection ID override. When set, the projection pipeline uses this ID instead of AggregateId to load and upsert the projection instance for the current event.

public string? OverrideProjectionId { get; set; }

Property Value

string

The overridden projection ID, or null to use the default aggregate ID.

Timestamp

Gets the persisted event's timestamp.

public DateTimeOffset Timestamp { get; }

Property Value

DateTimeOffset

The event timestamp.