Cratis Blog | Blog

Event sourcing in .NET with Chronicle: from zero to first projection

Fri, 28 Aug 2026 18:00:00 GMT

Event sourcing has a reputation for heavy setup: a store, a bus, projections infrastructure, and a day of wiring before the first event lands. This post takes the shortest honest path instead: one Docker container, one console project, and about ninety lines of C# that append events, project them into read models, and react to them — with the full event history inspectable in a browser at the end.

Everything below was executed as written. The versions are pinned so you can reproduce the run exactly:

Piece	Version
Chronicle kernel container	`cratis/chronicle:latest-development`, digest `sha256:a423610f88e088e53d3bb821fa972a35dc84e254297bf8d720653316b68e61bf` (Chronicle Server 16.38.5)
Client package	`Cratis.Chronicle` 16.38.5
.NET SDK	8.0.408 (`net8.0` target)
Extra package on .NET 8	`System.Collections.Immutable` 10.0.0 (see the note in step 2)

latest-development is a moving tag; if you pull it later you may get a newer kernel. The digest above is the exact image this post was verified against. Chronicle and its bundled local Workbench are MIT-licensed, self-hosted software — what you run here is yours to run.

What you will build

A minimal .NET console application for a tiny library domain: a book arrives, gets borrowed, and comes back. Each of those facts is an event appended to Chronicle’s event log. Two read models are projected from those events — declaratively, with no update code — and a reactor performs a side effect when a book is returned. At the end you open the bundled Workbench and see the whole history.

1. Run Chronicle

The development image bundles the Chronicle kernel and its MongoDB storage in a single container — no separate database setup. Start it bound to loopback only, so nothing outside your machine can reach it:

docker run -d --name chronicle \
  -p 127.0.0.1:35000:35000 \
  cratis/chronicle:latest-development

Port 35000 carries gRPC, the REST API, and the Workbench on a single TLS port, using a self-signed development certificate the container generates at startup. Give it a few seconds, then confirm it is up:

docker logs chronicle 2>&1 | grep "Starting Cratis Chronicle Server"

Starting Cratis Chronicle Server - Version 16.38.5.0

2. Create the application

Create a console project and add the Chronicle client at the pinned version:

mkdir Quickstart && cd Quickstart
dotnet new console --framework net8.0
dotnet add package Cratis.Chronicle --version 16.38.5
dotnet add package System.Collections.Immutable --version 10.0.0

Why the extra package? On a net8.0 target, Cratis.Chronicle 16.38.5 fails at startup with Could not load file or assembly 'System.Collections.Immutable, Version=10.0.0.0' unless you add the package explicitly — the client assembly references it, but the package does not declare the dependency. On the .NET 10 SDK with a net10.0 target and Cratis.Chronicle 17.0.0, the extra package is not needed; we verified both combinations against the same kernel.

3. Define the events

Events are immutable facts, modeled as records marked with [EventType]. The attribute is how Chronicle discovers the type — the type name is the identity, so there is nothing else to configure:

using Cratis.Chronicle.Events;

[EventType]
public record BookAdded(string Title, string Isbn);

[EventType]
public record BookBorrowed(string MemberName);

[EventType]
public record BookReturned;

BookReturned carries no data at all. That it happened, on a particular book’s stream, is the whole story — not every fact needs a payload.

4. Declare the read models

Events are the write side. To read current state, you declare the shape you want and which events feed each field, and Chronicle keeps it in sync — you never write an UPDATE:

using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<BookAdded>]
public record Book(
    [Key]
    Guid Id,

    string Title,

    string Isbn,

    [SetValue<BookAdded>(false)]
    [SetValue<BookBorrowed>(true)]
    [SetValue<BookReturned>(false)]
    bool OnLoan,

    [SetFrom<BookBorrowed>(nameof(BookBorrowed.MemberName))]
    string? BorrowedBy);

Read the attributes as a sentence: a book enters the view from BookAdded; OnLoan flips with each borrow and return; BorrowedBy is whoever borrowed it. Title and Isbn map from the event by naming convention — no per-property attributes needed when the names match.

The second read model answers “what is out on loan right now?” by existing only while a loan is active:

[FromEvent<BookBorrowed>]
[RemovedWith<BookReturned>]
public record BorrowedBook(
    [Key]
    Guid Id,

    string MemberName);

When a BookBorrowed lands, a BorrowedBook appears; when the matching BookReturned arrives, it is removed. No flag to maintain, no filter to remember.

