Cratis.Chronicle.AspNetCore 15.7.0

<div align="center"> <a href="https://cratis.io"> <img src="full-logo.png" alt="Cratis Chronicle" width="480"> </a>

<h3 align="center">Cratis Chronicle</h3>

<p align="center"> An Event Sourcing database for .NET — built with ease of use, productivity, compliance, and maintainability in mind. <br /> <a href="https://cratis.io"><strong>Explore the docs »</strong></a> <br /> <br /> <a href="https://github.com/cratis/samples">View Samples</a>  ·  <a href="https://github.com/cratis/chronicle/issues/new?labels=bug">Report a Bug</a>  ·  <a href="https://github.com/cratis/chronicle/issues/new?labels=enhancement">Request a Feature</a>  ·  <a href="https://discord.gg/kt4AMpV8WV">Join the Discord</a> </p>

<p align="center"> <a href="https://discord.gg/kt4AMpV8WV"> <img src="https://img.shields.io/discord/1182595891576717413?label=Discord&logo=discord&color=7289da" alt="Discord"> </a> <a href="http://nuget.org/packages/cratis.chronicle"> <img src="https://img.shields.io/nuget/v/Cratis.Chronicle?logo=nuget" alt="NuGet"> </a> <a href="https://hub.docker.com/r/cratis/chronicle"> <img src="https://img.shields.io/docker/v/cratis/chronicle?label=Chronicle&logo=docker&sort=semver" alt="Docker"> </a> <a href="https://github.com/Cratis/Chronicle/actions/workflows/dotnet-build.yml"> <img src="https://github.com/cratis/Chronicle/actions/workflows/dotnet-build.yml/badge.svg" alt="C# Build"> </a> <a href="https://github.com/Cratis/Chronicle/actions/workflows/publish.yml"> <img src="https://github.com/cratis/Chronicle/actions/workflows/publish.yml/badge.svg" alt="Publish"> </a> <a href="https://github.com/Cratis/Documentation/actions/workflows/pages.yml"> <img src="https://github.com/Cratis/Documentation/actions/workflows/pages.yml/badge.svg" alt="Documentation site"> </a> </p> </div>

📖 Table of Contents

• 📖 Table of Contents
• 🧭 About
• ✨ Key Features
  • 🏗️ Event Sourcing Foundation
  • 🎯 Real-time Processing
  • 🛡️ Enterprise Ready
  • 🚀 Developer Experience
• 🚀 Getting Started
  • Prerequisites
  • Installation
  • Quick Example
    • ASP.NET Core setup (Program.cs)
    • Define events
    • Append events
    • React to events (Reactor)
    • Build read models (Reducer)
    • Declarative projections
• 🏛️ Architecture
• 📚 Documentation
• 🤝 Contributing
• 💬 Support
• 📊 Repository Stats
• 📄 License
• 🙏 Acknowledgements

🧭 About

Cratis Chronicle is an Event Sourcing database that captures every state change in your system as an immutable sequence of events — rather than storing only the current state. This unlocks powerful capabilities like full audit trails, time-travel debugging, and event-driven architectures without the usual complexity.

Chronicle ships with:

• 🖥️ Chronicle Kernel — the server that manages event storage, processing, and querying
• 📦 .NET Client SDK — a rich C# library for interacting with Chronicle from any .NET application
• 🌐 Web Workbench — a built-in management dashboard for monitoring, browsing events, and administration
• 🗄️ MongoDB Backend — optimized storage layer with an extensible model for other data stores

For core values and principles, read our core values and principles.

✨ Key Features

🏗️ Event Sourcing Foundation

🎯 Real-time Processing

🛡️ Enterprise Ready

🚀 Developer Experience

🚀 Getting Started

Prerequisites

• .NET 8+
• Docker (to run the Chronicle Kernel and MongoDB)

Installation

Run Chronicle and MongoDB with Docker Compose:

