Repository files navigation

$ dotnet add package EventFlow

EventFlow is a basic CQRS+ES framework designed to be easy to use.

Have a look at ourgetting started guide,thedo’s and don’ts and theFAQ.

Alternatively, join ourDiscord server to engage with the community. Its hopefully getting a reboot to kickstart the upcoming release of v1.

• Easy to use: Designed with sensible defaults and implementations that make iteasy to create an example application
• Highly configurable and extendable: EventFlow uses interfaces for every part ofits core, making it easy to replace or extend existing features with customimplementation
• No use of threads or background workers
• MIT licensed Easy to understand and use license for enterprise

Development of version 1.0 has started and is mainly braking changes regarding changesrelated to replacing EventFlow types with that of Microsoft extension abstractions,mainlyIServiceProvider andILogger<>.

The following list key characteristics of each version as well as its related branches(not properly configured yet).

• 1.x

  Represents the next iteration of EventFlow that aligns EventFlow with the standardpackages for .NET. Releases here will only support .NET Standard, .NET Coreand .NET versions 6+ going forward.

  • Released
  • Still development
  • Not all projects migrated yet

  Read themigration guide to view the full list of breakingchanges as well as recommendations on how to migrate.

  Documentation

  Version 1.x documentation has been pulled into this repository in order to havethe code and documentation closer together and have the documentationupdated in the same pull-requests as any code changes. The compiled version of thedocumentation is available athttps://geteventflow.net/.

  NuGet package status

  • 🟢 ported
  • 💚 newly added to 1.0
  • 🟠 not yet ported to 1.0
  • 💀 for packages that are removed as part of 1.0 (see themigration guide for details)

  Projects

  • 🟢EventFlow
  • 🟠EventFlow.AspNetCore
  • 💀EventFlow.Autofac
  • 💀EventFlow.DependencyInjection
  • 🟠EventFlow.Elasticsearch
  • 🟢EventFlow.EntityFramework
  • 🟠EventFlow.EventStores.EventStore
  • 🟢EventFlow.Hangfire
  • 🟢EventFlow.MongoDB
  • 🟢EventFlow.MsSql
  • 💀EventFlow.Owin
  • 🟢EventFlow.PostgreSql
  • 🟠EventFlow.Redis
  • 🟢EventFlow.RabbitMQ
  • 🟢EventFlow.Sql
  • 🟢EventFlow.SQLite
  • 🟢EventFlow.TestHelpers

  Branches

  • develop-v1: Development branch, pull requests should be done here
  • release-v1: Release branch, merge commits are done to this branch fromdevelop-v1 to create releases. Typically each commit represents a release

• 0.x (legacy)

  The current stable version of EventFlow and has been the version of EventFlowfor almost six years. 0.x versions have .NET Framework support and limitedsupport to the Microsoft extension packages through extra NuGet packages.

  Feature and bug fix releases will still be done while there's interest inthe community.

  Branches

  • develop-v0: Development branch, pull requests should be done here
  • release-v0: Release branch, merge commits are done to this branch fromdevelop-v0 to create releases. Typically each commit represents a release

  Documentation

  Version 0.x documentation is (although a bit outdated) is live athttps://docs.geteventflow.net/.

• GOTO Aarhus 2022 byrasmusPractical event sourcing using EventFlow

• Complete: Shows a complete example on how to useEventFlow with in-memory event store and read models in a relatively few linesof code
• Shipping: To get a more complete example of how EventFlowcould be used,have a look at the shipping example found here in the code base. The exampleis based on the shipping example from the book "Domain-Driven Design -Tackling Complexity in the Heart of Software" by Eric Evans. Itsin-progress, but should provide inspiration on how to use EventFlow on alarger scale. If you have ideas and/or comments, create a pull request oran issue

List of examples create by different community members. Note that many of theseexamples will be using EventFlow 0.x.

Create a pull request to get your exampled linked from here.

• Racetimes:Shows some features of EventFlow that are not covered in thecomplete example. It features entities, a read model foran entity, delete on read models, specifications and snapshots.

  • Racetimes for Azure Functions:Extends the above example to support the HTTP access via Azure Functions

  • Racetimes for Azure Functions and Event Grid:Further extends the Azure Functions Example to publish to Event Grid, following the RabbitMQ pattern

• .NET Core:A Web API running .NET Core 2.2 using the event flow. It uses the pre-definedcommand/entities/events from thecomplete example. There are endpoints tocreate a new example event, getting a data model and to replay all data models.

• ElasticSearch/.NET Core:It is configured with EventFlow, ElasticSearch, EventStore, and RabbitMq. See "withRabbitMq" branch for #384.

