Table of Contents

Class IdentityMappedAggregateExtensions

Namespace
Excalibur.EventSourcing
Assembly
Excalibur.EventSourcing.dll

Resolves externally-identified aggregates through an IIdentityMapStore without exposing the window between reserving an identity and writing the event stream.

public static class IdentityMappedAggregateExtensions
Inheritance
IdentityMappedAggregateExtensions
Inherited Members

Methods

CreateOrUpdateAsync<TAggregate, TKey>(IIdentityMapStore, IEventSourcedRepository<TAggregate, TKey>, string, string, string, TKey, Func<TKey, TAggregate>, Action<TAggregate>, CancellationToken)

Resolves an external identifier to its aggregate, creating the aggregate if no event stream exists for it yet, applies the caller's change, and saves — in one operation.

public static Task<SaveResult> CreateOrUpdateAsync<TAggregate, TKey>(this IIdentityMapStore store, IEventSourcedRepository<TAggregate, TKey> repository, string externalSystem, string externalId, string aggregateType, TKey candidateId, Func<TKey, TAggregate> create, Action<TAggregate> update, CancellationToken cancellationToken) where TAggregate : class, IAggregateRoot<TKey>, IAggregateSnapshotSupport where TKey : struct, IParsable<TKey>

Parameters

store IIdentityMapStore

The identity map store.

repository IEventSourcedRepository<TAggregate, TKey>

The repository that owns the aggregate's event stream.

externalSystem string

The external system name.

externalId string

The external identifier value.

aggregateType string

The aggregate type name used in the mapping.

candidateId TKey

The ID to reserve if this external identifier has no mapping yet. Ignored when a mapping already exists, so it is safe — and expected — to pass a freshly generated ID on every call.

create Func<TKey, TAggregate>

Produces the aggregate when no event stream exists for the resolved ID. Receives the resolved ID, which is the reserved one whether this call created the mapping or found an existing one.

update Action<TAggregate>

Applies the change when an event stream already exists.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<SaveResult>

The result of saving the aggregate.

Type Parameters

TAggregate

The aggregate type.

TKey

The aggregate ID type.

Remarks

Prefer this over branching on MappingWasCreated yourself. A binding and an event stream are two writes to two stores with nothing atomic between them, so MappingWasCreated answers "did I win the race to reserve this ID" and never "does a stream exist". Code that treats it as the insert-versus-update discriminator is wrong in one direction and permanently: if anything interrupts between the bind and the append — cancellation at a deadline, a crash, an eviction — the mapping is committed, the stream never arrives, and from then on every call takes the already-exists branch, finds nothing, and either throws or silently does nothing for that external identifier forever. Nothing downstream learns of it.

This method decides by asking the store that owns the answer, so a torn state heals itself: a reservation whose append never landed is simply created on the next call. There is no compensating delete to get right, and there could not be — an unbind in a failure path only runs if the process survives to run it, which is precisely the case that produced the tear, and it races any concurrent writer that has already resolved the same mapping.

The two-callback shape is ConcurrentDictionary<TKey, TValue>'s AddOrUpdate: the caller supplies what to do in each case and the operation owns the decision between them, so there is no flag to misread.

At-least-once, so update must be idempotent on the event identifier. This is one operation to its caller, not one transaction: a redelivered change replays update, and a save that commits but whose acknowledgement is lost is retried. Concurrent callers for the same external identifier resolve the same ID and contend on the stream's optimistic concurrency, which surfaces as the repository's usual concurrency failure.