5. React to an event

When you need to do something the moment a fact lands — notify someone, call another system — you write a reactor. IReactor is a marker interface; add a method whose first parameter is the event you care about, and Chronicle routes matching events to it:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

public class BookReturnedNotifier : IReactor
{
    public Task Returned(BookReturned @event, EventContext context)
    {
        Console.WriteLine($"Reactor: book {context.EventSourceId} was returned — notify the next member in line.");
        return Task.CompletedTask;
    }
}

6. Connect, append, and query

Now the program that ties it together. In a console app there is no host or DI container, so you create the ChronicleClient yourself, open an event store, and explicitly ask Chronicle to discover and register the artifacts you just defined:

using Cratis.Chronicle;
using Cratis.Chronicle.Connections;

using var client = new ChronicleClient(ChronicleConnectionString.Development);
var eventStore = await client.GetEventStore("Quickstart");
Console.WriteLine($"Connected to event store: {eventStore.Name}");

await eventStore.DiscoverAll();
await eventStore.RegisterAll();

var bookId = Guid.NewGuid();

var appendResult = await eventStore.EventLog.Append(
    bookId,
    new BookAdded("The Pragmatic Programmer", "978-0135957059"));
Console.WriteLine($"Appended BookAdded at sequence {appendResult.SequenceNumber} (success: {appendResult.IsSuccess})");

appendResult = await eventStore.EventLog.Append(bookId, new BookBorrowed("Jane Doe"));
Console.WriteLine($"Appended BookBorrowed at sequence {appendResult.SequenceNumber} (success: {appendResult.IsSuccess})");

// Give the freshly registered read models a moment to come online before the first query.
await Task.Delay(TimeSpan.FromSeconds(5));

var books = await eventStore.ReadModels.GetInstances<Book>();
foreach (var book in books)
{
    Console.WriteLine($"Book read model: {book.Title} ({book.Isbn}) OnLoan={book.OnLoan} BorrowedBy={book.BorrowedBy}");
}

var borrowed = await eventStore.ReadModels.GetInstances<BorrowedBook>();
foreach (var loan in borrowed)
{
    Console.WriteLine($"BorrowedBook read model: {loan.Id} borrowed by {loan.MemberName}");
}

appendResult = await eventStore.EventLog.Append(bookId, new BookReturned());
Console.WriteLine($"Appended BookReturned at sequence {appendResult.SequenceNumber} (success: {appendResult.IsSuccess})");

// Give the reactor a moment to observe the event.
await Task.Delay(TimeSpan.FromSeconds(5));

books = await eventStore.ReadModels.GetInstances<Book>();
foreach (var book in books)
{
    Console.WriteLine($"Book read model after return: {book.Title} OnLoan={book.OnLoan}");
}

borrowed = await eventStore.ReadModels.GetInstances<BorrowedBook>();
Console.WriteLine($"BorrowedBook read models after return: {borrowed.Count()}");

ChronicleConnectionString.Development points at the local development kernel on chronicle://localhost:35000 with the built-in development credentials — the same connection new ChronicleClient() uses with no arguments. The event source id (bookId) is the identity of the thing each fact is about; every event appended against it becomes part of that book’s stream of history.

The two Task.Delay calls deserve honesty: GetInstances replays events on demand, but registration of freshly declared read models and delivery to reactors are asynchronous. On our machine, querying immediately after the very first registration returned empty results; five seconds was comfortably enough. In a long-running application this is a non-issue — registration happens once at startup.

Put the event, read model, and reactor definitions after the top-level statements (or in separate files) and run it:

dotnet run

Connected to event store: Quickstart
Appended BookAdded at sequence 0 (success: True)
Appended BookBorrowed at sequence 1 (success: True)
Book read model: The Pragmatic Programmer (978-0135957059) OnLoan=True BorrowedBy=Jane Doe
BorrowedBook read model: c6dc1472-3d85-4dd9-97bf-60e009e29caf borrowed by Jane Doe
Appended BookReturned at sequence 2 (success: True)
Reactor: book c6dc1472-3d85-4dd9-97bf-60e009e29caf was returned — notify the next member in line.
Book read model after return: The Pragmatic Programmer OnLoan=False
BorrowedBook read models after return: 0

That is the whole loop — append, project, react. The book’s OnLoan flag flipped, the BorrowedBook appeared and disappeared, and the reactor fired — and you never wrote an update statement.

7. See the history