• Vehicle Tracking:A Microservice on .NET Core 2.2 with docker based, you can up the service with docker-compose, this project using varioustools to up the services aka. Linux Docker based on .NET Core, RabbitMq, EntityFramework with SQL Server and using EventFlow following CQRS-ES architectureand all microservice can access through ApiGateway which using Ocelot

• RestAirline:A classic DDD with CQRS-ES, Hypermedia API project based on EventFlow. It's targeted to ASP.NET Core 2.2 and can be deployed to docker and k8s.

• Full Example:A console application on .NET Core 2.2. You can up the services usingdocker-compose file. Docker-compose file include EventStore, RabbitMq, MongoDb, and PostgreSQL. It include following EventFlow concepts:

  • Aggregates
  • Command bus and commands
  • Synchronous subscriber
  • Event store (GES)
  • In-memory read model.
  • Snapshots (MongoDb)
  • Sagas
  • Event publising (In-memory,RabbitMq)
  • Metadata
  • Command bus decorator, custom value object, custom execution result, ...

Here is a list of the EventFlow concepts. Use the links to navigateto the documentation.

• Aggregates:Domains object that guarantees the consistency of changes being made withineach aggregate
• Command bus and commands:Entry point for all command/operation execution.
• Event store:Storage of the event stream for aggregates. Currently there is support forthese storage types.
  • In-memory - only for test
  • Files - only for test
  • Microsoft SQL Server
  • Entity Framework Core
  • SQLite
  • PostgreSQL
  • EventStore -home page
• Subscribers:Listeners that act on specific domain events. Useful if an specific actionneeds to be triggered after a domain event has been committed.
• Read models:Denormalized representation of aggregate events optimized for reading fast.Currently there is support for these read model storage types.For the SQL storage types the queries are being generated automatically with quoted columns and table names.
  • Elasticsearch
  • In-memory - only for test
  • Microsoft SQL Server
  • Entity Framework Core
  • SQLite
  • PostgreSQL
• Snapshots:Instead of reading the entire event stream every single time, a snapshot canbe created every so often that contains the aggregate state. EventFlowsupports upgrading existing snapshots, which is useful for long-livedaggregates. Snapshots in EventFlow are opt-in and EventFlow has support for
  • In-memory - only for test
  • Microsoft SQL Server
  • Entity Framework Core
  • SQLite
  • PostgreSQL
• Sagas:Also known asprocess managers, coordinates and routes messages betweenbounded contexts and aggregates
• Queries:Value objects that represent a query without specifying how its executed,that is let to a query handler
• Jobs: Perform scheduled tasks ata later time, e.g. publish a command. EventFlow provides support for thesejob schedulers
  • Hangfire -home page
• Event upgrade:As events committed to the event store is never changed, EventFlow uses theconcept of event upgraders to deprecate events and replace them with newduring aggregate load.
• Event publishing: Sometimes you want other applications or services toconsume and act on domains. For this EventFlow supports event publishing.
  • RabbitMQ
• Metadata:Additional information for each aggregate event, e.g. the IP ofthe user behind the event being emitted. EventFlow ships withseveral providers ready to use used.
• Value objects:Data containing classes used to validate and hold domain data, e.g. ausername or e-mail.

Here's a complete example on how to use the default in-memory event storealong with an in-memory read model.

The example consists of the following classes, each shown below

• ExampleAggregate: The aggregate root
• ExampleId: Value object representing the identity of the aggregate root
• ExampleEvent: Event emitted by the aggregate root
• ExampleCommand: Value object defining a command that can be published to theaggregate root
• ExampleCommandHandler: Command handler which EventFlow resolves using its IoCcontainer and defines how the command specific is applied to the aggregate root
• ExampleReadModel: In-memory read model providing easy access to the currentstate

Note: This example is part of the EventFlow test suite, so checkout thecode and give it a go.

