Class DomainEvent
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
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
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
causationIdstringThe 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
correlationIdGuidThe 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
correlationIdstringThe 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
Returns
- DomainEvent
This event instance for method chaining.