State-based storage shows you what the data is. Chronicle also shows you every fact that made it so. Open the bundled Workbench at https://localhost:35000 — your browser will warn about the self-signed development certificate; that is expected for the local development image. Log in with the development image’s default credentials (username Admin, password ChangeMeNow! — see Workbench development mode), pick the Quickstart event store, and select Sequences: your BookAdded, BookBorrowed, and BookReturned are sitting there in order, permanent, with their event source id and timestamps. The Workbench is a bundled local browser surface for authorized inspection of Chronicle runtime state — run the program again and watch new events arrive.

Clean up

When you are done, remove the container and the image:

docker rm -f chronicle
docker rmi cratis/chronicle:latest-development

Deleting your Quickstart folder removes everything else — event data lives inside the container, so removing it removes the data too.

Where to go next

The console quickstart covers this same path in the documentation, including querying the materialized read models in MongoDB directly.
The tutorial builds the library domain one concept at a time — strongly-typed ids, hosts, and DI included.
The ASP.NET Core and Worker Service guides show the same pieces with the host’s DI container doing the wiring.
Chronicle also ships TypeScript, Kotlin/Java (JVM), and Elixir clients — with a Python client coming soon (no commitment implied) — so the event log is not a .NET-only story.

Event sourcing in any language: how Chronicle's gRPC contract works

Fri, 28 Aug 2026 12:00:00 GMT

Event sourcing libraries are usually tied to one language: the store, the client, and the programming model ship as a single package for a single ecosystem. Chronicle takes a different shape. It is an event-sourcing database and processing runtime with a first-class .NET SDK and additional TypeScript, Kotlin/Java (JVM), and Elixir clients — with a Python client coming soon — and the boundary between the server and every one of those clients is a wire contract, not a language binding.

This post walks through how that contract works: what the server exposes, how the shipped clients are layered on top of it, and what a new client for another language actually has to implement.

One kernel, one wire contract

Chronicle uses a .NET/Orleans actor-based kernel behind gRPC/HTTP surfaces and supports multiple event stores, namespaces, and persistent event-store subscriptions with outbox/inbox sequences. The kernel is where the event-sourcing behavior lives; clients talk to it over the network.

The contract itself is a set of 22 canonical .proto files in the Chronicle repository, under Source/Kernel/Protobuf. Together they describe the full client-facing surface: event types and event sequences, event stores and namespaces, observation (reactors, reducers, and event-store subscriptions), projections and read models, jobs, constraints, compliance, identities, recommendations, and the host and client handshake itself.

Because the boundary is protobuf over gRPC, any language with a gRPC implementation can talk to it. There is nothing .NET-specific on the wire — the .NET SDK is a client of the same contract as everyone else.

How every client is layered

Every client Chronicle has shipped follows the same layering, documented in the Building a Chronicle Client guide:

The canonical .proto files — owned by the kernel, versioned with it.
A generated contracts package per language — strongly-typed bindings generated from the protos and published as an ordinary package. It is regenerated by Chronicle’s own pipeline on every kernel release and treated as read-only.
An idiomatic client — the hand-maintained package developers actually import. This is where the language’s own idioms live: decorators in TypeScript, annotations on the JVM, processes and supervision in Elixir, attributes in .NET. It depends on the contracts package; its users never have to.
Optional convenience packages — hosting integrations such as ASP.NET Core or Spring Boot support, layered above the idiomatic client.

The result is that “event sourcing in language X” doesn’t mean porting a database. It means generating bindings from the same 22 contracts and writing the idiomatic layer that makes them feel native.

What a new client implements

Hand-rolling a client means solving the same handful of plumbing problems every existing client has solved before it can do anything useful:

Typed bindings generated from the wire contract, kept in a separate contracts package rather than hand-edited.
Authentication — parsing the connection string’s authentication modes and exchanging credentials for a token, keeping it fresh.
Connection lifecycle — discovering servers, reconnecting when a connection drops.
Contract-version checking — rejecting a server whose contract has drifted instead of silently sending it garbage.

None of that is domain logic, and all of it is written down: the Building a Chronicle Client section of the documentation is the experience of building the TypeScript, Kotlin, and Elixir clients distilled into a checklist, with a page explaining the why behind each item.

Chronicle in your language today

Each shipped client has its own landing page with installation and a first taste of the API:

.NET — the first-class SDK, Cratis.Chronicle on NuGet.
TypeScript and Node.js — @cratis/chronicle on npm.
Kotlin and Java (JVM) — io.cratis:chronicle on Maven Central, including a Spring Boot starter.
Elixir — cratis_chronicle on Hex.
Python — coming soon: pre-alpha, no package published yet, and no commitment implied.

