faysilalshareef/event-design

Event Design -- Event Hierarchy Pattern

Core Principles

• Abstract Event base class carries all metadata (Id, AggregateId, Sequence, UserId, Type, DateTime, Version)
• Generic Event<TData> : Event adds a typed Data property constrained to IEventData
• IEventData interface has a single [JsonIgnore] EventType Type { get; } property
• Concrete events are classes with primary constructors inheriting from Event<TData>
• Event data are immutable records implementing IEventData
• EventType enum (not string constants) identifies event types and drives the EF Core discriminator
• Sequence tracking ensures ordering; Version field supports schema evolution

Key Patterns

Abstract Event Base Class

namespace {Company}.{Domain}.Commands.Domain.Events;

public abstract class Event
{
    public long Id { get; protected set; }
    public Guid AggregateId { get; protected set; }
    public int Sequence { get; protected set; }
    public Guid? UserId { get; protected set; }
    public EventType Type { get; protected set; }
    public DateTime DateTime { get; protected set; }
    public int Version { get; protected set; }
}

Key details:

• Id is long (auto-generated by the database), NOT Guid
• All setters are protected set -- only derived classes can set them
• Type is an EventType enum value, NOT a string
• UserId is nullable (Guid?) for system-generated events

Generic Event with Typed Data

namespace {Company}.{Domain}.Commands.Domain.Events;

public abstract class Event<TData> : Event
    where TData : IEventData
{
    protected Event(
        Guid aggregateId,
        int sequence,
        Guid? userId,
        TData data,
        int version = 1
    )
    {
        AggregateId = aggregateId;
        Sequence = sequence;
        UserId = userId;
        Type = data.Type;
        Data = data;
        DateTime = DateTime.UtcNow;
        Version = version;
    }

    public TData Data { get; protected set; }
}

Key details:

• Constructor takes aggregateId, sequence, userId, data, and optional version
• Type is set from data.Type -- the event data knows its own type
• DateTime is set to DateTime.UtcNow in the constructor
• Version defaults to 1

IEventData Interface

using System.Text.Json.Serialization;

namespace {Company}.{Domain}.Commands.Domain.Events.DataTypes;

public interface IEventData
{
    [JsonIgnore]
    EventType Type { get; }
}

Key details:

• The Type property is [JsonIgnore] so it is NOT serialized into the Data JSON column
• Each implementation returns the appropriate EventType enum value

EventType Enum

namespace {Company}.{Domain}.Commands.Domain.Enums;

public enum EventType
{
    OrderCreated,
    OrderUpdated,
    OrderItemsAdded,
    OrderItemsRemoved,
    OrderCompleted,
    OrderCancelled,
    InvoiceGenerated,
    InvoiceUpdated
}

Concrete Event Class (Primary Constructor)

using {Company}.{Domain}.Commands.Domain.Events.DataTypes;

namespace {Company}.{Domain}.Commands.Domain.Events.Orders;

public class OrderCreated(
    Guid aggregateId,
    Guid? userId,
    OrderCreatedData data,
    int sequence = 1,
    int version = 1) : Event<OrderCreatedData>(aggregateId, sequence, userId, data, version)
{
}

Key details:

• Uses C# primary constructor syntax
• Parameter order: aggregateId, userId, data, then optional sequence and version
• sequence defaults to 1 (creation events are always sequence 1)
• The class body is empty -- all logic is in the base class constructor

Another Concrete Event (Non-Creation)

namespace {Company}.{Domain}.Commands.Domain.Events.Orders;

public class OrderUpdated(
    Guid aggregateId,
    Guid? userId,
    OrderUpdatedData data,
    int sequence,
    int version = 1) : Event<OrderUpdatedData>(aggregateId, sequence, userId, data, version)
{
}

Note: Non-creation events do NOT default sequence -- it must be passed explicitly.

Event Data Records

using {Company}.{Domain}.Commands.Domain.Enums;

namespace {Company}.{Domain}.Commands.Domain.Events.DataTypes;

// Creation event data
public record OrderCreatedData(
    string CustomerName,
    decimal Total,
    OrderStatus Status,
    List<Guid> Items
) : IEventData
{
    public EventType Type => EventType.OrderCreated;
}

// Update event data
public record OrderUpdatedData(
    string CustomerName,
    decimal Total,
    OrderStatus Status
) : IEventData
{
    public EventType Type => EventType.OrderUpdated;
}

// Collection modification event data
public record OrderItemsAddedData(
    List<Guid> Items
) : IEventData
{
    public EventType Type => EventType.OrderItemsAdded;
}

Key details:

• Event data types are records (immutable by default)
• Each record implements IEventData with a body-expression Type property
• Records use positional syntax (constructor parameters become properties)
• Data can contain primitive types, strings, enums, List<T>, and nested records

Creating Events (via Extension Methods)

Events are typically created through extension methods on command interfaces:

namespace {Company}.{Domain}.Commands.Domain.Extensions;

public static class EventsExtensions
{
    public static OrderCreated ToEvent(this ICreateOrderCommand command)
    {
        return new OrderCreated(
            aggregateId: command.Id,
            userId: command.UserId,
            data: new OrderCreatedData(
                command.CustomerName,
                command.Total,
                OrderStatus.Pending,
                command.Items
            )
        );
    }

    public static OrderUpdated ToEvent(this IUpdateOrderCommand command, int sequence)
    {
        return new OrderUpdated(
            aggregateId: command.OrderId,
            userId: command.UserId,
            data: new OrderUpdatedData(
                command.CustomerName,
                command.Total,
                command.Status
            ),
            sequence: sequence
        );
    }
}

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | String constants for event types | Use EventType enum | | Mutable event data classes | Use immutable records | | Event<TData> with init properties | Use protected constructor with parameters | | Setting Type manually on events | Let data.Type set it via the constructor | | Guid for Event.Id | Use long Id (database auto-increment) | | Public setters on Event properties | All setters must be protected set | | System.Text.Json for IEventData.Type | Use [JsonIgnore] (System.Text.Json attribute) |

Detect Existing Patterns

# Find Event base class
grep -r "abstract class Event$" --include="*.cs" src/Domain/

# Find Event<TData> generic class
grep -r "class Event<TData>" --include="*.cs" src/Domain/

# Find IEventData implementations
grep -r ": IEventData" --include="*.cs" src/Domain/

# Find EventType enum
grep -r "enum EventType" --include="*.cs" src/Domain/

# Find concrete event classes
grep -r "Event<.*Data>" --include="*.cs" src/Domain/Events/

Adding to Existing Project

1. Locate the Event hierarchy in Domain/Events/Event.cs
2. Add new EventType values to the EventType enum
3. Create event data record implementing IEventData with the new EventType
4. Create concrete event class with primary constructor inheriting Event<TData>
5. Add extension method (ToEvent) on the command interface
6. Register in EF Core -- add GenericEventConfiguration and discriminator mapping
7. Keep Version at 1 unless doing schema migration