services:
  mongo:
    image: mongo:6
    ports:
      - "27017:27017"

  chronicle:
    image: cratis/chronicle:latest
    ports:
      - "35000:35000"   # gRPC / API
      - "8080:8080"     # Web Workbench
    environment:
      - CONNECTIONSTRINGS__EVENTSTORE=mongodb://mongo:27017
    depends_on:
      - mongo

docker compose up -d

Add the NuGet package to your .NET project:

# ASP.NET Core
dotnet add package Cratis.Chronicle.AspNetCore

# Console / Worker Service
dotnet add package Cratis.Chronicle

Quick Example

ASP.NET Core setup (Program.cs)

var builder = WebApplication.CreateBuilder(args)
    .AddCratisChronicle(options => options.EventStore = "MyApp");

var app = builder.Build();
app.UseCratisChronicle();
app.Run();

Define events

[EventType]
public record UserOnboarded(string Name, string Email);

[EventType]
public record BookAddedToInventory(string Title, string Author, string ISBN);

Append events

// Inject IEventLog or grab it from the event store
await eventLog.Append(Guid.NewGuid(), new UserOnboarded("Jane Doe", "jane@example.com"));
await eventLog.Append(Guid.NewGuid(), new BookAddedToInventory("Domain-Driven Design", "Eric Evans", "978-0321125217"));

React to events (Reactor)

public class UserNotifier : IReactor
{
    public async Task Onboarded(UserOnboarded @event, EventContext context)
    {
        // send welcome email, provision resources, etc.
        Console.WriteLine($"Welcome, {@event.Name}!");
    }
}

Build read models (Reducer)

public class BooksReducer : IReducerFor<Book>
{
    public Task<Book> Added(BookAddedToInventory @event, Book? current, EventContext context) =>
        Task.FromResult(new Book(
            Guid.Parse(context.EventSourceId),
            @event.Title,
            @event.Author,
            @event.ISBN));
}

Declarative projections

public class BorrowedBooksProjection : IProjectionFor<BorrowedBook>
{
    public void Define(IProjectionBuilderFor<BorrowedBook> builder) => builder
        .From<BookBorrowed>(from => from
            .Set(m => m.UserId).To(e => e.UserId)
            .Set(m => m.Borrowed).ToEventContextProperty(c => c.Occurred))
        .Join<BookAddedToInventory>(b => b
            .On(m => m.Id)
            .Set(m => m.Title).To(e => e.Title))
        .RemovedWith<BookReturned>();
}

Full working samples are available in the Samples repository.

🏛️ Architecture

┌──────────────────────────────────────────────────────────┐
│                  Your .NET Application                   │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Events · Reactors · Reducers · Projections        │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│                   Chronicle Client SDK                   │
└─────────────────────────────┬────────────────────────────┘
                              │  gRPC
┌─────────────────────────────┴────────────────────────────┐
│                     Chronicle Kernel                     │
│                                                          │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────┐  │
│  │  Event Store   │  │   Projection   │  │    Web     │  │
│  │   (MongoDB)    │  │   Engine       │  │ Workbench  │  │
│  └────────────────┘  └────────────────┘  └────────────┘  │
└──────────────────────────────────────────────────────────┘

Chronicle follows a client-server model:

📚 Documentation

Full documentation is available at https://cratis.io.

🤝 Contributing

Contributions are what make the open-source community an amazing place to learn, inspire, and create. Any contribution you make is greatly appreciated!

1. Fork the repository
2. Create a feature branch: git checkout -b feature/AmazingFeature
3. Commit your changes: git commit -m 'Add some AmazingFeature'
4. Push to the branch: git push origin feature/AmazingFeature
5. Open a Pull Request

Looking for a good first issue? Check out the contribute page.

For detailed build and development instructions, see the contributing guide.

You can also browse the code directly in your browser:

💬 Support

📊 Repository Stats

📄 License

Distributed under the MIT License. See LICENSE for full details.

🙏 Acknowledgements

• MongoDB — the default storage backend powering Chronicle
• Microsoft Orleans — distributed actor framework used in the Chronicle Kernel
• Louis3797/awesome-readme-template — README inspiration
• All our contributors and the open-source community ❤️