Interface IIdentityMapStore
- Namespace
- Excalibur.Data.IdentityMap
- Assembly
- Excalibur.Data.IdentityMap.dll
Provides identity resolution between external system identifiers and internal aggregate IDs.
public interface IIdentityMapStore
- Extension Methods
Remarks
Used during CDC ingestion, API anti-corruption layers, and import pipelines to maintain stable mappings between foreign keys and domain aggregate identifiers.
All identifiers are stored as strings at the persistence layer, following the framework convention where aggregate roots normalize typed keys to strings. Use the typed extension methods in IdentityMapStoreExtensions for compile-time safety.
Methods
BindAsync(string, string, string, string, CancellationToken)
Creates or updates a mapping between an external identifier and an aggregate ID.
ValueTask BindAsync(string externalSystem, string externalId, string aggregateType, string aggregateId, CancellationToken cancellationToken)
Parameters
externalSystemstringThe external system name.
externalIdstringThe external identifier value.
aggregateTypestringThe aggregate type name.
aggregateIdstringThe internal aggregate ID to map to.
cancellationTokenCancellationTokenCancellation token.
Returns
ResolveAsync(string, string, string, CancellationToken)
Resolves an external identifier to its mapped aggregate ID.
ValueTask<string?> ResolveAsync(string externalSystem, string externalId, string aggregateType, CancellationToken cancellationToken)
Parameters
externalSystemstringThe external system name (e.g., "LegacyCore", "SAP").
externalIdstringThe external identifier value.
aggregateTypestringThe target aggregate type name (e.g., "Order", "Account").
cancellationTokenCancellationTokenCancellation token.
Returns
ResolveBatchAsync(string, IReadOnlyList<string>, string, CancellationToken)
Resolves a batch of external identifiers to their mapped aggregate IDs.
ValueTask<IReadOnlyDictionary<string, string>> ResolveBatchAsync(string externalSystem, IReadOnlyList<string> externalIds, string aggregateType, CancellationToken cancellationToken)
Parameters
externalSystemstringThe external system name (shared by all IDs in the batch).
externalIdsIReadOnlyList<string>The external identifier values to resolve.
aggregateTypestringThe target aggregate type name.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<IReadOnlyDictionary<string, string>>
A dictionary mapping external IDs to aggregate IDs for entries that exist.
Remarks
The default implementation falls back to sequential per-item ResolveAsync(string, string, string, CancellationToken) calls. Override in stores that support efficient batch lookups (e.g., SQL WHERE IN clause).
TryBindAsync(string, string, string, string, CancellationToken)
Creates a mapping only if no mapping exists for the external identifier. Returns the existing aggregate ID if one is already bound.
ValueTask<IdentityBindResult> TryBindAsync(string externalSystem, string externalId, string aggregateType, string aggregateId, CancellationToken cancellationToken)
Parameters
externalSystemstringThe external system name.
externalIdstringThe external identifier value.
aggregateTypestringThe aggregate type name.
aggregateIdstringThe aggregate ID to bind if no mapping exists.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<IdentityBindResult>
A result containing the aggregate ID (either newly bound or existing) and whether the binding was newly created.
UnbindAsync(string, string, string, CancellationToken)
Removes a mapping for an external identifier.
ValueTask<bool> UnbindAsync(string externalSystem, string externalId, string aggregateType, CancellationToken cancellationToken)
Parameters
externalSystemstringThe external system name.
externalIdstringThe external identifier value.
aggregateTypestringThe aggregate type name.
cancellationTokenCancellationTokenCancellation token.