RootBlocks 0.8.0

RootBlocks

RootBlocks is a set of .NET packages that provide the building blocks of Domain-Driven Design (DDD). It covers entities, aggregate roots, value objects, enumeration classes, domain events, a unit of work with a transactional outbox, and persistence helpers for Entity Framework Core and raw SQL. You write the business rules and RootBlocks handles the repetitive parts.

public class Post : Entity< PostId >, IAggregateRoot
{
    public string Title { get; private set; }
    public DateTime? PublishedOn { get; private set; }

    public Post( string title ) : base( PostId.New() ) => Title = title;

    public void Publish()
    {
        PublishedOn = DateTime.UtcNow;
        AddDomainEvent( new PostPublished( Id ) );
    }
}

// In a command handler
var post = await posts.GetByIdAsync( postId, cancellationToken );
post.Publish();
unitOfWork.RegisterDirty( post );
await unitOfWork.CommitAsync( cancellationToken ); // saves the post and PostPublished together, then publishes it

Features

• Domain model: Entity<T> with domain events and audit dates, IAggregateRoot, ValueObject with structural equality, Enumeration classes, DomainEvent with causation and correlation IDs, and domain exceptions.
• Unit of work for EF Core: commits aggregates, collects their domain events, and checks optimistic concurrency with a RowVersion.
• Transactional outbox: events are saved in the same transaction as the change, published straight after, and retried with exponential backoff by a background dispatcher. One outbox per context, so each module of a modular monolith has its own. Plain SQL only: no Service Broker, so it runs on Azure SQL and in containers.
• Soft delete, UTC dates and auditing handled by the base DbContext and entity configurations.
• CQRS read side: an IConnectionFactory for Dapper or ADO.NET, with drivers for SQL Server, PostgreSQL, MySQL, Oracle and SQLite.
• Integrations: MediatR for in-process events, Serilog for log context, and transformers for the built-in ASP.NET Core OpenAPI document.

Packages

See Target frameworks for what each target means for your project.

Installation

Install the packages you need from NuGet:

dotnet add package RootBlocks
dotnet add package RootBlocks.Persistence.EntityFramework
dotnet add package RootBlocks.Messaging.MediatR
dotnet add package RootBlocks.Persistence.SqlClient   # or .Npgsql, .MySqlClient, .Oracle, .SQLite

RootBlocks does not ship an identifier type. Entity<T> accepts any T : IEquatable<T>, such as Guid, int or string. For strongly-typed IDs like PostId, use the separate StronglyTypedIdentifier library, which also provides the EF Core and ASP.NET Core integration for those IDs. The examples in these docs use it.

Then wire it up in your composition root:

builder.Services
       .AddMediatR( cfg => cfg.RegisterServicesFromAssembly( typeof( PublishPostCommand ).Assembly ) )
       .AddMessaging()                                     // IEventPublisher through MediatR
       .AddSqlClientPersistence( connectionString )        // IConnectionFactory for queries
       .AddDbContext< Context >( o => o.UseSqlServer( connectionString ) )
       .AddOutbox< Context >( builder.Configuration )      // when the context calls modelBuilder.ApplyOutbox()
       .AddScoped< IUnitOfWork, UnitOfWork >()
       .AddScoped< IPostRepository, PostRepository >();

Getting started builds this up step by step.

Upgrading from 0.5

Version 0.6 rewrote the outbox: it is now per context, retried, and free of Service Broker. The old API still compiles with obsolete warnings. See Upgrading to 0.6 for the migration.

Documentation

• Getting started: build a working aggregate, from the domain model to the API, step by step.
• Core library
  • Domain model: entities, aggregate roots, value objects, enumerations, domain events and domain exceptions.
  • Utilities: pagination, extension methods, validation, retry and the other abstractions.
• Packages
  • Entity Framework persistence: DatabaseContext, configurations, UnitOfWork and the outbox.
  • Connection factory and database drivers
  • Messaging with MediatR
  • Serialization
  • Logging with Serilog
  • OpenAPI
• Configuration reference: every registration method and setting in one place.
• Upgrading to 0.6
• Target frameworks
• The Blogs sample: a full reference application.
• Contributing: building, testing, versioning and releasing.

Sample

samples/Blogs is a minimal API that uses every package together. It has three aggregates (Person, Blog, Post), MediatR commands, EF Core with the outbox for writes and Dapper for reads, and a Scalar UI over the OpenAPI document. See the sample guide.

dotnet run --project samples/Blogs/src/Blogs.Api/

Building from source

dotnet build RootBlocks.slnx
dotnet test     # the EF tests need Docker for SQL Server

The SDK is pinned in global.json. See Contributing for conventions, versioning and releases.

License

MIT © Sébastien de Salvador