Purview.EventSourcing.AzureStorage 2.0.0-prerelease.4

Purview EventSourcing

Purview EventSourcing is a .NET event sourcing framework for building aggregate-based applications with provider-agnostic store facades, source-generated aggregates, transaction coordination, and storage packages for SQL Server, Azure Storage, MongoDB, and Azure Cosmos DB.

Why use it

• Build aggregates on top of AggregateBase and load/save them through IEventStore.
• Add queryable read models with IQueryableEventStore when you need filtering, paging, and list views.
• Generate aggregate event types and registration code from partial methods using the source generator support included in Purview.EventSourcing.
• Coordinate multi-aggregate saves through IEventStoreTransactionFactory.
• Swap storage providers without changing your application-facing aggregate APIs.

Packages

Install the packages you need

dotnet add package Purview.EventSourcing
dotnet add package Purview.EventSourcing.SqlServer

Provider packages layer on top of the core Purview.EventSourcing package. Add only the providers required for your chosen persistence strategy.

Quick start

1. Define an aggregate

using Purview.EventSourcing.Aggregates;

[GenerateAggregate]
public partial class OrderAggregate : AggregateBase
{
    public string CustomerId { get; private set; } = default!;
    public decimal Total { get; private set; }

    [GenerateAggregateEvent]
    public partial void CreateOrder(string customerId);

    [GenerateAggregateEvent]
    public partial void AddLineItem(string productId, string productName, int quantity, decimal unitPrice);
}

2. Register storage

builder.Services.AddSqlServerEventStore();
builder.Services.AddSqlServerSnapshotQueryableEventStore();

{
  "ConnectionStrings": {
    "eventstore-sqlserver": "Server=.;Database=MyApp;Trusted_Connection=True;"
  }
}

3. Load and save through the provider-agnostic facade

public sealed class OrderService(IEventStore store)
{
    public async Task PlaceOrderAsync(string orderId, string customerId, CancellationToken cancellationToken)
    {
        var order = await store.GetAsync<OrderAggregate>(orderId, cancellationToken)
            ?? await store.CreateAsync<OrderAggregate>(orderId, cancellationToken: cancellationToken);

        order.CreateOrder(customerId);
        order.AddLineItem("SKU-1", "Demo product", 1, 19.99m);

        await store.SaveAsync(order, cancellationToken);
    }
}

4. Query through a snapshot-backed facade

public sealed class OrderQueries(IQueryableEventStore store)
{
    public Task<long> CountActiveOrdersAsync(CancellationToken cancellationToken) =>
        store.CountAsync<OrderAggregate>(o => !o.Details.IsDeleted, cancellationToken);
}

5. Coordinate multi-aggregate saves

public sealed class CheckoutService(
    IEventStoreTransactionFactory transactionFactory,
    IQueryableEventStore store)
{
    public async Task<bool> CheckoutAsync(
        OrderAggregate order,
        InventoryAggregate inventory,
        CancellationToken cancellationToken)
    {
        await using var transaction = transactionFactory.Create();
        transaction.Enlist(order, store);
        transaction.Enlist(inventory, store);

        var result = await transaction.CommitAsync(cancellationToken);
        return result.Success;
    }
}

Storage provider matrix

For SQL Server and Azure SQL schema, permissions, and event-versioning guidance, see docs/sql-server.md.

Sample application

The sample solution demonstrates how the framework is intended to be consumed:

• EventSourcing.Samples.Web uses the non-generic IEventStore and IQueryableEventStore facades.
• EventSourcing.Samples.QuickStart is a console app that demonstrates related aggregates, multi-aggregate transactions, and rollback-on-failure behavior without external infrastructure.
• EventSourcing.Samples.AppHost wires up SQL Server, Redis, Azurite, and the web app for Aspire-driven local runs.
• Sample services such as CartCheckoutService, OrderFulfillmentService, and StockTransferService demonstrate multi-aggregate workflows.

Repository layout

Development workflow

dotnet tool restore
dotnet restore src/Purview.EventSourcing.slnx
dotnet build src/Purview.EventSourcing.slnx --configuration Release
dotnet csharpier check src
dotnet test --project src/tests/EventSourcing.UnitTests/EventSourcing.UnitTests.csproj --configuration Release

Additional notes:

• just recipes in the Justfile wrap the same restore, build, test, pack, and version commands for local development.
• Integration tests use Testcontainers; local Docker support is recommended.
• package.json is the release version source of truth for builds and packages.
• dotnet pack or just pack writes packages to artifacts/packages.

Release workflow

1. Update the package version with the repository release process.
2. Review the generated CHANGELOG.md and package version changes.
3. Build, test, and pack the repository.
4. Let the GitHub Actions CD workflow create the tag, publish the GitHub release, and push NuGet packages.

Do not create release tags manually.

Documentation

• SQL Server event store guide
• Core package README
• SQL Server provider README
• MongoDB provider README
• Cosmos DB provider README