[Test]publicasyncTaskExample(){// We wire up EventFlow with all of our classes. Instead of adding events,// commands, etc. explicitly, we could have used the the simpler// AddDefaults(Assembly) instead.varserviceCollection=newServiceCollection().AddLogging().AddEventFlow(o=>o.AddEvents(typeof(ExampleEvent)).AddCommands(typeof(ExampleCommand)).AddCommandHandlers(typeof(ExampleCommandHandler)).UseInMemoryReadStoreFor<ExampleReadModel>());using(varserviceProvider=serviceCollection.BuildServiceProvider()){// Create a new identity for our aggregate rootvarexampleId=ExampleId.New;// Resolve the command bus and use it to publish a commandvarcommandBus=serviceProvider.GetRequiredService<ICommandBus>();awaitcommandBus.PublishAsync(newExampleCommand(exampleId,42),CancellationToken.None);// Resolve the query handler and use the built-in query for fetching// read models by identity to get our read model representing the// state of our aggregate rootvarqueryProcessor=serviceProvider.GetRequiredService<IQueryProcessor>();varexampleReadModel=awaitqueryProcessor.ProcessAsync(newReadModelByIdQuery<ExampleReadModel>(exampleId),CancellationToken.None);// Verify that the read model has the expected magic numberexampleReadModel.MagicNumber.Should().Be(42);}}

// The aggregate rootpublicclassExampleAggregate:AggregateRoot<ExampleAggregate,ExampleId>,IEmit<ExampleEvent>{privateint?_magicNumber;publicExampleAggregate(ExampleIdid):base(id){}// Method invoked by our commandpublicvoidSetMagicNumber(intmagicNumber){if(_magicNumber.HasValue)throwDomainError.With("Magic number already set");Emit(newExampleEvent(magicNumber));}// We apply the event as part of the event sourcing system. EventFlow// provides several different methods for doing this, e.g. state objects,// the Apply method is merely the simplestpublicvoidApply(ExampleEventaggregateEvent){_magicNumber=aggregateEvent.MagicNumber;}}

// Represents the aggregate identity (ID)publicclassExampleId:Identity<ExampleId>{publicExampleId(stringvalue):base(value){}}

// A basic event containing some informationpublicclassExampleEvent:AggregateEvent<ExampleAggregate,ExampleId>{publicExampleEvent(intmagicNumber){MagicNumber=magicNumber;}publicintMagicNumber{get;}}

// Command for update magic numberpublicclassExampleCommand:Command<ExampleAggregate,ExampleId>{publicExampleCommand(ExampleIdaggregateId,intmagicNumber):base(aggregateId){MagicNumber=magicNumber;}publicintMagicNumber{get;}}

// Command handler for our commandpublicclassExampleCommandHandler:CommandHandler<ExampleAggregate,ExampleId,ExampleCommand>{publicoverrideTaskExecuteAsync(ExampleAggregateaggregate,ExampleCommandcommand,CancellationTokencancellationToken){aggregate.SetMagicNumber(command.MagicNumber);returnTask.CompletedTask;;}}

// Read model for our aggregatepublicclassExampleReadModel:IReadModel,IAmReadModelFor<ExampleAggregate,ExampleId,ExampleEvent>{publicintMagicNumber{get;privateset;}publicTaskApplyAsync(IReadModelContextcontext,IDomainEvent<ExampleAggregate,ExampleId,ExampleEvent>domainEvent,CancellationToken_cancellationToken{MagicNumber=domainEvent.AggregateEvent.MagicNumber;returnTask.CompletedTask;}}

EventFlow is still under development, especially the parts regardinghow read models are re-populated.

EventFlowis currently used in production environments and performs very well,but it needs to mature before key APIs are stable.

EventFlow is greatly opinionated, but it's possible to create new implementationsfor almost every part of EventFlow by registering a different implementation ofan interface.

Many of the technical design decisions in EventFlow is based on articles. Thissection lists some of them. If you have a link with a relevant article, pleaseshare it by creating an issue with the link.

• Domain-Driven Design
  • Domain-Driven Design Referenceby Eric Evans
  • DDD Decoded - Bounded Contexts Explained
  • Going "Events-First" for Microservices with Event Storming and DDD
• General CQRS+ES
  • CQRS Journey by Microsoftpublished by Microsoft
  • An In-Depth Look At CQRSby Mike Mogosanu
  • CQRS, Task Based UIs, Event Sourcing agh!by Greg Young
  • Busting some CQRS mythsby Jimmy Bogard
  • CQRS appliedby Gabriel Schenker
  • DDD Decoded - Entities and Value Objects Explained
• Eventual consistency
  • How To Ensure Idempotency In An Eventual Consistent DDD/CQRS Applicationby Mike Mogosanu
  • DDD Decoded - Don't Fear Eventual Consistency
• Whynot to implement "unit of work" in DDD
  • Unit Of Work is the new Singletonby Mike Mogosanu
  • The Unit of Work and Transactions In Domain-Driven Designby Mike Mogosanu

EventFlow has several tests that verify that its ability to use the systems itintegrates with correctly.

• Elasticsearch
• EventStore
• RabbitMQ
• Microsoft SQL Server
• PostgreSQL

To setup a local test environment run the following commands in the checkoutdirectory of EventFlow.

docker-compose pulldocker-compose up

Alternatively, you can skip the NUnit tests marked with theintegrationcategory.

• Contributors
• JetBrains: OSS licenses
• olholm: Current logo
• iconmonstr: First logo
• JC008: License for Navicat Essentials for SQLite

EventFlow was originally developed in my spare time while I worked at botheBay (2015 to 2021) andSchibsted (2021 and onward).

The MIT License (MIT)Copyright (c) 2015-2025 Rasmus Mikkelsenhttps://github.com/eventflow/EventFlowPermission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.