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
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe aggregate type name.
committedVersionlongThe persisted event's zero-based stream version.
timestampDateTimeOffsetThe persisted event's timestamp.
isReplaybooltrue 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
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
Timestamp
Gets the persisted event's timestamp.
public DateTimeOffset Timestamp { get; }
Property Value
- DateTimeOffset
The event timestamp.