Read the migration guide to view the full list of breaking changes as well as recommendations on how to migrate.

Documentation

Version 1.x documentation has been pulled into this repository in order to have the code and documentation closer together and have the documentation updated in the same pull-requests as any code changes. The compiled version of the documentation is available at https://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 the migration 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 from develop-v1 to create releases. Typically each commit represents a release

Talks directly related to EventFlow

• GOTO Aarhus 2022 by rasmus Practical event sourcing using EventFlow

Examples

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

External Examples

List of examples create by different community members. Note that many of these examples 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 the complete example. It features entities, a read model for an 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-defined command/entities/events from the complete example. There are endpoints to create 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 various tools to up the services aka. Linux Docker based on .NET Core, RabbitMq, EntityFramework with SQL Server and using EventFlow following CQRS-ES architecture and 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 using docker-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, ...

Overview

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

• Aggregates: Domains object that guarantees the consistency of changes being made within each 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 for these 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 action needs 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 can be created every so often that contains the aggregate state. EventFlow supports upgrading existing snapshots, which is useful for long-lived aggregates. 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 as process managers, coordinates and routes messages between bounded 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 at a later time, e.g. publish a command. EventFlow provides support for these job schedulers
  • Hangfire - home page
• Event upgrade: As events committed to the event store is never changed, EventFlow uses the concept of event upgraders to deprecate events and replace them with new during aggregate load.
• Event publishing: Sometimes you want other applications or services to consume and act on domains. For this EventFlow supports event publishing.
  • RabbitMQ
• Metadata: Additional information for each aggregate event, e.g. the IP of the user behind the event being emitted. EventFlow ships with several providers ready to use used.
• Value objects: Data containing classes used to validate and hold domain data, e.g. a username or e-mail.

Complete example

Here's a complete example on how to use the default in-memory event store along 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 the aggregate root
• ExampleCommandHandler: Command handler which EventFlow resolves using its IoC container and defines how the command specific is applied to the aggregate root
• ExampleReadModel: In-memory read model providing easy access to the current state

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

State of EventFlow

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

EventFlow is 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 implementations for almost every part of EventFlow by registering a different implementation of an interface.

Useful articles related to EventFlow and DDD

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

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

Integration tests

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

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

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

Alternatively, you can skip the NUnit tests marked with the integration category.

Thanks

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

Star History

License

EventFlow was originally developed <u>in my spare time</u> while I worked at both <a href="https://www.ebay.com/">eBay (2015 to 2021)</a> and <a href="https://schibsted.com/">Schibsted (2021 and onward)</a>.