CQRSlite Documentation

CQRSlite is a lightweight CQRS (Command Query Responsibility Segregation) and Event Sourcing framework for .NET. It separates the application into a Write Side (Commands) and a Read Side (Queries).

Write Side (Commands)

• ICommandSender: Entry point for sending commands.
• Command Handlers: Process commands and interact with the domain.
• ISession (Unit of Work): Tracks changes to aggregates.
• IRepository: Persists aggregates.
• Aggregate Roots: Maintain domain consistency and emit events.
• IEventStore: Persists and retrieves events.

Read Side (Queries)

• IQueryProcessor: Entry point for processing queries.
• Query Handlers: Retrieve data from read models or DTOs.
• Event Handlers: Listen to events to update read models.

Core Design Principles

• Minimal Dependencies: Only depends on Microsoft.Extensions.Caching.Memory and Microsoft.CSharp.
• Pluggability: Every component is replaceable with custom implementations.
• Convention over Configuration: Uses convention-based routing (e.g., for event application).
• Target Frameworks: netstandard2.0 and net9.0.

CQRSlite supports optimistic concurrency checking. To use it:

1. Include an ExpectedVersion property in your command.
2. When retrieving the aggregate via ISession.Get<T>(id, expectedVersion), CQRSlite will throw a ConcurrencyException if the version in the store does not match the expectedVersion provided.

public class ChangeProductPrice : ICommand
{
    public Guid Id { get; set; }
    public decimal NewPrice { get; set; }
    public int ExpectedVersion { get; set; } // Important!
}

public class ProductCommandHandler : ICommandHandler<ChangeProductPrice>
{
    private readonly ISession _session;

    public ProductCommandHandler(ISession session)
    {
        _session = session;
    }

    public async Task Handle(ChangeProductPrice message)
    {
        // Pass expected version - throws ConcurrencyException if mismatch
        var product = await _session.Get<Product>(message.Id, message.ExpectedVersion);
        product.ChangePrice(message.NewPrice);
        await _session.Commit();
    }
}

CQRSlite uses specific interfaces to categorize messages:

• Commands (ICommand): Represent an intent to change state. They can include concurrency control by including an ExpectedVersion property.
• Events (IEvent): Represent something that has happened in the past. They typically include metadata like Version and TimeStamp alongside business data.
• Queries (IQuery<T>): Represent a request for data. The generic type T defines the expected return type (often a DTO).

// Command
public class CreateProduct : ICommand
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

// Command with Concurrency
public class UpdateProductPrice : ICommand
{
    public Guid Id { get; set; }
    public decimal NewPrice { get; set; }
    public int ExpectedVersion { get; set; }
}

// Event
public class ProductCreated : IEvent
{
    public Guid Id { get; set; }
    public int Version { get; set; }
    public DateTimeOffset TimeStamp { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

// Query
public class GetProduct : IQuery<ProductDto>
{
    public Guid Id { get; set; }
}

Aggregates manage state and enforce business rules. To implement one:

1. Inherit from AggregateRoot.
2. Use ApplyChange(event) to record new state changes.
3. Implement Apply(event) private methods to update the internal state when an event is applied (this is used during rehydration).
4. Provide a private parameterless constructor for rehydration purposes.

public class Product : AggregateRoot
{
    private string _name;
    private decimal _price;
    private bool _discontinued;

    public Product(Guid id, string name, decimal price)
    {
        Id = id;
        ApplyChange(new ProductCreated(id, name, price));
    }

    private Product() { } // For rehydration

    public void ChangePrice(decimal newPrice)
    {
        if (_discontinued)
            throw new InvalidOperationException("Cannot change price of discontinued product");

        ApplyChange(new ProductPriceChanged(Id, newPrice));
    }

    private void Apply(ProductCreated e)
    {
        _name = e.Name;
        _price = e.Price;
    }

    private void Apply(ProductPriceChanged e)
    {
        _price = e.NewPrice;
    }
}