Table of Contents

Class DomainEvent

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Base record for domain events with clean, parameterless construction.

public abstract record DomainEvent : IDomainEvent, IDispatchEvent, IDispatchMessage, IEquatable<DomainEvent>
Inheritance
DomainEvent
Implements
Inherited Members
Extension Methods

Remarks

Provides a low-boilerplate base for defining domain events as records:

public record OrderCreated(string OrderId, decimal Total) : DomainEvent;

// With metadata var evt = new OrderCreated("ord-1", 99.99m) .WithCorrelationId(correlationId);

Default behavior:

  • EventId: Auto-generated UUID v7 string for time-ordered uniqueness
  • OccurredAt: UTC timestamp at construction time
  • Metadata: Null (attach via fluent API or infrastructure)

Properties

CausationId

Gets the causation ID identifying the command or event that directly caused this event.

public virtual string? CausationId { get; }

Property Value

string

The causation ID, or null if not set.

Remarks

Reads CausationId (the framework's declared key, and what every framework write path now writes), falling back to the legacy "CausationId"/"causationId" spellings for events persisted before those two keys were unified with this one.

CorrelationId

Gets the correlation ID for tracking a chain of related operations across services.

public virtual string? CorrelationId { get; }

Property Value

string

The correlation ID, or null if not set.

Remarks

Reads CorrelationId (the framework's declared key, and what every framework write path now writes), falling back to the legacy "CorrelationId"/"correlationId" spellings for events persisted before those two keys were unified with this one.

EventId

Gets the unique identifier for this event instance.

[JsonRequired]
public virtual string EventId { get; init; }

Property Value

string

The unique identifier for this event instance.

Remarks

This value must be the same on every delivery of this event. It is the identity the inbox deduplicates on, so an event whose EventId differs between a delivery and its own redelivery is never recognised as a duplicate: the handler runs again and nothing records that it did.

A payload that omits this field is refused. The initializer below supplies an identity when you construct an event in process, so you never have to invent one — but it does NOT fire for a deserialized payload, and a property initializer never does. Before the field was required on the wire, an omitted eventId therefore produced a non-nullable string holding null, and the inbox skipped it and deduplicated on whatever transport-level identity answered next, or on none at all. Deserialization now fails instead, so a producer that does not emit the field learns immediately rather than losing deduplication silently.

Do not override this as a computed value. The idiom CorrelationId and CausationId use immediately below — deriving from Metadata — is wrong here: a computed property is never deserialized, and it is null whenever Metadata is absent, which reintroduces exactly the missing-identity case the requirement above closes. Keep this a stored value and make sure it round-trips.

Metadata

Gets optional metadata for cross-cutting concerns. Examples: UserId, TenantId, custom tags.

public virtual IDictionary<string, object>? Metadata { get; init; }

Property Value

IDictionary<string, object>

Optional metadata for cross-cutting concerns.

OccurredAt

Gets the UTC timestamp when this event occurred.

public virtual DateTimeOffset OccurredAt { get; init; }

Property Value

DateTimeOffset

The UTC timestamp when this event occurred.

Methods

WithCausationId(string?)

Sets the causation ID identifying the command or event that caused this event.

public DomainEvent WithCausationId(string? causationId)

Parameters

causationId string

The ID of the event that caused this event.

Returns

DomainEvent

A new event instance with the causation ID set.

WithCorrelationId(Guid)

Sets the correlation ID for tracking across services.

public DomainEvent WithCorrelationId(Guid correlationId)

Parameters

correlationId Guid

The correlation ID.

Returns

DomainEvent

A new event instance with the correlation ID set.

WithCorrelationId(string?)

Sets the correlation ID for tracking across services.

public DomainEvent WithCorrelationId(string? correlationId)

Parameters

correlationId string

The correlation ID string.

Returns

DomainEvent

A new event instance with the correlation ID set.

WithMetadata(string, object)

Adds metadata to this event.

public DomainEvent WithMetadata(string key, object value)

Parameters

key string

The metadata key.

value object

The metadata value.

Returns

DomainEvent

This event instance for method chaining.