
<Sponsorships>

[**Progress**](https://www.telerik.com/campaigns/maui/migration-to-dot-net-maui?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=maui-ebook-mnm-na)
prepared a free eBook for you - [**Migration to .NET MAUI.**](https://www.telerik.com/campaigns/maui/migration-to-dot-net-maui?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=maui-ebook-mnm-na)
Do you plan to start your first cross-platform app with .NET MAUI?
You're in the right place.
This eBook will help you examine the benefits of using .NET MAUI for the dev experience,
the app and its end users, plus any downsides.
[**Grab the free MAUI eBook here.**](https://www.telerik.com/campaigns/maui/migration-to-dot-net-maui?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=maui-ebook-mnm-na)

[**IcePanel**](https://u.icepanel.io/1eec0e6f) is a collaborative C4 model modelling & diagramming tool that helps explain complex software systems.
With an interactive map, you can align your software engineering & product teams on technical decisions across the business.
[**Check it out here.**](https://u.icepanel.io/1eec0e6f)

</Sponsorships>

How should you handle errors in your code?

This has been a topic of many discussions, and I want to share my opinion.

One school of thought suggests using exceptions for flow control.
This is not a good approach because it makes the code harder to reason about.
The caller must know the implementation details and which exceptions to handle.

Exceptions are for exceptional situations.

Today, I want to show you how to implement error handling using the **Result pattern.**

It's a functional approach to error handling, making your code more expressive.

## Exceptions For Flow Control

Using exceptions for flow control is an approach to implement the **fail-fast** principle.

As soon as you encounter an error in the code, you throw an exception —
effectively terminating the method, and making the caller responsible for handling the exception.

The problem is the caller must know which exceptions to handle.
And this isn't obvious from the method signature alone.

Another common use case is throwing exceptions for validation errors.

Here's an example in the `FollowerService`:

```csharp
public sealed class FollowerService
{
    private readonly IFollowerRepository _followerRepository;

    public FollowerService(IFollowerRepository followerRepository)
    {
        _followerRepository = followerRepository;
    }

    public async Task StartFollowingAsync(
        User user,
        User followed,
        DateTime createdOnUtc,
        CancellationToken cancellationToken = default)
    {
        if (user.Id == followed.Id)
        {
            throw new DomainException("Can't follow yourself");
        }

        if (!followed.HasPublicProfile)
        {
            throw new DomainException("Can't follow non-public profile");
        }

        if (await _followerRepository.IsAlreadyFollowingAsync(
                user.Id,
                followed.Id,
                cancellationToken))
        {
            throw new DomainException("Already following");
        }

        var follower = Follower.Create(user.Id, followed.Id, createdOnUtc);

        _followerRepository.Insert(follower);
    }
}
```

## Use Exceptions for Exceptional Situations

A rule of thumb I follow is to use exceptions for exceptional situations.
Since you already expect potential errors, why not make it explicit?

You can group all application errors into two groups:

- Errors you know how to handle
- Errors you don't know how to handle

Exceptions are an excellent solution for the errors you don't know how to handle.
And you should catch and handle them at the lowest level possible.

What about the errors you know how to handle?

You can handle them in a functional way with the **Result pattern.**
It's explicit and clearly expresses the intent that the method can fail.
The drawback is the caller has to manually check if the operation failed.

## Expressing Errors Using the Result Pattern

The first thing you will need is an `Error` class to represent application errors.

- `Code` - unique name for the error in the application
- `Description` - contains developer-friendly details about the error

```csharp
public sealed record Error(string Code, string Description)
{
    public static readonly Error None = new(string.Empty, string.Empty);
}
```

Then, you can implement the `Result` class using the `Error` to describe the failure.
This implementation is very bare-bones, and you could add many more features.
In most cases, you also need a generic `Result<T>` class, which will wrap a value inside.

Here's what the `Result` class looks like:

```csharp
public class Result
{
    private Result(bool isSuccess, Error error)
    {
        if (isSuccess && error != Error.None ||
            !isSuccess && error == Error.None)
        {
            throw new ArgumentException("Invalid error", nameof(error));
        }

        IsSuccess = isSuccess;
        Error = error;
    }

    public bool IsSuccess { get; }

    public bool IsFailure => !IsSuccess;

    public Error Error { get; }

    public static Result Success() => new(true, Error.None);

    public static Result Failure(Error error) => new(false, error);
}
```

The only way to create a `Result` instance is by using static methods:

- `Success` - creates a success result
- `Failure` - creates a failure result with the specified `Error`

If you want to avoid building your own `Result` class, take a look at the [FluentResults](https://github.com/altmann/FluentResults) library.

## Applying the Result Pattern

Now that we have the `Result` class let's see how to apply it in practice.

Here's a refactored version of the `FollowerService`.
Notice a few things:

- No more throwing exceptions
- The `Result` return type is explicit
- It's clear which errors the method returns

Another benefit of error handling using the **Result pattern** is that it's easier to test.

```csharp {10,18,23,31,38}
public sealed class FollowerService
{
    private readonly IFollowerRepository _followerRepository;

    public FollowerService(IFollowerRepository followerRepository)
    {
        _followerRepository = followerRepository;
    }

    public async Task<Result> StartFollowingAsync(
        User user,
        User followed,
        DateTime utcNow,
        CancellationToken cancellationToken = default)
    {
        if (user.Id == followed.Id)
        {
            return Result.Failure(FollowerErrors.SameUser);
        }

        if (!followed.HasPublicProfile)
        {
            return Result.Failure(FollowerErrors.NonPublicProfile);
        }

        if (await _followerRepository.IsAlreadyFollowingAsync(
                user.Id,
                followed.Id,
                cancellationToken))
        {
            return Result.Failure(FollowerErrors.AlreadyFollowing);
        }

        var follower = Follower.Create(user.Id, followed.Id, utcNow);

        _followerRepository.Insert(follower);

        return Result.Success();
    }
}
```

## Documenting Application Errors

You can use the `Error` class to document all possible errors in your application.

One approach is to create a static class called `Errors`.
It will have nested classes inside containing the specific errors.
The usage would look like `Errors.Followers.NonPublicProfile`.

However, the approach I like to use is to create a specific class containing the errors.

Here's the `FollowerErrors` class documenting the possible errors for the `Follower` entity:

```csharp
public static class FollowerErrors
{
    public static readonly Error SameUser = new Error(
        "Followers.SameUser", "Can't follow yourself");

    public static readonly Error NonPublicProfile = new Error(
        "Followers.NonPublicProfile", "Can't follow non-public profiles");

    public static readonly Error AlreadyFollowing = new Error(
        "Followers.AlreadyFollowing", "Already following");
}
```

Instead of static fields, you can also use static methods returning an error.
You would call this method with a concrete argument to get an `Error` instance.

```csharp
public static class FollowerErrors
{
    public static Error NotFound(Guid id) => new Error(
        "Followers.NotFound", $"The follower with Id '{id}' was not found");
}
```

## Converting Results Into API Responses

The `Result` object will eventually reach the Minimal API (or controller) endpoint in ASP.NET Core.
Minimal APIs return an `IResult` response, and controllers return an `IActionResult` response.
Regardless, you must convert the `Result` instance into a valid API response.

The straightforward approach is checking the `Result` state and returning an HTTP response.
Here's an example where we check the `Result.IsFailure` flag:

```csharp
app.MapPost(
    "users/{userId}/follow/{followedId}",
    (Guid userId, Guid followedId, FollowerService followerService) =>
    {
        var result = await followerService.StartFollowingAsync(
            userId,
            followedId,
            DateTime.UtcNow);

        if (result.IsFailure)
        {
            return Results.BadRequest(result.Error);
        }

        return Results.NoContent();
    });
```

However, this is an excellent opportunity for a more functional approach.
You can implement the `Match` extension method to provide a callback for each `Result` state.
The `Match` method will execute the respective callback and return the result.

Here's the implementation of `Match`:

```csharp
public static class ResultExtensions
{
    public static T Match<T>(
        this Result result,
        Func<T> onSuccess,
        Func<Error, T> onFailure)
    {
        return result.IsSuccess ? onSuccess() : onFailure(result.Error);
    }
}
```

And this is how you would use the `Match` method in a Minimal API endpoint:

```csharp
app.MapPost(
    "users/{userId}/follow/{followedId}",
    (Guid userId, Guid followedId, FollowerService followerService) =>
    {
        var result = await followerService.StartFollowingAsync(
            userId,
            followedId,
            DateTime.UtcNow);

        return result.Match(
            onSuccess: () => Results.NoContent(),
            onFailure: error => Results.BadRequest(error));
    });
```

Much more concise. Don't you think so?

## Summary

If you take one thing with you from this week's issue, it should be this: exceptions are for exceptional situations.
Moreover, you should only use exceptions for errors you don't know how to handle.
In all other cases, expressing the error clearly with the **Result pattern** is more valuable.

Using the `Result` class allows you to:

- Express the intent that a method _could_ fail
- Encapsulate an application error inside
- Provide a functional way to handle errors

Additionally, you can document all application errors with the `Error` class.
This is helpful for developers to know which errors they need to handle.

You can even convert this to actual _documentation_.
For example, I wrote a simple program that scans the project for all `Error` fields.
It then converts this into a table format and uploads it to a Confluence page.

So I encourage you to try the **Result pattern** and see how it can improve your code.

See you next week.

---



<Sponsorships>

Will .NET become #1 for cross-platform desktop development?
With [**DotNetBrowser's**](https://links.teamdev.com/avalonia-case-study-mj) recent update, Avalonia UI finally gets the much-awaited cross-platform web view control.
Check out the story and [**try it for free now.**](https://links.teamdev.com/avalonia-case-study-mj)

Get all the latest .NET news once a month in the [**.NET Annotated newsletter.**](https://www.jetbrains.com/lp/dotnet-annotated/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetannotated)
It is hosted by Rachel Appel, a Developer Advocate at JetBrains, and guest curators from the wider .NET community.
Feel free to suggest an article too because sharing is caring! [**Join free here.**](https://www.jetbrains.com/lp/dotnet-annotated/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetannotated)

</Sponsorships>

Today I want to show you how to use the **CQRS** pattern to build fast and scalable applications.

The CQRS pattern separates the writes and reads in the application.

This separation can be logical or physical and has many benefits:

- Complexity management
- Improved performance
- Scalability
- Flexibility
- Security

I'm also going to show you how to implement CQRS in your application using MediatR.

But first, we have to understand what CQRS is.

## What Exactly is CQRS?

[CQRS](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) stands for **Command Query Responsibility Segregation**.
The CQRS pattern uses separate models for reading and updating data.
The benefits of using CQRS are complexity management, improved performance, scalability, and security.

The standard approach for working with a database is using the same model to query and update data.
This is simple and works great for most CRUD operations.
However, in more complex applications, it becomes difficult to maintain.
On the write side, you could have complex business logic and validation in the model.
On the read side, you may need to perform many different queries.

Also, consider how we create the data model.
Applying SQL data modeling best practices will give you a normalized database.
This is generally fine, but it's optimized for writing.

Having separate models for commands and queries allows you to scale them independently.
The separation could be logical while using the same database.
You could split the subsystems for commands and queries into separate services.
And you can even have multiple databases optimized for writing or reading data.

## How Is It Different From CQS?

[CQS](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation) stands for **Command Query Separation**.
It's a term coined by Bertrand Meyer in his book [Object-Oriented Software Construction.](https://en.wikipedia.org/wiki/Object-Oriented_Software_Construction)

The basic premise of CQS is splitting an object's methods into **Commands** and **Queries**.

- **Commands**: Change the state of a system but don't return a value
- **Queries**: Return a value and don't change the state of the system (no side effects)

This doesn't mean a command can never return a value.
A typical example is popping a value from a stack.
It returns a value and changes the state of the system.
But the intent is what matters here.

CQS is a _principle._
You can follow this principle if it makes sense, but be pragmatic.

CQRS is the evolution of CQS.
CQRS works on the architectural level.
At the same time, CQS works on the method (or class) level.

## Many Flavors of CQRS

Here's a high-level overview of a CQRS system using multiple databases.
Commands update the write database.
Then, you need to synchronize the updates with the read database.
This introduces eventual consistency to CQRS systems.

Eventual consistency significantly increases the complexity of your application.
You must consider what happens if the synchronization process fails, and have a fault tolerance strategy.

<Image
  src="blogs/mnw_060/cqrs.png"
  width={1207}
  height={708}
  alt="Diagram of a system using CQRS with two databases."
/>

There are many flavors of this approach:

- SQL database on the write side and NoSQL database (for example, [RavenDB](https://ravendb.net/)) on the read side
- Event sourcing on the write side and NoSQL database on the read side
- Using Redis or some other distributed cache on the read side

Separating the models for updating and reading data allows you to choose the best database for your requirements.

## Logical CQRS Architecture

How do you apply the CQRS pattern to your system?
I prefer using [MediatR.](https://github.com/jbogard/MediatR)

MediatR implements the [mediator pattern](https://refactoring.guru/design-patterns/mediator) to solve a simple problem - decoupling the in-process sending of messages from handling messages.

You can extend MediatR's `IRequest` interface with a custom `ICommand` and `IQuery` abstraction.
This allows you to define commands and queries in your system explicitly.

On the write side, I typically use [EF Core](https://learn.microsoft.com/en-us/ef/core/) and a rich domain model to encapsulate business logic.
The command flow uses EF to load an entity into memory, execute the domain logic, and save the changes to the database.

On the read side, I want as little indirection as possible.
Using [Dapper](https://github.com/DapperLib/Dapper) with raw SQL queries is an excellent choice.
You can also create views in the database and query them.
Alternatively, you could use EF Core to execute queries with projections.

<Image
  src="blogs/mnw_060/cqrs_application.png"
  width={1578}
  height={1182}
  alt="Diagram of an application using CQRS on the architectural level."
/>

## Implementing CQRS With MediatR

Implementing CQRS with MediatR has two components:

- Defining your command or query class
- Implementing the respective command or query handler

I made an in-depth video explaining this process, and you can [watch it here.](https://youtu.be/vdi-p9StmG0)

You use the `ISender` interface to `Send` the command or query.
MediatR takes care of routing the command or query to the respective handler.

The request will pass through the _request pipeline_.
It's a wrapper around each request, and you can use it to solve cross-cutting concerns with `IPipelineBehavior`.
For example, you can implement [validation for commands with FluentValidation.](cqrs-validation-with-mediatr-pipeline-and-fluentvalidation)

```csharp
[ApiController]
[Route("api/bookings")]
public class BookingsController : ControllerBase
{
    private readonly ISender _sender;

    public BookingsController(ISender sender)
    {
        _sender = sender;
    }

    [HttpPut("{id}/confirm")]
    public async Task<IActionResult> ConfirmBooking(
        Guid id,
        CancellationToken cancellationToken)
    {
        var command = new ConfirmBookingCommand(id);

        var result = await _sender.Send(command, cancellationToken);

        if (result.IsFailure)
        {
            return BadRequest(result.Error);
        }

        return NoContent();
    }
}

```

Here's an example of a command handler with repositories and a rich domain model:

```csharp
internal sealed class ConfirmBookingCommandHandler
    : ICommandHandler<ConfirmBookingCommand>
{
    private readonly IDateTimeProvider _dateTimeProvider;
    private readonly IBookingRepository _bookingRepository;
    private readonly IUnitOfWork _unitOfWork;

    public ConfirmBookingCommandHandler(
        IDateTimeProvider dateTimeProvider,
        IBookingRepository bookingRepository,
        IUnitOfWork unitOfWork)
    {
        _dateTimeProvider = dateTimeProvider;
        _bookingRepository = bookingRepository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result> Handle(
        ConfirmBookingCommand request,
        CancellationToken cancellationToken)
    {
        var booking = await _bookingRepository.GetByIdAsync(
            request.BookingId,
            cancellationToken);

        if (booking is null)
        {
            return Result.Failure(BookingErrors.NotFound);
        }

        var result = booking.Confirm(_dateTimeProvider.UtcNow);

        if (result.IsFailure)
        {
            return result;
        }

        await _unitOfWork.SaveChangesAsync(cancellationToken);

        return Result.Success();
    }
}
```

Here's an example of a query handler that uses Dapper and raw SQL:

```csharp
internal sealed class SearchApartmentsQueryHandler
    : IQueryHandler<SearchApartmentsQuery, IReadOnlyList<ApartmentResponse>>
{
    private static readonly int[] ActiveBookingStatuses =
    {
        (int)BookingStatus.Reserved,
        (int)BookingStatus.Confirmed,
        (int)BookingStatus.Completed
    };

    private readonly ISqlConnectionFactory _sqlConnectionFactory;

    public SearchApartmentsQueryHandler(
        ISqlConnectionFactory sqlConnectionFactory)
    {
        _sqlConnectionFactory = sqlConnectionFactory;
    }

    public async Task<Result<IReadOnlyList<ApartmentResponse>>> Handle(
        SearchApartmentsQuery request,
        CancellationToken cancellationToken)
    {
        if (request.StartDate > request.EndDate)
        {
            return new List<ApartmentResponse>();
        }

        using var connection = _sqlConnectionFactory.CreateConnection();

        const string sql = """
            SELECT
                a.id AS Id,
                a.name AS Name,
                a.description AS Description,
                a.price_amount AS Price,
                a.price_currency AS Currency,
                a.address_country AS Country,
                a.address_state AS State,
                a.address_zip_code AS ZipCode,
                a.address_city AS City,
                a.address_street AS Street
            FROM apartments AS a
            WHERE NOT EXISTS
            (
                SELECT 1
                FROM bookings AS b
                WHERE
                    b.apartment_id = a.id AND
                    b.duration_start <= @EndDate AND
                    b.duration_end >= @StartDate AND
                    b.status = ANY(@ActiveBookingStatuses)
            )
            """;

        var apartments = await connection
            .QueryAsync<ApartmentResponse, AddressResponse, ApartmentResponse>(
                sql,
                (apartment, address) =>
                {
                    apartment.Address = address;

                    return apartment;
                },
                new
                {
                    request.StartDate,
                    request.EndDate,
                    ActiveBookingStatuses
                },
                splitOn: "Country");

        return apartments.ToList();
    }
}
```

## Closing Thoughts

Separating commands and queries can improve performance and scalability in the long run.
You can optimize commands and queries differently based on your requirements.

Commands encapsulate complex business logic and validation.
Using EF Core and a rich domain model is an excellent solution.

Queries are all about performance, so you want to use what's fastest.
This could be raw SQL queries with Dapper, EF Core projections, or Redis.

If you want the system I use to build scalable applications with CQRS and MediatR, check out [**Pragmatic Clean Architecture.**](/pragmatic-clean-architecture)

Stay awesome!

---



<Sponsorships>

[**Progress**](https://www.telerik.com/campaigns/blazor/planning-a-blazor-application?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-ebook-mnm-na)
prepared a free eBook for you - [**Planning a Blazor Application.**](https://www.telerik.com/campaigns/blazor/planning-a-blazor-application?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-ebook-mnm-na)
This eBook documents a high-level outline of what developers need to consider when choosing Blazor: migration strategies, target platforms, tooling, testing and UI.
[**Get the Blazor eBook here.**](https://www.telerik.com/campaigns/blazor/planning-a-blazor-application?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-ebook-mnm-na)

[**IcePanel**](https://u.icepanel.io/1eec0e6f) is a collaborative C4 model modelling & diagramming tool that helps explain complex software systems.
With an interactive map, you can align your software engineering & product teams on technical decisions across the business.
[**Check it out here.**](https://u.icepanel.io/1eec0e6f)

</Sponsorships>

Dependency injection (DI) is one of the most exciting features of ASP.NET Core.
It helps us build more testable and maintainable applications.
However, ASP.NET Core's built-in DI system sometimes needs a little help to achieve more advanced scenarios.

So I want to introduce you to a powerful library for enhancing your ASP.NET Core DI - [Scrutor.](https://www.nuget.org/packages/Scrutor)

If you're an ASP.NET Core developer, you're already familiar with Dependency Injection.
It's a fundamental part of building modular and maintainable applications.

Let's explore how Scrutor can simplify and enhance your DI setup.

## What is Dependency Injection?

[Dependency Injection](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-7.0)
is a software design pattern used in ASP.NET Core to achieve the [Inversion of Control (IOC)](https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/architectural-principles#dependency-inversion)
principle.
This promotes loose coupling and makes your code more testable, maintainable, and extensible.

DI allows you to inject dependencies into your classes rather than create them within the class.
The framework takes care of providing the required instances at runtime.
It also manages the disposal of these dependencies based on the service lifetime.

Here's an example of combining constructor and method injection in a controller:

```csharp
[ApiController]
[Route("api/activities")]
public class ActivitiesController : ControllerBase
{
    private readonly ILogger<ActivitiesController> _logger;

    // Constructor injection
    public ActivitiesController(ILogger<ActivitiesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public async Task<IActionResult> Get(ISender sender) // Method injection
    {
        var activities = await sender.Send(new GetActivitiesQuery());

        return Ok(activities);
    }
}
```

## Service Lifetimes in ASP.NET Core

Before we dive into Scrutor, let's briefly discuss [service lifetimes in ASP.NET Core.](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection#service-lifetimes)
When you register a service in the DI container, you specify its lifetime.
The service lifetime defines how long the DI container should maintain the service.

ASP.NET Core provides three main lifetimes:

- **Singleton**: A single instance of the service is created and reused throughout the application's lifetime.
- **Scoped**: A new instance is created for each scope (usually a web request). Services created in the same scope share the same instance.
- **Transient**: A new instance is created every time the service is requested.

Understanding service lifetimes is crucial when designing your application's architecture.

## What is Scrutor?

The [Scrutor library](https://github.com/khellang/Scrutor) improves your dependency injection code by extending the existing features from `Microsoft.Extensions.DependencyInjection`.

These extensions add support for advanced assembly scanning and service decoration.

To get started using Scrutor, you need to install the NuGet package:

```powershell
Install-Package Scrutor
```

## Assembly Scanning With Scrutor

One of the most powerful features of Scrutor is its ability to perform assembly scanning.
Rather than manually registering each service, Scrutor allows you to scan your assemblies for types that should be registered with the DI container.
This can significantly reduce the boilerplate code required for service registration, making your code cleaner and more maintainable.

The entry point for assembly scanning is the `Scan` method, which accepts a delegate to define the DI setup.

Here's an example of scanning two assemblies and registering the classes inside as scoped services:

```csharp
builder.Services.Scan(selector => selector
    .FromAssemblies(
        typeof(PersistenceAssembly).Assembly,
        typeof(InfrastructureAssembly).Assembly)
    .AddClasses(publicOnly: false)
    .UsingRegistrationStrategy(RegistrationStrategy.Skip)
    .AsMatchingInterface()
    .WithScopedLifetime());
```

Let's unpack what's happening here:

- `FromAssemblies` - allows you to specify which assemblies to scan
- `AddClasses` - adds the classes from the selected assemblies
- `UsingRegistrationStrategy` - defines which `RegistrationStrategy` to use
- `AsMatchingInterface` - registers the types as matching interfaces (`ClassName` → `IClassName`)
- `WithScopedLifetime` - registers the types with a scoped service lifetime

There are three values for `RegistrationStrategy` you can use:

- `RegistrationStrategy.Skip` - skips registrations if service already exists
- `RegistrationStrategy.Append`- appends a new registration for existing services
- `RegistrationStrategy.Throw`- throws when trying to register an existing service

You can also specify a filter to `AddClasses` to select specific types you want to configure.
Here's an example of registering repository implementations:

```csharp
services.Scan(scan => scan
    .FromAssemblies(typeof(PersistenceAssembly).Assembly)
    .AddClasses(
        filter => filter.Where(x => x.Name.EndsWith("Repository")),
        publicOnly: false)
    .UsingRegistrationStrategy(RegistrationStrategy.Throw)
    .AsMatchingInterface()
    .WithScopedLifetime());
```

## Service Decoration With Scrutor

Service decoration is another valuable feature offered by Scrutor.
It enables you to modify or extend services during registration without changing the original implementation.

This is incredibly useful when adding cross-cutting concerns or other modifications to services without altering their core functionality.
For example, you can implement a [caching decorator for repositories.](decorator-pattern-in-asp-net-core)

Here's how you can configure a decorator with Scrutor's `Decorate` method:

```csharp
services.AddScoped<IActivitiesRepository, ActivitiesRepository>();

services.Decorate<IActivitiesRepository, PermissionActivitiesRepository>();
```

It will decorate the `ActivitiesRepository` service using the `PermissionActivitiesRepository`.
This also means that `PermissionActivitiesRepository` can inject an `IActivitiesRepository` instance, and at runtime, this is resolved as `ActivitiesRepository`.

Here's how you can implement the `PermissionActivitiesRepository`:

```csharp {3,7,21}
public class PermissionActivitiesRepository : IActivitiesRepository
{
    private readonly IActivitiesRepository _decorated;
    private readonly IPermissionChecker _permissionChecker;

    public PermissionActivitiesRepository(
        IActivitiesRepository decorated,
        IPermissionChecker permissionChecker)
    {
        _decorated = decorated;
        _permissionChecker = permissionChecker;
    }

    public List<Activity> Get()
    {
        if (!_permissionChecker.HasPermission(Permissions.FetchActivities))
        {
            return new();
        }

        return _decorated.Get();
    }
}
```

## Takeaway

Scrutor can improve your ASP.NET Core DI by simplifying service registration through assembly scanning and enabling service decoration.
You can use Scrutor's capabilities to write cleaner, more maintainable, and flexible DI code while reducing the complexity of your startup configuration.

Assembly scanning can reduce the boilerplate code required for service registration.
It also allows you to create custom conventions for registering services.

Service decoration has been a real game-changer for me.
It's the simplest way to introduce cross-cutting concerns in your application.
For example, I used to add an idempotency check before handling events.

Hope this was valuable.

Stay awesome!

---



<Sponsorships>

Want to move to [**JetBrains Rider**](https://www.jetbrains.com/dotnet/guide/tutorials/resharper-to-rider/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetguide)
but not sure where to start?
For a smooth experience, check out this guide where we look at the essential functionality you'll find helpful when [**migrating from Visual Studio.**](https://www.jetbrains.com/dotnet/guide/tutorials/resharper-to-rider/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetguide)

Do you build complex software systems?
See how [**NServiceBus**](https://go.particular.net/milanjovanovic) makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling.
[**Get started for FREE.**](https://go.particular.net/milanjovanovic)

</Sponsorships>

NServiceBus is a feature-rich messaging framework supporting many different message transports.
It's developed and maintained by [Particular Software.](https://particular.net/)
And it simplifies the process of building complex distributed systems across various cloud-based queueing technologies.

The basic building blocks of NServiceBus are messages and endpoints.
A message contains the required information to execute a business operation.
Endpoints are logical entities that send and receive messages.

And now let's see how to get started with NServiceBus, from installation and setup to building your first NServiceBus endpoint.

In this week's newsletter, you will learn how to:

- Configure an endpoint to use Azure Service Bus
- Send and publish messages using `IMessageSession`
- Handle messages with NServiceBus

Let's dive in!

## What is NServiceBus?

[NServiceBus](https://go.particular.net/milanjovanovic) is a messaging framework and platform that simplifies building reliable, scalable, and maintainable distributed systems.
It's designed to address the challenges that arise when building applications that are distributed across multiple servers.

One of NServiceBus's foundational principles is its embrace of a message-driven architecture.
In this model, components communicate by sending and receiving messages.
Messages are the fundamental units of communication, representing commands, events, or data that services exchange.

Why is this significant?

Message-driven architectures offer several advantages:

- Asynchronous communication
- Loose coupling
- Reliability

NServiceBus supports the powerful publish/subscribe (pub/sub) messaging pattern.
This pattern allows services to publish events and subscribe to events of interest.
When a service publishes an event, all interested subscribers receive a copy of the event.
This is a key feature for building event-driven architectures, where services react to and process events in response to various actions or changes in the system.

## Configuring the NServiceBus Endpoint

NServiceBus uses the concept of an _endpoint_ to send and receive messages.
It's a logical component that communicates with other components.
You define your message handlers and sagas inside of an endpoint.

Let's start by installing the `NServiceBus` NuGet package:

```powershell
Install-Package NServiceBus.Extensions.Hosting
```

Now you can configure an _endpoint_ to use [Azure Service Bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview)
to send messages:

```csharp
var builder = WebApplication.CreateBuilder();

builder.Host.UseNServiceBus(context =>
{
    var endpointConfiguration = new EndpointConfiguration("Training");

    var transport = endpointConfiguration
        .UseTransport<AzureServiceBusTransport>();

    var connectionString = builder.Configuration
        .GetConnectionString("AzureServiceBusConnectionString");
    transport.ConnectionString(connectionString);

    endpointConfiguration.EnableInstallers();

    return endpointConfiguration;
});

var app = builder.Build();

app.Run();
```

The call to `UseNServiceBus` tells the host to use NServiceBus.
Inside the callback, you can configure the endpoint that will start when the host runs.

One more important aspect is calling `EnableInstallers` to set up the Azure Service Bus topology.
This will tell NServiceBus to create the required queues, so you don't have to do it manually.

## Publishing Messages in NServiceBus

The next building block you need in any messaging system is the messages.
Messages are C# classes or interfaces that contain meaningful data for the business process.

NServiceBus supports three types of messages:

- `ICommand` - sends a request to perform an action
- `IEvent` - communicates that something significant occurred
- `IMessage` - for messages that aren't commands or events (typically for replies in _request-response_)

Events can have more than one handler, while a command should have only one handler.

Let's create our first message contract:

```csharp
using NServiceBus;

public class WorkoutCreated : IEvent
{
    public Guid Id [ get; set; ]
}
```

The `WorkoutCreated` message is an event that we will publish after creating a new `Workout`.

You can use the `IMessageSession` service to send messages from your controllers or Minimal API endpoints.

```csharp {4,10}
app.MapPost("api/workouts", async (
    Workout workout,
    AppDbContext context,
    IMessageSession messageSession) =>
{
    context.Add(workout);

    await context.SaveChangesAsync();

    await messageSession.Publish(new  WorkoutCreated { Id = workout.Id });

    return Results.Ok(workout);
});
```

NServiceBus has some built-in validation when sending messages.
You have to specify an `ICommand` when calling the `Send` method, or you will get an exception.
Similarly, you have to specify an `IEvent` when calling the `Publish` method.

## Handling Messages With NServiceBus

Once you send a message, you need a way to handle it and run some business logic.
To handle a message, you need to implement the `IHandleMessages` interface and specify which message you are handling.

Here's an implementation of the `WorkoutCreatedHandler`:

```csharp
public class WorkoutCreatedHandler : IHandleMessages<WorkoutCreated>
{
    private readonly ILogger<WorkoutCreated> _logger;

    public WorkoutCreatedHandler(ILogger<WorkoutCreated> logger)
    {
        _logger = logger;
    }

    public async Task Handle(
        WorkoutCreated message,
        IMessageHandlerContext context)
    {
        logger.LogInformation("Processing workout - {Id}", message.Id);

        // Continue to process the message.
    }
}
```

Implementing `IHandleMessages<WorkoutCreated>` tells NServiceBus how to process the `WorkoutCreated` message when an endpoint receives it.
This interface defines only one method: `Handle`.

The `Handle` method has an `IMessageHandlerContext` parameter, which allows you to send more messages.
This can be helpful when implementing a choreographed saga.
Processing one message triggers the next step in the chain until the entire process is completed.

## In Summary

In this week's issue, we discussed NServiceBus, a robust messaging framework for building distributed systems in .NET.
You learned how to configure NServiceBus with the Azure Service Bus transport.
We discussed the different message types in NServiceBus and how to publish and handle a message.

Building distributed systems is a complex endeavor, but NServiceBus simplifies many challenges.
By embracing a message-driven architecture and leveraging NServiceBus's features,
you'll be well-equipped to create resilient, scalable, and maintainable applications in the .NET ecosystem.

Further reading:

- [NServiceBus step-by-step tutorial](https://go.particular.net/milanjovanovic/getting-started-with-nservicebus)
- [Live coding an NServiceBus system](https://go.particular.net/milanjovanovic/live-coding-your-first-nservicebus-system)
- [NServiceBus monitoring demo](https://go.particular.net/milanjovanovic/monitoring-demo)
- [Messaging with Azure Service Bus](messaging-made-easy-with-azure-service-bus)
- [Implementing the Saga pattern](implementing-the-saga-pattern-with-rebus-and-rabbitmq)
- [Orchestration vs Choreography](orchestration-vs-choreography)

Hope this was helpful.

I'll see you next week!

---



<Sponsorships>

[**Telerik UI for Blazor**](https://www.telerik.com/blogs/why-modernize-blazor-winning-strategy-next-application?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-mnm-content-exposure) -
a winning strategy for your next application.
With .NET 8 just around the corner, there's a lot of talk about Blazor becoming a "drop-in" replacement for MVC or Razor Pages.
If you are exploring how to modernize existing applications, moving from MVC, Razor Pages or Web Forms,
[**take a look at what Blazor brings to the table.**](https://www.telerik.com/blogs/why-modernize-blazor-winning-strategy-next-application?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-mnm-content-exposure)

[**IcePanel**](https://u.icepanel.io/1eec0e6f) is a collaborative C4 model modelling & diagramming tool that helps explain complex software systems.
With an interactive map, you can align your software engineering & product teams on technical decisions across the business.
[**Check it out here.**](https://u.icepanel.io/1eec0e6f)

</Sponsorships>

Validation is an essential cross-cutting concern that you need to solve in your application.
You want to ensure the request is valid before you consider processing it.

Another important question you need to answer is how you approach different types of validation.
For example, I consider input and business validation differently, and each deserves a specific solution.

I want to show you an elegant solution for validation using [MediatR](https://github.com/jbogard/MediatR)
and [FluentValidation.](https://docs.fluentvalidation.net/en/latest/index.html)

If you aren't using [CQRS](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) with MediatR, don't worry.
Everything I explain about validation can easily be adapted to other paradigms.

Here's what I'm going to talk about in this week's newsletter:

- Standard validation approach
- Input vs business validation
- Separating validation logic
- Generic `ValidationBehavior`

Let's dive in.

## The Standard Command Validation Approach

The standard way of implementing validation is right before processing the command.
The validation is tightly coupled to the command handler, which could be problematic.

I find this approach difficult to maintain as the complexity of the validation increases.
Each change to the validation logic also touches the handler, and the handler itself can grow out of control.

It also makes it harder to differentiate between input and _business_ validation.

Here's an example `ShipOrderCommandHandler` that checks if the `ShippingAddress.Country` is one of the supported countries:

```csharp
internal sealed class ShipOrderCommandHandler
    : IRequestHandler<ShipOrderCommand>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IShippingService _shippingService;
    private readonly ShipmentSettings _shipmentSettings;

    public async Task Handle(
        ShipOrderCommand command,
        CancellationToken cancellationToken)
    {
        if (!_shipmentSettings
                .SupportedCountries
                .Contains(command.ShippingAddress.Country))
        {
            throw new ArgumentException(nameof(ShipOrderCommand.Address));
        }

        var order = _orderRepository.Get(command.OrderId);

        _shippingService.ShipTo(
            command.ShippingAddress,
            command.ShippingMethod);
    }
}
```

What if we can separate command validation and command handling?

## Input Validation and Business Validation

I mentioned input and _business_ validation in the previous section.

Here's how I consider them to be different:

- **Input validation** - We only validate that the command is _processable_.
  These are simple validations, such as checking for `null` values, empty strings, etc.
- **Business validation** - We validate the command to satisfy the business rules.
  This includes checking the system state for required preconditions before processing the command.

Another way to compare them is cheap vs. expensive.
Input validation is usually cheap to execute and can be done in memory.
While business validation involves reading state and is slower.

So, input validation sits at the entry point of the use case before handling the request.
After it completes, we have a _valid_ command.
And this is a rule I always follow - an invalid command should never reach the handler.

## Input Validation With FluentValidation

[FluentValidation](https://docs.fluentvalidation.net/en/latest/index.html) is an excellent validation library for .NET,
which uses a fluent interface and lambda expressions for building strongly typed validation rules.

Here's the `ShipOrderCommand` that we want to validate:

```csharp
public sealed record ShipOrderCommand : IRequest
{
    public Guid OrderId { get; set; }

    public string ShippingMethod { get; set; }

    public Address ShippingAddress { get; set; }
}
```

To implement a validator with [FluentValidation,](https://github.com/FluentValidation/FluentValidation)
you create a class that inherits from the `AbstractValidator<T>` base class.
Then, you can add the validation rules from the constructor using `RuleFor`:

```csharp
public sealed class ShipOrderCommandValidator
    : AbstractValidator<ShipOrderCommand>
{
    public ShipOrderCommandValidator(ShipmentSettings settings)
    {
        RuleFor(command => command.OrderId)
            .NotEmpty()
            .WithMessage("The order identifier can't be empty.");

        RuleFor(command => command.ShippingMethod)
            .NotEmpty()
            .WithMessage("The shipping method can't be empty.");

        RuleFor(command => command.ShippingAddress)
            .NotNull()
            .WithMessage("The shipping address can't be empty.");

        RuleFor(command => command.ShippingAddress.Country)
            .Must(country => settings.SupportedCountries.Contains(country))
            .WithMessage("The shipping country isn't supported.");
    }
}
```

The naming convention I like to use is the name of the command and append _Validator_.
You can also enforce this by writing [architecture tests.](enforcing-software-architecture-with-architecture-tests)

To automatically register all validators from an assembly, you need to call the `AddValidatorsFromAssembly` method:

```csharp
services.AddValidatorsFromAssembly(ApplicationAssembly.Assembly);
```

## Running Validation From the Use Case

To run the `ShipOrderCommandValidator`, you can use the `IValidator<T>` service and inject it from the constructor.

The validator exposes a few methods you can call, like `Validate`, `ValidateAsync`, or `ValidateAndThrow`.

The `Validate` method returns a `ValidationResult` object which contains two properties:

- `IsValid` - a boolean flag saying whether the validation succeeded
- `Errors` - a collection of `ValidationFailure` objects containing any validation failures

Alternatively, calling the `ValidateAndThrow` method throws a `ValidationException` if validation fails.

```csharp
internal sealed class ShipOrderCommandHandler
    : IRequestHandler<ShipOrderCommand>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IShippingService _shippingService;
    private readonly IValidator<ShipOrderCommand> _validator;

    public async Task Handle(
        ShipOrderCommand command,
        CancellationToken cancellationToken)
    {
        _validator.ValidateAndThrow(command);

        var order = _orderRepository.Get(command.OrderId);

        _shippingService.ShipTo(
            command.ShippingAddress,
            command.ShippingMethod);
    }
}
```

This approach forces you to define an explicit dependency on `IValidator` in every command handler.

What if we can implement this cross-cutting concern in a more generic way?

## MediatR Validation Pipeline

Here's a complete implementation of a `ValidationBehavior` using FluentValidation and MediatR's `IPipelineBehavior`.

The `ValidationBehavior` acts as a middleware for the request pipeline and performs validation.
If the validation fails, it will throw a custom `ValidationException` with a collection of `ValidationError` objects.

I also want to highlight the use of `ValidateAsync`, which allows you to define asynchronous validation rules.
You must call the `ValidateAsync` method if you have asynchronous rules.
Otherwise, the validator will throw an exception.

```csharp
public sealed class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : ICommandBase
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        var context = new ValidationContext<TRequest>(request);

        var validationFailures = await Task.WhenAll(
            _validators.Select(validator => validator.ValidateAsync(context)));

        var errors = validationFailures
            .Where(validationResult => !validationResult.IsValid)
            .SelectMany(validationResult => validationResult.Errors)
            .Select(validationFailure => new ValidationError(
                validationFailure.PropertyName,
                validationFailure.ErrorMessage))
            .ToList();

        if (errors.Any())
        {
            throw new Exceptions.ValidationException(errors);
        }

        var response = await next();

        return response;
    }
}
```

Don't forget to register the `ValidationBehavior` with MediatR by calling `AddOpenBehavior`:

```csharp
services.AddMediatR(config =>
{
    config.RegisterServicesFromAssemblyContaining<ApplicationAssembly>();

    config.AddOpenBehavior(typeof(ValidationBehavior<,>));
});
```

## Handling Validation Exceptions

Here's a custom `ValidationExceptionHandlingMiddleware` middleware that only handles the custom `ValidationException`.
It converts the exception to a `ProblemDetails` response and includes any validation errors.

You can easily expand this to be a generic global exception handler.

```csharp
public sealed class ValidationExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;

    public ValidationExceptionHandlingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exceptions.ValidationException exception)
        {
            var problemDetails = new ProblemDetails
            {
                Status = StatusCodes.Status400BadRequest,
                Type = "ValidationFailure",
                Title = "Validation error",
                Detail = "One or more validation errors has occurred"
            };

            if (exception.Errors is not null)
            {
                problemDetails.Extensions["errors"] = exception.Errors;
            }

            context.Response.StatusCode = StatusCodes.Status400BadRequest;

            await context.Response.WriteAsJsonAsync(problemDetails);
        }
    }
}
```

You also need to include the middleware in the request pipeline by calling `UseMiddleware`:

```csharp
app.UseMiddleware<ExceptionHandlingMiddleware>();
```

## Takeaway

This implementation of `ValidationBehavior` is something I use in real projects, and it works incredibly well.
If I don't want to throw an exception, I can update the `ValidationBehavior` to return a result object instead.

How do you apply this if you're not using MediatR?

I'm using an `IPipelineBehavior`, which allows me to implement a _middleware_ wrapping each request.

So, all you need is a way to implement middleware and place your validation inside.
And I like having options, so here are [three ways to create middleware in ASP.NET Core.](3-ways-to-create-middleware-in-asp-net-core)

Hope this was valuable.

Stay awesome!

---



<Sponsorships>

Do you build complex software systems?
See how [**NServiceBus**](https://go.particular.net/milanjovanovic) makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling.
[**Get started for FREE.**](https://go.particular.net/milanjovanovic)

Want to learn [**Blazor?**](https://www.jetbrains.com/dotnet/guide/tutorials/blazor-essentials/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetguide)
Check out this [**Blazor Essentials tutorial,**](https://www.jetbrains.com/dotnet/guide/tutorials/blazor-essentials/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetguide)
where Rachel Appel, Developer Advocate at JetBrains, explores working with its components, forms, data, JavaScript interoperability, and more.

</Sponsorships>

You start building a beautiful monolith system.
Maybe a [**modular monolith**](what-is-a-modular-monolith).

The system grows over time, and requirements are ever-changing. Slowly, cracks begin to appear in the system.

This could be for organizational reasons and distributing the work across a team.
Or it could be because of scaling issues and performance bottlenecks.

You begin evaluating the possible solutions, and the benefits and tradeoffs of each one.
At last, you come to a decision.

It's time to migrate parts of the system to individual (micro)services.

So, how do we approach this migration from monolith to microservices?

That is the topic of this week's newsletter.

Let's dive in!

## Decoupling Using Bounded Contexts

The first step in moving from a monolith to microservices is identifying the bounded contexts.
Because they represent cohesive parts of the domain that are candidates for extraction.

One solution is to identify [bounded contexts](https://martinfowler.com/bliki/BoundedContext.html)
using the domain-driven design strategic modeling.

Bounded contexts define the explicit boundaries between modules and separate the responsibilities.
This is one of the biggest challenges when migrating to microservices.
[Identifying good boundaries](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/domain-analysis)
between modules ensures microservices are narrowly focused on one problem domain.

Defining boundaries is also easier in a monolith because you aren't working with a distributed system.
[Refactoring bad boundaries](https://cloud.google.com/architecture/microservices-architecture-refactoring-monoliths)
is less risky, and you have more freedom to "get it right".

<Image
  src="blogs/mnw_056/bounded_contexts.png"
  width={978}
  height={597}
  alt="Bounded contexts."
/>

And the size of the bounded context shouldn't worry you.
Instead, focus on [service boundaries.](https://go.particular.net/right-sized-services)

The next problem you need to solve is coupling.
Coupling is manifested in two ways:

- Database dependencies
- Communication between modules

You can solve these problems from the start by building a modular monolith.
But I'll also explain the guiding principles you can use to solve coupling.

## How a Modular Monolith Solves Coupling

A [modular monolith](what-is-a-modular-monolith) is a catchy name for a monolith system built from a few
bounded contexts (modules) and following a set of principles to control coupling.
Each module contains a cohesive set of functionalities and is isolated from other modules in the system.
The isolation refers to database dependencies and inter-module communication.

<Image
  src="blogs/mnw_056/modular_monolith.png"
  width={978}
  height={597}
  alt="Modular monolith."
/>

You can think of a module as a distinct application within the system.
A module has its own domain, entities, use cases, database tables.
The modules are deployed together as a single executable application.
But they are otherwise independent.

You can apply different architectural approaches to each module, like [**Clean Architecture**](/pragmatic-clean-architecture).

So I mentioned that you need to reduce the coupling between modules.

Here are two principles to solve database coupling:

- Modules can't share tables in the database
- Modules can't directly query the database tables of other modules

Sharing database tables leads to a high degree of coupling, and this is exactly what you are trying to avoid.
You can isolate the data for each module on a logical level using schemas or physically with different databases.

A module should expose a public API that other modules can call.
This public API is the entry point into the module.
And this is the only way for modules to communicate.

Communication between modules can be [**synchronous**](modular-monolith-communication-patterns#synchronous-communication-with-method-calls)
using method calls, or [**asynchronous**](modular-monolith-communication-patterns#asynchronous-communication-with-messaging)
using a message bus.

My preferred approach is asynchronous communication using messaging.
It's loosely coupled and makes the transition to microservices easier.

## Adding a Message Broker To The System

To implement asynchronous communication between modules, you can introduce a message broker.
But you don't need to introduce a full-blown message broker from the start.

You can implement messaging between modules using an abstraction like [MassTransit](https://masstransit.io) while abstracting away the transport mechanism.

MassTransit has an in-memory transport that works well inside a single process.
It's very fast.
But it isn't durable, and you can lose messages if the bus is stopped.

You only need to configure a different transport mechanism when introducing a real message broker.
But you don't need to change your messaging code.

<Image
  src="blogs/mnw_056/modular_monolith_queue.png"
  width={978}
  height={597}
  alt="Modular monolith with a queue."
/>

What is the purpose of messaging inside a modular monolith?

Designing your system like this makes the modules loosely coupled and independent.
The price you pay in increased complexity at the start is justified as the project matures.

## Extracting Modules to Microservices

We decided to move from a monolith system to microservices.
Since we built our system in a modular way, the migration comes down to extracting a module into a new process.

You should introduce a [**reverse proxy**](implementing-an-api-gateway-for-microservices-with-yarp) in front of your services to route incoming traffic.
This will hide the implementation details of the microservices system from client applications.

The new microservice needs to connect to the message bus, but we don't need to change anything in our code.
Using messaging for communication between modules simplifies the migration process.
This might remind you of [event-driven architecture](https://go.particular.net/break-that-big-ball-of-mud).

If you implement inter-module communication using method calls, you must replace that implementation with HTTP calls over the network.
Because you're now building a distributed system, and the previous implementation using method calls will not work.
You also need to consider authentication, fault tolerance...

<Image
  src="blogs/mnw_056/extracting_modules.png"
  width={978}
  height={597}
  alt="Microservices with extracting modules."
/>

[**Extracting modules**](breaking-it-down-how-to-migrate-your-modular-monolith-to-microservices) from the monolith system leads to replacing all the functionalities of the old system with new microservices.
This process of migrating to microservices follows the [strangler fig pattern.](https://learn.microsoft.com/en-us/azure/architecture/patterns/strangler-fig)

## Closing Thoughts

The biggest blocker for moving from a monolith to microservices is coupling.
Coupling is a change preventer.
So, this is the first thing you need to tackle.

You need to solve coupling at the database level and between components in the code.
Building the system in a modular way can prevent these problems from the start.

Which is why a Modular monolith is an excellent approach.

You can identify bounded contexts in the system and use them as the boundaries in the monolith.
And getting the boundaries right is easier in a monolith.

[**Migrating to microservices**](breaking-it-down-how-to-migrate-your-modular-monolith-to-microservices) comes down to extracting the modules into individual services.

Of course, you still need to think about security and fault tolerance because you now have a distributed system.

Talking about architecture in abstract terms can be difficult to grasp, but it's important when discussing conceptual solutions.

I'll show you a practical Modular monolith implementation soon to complete the circle.

Until then, I hope this was valuable.

See you next week!

---



<Sponsorships>

[**Progress**](https://www.telerik.com/campaigns/blazor/ebook-blazor-hybrid?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-blazor-hybrid-ebook)
prepared a free eBook for you - [**Blazor Hybrid and Web in One Solution.**](https://www.telerik.com/campaigns/blazor/ebook-blazor-hybrid?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-blazor-hybrid-ebook)
Dive into Blazor cross-platform apps, potential roadblocks, testing with Razor components, and more.
[**Get the Blazor eBook here.**](https://www.telerik.com/campaigns/blazor/ebook-blazor-hybrid?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-blazor-hybrid-ebook)

[**IcePanel**](https://u.icepanel.io/1eec0e6f) is a collaborative C4 model modelling & diagramming tool that helps explain complex software systems.
With an interactive map, you can align your software engineering & product teams on technical decisions across the business.
[**Check it out here.**](https://u.icepanel.io/1eec0e6f)

</Sponsorships>

The ability to conditionally turn features on or off in your application without redeploying the code is a powerful tool.

It lets you quickly iterate on new features and frequently integrate your changes with the main branch.

You can use **feature flags** to achieve this.

**Feature flags** are a software development technique that allows you to wrap application features in a conditional statement.
You can then toggle the feature on or off in runtime to control which features are enabled.

We have a lot to cover in this week's newsletter:

- Feature flag fundamentals in .NET
- Feature filters and phased rollouts
- Trunk-based development
- A/B testing

Let's dive in!

## Feature Flags In .NET

[Feature flags](https://github.com/microsoft/FeatureManagement-Dotnet) provide a way for .NET and ASP.NET Core applications to turn features on or off dynamically.

To get started, you need to install the `Microsoft.FeatureManagement` library in your project:

```powershell
Install-Package Microsoft.FeatureManagement
```

This library will allow you to develop and expose application functionality based on features.
It's useful when you have special requirements when a new feature should be enabled and under what conditions.

The next step is to register the required services with dependency injection by calling `AddFeatureManagement`:

```csharp
builder.Services.AddFeatureManagement();
```

And you are ready to create your first feature flag.
Feature flags are built on top of the .NET configuration system.
Any .NET configuration provider can act as the backbone for exposing feature flags.

Let's create a feature flag called `ClipArticleContent` in our `appsettings.json` file:

```json
"FeatureManagement": {
  "ClipArticleContent": false
}
```

By convention, feature flags have to be defined in the `FeatureManagement` configuration section.
But you can change this by providing a different configuration section when calling `AddFeatureManagement`.

Microsoft recommends exposing feature flags using enums and then consuming them with the `nameof` operator.
For example, you would write `nameof(FeatureFlags.ClipArticleContent)`.

However, I prefer defining feature flags as constants in a static class because it simplifies the usage.

```csharp
// Using enums
public enum FeatureFlags
{
    ClipArticleContent = 1
}

// Using constants
public static class FeatureFlags
{
    public const string ClipArticleContent = "ClipArticleContent";
}
```

To check the feature flag state, you can use the `IFeatureManager` service.
In this example, if the `ClipArticleContent` feature flag is turned on, we will return only the first thirty characters of the article's content.

```csharp {8}
app.MapGet("articles/{id}", async (
    Guid id,
    IGetArticle query,
    IFeatureManager featureManager) =>
{
    var article = query.Execute(id);

    if (await featureManager.IsEnabledAsync(FeatureFlags.ClipArticleContent))
    {
        article.Content = article.Content.Substring(0, 50);
    }

    return Results.Ok(article);
});
```

You can also apply feature flags on a controller or endpoint level using the `FeatureGate` attribute:

```csharp
[FeatureGate(FeatureFlags.EnableArticlesApi)]
public class ArticlesController : Controller
{
   // ...
}
```

This covers the fundamentals of using feature flags, and now, let's tackle more advanced topics.

## Feature Filters And Phased Rollouts

The feature flags I showed you in the previous section were like a simple on-off switch.
Although practical, you might want more flexibility from your feature flags.

The `Microsoft.FeatureManagement` package comes with a few built-in feature filters that allow you to create dynamic rules for enabling feature flags.

The available feature filters are
[`Microsoft.Percentage`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.featuremanagement.featurefilters.percentagefilter?view=azure-dotnet),
[`Microsoft.TimeWindow`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.featuremanagement.featurefilters.timewindowfilter?view=azure-dotnet)
and [`Microsoft.Targeting`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.featuremanagement.featurefilters.targetingfilter?view=azure-dotnet).

Here's an example of defining a `ShowArticlePreview` feature flag that uses a percentage filter:

```json {3,6}
"FeatureFlags": {
  "ClipArticleContent": false,
  "ShowArticlePreview": {
    "EnabledFor": [
      {
        "Name": "Percentage",
        "Parameters": {
          "Value": 50
        }
      }
    ]
  }
}
```

This means the feature flag will be randomly turned on 50% of the time.
The downside is the same user might see different behavior on subsequent requests.
A more realistic scenario is to have the feature flag state be cached for the duration of the user's session.

To use the `PercentageFilter`, you need to enable it by calling `AddFeatureFilter`:

```csharp
builder.Services.AddFeatureManagement().AddFeatureFilter<PercentageFilter>();
```

Another interesting feature filter is the `TargetingFilter`, which allows you to target specific users.
Targeting is used in phased rollouts, where you want to introduce a new feature to your users gradually.
You start by enabling the feature for a small percentage of users and slowly increase the rollout percentage while monitoring how the system responds.

## Trunk-based Development and Feature Flags

[Trunk-based development](https://trunkbaseddevelopment.com/) is a Git branching strategy where all developers work in short-lived branches or directly in the trunk, the main codebase.
The _"trunk"_ is the main branch of your repository.
If you're using Git, it will be either the `main` or `master` branch.
Trunk-based development avoids the "merge hell" problem caused by long-lived branches.

So, how do feature flags fit into trunk-based development?

The only way to ensure the trunk is always releasable is to hide incomplete features behind feature flags.
You continue pushing changes to the trunk as you work on the feature while the feature flag remains turned off on the main branch.
When the feature is complete, you turn on the feature flag and release it to production.

<Image
  src="blogs/mnw_055/trunk_based_development.png"
  width={900}
  height={468}
  alt="Trunk based development."
/>

## How I Used Feature Flags for A/B Testing On My Website

A/B testing (split testing) is an experiment where two or more variants of a page (or feature) are shown randomly to users.
Statistical analysis is performed in the background to determine which variation performs better for a given conversion goal.

Here's an example A/B test I performed on my website:

<Image
  src="blogs/mnw_055/split_test.png"
  width={1400}
  height={1700}
  alt="Split test with two variants."
/>

The hypothesis was that removing the image and focusing on the benefits would make more people want to subscribe.
I measure this using the conversion rate, which is the number of people visiting the page divided by the number of people subscribing.

I'm using a platform called [Posthog](https://posthog.com) to run experiments, which automatically calculates the results.

You can see that the _test_ variant has a significantly higher conversion rate, so it becomes the winner of the A/B test.

<Image
  src="blogs/mnw_055/experiment_results.png"
  width={907}
  height={749}
  alt="Split test with two variants experiment results."
/>

## Takeaway

The ability to dynamically turn features on or off without deploying the code is like a superpower.
Feature flags give you this ability with very little work.

You can work with feature flags in .NET by installing the `Microsoft.FeatureManagement` library.
Feature flags build on top of the .NET configuration system, and you can check the feature flag state using the `IFeatureManager` service.

Another use case for feature flags is A/B testing.
I run weekly experiments on my website, testing changes that will improve my conversion rate.
Feature flags help me decide which version of the website to show to the user.
And then, I can measure results based on the user's actions.

I also made a video about [**feature flagging in .NET,**](https://youtu.be/QVEUgIC7Wpo) and you can watch it [**here**](https://youtu.be/QVEUgIC7Wpo) if you want to learn more.

Hope this was valuable.

Stay awesome!

---



<Sponsorships>

[**JetBrains .NET Day Online '23**](https://lp.jetbrains.com/dotnet-day-2023/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetday23)
is a free virtual event that will take place on September 26.
Ten amazing community speakers will share what they're passionate about in the .NET world.
Topics include C#, F#, Blazor, Avalonia, EF Core, xUnit, and more.
[**Register to save the date.**](https://lp.jetbrains.com/dotnet-day-2023/?utm_source=milan&utm_medium=newsletter&utm_campaign=dotnetday23)

Do you build complex software systems?
See how [**NServiceBus**](https://go.particular.net/milanjovanovic) makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling.
[**Get started for FREE.**](https://go.particular.net/milanjovanovic)

</Sponsorships>

How often do you think about concurrency conflicts when writing code?

You write the code for a new feature, confirm that it works, and call it a day.

But one week later, you find out you introduced a nasty bug because you didn't think about concurrency.

The most common issue is race conditions with two competing threads executing the same function.
If you don't consider this during development, you introduce the risk of leaving the system in a corrupted state.

In this week's newsletter, I'll challenge you to spot the race condition in a method for reserving a booking.
The business requirement is you can't have two overlapping reservations for the same dates.

And then, I'll show you how to solve this race condition using EF Core optimistic concurrency.

Let's dive in!

## What's Wrong With This Code?

There's a race condition hiding somewhere in this code snippet.

Can you see it?

```csharp {9,18}
public Result<Guid> Handle(
    ReserveBooking command,
    AppDbContext dbContext)
{
    var user = dbContext.Users.GetById(command.UserId);
    var apartment = dbContext.Apartments.GetById(command.ApartmentId);
    var (startDate, endDate) = command;

    if (dbContext.Bookings.IsOverlapping(apartment, startDate, endDate))
    {
        return Result.Failure<Guid>(BookingErrors.Overlap);
    }

    var booking = Booking.Reserve(apartment, user, startDate, endDate);

    dbContext.Add(booking);

    dbContext.SaveChanges();

    return booking.Id;
}
```

The call to `IsOverlapping` is an optimistic check to see if there's an existing booking for the specified dates.

```csharp
if (dbContext.Bookings.IsOverlapping(apartment, startDate, endDate)) { }
```

If it returns `true`, we're trying to double-book the apartment.
So we return a failure, and the method completes.

But if it returns `false`, we reserve a booking and call `SaveChanges` to persist the changes in the database.

And there lies the problem.

There's a chance for a concurrent request to pass the `IsOverlapping` check and attempt to reserve the booking.
Without any concurrency control, both requests will succeed, and we will end up with an inconsistent state in the database.

So how can we solve this?

## Optimistic Concurrency With EF Core

The pessimistic concurrency approach acquires a lock for the data before modifying it.
It's slower and causes competing transactions to be blocked until the lock is released.
EF Core doesn't support this approach out of the box.

You can also solve this problem using optimistic concurrency with EF Core.
It doesn't take any locks, but any data modifications will fail to save if the data has changed since it was queried.

To implement optimistic concurrency in EF Core, you need to configure a property as a _concurrency token_.
It's loaded and tracked with the entity.
When you call `SaveChanges`, EF Core will compare the value of the concurrency token to the value in the database.

Let's assume we're using SQL Server, which has a native [`rowversion`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/rowversion-transact-sql?view=sql-server-ver16) column.
The `rowversion` automatically changes when the row is updated, so it's a great option for a concurrency token.

To configure a `byte[]` property as a concurrency token you can decorate it with the `Timestamp` attribute.
It will be mapped to a `rowversion` column in SQL Server.

```csharp {5}
public class Apartment
{
    public Guid Id { get; set; }

    [Timestamp]
    public byte[] Version { get; set; }
}
```

I prefer a different approach because attributes pollute the entity.

You can do the same with the Fluent API.
I will even use a shadow property to hide the concurrency token from the entity class.

```csharp {4,5}
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Apartment>()
        .Property<byte[]>("Version")
        .IsRowVersion();
}
```

The exact configuration will differ based on the database you are using, so check the documentation.

## How Optimistic Concurrency Works In Practice

So here's what changes when we configure the concurrency token.

When loading the `Apartment` entity, EF will also load the concurrency token.

```sql
SELECT a.Id, a.Version
FROM Apartments a
WHERE a.Id = @p0
```

And when we call `SaveChanges`, the update statement will compare the concurrency token value with the one in the database:

```sql
UPDATE Apartments a
SET a.LastBookedOnUtc = @p0
WHERE a.Id = @p1 AND a.Version = @p2;
```

If the `rowversion` in the database changes, the number of updated rows will be `0`.

EF Core expects to update `1` row, so it will throw a `DbUpdateConcurrencyException`, which you need to handle.

## Handling Concurrency Exceptions

Now that you know how to use optimistic concurrency with EF Core, you can fix the previous code snippet.

If two concurrent requests pass the `IsOverlapping` check, only one can complete the `SaveChanges` call.
The other concurrent request will run into a `Version` mismatch in the database and throw a `DbUpdateConcurrencyException`.

In case of a concurrency conflict, we need to add a `try-catch` statement to catch the `DbUpdateConcurrencyException`.
How you handle the actual exception depends on your business requirements.
And sometimes, [race conditions](https://go.particular.net/milanjovanovic/raceconditions) might not even exist.

```csharp {24}
public Result<Guid> Handle(
    ReserveBooking command,
    AppDbContext dbContext)
{
    var user = dbContext.Users.GetById(command.UserId);
    var apartment = dbContext.Apartments.GetById(command.ApartmentId);
    var (startDate, endDate) = command;

    if (dbContext.Bookings.IsOverlapping(apartment, startDate, endDate))
    {
        return Result.Failure<Guid>(BookingErrors.Overlap);
    }

    try
    {
        var booking = Booking.Reserve(apartment, user, startDate, endDate);

        dbContext.Add(booking);

        dbContext.SaveChanges();

        return booking.Id;
    }
    catch (DbUpdateConcurrencyException)
    {
        return Result.Failure<Guid>(BookingErrors.Overlap);
    }
}
```

## When Should You Use Optimistic Concurrency?

Optimistic concurrency considers the best scenario is also the most probable one.
It assumes conflicts between transactions will be infrequent and doesn't acquire locks on the data.
This means your system can scale better because there is no blocking slowing down performance.

However, you must still expect concurrency conflicts and implement custom logic to handle them.

Optimistic concurrency is a good choice if your application doesn't expect many conflicts.

Another reason to use optimistic concurrency is when you can't hold an open connection to the database for the length of the transaction.
This is required for pessimistic locking.

Hope this was helpful.

I'll see you next week!

---



<Sponsorships>

[**How to Get Started with Telerik Blazor Data Grid:**](https://www.telerik.com/blogs/how-to-get-started-telerik-blazor-data-grid?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-content-exposure&utm_content=get-started-telerik-blazor-data-grid)
If there's one thing you're likely to find yourself doing in your Blazor web applications, it's working with data.
The simplest (and most common) way to do this is often via a table (or grid).
[**Learn how the Telerik UI for Blazor DataGrid**](https://www.telerik.com/blogs/how-to-get-started-telerik-blazor-data-grid?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-content-exposure&utm_content=get-started-telerik-blazor-data-grid)
can make working with data in your Blazor web applications much easier.

[**IcePanel**](https://u.icepanel.io/1eec0e6f) is a collaborative [**C4 model modelling & diagramming tool**](https://u.icepanel.io/1eec0e6f) that helps explain complex software systems.
With an interactive map, you can align your software engineering & product teams on technical decisions across the business.

</Sponsorships>

Modern software applications rarely work in isolation.
On the contrary, a typical application will talk to several external systems like databases, messaging systems, cache providers, and many 3rd party services.
And it's up to you to ensure everything functions correctly.

Hopefully, I don't have to convince you about the value of writing tests.

You should be writing tests.
Period.

However, I do want to discuss the _value_ of **integration testing**.

**Unit tests** are helpful to test business logic in isolation, without any external services.
They are easy to write and provide almost instant feedback.

But you can't be fully confident in your application without **integration tests**.

So, in this week's newsletter, I'll show you how to use **Docker** for integration testing.

Here's what we will use to write **integration tests**:

- **Testcontainers**
- Docker
- [**xUnit**](creating-data-driven-tests-with-xunit)

Let's dive in!

## What is Testcontainers?

[Testcontainers](https://dotnet.testcontainers.org/) is a library for writing tests with throwaway Docker containers.

Why should you use it?

Integration testing is considered "difficult" because you have to maintain testing infrastructure.
Before running tests, you need to make sure the database is up and running.
You also have to seed any data required for the tests.
If you have tests running in parallel on the same database, they could interfere with each other.

A possible solution could be using in-memory variations of the required services.
But this isn't much different from using mocks.
In-memory services might not have all the features of the production service.

Testcontainers solves this by using Docker to spin up real services for integration testing.

Here's an example of creating a **SQL Server** container:

```csharp
MsSqlContainer dbContainer = new MsSqlBuilder()
    .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
    .WithPassword("Strong_password_123!")
    .Build();
```

You can then use the `MsSqlContainer` instance to get a connection string for the database running inside the container.

Do you see how this is valuable for writing integration tests?

No more need for mocks or fake in-memory databases.
Instead, you can use the real deal.

I won't do a deep dive into this library here, so refer to the documentation for more information.

## Implementing a Custom WebApplicationFactory

**ASP.NET Core** provides an in-memory test server that we can use to spin up an application instance for running tests.
The `Microsoft.AspNetCore.Mvc.Testing` package provides the `WebApplicationFactory` class that we will use as the base for our implementation.

`WebApplicationFactory<TEntryPoint>` is used to create a `TestServer` for the integration tests.

The custom `IntegrationTestWebAppFactory` will do a few things:

- Create and configure a `MsSqlContainer` instance
- Call `ConfigureTestServices` to set up EF Core with the container database
- Start and stop the container instance with `IAsyncLifetime`

`MsSqlContainer` has a `GetConnectionString` method to grab the connection string for the current container.
Note that this can change between tests, as each test class will create a separate container instance.
Test cases inside the same test class will use the same container instance.
So keep that in mind if you need to do a cleanup between tests.

Another thing to keep in mind is **database migrations**.
You will have to run them manually before every test to create the required database structure.

Starting the container instance is done asynchronously using `IAsyncLifetime`.
The container is started inside `StartAsync` before any of the tests run.
And it's stopped inside `StopAsync`.

Here's the complete code for `IntegrationTestWebAppFactory`:

```csharp
public class IntegrationTestWebAppFactory
    : WebApplicationFactory<Program>,
      IAsyncLifetime
{
    private readonly MsSqlContainer _dbContainer = new MsSqlBuilder()
        .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
        .WithPassword("Strong_password_123!")
        .Build();

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureTestServices(services =>
        {
            var descriptorType =
                typeof(DbContextOptions<ApplicationDbContext>);

            var descriptor = services
                .SingleOrDefault(s => s.ServiceType == descriptorType);

            if (descriptor is not null)
            {
                services.Remove(descriptor);
            }

            services.AddDbContext<ApplicationDbContext>(options =>
                options.UseSqlServer(_dbContainer.GetConnectionString()));
        });
    }

    public Task InitializeAsync()
    {
        return _dbContainer.StartAsync();
    }

    public new Task DisposeAsync()
    {
        return _dbContainer.StopAsync();
    }
}
```

## Creating The Base Test Class

The base test class will implement a class fixture interface `IClassFixture`.
It indicates the class contains tests and provides shared object instances across the test cases inside.
This is a good place to instantiate any services that are required for most tests.

For example, I'm creating an `IServiceScope` for resolving scoped services inside the tests.

- `ISender` for sending commands and queries
- `ApplicationDbContext` for database setup or verifying results

```csharp
public abstract class BaseIntegrationTest
    : IClassFixture<IntegrationTestWebAppFactory>,
      IDisposable
{
    private readonly IServiceScope _scope;
    protected readonly ISender Sender;
    protected readonly ApplicationDbContext DbContext;

    protected BaseIntegrationTest(IntegrationTestWebAppFactory factory)
    {
        _scope = factory.Services.CreateScope();

        Sender = _scope.ServiceProvider.GetRequiredService<ISender>();

        DbContext = _scope.ServiceProvider
            .GetRequiredService<ApplicationDbContext>();
    }

    public void Dispose()
    {
        _scope?.Dispose();
        DbContext?.Dispose();
    }
}
```

With all the infrastructure in place, we're finally ready to write the tests.

## Putting It All Together - Writing Integration Tests

Here's a `ProductTests` class with an integration test inside.

I use the _Arrange-Act-Assert_ pattern to structure tests:

- _Arrange_ - create the `CreateProduct.Command` instance
- _Act_ - send the command using `ISender` and store the result
- _Assert_ - use the result from the _Act_ step to verify the database state

The value of writing integration tests like this is that you can use the complete **MediatR** request pipeline.
If you have any `IPipelineBehavior` wrapping the request, it will also be executed.

The same applies if you write your business logic inside service classes.
Instead of resolving the `ISender`, you would resolve the specific services you want to test.

Most importantly, this test uses a real database instance running inside a **Docker container**.

```csharp
public class ProductTests : BaseIntegrationTest
{
    public ProductTests(IntegrationTestWebAppFactory factory)
        : base(factory)
    {
    }

    [Fact]
    public async Task Create_ShouldCreateProduct()
    {
        // Arrange
        var command = new CreateProduct.Command
        {
            Name = "AMD Ryzen 7 7700X",
            Category = "CPU",
            Price = 223.99m
        };

        // Act
        var productId = await Sender.Send(command);

        // Assert
        var product = DbContext
            .Products
            .FirstOrDefault(p => p.Id == productId);

        Assert.NotNull(product);
    }
}
```

## Running Integration Tests In CI/CD Pipelines

You can also run integration tests with **Testcontainers** inside **CI/CD pipelines**.
The only requirement is that it supports Docker.

**GitHub Actions** does support Docker.
If you are hosting your project there, integration tests will work out of the box.

You can learn more about [**building a CI/CD pipeline with GitHub Actions here.**](how-to-build-ci-cd-pipeline-with-github-actions-and-dotnet)

And if you want a plug-in solution, here's a GitHub Actions workflow you can use:

```yaml
name: Run Tests 🚀

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  run-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '7.0.x'

      - name: Restore
        run: dotnet restore ./Products.Api.sln

      - name: Build
        run: dotnet build ./Products.Api.sln --no-restore

      - name: Test
        run: dotnet test ./Products.Api.sln --no-build
```

## Takeaway

**Testcontainers** is an excellent solution for writing **integration tests** with Docker.
You can spin up and configure any **Docker** image and use it from your application.
This is far better than using mocks or in-memory variations because they lack many features.

If you have a CI/CD pipeline that supports Docker, Testcontainers will work out of the box.

Only a few integration tests will drastically improve your confidence in the system.

You can grab the [**source code for this newsletter**](https://github.com/m-jovanovic/testcontainers-sample) on my GitHub.\
It's completely free, so what are you waiting for?

And if you prefer video, here's a quick tutorial on [**integration testing with Testcontainers.**](https://youtu.be/tj5ZCtvgXKY)

Hope this was valuable.

Stay awesome!

---



<Sponsorships>

This week's issue is sponsored by [**NServiceBus.**](https://go.particular.net/milanjovanovic)
Do you build complex software systems?
See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling.
[**Get started for FREE.**](https://go.particular.net/milanjovanovic)

And [**ReSharper,**](https://www.jetbrains.com/resharper/?utm_source=milan&utm_medium=newsletter&utm_campaign=resharper)
which is a productivity extension by JetBrains that makes Visual Studio a much better IDE.
Check out the [**ReSharper Essentials**](https://www.jetbrains.com/dotnet/guide/tutorials/resharper-essentials/?utm_source=milan&utm_medium=newsletter&utm_campaign=resharper)
video series to learn how to write better code faster by using on-the-fly code analysis,
automated solution-wide refactorings, and instant fixes to eliminate errors and code smells.

</Sponsorships>

More than 63%+ of organizations said in a [Dzone survey](https://dzone.com/articles/new-research-shows-63-percent-of-enterprises-are-a)
that they are adopting **Microservices** for some or all of their applications.

As more businesses adopt the use of Microservice architectures, we as developers have to become more skilled with Microservices communication.

Working with **distributed systems** is both fun and challenging at the same time.
One of those challenges is designing **effective communication** between services.

More centralization or less centralization?
More coupling or less coupling?
More control or less control?

These are only a few questions you need to answer.

In this week's newsletter, we will:

- Break down **Orchestration vs. Choreography**
- Understand key differences and **tradeoffs** between them
- Create a framework for deciding which approach to use

Let's dive in!

## What Are Microservices?

**Microservices** are a **software architecture** style where an application is built from small, autonomous services.
Each microservice serves a distinct purpose and can be independently deployed.

You probably already know this, so this is a quick refresher.

<Image src="blogs/mnw_052/microservices_hell.png" width={900} height={468} />

Here are the key tenets of Microservices:

- Independent development
- Deployment independence
- Technological freedom
- Scalability
- Resilience

A significant challenge is designing effective inter-service communication within this distributed environment.

Inside a Monolith system, communication happens through direct method calls.
This is a straightforward approach that works well when all components live within a single process.
However, this doesn't work with microservices.

## Orchestration - Command-driven Communication

**Orchestration** is a centralized approach to Microservices communication.
One of the services takes on the role of the **orchestrator** and coordinates the communication between services.

Orchestration uses **command-driven** communication.
The command communicates the intent of the action.
The sender wants something to happen, and the recipient doesn't need to know who sent the command.

An example of orchestration can be a [**Saga implemented with RabbitMQ.**](implementing-the-saga-pattern-with-rebus-and-rabbitmq)

<Image src="blogs/mnw_052/orchestration.png" width={1021} height={600} />

It has some nice **benefits**:

- Simple
- Centralized
- Ease of troubleshooting
- Monitoring is straightforward

**Orchestration** is typically **simpler** to implement and maintain than choreography.
Because there is a central coordinator, you can manage and monitor service interactions.
This, in turn, improves troubleshooting, as you know where to look when something goes wrong.

The **drawbacks** of orchestration are:

- Tight coupling
- Single point of failure
- Difficulty adding, removing, or replacing microservices

## Choreography - Event-driven Communication

**Choreography** is a **decentralized** communication approach.
Choreography uses **event-driven** communication - as opposed to orchestration, which uses commands.

An **event** is something that has happened in the past and is a fact.
The sender does not know who will handle the event or what will happen after processing it.

I talked about events in-depth in the newsletter about [**publishing domain events.**](how-to-use-domain-events-to-build-loosely-coupled-systems)

<Image src="blogs/mnw_052/choreography.png" width={1021} height={600} />

The most important **benefits** of choreography are:

- Loose coupling
- Ease of maintenance
- Decentralized control
- Asynchronous communication

**Choreography** allows microservices to be **loosely coupled**, which means they can operate independently and asynchronously.
This makes the system more scalable and resilient.
A failure of one microservice won't necessarily affect microservices.

Of course, there are **downsides** to choreography:

- Complexity
- Monitoring is difficult
- Difficulty troubleshooting

It's more complex to implement and maintain than orchestration.

Effective monitoring is the biggest challenge from my experience.

## The Crossroads: Which One Should You Choose?

So, how do you know which one to pick for your system?

I always start with the requirements of the system I'm building.
And then, I look at the pros and cons of orchestration vs. choreography.
Here's a small framework to help you decide.

**Orchestration** excels when:

- You need to wait for the completion of intermediate steps (such as credit card payment confirmation)
- You need to make a conditional choice of subsequent steps
- The process must be carried out atomically (entirely or not at all)
- The process needs to be centralized in one place for monitoring

This also means you will need a central database managed by the orchestrator to handle all workflow-related state.

**Choreography** works best when:

- The process can rely on the input message without needing additional context
- Steps clearly follow one another
- Progress is made in one direction

You can benefit from increased flexibility (such as modifying individual steps in isolation)
Unfortunately, choreography can make it difficult to trace, debug, or monitor the processes triggered by an event.
And the larger the event stream is, the more challenging it becomes.

So, think carefully before opting for orchestration or choreography.

Both approaches bring their advantages but also downsides.

## Takeaway

**Orchestration** defines a sequence of steps that each microservice must follow.
This is great for identifying and addressing complex service interdependencies.
Another benefit is that business logic can be managed and monitored in one place.

**Choreography**, on the other hand, is a decentralized technique for microservices communication.
Each service can operate independently while still being part of the larger architecture.

To decide which approach to use, you should observe your system and identify what you stand to gain or lose.
Everything is a tradeoff.

There's also an **alternative approach** I want to mention.

You could go for a **hybrid approach** that integrates orchestration and choreography.

In a **hybrid approach**, you decide which communication technique to use for a specific workflow.
Some workflows can benefit from orchestration, and others can benefit more from choreography.

Hope this was helpful.

I'll see you next week!

---


Previous issues of The .NET Weekly