This is a template for creating your own application using using Clean Architecture, utilizing building blocks from Domain-Driven Design. Read and write operations have been separated according to the CQRS pattern. System observability is ensured by the implementation of OpenTelemetry and the Aspire Dashboard. Additionally, you'll find implementations of design patterns such as mediator, factory, strategy, and several others.
- 1. Instalation
- 2. Introduction
- 3. Domain
- 4. Architecture
- 5. Observability
- 6. Design patterns implemented in this project
- 7. Tests
I do recommend using CLI instead Visual Studnio Wizard when creating your application based on this template because Vistual Studio doesn't keep folders structure correctly.
Install using CLI.
dotnet new install Clean.Architecture.And.DDD.Template::1.0.2
Once installed type
dotnet new ca-and-ddd -o "MyDreamProject"
The template uses MSSQL as a database provider. Migrations will be applied automatically during project startup, so you don't have to do anything.
As a result of running command from step 1.1 all files and folders will be created. Among them you will find docker-compose.yaml. Simply run the command 'docker-compose up' to create required containers. docker-compose.yaml provides instances of: MSSQL, Redis, RabbitMQ, and Aspire Dashboard.
I couldn't find any repository that met the following criteria:
- Implemented Mediator pattern using MassTransit library instead of MediatR with added message interception support (similar to IPipelineBehaviour in MediatR.
- Implemented system observability using Open Telemetry.
- Implemented Domain Events as part of Eventual Consistency, so Domain Events are not published in the same transaction as saving/updating Aggregate.
Even when encountering projects that fulfilled one of these points, they often conflicted with others or omitted them entirely. Therefore, I decided to create a project that meets the above criteria. I am sharing it in case someone else is looking for something similar.
The e-commerce domain was deliberately chosen because it is widely known and understood. This template consists of two aggregates: Customer and Order. I decided to extend the domain just enough to utilize all the building blocks, but nothing more. The goal of this repository is to create a template that provides an example implementation. Keeping things simple in the Domain layer allows you to focus on understanding complex topics, such as the building blocks of the Domain-Driven Design approach.
There are two aggregates in the Domain Layer. These are:
Customer – This is the most important aggregate in our layer because it is responsible for placing orders. In other words, this is the entity that starts the process of placing orders. Besides placing orders, the customer can also change their e-mail address and verify it.
Order – This represents a particular order. It has a list of order items, along with their price, quantity, etc.
Domain events allow informing other parts of the application about changes that have occurred within our domain. They are an excellent way to implement business processes in a loosely coupled manner. Each domain event represents a specific action adhering to the (Single Responsibility Principle, SRP) that has happened in the system; therefore, event names are represented in the past tense, e.g., OrderCreatedDomainEvent. When a domain event is published, all interested parties can react to it. As the number of "interested parties" for a given domain event grows, all that needs to be done is to create an additional handler to perform extra logic. This approach also aligns with the Open/Closed Principle.
In our solution, domain events are stored in the database within the same transaction as the aggregate's save operation. This means they are not dispatched immediately but only after the aggregate has been successfully saved. Once this happens, the DomainEventsProcessor retrieves the events from the database and publishes them.
For example: When a Customer places an order, an event called OrderCreatedDomainEvent is stored in the database and then retrieved and published by the DomainEventsProcessor. An event handler, OrderCreatedDomainEventHandler, listens for this event and handles sending an email to the customer who placed the order. Implementing the business process in this way allows for leveraging the eventual consistency approach.
By applying the Clean Architecture approach, we achieved a separation of the application into layers that are independent of each other, making them easy to test. The project consists of four layers, as shown in the image below.
The presentation layer (in our case, simply a RESTful API) is responsible for interacting with users by receiving and processing HTTP requests. It performs validation of commands and queries, and then communicates directly with the application layer to handle the request.
The Infrastructure layer is responsible for implementing technical aspects such as database access and broad integrations with external systems. This layer is also responsible for implementing interfaces defined in the domain and application layers. The Infrastructure layer referances the Application layer.
This layer orchestrates processes in the application. The Application Layer only references the Domain Layer. Most of the application logic resides in command handlers, where you can implement specific scenarios (use cases).
This is the most important layer, as it contains business logic and implements business processes. It consists of aggregates, value objects, domain services, and other domain-related elements. This layer is the heart of the whole system. The domain layer is completely independent; it does not reference other layers and does not depend on any external libraries, making it very easy to test and maintain.
Saving and publishing domain events only after the aggregate has been saved means that we must use the approach known as eventual consistency.
In our case: When a Customer places an order, an event called OrderCreatedDomainEvent is stored in the database and then retrieved and published by the DomainEventsProcessor. An event handler, OrderCreatedDomainEventHandler, listens for this event and handles sending an email to the customer who placed the order.
If we decided to publish the OrderCreatedDomainEvent just before saving the aggregate to the database, there could be a situation where we send an email to the customer, but the save operation fails, for example, due to network issues.
Integration events are used to notify other modules or systems about important events that occurred in our system. Through these events, we can achieve consistency at the level of components or microservices by synchronizing data. In our solution, domain events are mapped to integration events and are only published after the aggregate has been successfully saved. The IntegrationEventsProcessor is responsible for fetching and publishing integration events from the database.
In our solution, we have only one handler, which was included purely for demonstration purposes. The CustomerCreatedIntegrationEvent is sent to a RabbitMq queue. http://localhost:15672/ login: guest, password: guest.
public class CustomerCreatedIntegrationEventHandler : IConsumer<CustomerCreatedIntegrationEvent>
{
public Task Consume(ConsumeContext<CustomerCreatedIntegrationEvent> context)
{
//The CustomerCreatedIntegrationEvent was produced by the Customer aggregate,
//thus this handler should have never been placed here. However this repo is meant
//to provide a full working template, so it was placed here just to demonstrate
//how to register and handle incoming integration events.
return Task.CompletedTask;
}
}
This handler should be placed in a separate module or another microservice.
Implementation of CQRS involves separating write and read requests. Commands are responsible for changing the state of aggregates (saving and updating them), and such operations are available only through specific repositories, e.g., ICustomerRepository.
public interface ICustomerRepository
{
Task AddAsync(Customer customer, CancellationToken cancellationToken = default);
Task<Customer?> GetAsync(string email, CancellationToken cancellationToken = default);
Task UpdateAsync(Customer customer, CancellationToken cancellationToken = default);
}
Queries are responsible for retrieving entities from the database. Queries are placed in the infrastructure layer to directly utilize the DbContext and avoid creating unnecessary abstractions.
Please take a look at the example: GetCustomerQueryHandler
public sealed class GetCustomerQueryHandler : IConsumer<GetCustomerQuery>
{
private readonly AppDbContext _appDbContext;
public GetCustomerQueryHandler(AppDbContext appDbContext)
{
_appDbContext = appDbContext;
}
public async Task Consume(ConsumeContext<GetCustomerQuery> query)
{
var email = query.Message.Email;
var customer = await _appDbContext.Set<Customer>().Where(x => ((string)x.Email).Contains(email)).SingleOrDefaultAsync();
if (customer == null)
{
throw new CustomerNotFoundApplicationException(email);
}
await query.RespondAsync(new GetCustomerQueryResponse(customer.FullName, customer.Age.Value, customer.Email.Value));
}
}
Cross-cutting concerns are implemented using MassTransit filters. There are three filters:
cfg.ConfigureMediator((context, cfg) =>
{
//The order of filter registration matters.
//LoggingFilter will be executed last, after the changes to the database have been commited.
cfg.UseConsumeFilter(typeof(LoggingFilter<>), context);
cfg.UseConsumeFilter(typeof(RedisFilter<>), context);
cfg.UseConsumeFilter(typeof(EventsFilter<>), context);
});
- Logging filter - is responsible for logging requests along with their total duration and payload. The current implementation logs all requests; however, you could, for example, detect only long-running requests and log them.
- RedisFilter - is responsible for counting all requests per day. This is just an example implementation that uses Redis. You could implement other logic here, such as caching, checking permissions, etc.
- EventsFilter - is responsible for saving Domain Events and Integration Events to the database.
The observability of the system has been ensured through the use of OpenTelemetry. Telemetry data is sent to the Aspire Dashboard collector and visualized there. With this approach, we can check how long an HTTP request took, how much time was spent communicating with the MSSQL database, and how much with Redis. Event logs are linked to requests, making it easy to navigate between them.
Aspire Dashboard is avaiable at: http://localhost:18888 once docker-compose has been launched.
Here is an example of creating a customer, which results in adding a new record in the Aspire Dashboard.
And here is the code responsible for setting up Open Telemetry.
Code
public static void InstallTelemetry(this WebApplicationBuilder builder, IConfiguration configuration, ConnectionMultiplexer redisConnection)
{
var telemetrySettings = builder.Configuration.GetSection(nameof(AppSettings)).Get<AppSettings>().Telemetry;
var url = $"{telemetrySettings.Host}:{telemetrySettings.Port}";
builder.Services.AddOpenTelemetry()
.ConfigureResource(resource => resource.AddService(telemetrySettings.Name, serviceInstanceId: Environment.MachineName))
.WithMetrics(metrics =>
{
metrics
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation();
metrics.AddOtlpExporter(options =>
{
if (!string.IsNullOrEmpty(url))
{
options.Endpoint = new Uri(url);
}
});
})
.WithTracing(tracing =>
{
tracing
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddRedisInstrumentation(redisConnection, opt => opt.FlushInterval = TimeSpan.FromSeconds(1))
.AddEntityFrameworkCoreInstrumentation(options =>
{
options.EnrichWithIDbCommand = (activity, command) =>
{
var stateDisplayName = $"{command.CommandType} {command.CommandText} Database: {command.Connection?.Database}";
activity.DisplayName = stateDisplayName;
activity.SetTag("db.name", stateDisplayName);
};
});
tracing.AddOtlpExporter(options =>
{
if (!string.IsNullOrWhiteSpace(url))
{
options.Endpoint = new Uri(url);
}
});
});
builder.Logging.AddOpenTelemetry(logging =>
{
if (!string.IsNullOrEmpty(url))
{
logging.AddOtlpExporter(options => options.Endpoint = new Uri(url));
}
});
}
The Mediator from the MassTransit library was chosen because it doesn't require the implementation of any interfaces, unlike the MediatR library. If we were to use the Mediator from MediatR instead of MassTransit, our domain event would look like this:
public sealed record CustomerCreatedDomainEvent(Guid CustomerId) : INotification
INotification intefrace comes from MediatR library. However our domain events look like this:
public sealed record CustomerCreatedDomainEvent(Guid CustomerId) : IDomainEvent;
IDomainEvent is just a marker interface that we keep in our Domain Layer.
This is particularly important because domain events located in the domain layer can remain free of any dependencies. I believe that the domain layer should be free from all libraries, making it easier to test.
https://masstransit.io/documentation/concepts/mediator
Domain Events are mapped to Integration Events thanks to EventMapperFactory class.
public class EventMapperFactory
{
private readonly Dictionary<Type, IEventMapper> _mappers;
public EventMapperFactory(Dictionary<Type, IEventMapper> mappers)
{
_mappers = mappers;
}
public IEventMapper GetMapper(IDomainEvent domainEvent)
{
if (_mappers.TryGetValue(domainEvent.GetType(), out var mapper))
{
return mapper;
}
return null;
}
}
The registration of new mappers is moved to the DependencyInjectionInstaller file presented below. As you can see, currently, we have only one mapper registered for the CustomerCreatedDomainEvent. To add another mapper, simply register it here. This approach supports the Open/Closed Principle.
builder.Services.AddSingleton<EventMapperFactory>(provider =>
{
var mappers = new Dictionary<Type, IEventMapper>
{
{ typeof(CustomerCreatedDomainEvent), provider.GetRequiredService<CustomerCreatedEventMapper>() },
};
return new EventMapperFactory(mappers);
});
The Strategy pattern is used to obtain the appropriate mapper for mapping Domain Events to Integration Events. Each mapper must implement the IEventMapper interface, which allows you to dynamically apply the correct mapper at runtime.