Skip to main content

ZeroAlloc.EventSourcing

Zero-allocation event sourcing for .NET 8+. Struct-based aggregate state, in-memory and SQL backends, source-generated aggregate boilerplate, optional OpenTelemetry instrumentation.

dotnet add package ZeroAlloc.EventSourcing
dotnet add package ZeroAlloc.EventSourcing.InMemory

Quick Start​

// Define the aggregate: an ID, events, a state struct and a partial aggregate class
public readonly record struct OrderId(Guid Value);
public sealed record OrderPlacedEvent(decimal Total);

public partial struct OrderState : IAggregateState<OrderState>
{
    public static OrderState Initial => default;
    public bool Placed { get; private set; }
    public decimal Total { get; private set; }

    internal OrderState Apply(OrderPlacedEvent e) => this with { Placed = true, Total = e.Total };
}

// The source generator adds ApplyEvent and OrderEventTypeRegistry
public sealed partial class Order : Aggregate<OrderId, OrderState>
{
    public void Place(decimal total)
    {
        if (State.Placed) throw new InvalidOperationException("Order already placed");
        Raise(new OrderPlacedEvent(total));
    }
}

// Wire up DI, after the serializer setup shown in Installation
services.AddSingleton<IEventTypeRegistry, OrderEventTypeRegistry>();
services
    .AddEventSourcing()
    .UseInMemoryEventStore()
    .UseAggregateRepository<Order, OrderId>(
        () => new Order(),
        id => new StreamId($"order-{id.Value}"));

// Use
var repo = sp.GetRequiredService<IAggregateRepository<Order, OrderId>>();
var orderId = new OrderId(Guid.NewGuid());
using var order = new Order();
order.Place(99.99m);
var saved = await repo.SaveAsync(order, orderId, CancellationToken.None);

Packages​

PackagePurpose
ZeroAlloc.EventSourcingCore abstractions — IEventStore, IAggregateRepository, Aggregate<TState>
ZeroAlloc.EventSourcing.InMemoryIn-memory event store for tests and development
ZeroAlloc.EventSourcing.SqlSQL Server and PostgreSQL backends
ZeroAlloc.EventSourcing.GeneratorsRoslyn source generators for aggregate boilerplate
ZeroAlloc.EventSourcing.TelemetryBCL ActivitySource + Meter decorator around IAggregateRepository<,> — spans and metrics; wire with .WithTelemetry(). See OpenTelemetry Instrumentation.

Documentation​

Getting Started​

Core Concepts (Read These First)​

Code Examples (Learn by Doing)​

Performance & Optimization​

Advanced Topics​

Observability​

Additional Resources​

Learning Paths​

Path 1: Learn Event Sourcing (1-2 hours)​

  1. Event Sourcing Fundamentals
  2. Your First Aggregate
  3. Examples: CreateFirstAggregate
  4. Examples: AppendAndRead

Path 2: Build Your First System (2-3 hours)​

  1. Installation
  2. Aggregates
  3. Events
  4. Examples: OrderAggregate
  5. Examples: TestingAggregates

Path 3: Optimize for Production (1-2 hours)​

  1. Performance Characteristics
  2. Zero-Allocation Design
  3. Optimization Strategies
  4. Snapshots
  5. Custom Snapshot Stores

Path 4: Extend the Framework (2-3 hours)​

  1. Custom Event Stores
  2. Advanced Projections
  3. Plugin Architecture
  4. Examples: CustomEventStore

Path 5: Contribute to the Project (1-2 hours)​

  1. Contributing Guide
  2. Examples: TestingAggregates
  3. Fork, branch, test, and submit PR

By Topic​

Understanding Event Sourcing​

Building Applications​

Testing​

Performance​

Custom Implementations​

File Organization​

docs/
├── INDEX.md (this file)
├── ADOPTION_GUIDE.md
├── getting-started/
│   ├── installation.md
│   ├── quick-start-example.md
│   └── first-aggregate.md
├── core-concepts/
│   ├── fundamentals.md
│   ├── aggregates.md
│   ├── events.md
│   ├── event-store.md
│   ├── snapshots.md
│   ├── projections.md
│   └── architecture.md
├── examples/
│   ├── 01-getting-started/
│   │   ├── CreateFirstAggregate.cs
│   │   └── AppendAndRead.cs
│   ├── 02-domain-modeling/
│   │   ├── OrderAggregate.cs
│   │   ├── OrderEvents.cs
│   │   └── OrderState.cs
│   ├── 03-testing/
│   │   ├── TestingAggregates.cs
│   │   └── TestingProjections.cs
│   └── 04-advanced/
│       ├── CustomEventStore.cs
│       ├── CustomProjection.cs
│       └── CustomSnapshotStore.cs
├── performance/
│   ├── characteristics.md
│   ├── zero-allocation.md
│   ├── optimization.md
│   └── benchmarks.md
└── advanced/
    ├── custom-event-store.md
    ├── custom-snapshots.md
    ├── custom-projections.md
    ├── plugin-architecture.md
    └── contributing.md

Key Statistics​

  • 19 documentation/example files
  • 7,000+ lines of documentation
  • 2,673 lines of runnable C# code
  • Covers all major concepts and patterns
  • Real-world examples and benchmarks

Need Help?​

Document Status​

  • Performance & Benchmarks: Complete (4 files, 2,050 lines)
  • Advanced Topics: Complete (5 files, 3,277 lines)
  • Code Examples: Complete (10 files, 2,673 lines)

Last Updated: 2026-04-04