Memoria.EventSourcing.Store.Cosmos 2.0.0

Memoria™

Event sourcing for .NET with two consistency models in one framework. Store state as classic event streams, or as dynamic consistency boundaries where the boundary is a tag query chosen per decision. Start with the mediator alone and add an event store when you need one — nothing forces you to take both.

From Latin memoria (memory).

📘 Documentation · 🚀 Getting started · 💡 Concepts · 🧭 Guides · 📗 Reference

📚 Examples · ⬆️ Upgrading · 📣 Release notes

📄 Licence at a glance

The framework is free and open source under the Apache License 2.0 — every package under the Memoria NuGet prefix, every version. Use it in anything, commercial or not, closed source or open, at any scale. No edition, no threshold, no key, nothing to sign.

StateLens, the browser tool that reads a store through your own domain assemblies and a manifest, is a separate product developed in its own repository: commercial, free for a single service and paid above that, under its own licence. Nothing in this repository is part of it, and installing the packages never requires it.

Already on 1.x? Upgrade to 2.0.0 walks through the two behaviours that move with the major version. Nothing in the store changes, so there is no data migration.

📥 Install

dotnet add package Memoria

Only Memoria is required. Add an event-sourcing package and a store when you need one:

dotnet add package Memoria.EventSourcing
dotnet add package Memoria.EventSourcing.Store.EntityFrameworkCore

The install guide explains when to reach for each of the packages listed below.

🔄 Quickstart

Register what you need at startup:

services.AddMemoria(typeof(Program));                    // Mediator: commands, queries, notifications
services.AddMemoriaEventSourcing(typeof(Program));       // Aggregates, streams, projections
services.AddMemoriaEntityFrameworkCore<MyDbContext>();   // Store

As a mediator

public record CreateProduct(string Name) : ICommand;

public class CreateProductHandler : ICommandHandler<CreateProduct>
{
    public Task<Result> Handle(CreateProduct command, CancellationToken cancellationToken = default) =>
        Task.FromResult(Result.Ok());
}

await dispatcher.Send(new CreateProduct("Espresso"));

See the Mediator quickstart for queries, notifications, validation, custom handlers, command sequences and SendAndPublish.

As an event store

[EventType("OrderPlaced")]
public record OrderPlacedEvent(Guid OrderId, decimal Amount) : IEvent;

var streamId = new CustomerStreamId(customerId);
var aggregateId = new OrderId(orderId);
var order = new Order(orderId, amount: 25.45m);

await domainService.SaveAggregate(streamId, aggregateId, order, expectedEventSequence: 0);

See the Event Sourcing quickstart for the full aggregate definition, and Streams or DCB? for choosing a consistency model.

Past that, the guides cover one task each, and the reference has the IDomainService API and a configuration page per package.

⚡ What you get

🔎 StateLens

StateLens is a browser tool for reading an event sourced store. Point it at a store, upload a zip of your own domain assemblies — with a statelens.json at its root naming the services in it — and it shows you the events that were appended, the aggregates and projections snapshotted from them, and the types both were written through. Open a row and the aggregate is folded from its events, so you can see the state a snapshot stands at and how far behind its history it is. It creates nothing and deletes nothing.

It began here, as Memoria Web, a reader of Memoria stores. It lives in its own repository now, which is private, and reads any framework's store, not only Memoria's: a service's manifest tells the tool which uploaded types are the streams, events, aggregates and projections, how they are named and folded, and where in the store the events and snapshots are. Memoria's own stores are described the same way as anyone else's.

It is a commercial product, separate from the framework: free over a single service, and paid above that, under the StateLens Licence. Its documentation is on its site, and a hosted instance at demo.statelens.dev is open by invitation, asked for through the site's contact form.

📦 Packages

Every package is published at the same version, so one number fits the whole set.

Package	Version	What it adds
Memoria		Required. Mediator core: commands, queries, notifications, dispatcher
Memoria.EventSourcing		Aggregates, streams, projections and IDomainService
Memoria.EventSourcing.Dcb		Dynamic consistency boundaries
Memoria.EventSourcing.Dcb.Store.EntityFrameworkCore		EF Core store for the DCB model
Memoria.EventSourcing.Store.EntityFrameworkCore		EF Core store: SQL Server, SQLite, PostgreSQL, MySQL, in-memory
Memoria.EventSourcing.Store.EntityFrameworkCore.Identity		The above, plus ASP.NET Core Identity in the same DbContext
Memoria.EventSourcing.Store.EntityFrameworkCore.Npgsql		PostgreSQL jsonb-aware event-property filtering
Memoria.EventSourcing.Store.Cosmos		Azure Cosmos DB store (SQL API)
Memoria.EventSourcing.Store.Cosmos.InMemory		In-process Cosmos DB stand-in for tests
Memoria.Messaging.ServiceBus		Publish to Azure Service Bus when a command succeeds
Memoria.Messaging.ServiceBus.InMemory		In-process Service Bus stand-in for tests
Memoria.Messaging.RabbitMq		Publish to RabbitMQ when a command succeeds
Memoria.Messaging.RabbitMq.InMemory		In-process RabbitMQ stand-in for tests
Memoria.Caching.Memory		Cache query results in-process
Memoria.Caching.Redis		Cache query results in Redis
Memoria.Validation.FluentValidation		Validate commands before they reach the handler

🗺️ Roadmap

Shipped work is in the release notes. Next up, in no fixed order:

• Pipelines
• Option to automatically validate commands
• Event Grid messaging provider
• Kafka messaging provider
• Amazon SQS messaging provider
• File store provider for event sourcing

🤝 Contributing

Bug reports, questions and feature requests are welcome as issues and discussions. For code, please open an issue first, and read CONTRIBUTING.md — it covers how to build and test and the conventions to follow. There is nothing to sign: the framework is Apache 2.0, and a contribution comes in under the same terms it goes out under.

By taking part you agree to the Code of Conduct.

⭐ Give a star

If Memoria is useful in your learning, samples, workshop or project, please give the repository a star. Thank you!

✨ Custom implementations and project support

Memoria is designed to be extended, with providers for store, messaging, caching and validation.

Need a provider that does not exist yet — a custom database store, a different message bus — or help applying Memoria to an existing codebase? Get in touch via LinkedIn.

📄 Licence

The framework is under the Apache License 2.0 — every package published under the Memoria NuGet prefix, every version, 1.x and 2.x alike. Build whatever you like with it, licence that however you like, ship it to whomever you like. The full text is in LICENSE.md.

StateLens is a commercial product, developed in its own private repository and licensed separately under the StateLens Licence. Running it is what the licence governs, metered by services — a named set of domain assemblies read over one connection string. One service is free, and always will be; above that it is priced by how many services one instance reads, on the tool's pricing page, with no limit on people, instances or environments. Nothing of it is in this repository.

Version 2.0.0-beta was briefly offered under the Reciprocal Public License 1.5 or a commercial licence covering the packages. That was withdrawn four days later at 2.0.0-beta.2, the framework returned to Apache 2.0, where it had been throughout 1.x, and 2.0.0 shipped under it. Anyone who took 2.0.0-beta under the earlier terms keeps them; Apache 2.0 grants strictly more.