Chronicles 0.9.2

Chronicles

Event sourcing and CQRS for .NET, backed by Azure Cosmos DB. Chronicles gives you append-only event streams, command handlers, state projections, and document projections — production-ready infrastructure you'd otherwise spend months building yourself.

Install

dotnet add package Chronicles

Quick start

// Define your events
record OrderPlaced(string OrderId, string CustomerId, decimal Total);
record OrderShipped(string OrderId, DateTimeOffset ShippedAt);

// Write events to a stream
var streamId = new StreamId("order", orderId);

await writer.WriteAsync(streamId, [
    new OrderPlaced(orderId, customerId, 49.99m),
]);

// Later: append more events
await writer.WriteAsync(streamId, [
    new OrderShipped(orderId, DateTimeOffset.UtcNow),
]);

// Read events back
await foreach (var evt in reader.ReadAsync(streamId))
{
    Console.WriteLine($"{evt.Metadata.Name} at {evt.Metadata.Timestamp}");
}

Three pillars

Event Store

Append-only, immutable event streams persisted to Azure Cosmos DB with optimistic concurrency control.

Events are your source of truth — immutable facts stored permanently.

CQRS

Command handlers validate business rules, emit events, and rebuild aggregate state from event history.

// Implement a stateful command handler
public class ShipOrderHandler : ICommandHandler<ShipOrder, OrderState>
{
    public OrderState CreateState(StreamId streamId) => new();

    public OrderState? ConsumeEvent(StreamEvent evt, OrderState state) =>
        evt.Data switch
        {
            OrderPlaced p => state with { CustomerId = p.CustomerId, Total = p.Total },
            _ => null,
        };

    public async ValueTask ExecuteAsync(
        ICommandContext<ShipOrder> context,
        OrderState state,
        CancellationToken cancellationToken)
    {
        if (state.CustomerId is null)
            throw new InvalidOperationException("Order does not exist.");

        context.AddEvent(new OrderShipped(context.Command.OrderId, DateTimeOffset.UtcNow));
    }
}

Document Store

Read-model projections driven by the Cosmos DB change feed — query-optimized, denormalized views.

Build fast read-side queries without CQRS complexity if you don't need it.

Sample

The sample/ directory contains a food-delivery microservices demo built with .NET Aspire. It covers three bounded contexts — Orders, Restaurants, and Couriers — and shows how to wire up event streams, command handlers, and document projections end-to-end.

Documentation

Contributing & community

• Questions: GitHub Discussions
• Bugs / features: GitHub Issues
• Contributing: see CONTRIBUTING.md
• Code of conduct: see CODE-OF-CONDUCT.md