All of them are built on the same wire contract: the same 22 canonical .proto files, generated into a contracts package for each language, with an idiomatic client layered on top.

Free and open source

Chronicle is MIT licensed and free to use, and so is everything Cratis publishes today.

Where to go next

Get started with Chronicle — your first event-sourced application.
Building a Chronicle Client — the full guide and checklist for bringing Chronicle to a new language.
Chronicle architecture — how the kernel is put together.
Chronicle on GitHub — the kernel, the contracts, and the .NET SDK.
Community and help — where to ask questions and follow along.

Choosing an event sourcing stack for .NET: an honest comparison

Fri, 28 Aug 2026 00:00:00 GMT

Choosing an event sourcing foundation for a .NET system is a long-lived decision. The event store outlives frameworks, UI rewrites, and often the team that chose it. Yet most comparisons available today reduce to popularity: the tools with the most blog posts win the evaluation before it starts.

We wanted something more useful — for you and, honestly, for us. So we compiled a comparison where every factual row names the exact versions compared and is reproducible from public documentation and released packages. Where our own product appears, the same rules apply, including the limitations.

The full matrix lives on cratis.io, and that page is the source of truth: Event sourcing in .NET: comparing KurrentDB, Marten, and Cratis Chronicle. This post is the walk-through.

The rules we set ourselves

Before writing a single row, we fixed the method:

Released, verifiable facts only. Every cell is cited from the named tool’s own public documentation, repository, or package-registry listing, at a named version, with the retrieval date recorded.
No performance, maturity, or superiority claims. Not “faster”, not “more mature”, not “production-proven”, not “best” — for any tool, including our own. Those claims need benchmarks and evidence a documentation comparison does not carry.
Caveats stay visible. The published page carries its limitations section in full: the matrix compares documentation, not behavior; a listed client package says nothing about feature parity; versions move.
A refresh promise. The matrix is re-verified when a compared tool ships a new major or minor release, changes its license or client list, or 90 days pass. If a compared tool disputes a row we cannot re-verify, we correct or remove it.

If a comparison cannot survive those rules, it is marketing, not a comparison.

The candidates, in one paragraph each

KurrentDB (formerly EventStoreDB) is a purpose-built event store database — events live in streams inside its own storage engine, with official gRPC clients for several languages. You bring your own CQRS layer and read-model infrastructure. It is licensed under the Kurrent License v1, which its own documentation notes is not an OSI-approved open source license.

Marten is a .NET library that turns PostgreSQL into a document and event store. It runs inside your application process, leans on PostgreSQL’s JSON support and ACID compliance, and has rich projection support — inline, async, and live. MIT licensed; PostgreSQL is a prerequisite and .NET is the boundary.

Cratis Chronicle is an event-sourcing database and processing runtime: a separate server with a first-class .NET SDK, released TypeScript, Java/Kotlin (JVM), and Elixir client packages, and a Python client coming soon (pre-alpha, unpublished, no commitment implied). MIT licensed. It pairs with Arc for CQRS and generated TypeScript proxies, and a React component library.

The canonical matrix pins the exact versions — KurrentDB server 26.0, Marten 9.30.0, Chronicle 17.0.0 — and cites every row.

You’re choosing an ecosystem, not only a database

Here is the part most comparisons skip: none of these tools lives alone. The event store is the center of a decision, but rarely the whole of it — around every store sits the layer you build applications with, the tooling you operate with, and the path events take to the rest of your architecture. Comparing the stores cell by cell and stopping there would miss where much of your time actually goes.

So the canonical matrix now carries an ecosystem section, compiled under the same rules — every cell restates the vendor’s own listing, with retrieval dates, and crowns nobody:

KurrentDB documents a server-side Connectors subsystem — pre-installed and enabled by default — that runs catch-up subscriptions and pushes filtered or transformed events to external systems through sinks, with a documented catalog covering Elasticsearch, HTTP, Kafka, MongoDB, RabbitMQ, and Serilog.
Marten is one member of JasperFx’s Critter Stack, described by its maintainers as one family of .NET tools for event sourcing, document storage, and messaging: Wolverine for messaging, Polecat, Fisher, Weasel, Alba, and CritterWatch alongside Marten itself.
Cratis Chronicle is part of the Cratis ecosystem: Arc for CQRS with generated TypeScript proxies, Components for React, the CLI and the Web Workbench for operating the store, released clients for .NET, TypeScript, JVM, and Elixir, and free AI skills, rules, and diagnostics that teach an assistant the platform’s conventions.

