Class ProjectionContext
- Namespace
- Excalibur.EventSourcing
- Assembly
- Excalibur.EventSourcing.Abstractions.dll
Provides contextual information about the projection processing environment
when handling events in a When<TEvent> handler.
public sealed class ProjectionContext
- Inheritance
-
ProjectionContext
- Inherited Members
Remarks
Use this context to tell a deliberate re-fold of history (a rebuild, a recovery, an on-demand build) from ordinary delivery, so that effects which are certainly wrong to repeat across the whole event log can be skipped:
builder.AddProjection<OrderSummary>(p => p
.Async()
.When<OrderPlaced>((proj, e, ctx) =>
{
proj.Total = e.Amount; // always correct, needs no guard
if (!ctx.IsReplay)
{
// Not a re-fold of history. Still potentially a REPEAT: delivery is
// at-least-once, so this must be idempotent on e.EventId regardless.
}
}));
IsReplay is not a duplicate-suppression mechanism and must not be used as one. It is false on a redelivery after a crash or a reader overlap, because such a delivery is not a re-fold of history. A handler with effects outside the projection state is idempotent or it is wrong.
Constructors
ProjectionContext(bool, long?, string)
Initializes a new instance of the ProjectionContext class.
public ProjectionContext(bool isReplay, long? globalPosition, string aggregateId)
Parameters
isReplayboolWhether this event is being processed during a projection rebuild/replay.
globalPositionlong?The global stream position of the event, if available.
aggregateIdstringThe identifier of the aggregate whose event is being applied.
Remarks
The aggregate identifier is required and there is no overload without it. Every event reaching a projection came from exactly one aggregate, so a context without an identity does not describe anything that can happen -- and a projection silently stamped with an empty id is the failure this type exists to prevent. Making it required moves that from a convention to something the compiler enforces.
Exceptions
- ArgumentException
Thrown when
aggregateIdis null or empty.
Properties
AggregateId
Gets the identifier of the aggregate whose event is being applied.
public string AggregateId { get; }
Property Value
- string
The identifier of the aggregate whose event is being applied. Never null or empty.
Remarks
Domain events do not carry the aggregate identifier; the stored envelope is authoritative for it. This is how a projection reaches it.
A projection read back by a client usually needs to store this. Projection stores key the stored document by the projection ID, but a read returns the document body alone, so an identifier never written into the body is not available to the caller. A client loading a projection to populate an edit screen then has nothing to send to an update command:
.When<CustomerCreated>((view, e, ctx) =>
{
view.Id = ctx.AggregateId; // the read model's own identity
view.Name = e.Name;
})
Always populated. The constructor rejects a null or empty identifier, so a handler never has to
guard it: a projection whose identity silently became "" is indistinguishable from one
that was never given an identity, and the type refuses to represent that state.
GlobalPosition
Gets the global stream position of the event, if available.
public long? GlobalPosition { get; }
Property Value
- long?
The global position in the all-events stream, or null if the apply carried no position (e.g., an ephemeral projection replay, which reads one aggregate's stream rather than the global one).
IsReplay
Gets a value indicating whether the current event is being processed during a projection rebuild or replay, as opposed to live event processing.
public bool IsReplay { get; }
Property Value
Methods
Replay(long, string)
Creates a replay context for an event belonging to the specified aggregate.
public static ProjectionContext Replay(long globalPosition, string aggregateId)
Parameters
globalPositionlongThe global stream position of the event.
aggregateIdstringThe identifier of the aggregate whose event is being applied.
Returns
- ProjectionContext
A new ProjectionContext configured for replay.