Table of Contents

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

isReplay bool

Whether this event is being processed during a projection rebuild/replay.

globalPosition long?

The global stream position of the event, if available.

aggregateId string

The 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 aggregateId is 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

bool

true if the event is part of a rebuild/replay; false if it is a live event from SaveAsync.

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

globalPosition long

The global stream position of the event.

aggregateId string

The identifier of the aggregate whose event is being applied.

Returns

ProjectionContext

A new ProjectionContext configured for replay.