None of this makes any tool better. It changes what you are evaluating. If you pick a store, you are also picking — or committing to build — everything around it: ask what surrounds each candidate, who maintains it, and how much of it you would otherwise write yourself. The ecosystem rows on the comparison page carry citations and retrieval dates so you can verify each listing the same way you verify a storage row.

How to actually choose

The matrix deliberately does not crown a winner. Instead, ask fit questions:

Do you want a dedicated event database and your own application layer? A purpose-built store with bring-your-own CQRS gives maximum control and maximum assembly work.
Are you a PostgreSQL shop wanting minimum new infrastructure? A library-on-PostgreSQL approach is hard to beat for operational simplicity.
Do you want event sourcing, CQRS, and frontend integration designed together? An integrated platform trades some flexibility for coherence: projections, read models, generated frontend contracts, and query updates that share one design. That trade-off is real — coherence and lock-in concerns are two views of the same property, and you should weigh both.
Is your organization polyglot? Check which client languages are first-party and what each client actually supports. Client existence is not client parity — for any tool, including ours.
Who explains the system at 3 a.m.? Compare the operational surfaces: what does each tool show you about subscription progress, failed projections, and replay?

None of these questions has a universal answer. A team that answers “PostgreSQL shop, .NET only, minimal infrastructure” is describing Marten’s sweet spot. A team that wants a dedicated event database under a stack they assemble themselves is describing KurrentDB’s. A team that wants the store, the CQRS layer, and the frontend contract designed together is describing Chronicle’s.

Verify us

Every row on the comparison page carries its source and retrieval date precisely so you do not have to take our word for it. Open the cited documentation, check the cell, and if you find one that no longer matches its source, tell us — we will re-verify and fix it.

That is the comparison we wished existed when we started. Use it, argue with it, and hold us to the refresh promise.

The Cratis ecosystem at a glance

Fri, 28 Aug 2026 00:00:00 GMT

Cratis is an open-source, MIT-licensed platform for building event-sourced and CQRS applications. This post is a quick tour of the ecosystem: what each piece does, how the pieces fit together, and where to go to learn more.

Chronicle: the center of the stack

At the center is Chronicle, an event-sourcing database and processing runtime with a first-class .NET SDK and additional TypeScript, Kotlin/Java (JVM), and Elixir clients — with a Python client coming soon — plus pluggable storage-provider implementations including MongoDB (default), PostgreSQL, SQL Server, and SQLite.

Chronicle’s kernel runs on Microsoft Orleans and exposes a language-agnostic gRPC/protobuf boundary, so any language can implement the contract. AI agents can connect to a running Chronicle through the Chronicle MCP server, regardless of client language.

Building applications: Arc and Components

Arc — an opinionated CQRS application framework for ASP.NET Core: commands, queries, validation, authorization, and TypeScript proxy generation. Arc works without event sourcing, with optional Chronicle integration.
Components — React components for CQRS and event-sourced applications built with Arc: command dialogs, typed forms, and query-backed data tables.

Inspecting and diagnosing: CLI and Workbench

CLI — terminal workflows for inspecting and diagnosing Chronicle: events, observers, projections, read models, and failed partitions.
Workbench — the web-based inspection surface for Chronicle event stores.

The model-first layer (experimental)

Cratis also includes an experimental model-first layer, currently in early development:

Studio — the collaborative environment for designing, visualizing, and editing Screenplay event models (experimental).
Screenplay — a model-first language for event-sourced, CQRS systems — commands, events, projections — rendered by Stage into an Arc + Chronicle application (experimental).
Stage — renders Screenplay models into reviewable Arc + Chronicle applications (experimental).
Scene — describing a user interface without describing a platform: the UI model of the model-first layer (experimental).
Prologue — captures existing system behavior (SQL Server CDC, Postgres logical replication, HTTP, OTLP) into event models for the model-first layer (experimental).

Free and open source

Everything Cratis publishes today is MIT licensed and free to use.

Where to go next

The Cratis Stack — how the pieces fit together end to end.
Why developers choose Cratis — the reasoning behind the stack.
Get started with Chronicle — your first event-sourced application.
Samples — runnable event sourcing and CQRS samples for the whole stack.
Cratis on GitHub — every repository, all open source.
Community and help — where to ask questions and follow along.