
<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>

[**EF Core is too slow?**](https://entityframework-extensions.net/?utm_source=milanjovanovic&utm_medium=newsletter)
Discover how you can easily insert 14x faster (reducing saving time by 94%).
Boost your performance with our method integrated within EF Core: Bulk Insert, update, delete, and merge.
Join 5,000+ satisfied customers who have trusted our library since 2014.
[**Click here to learn more**](https://entityframework-extensions.net/?utm_source=milanjovanovic&utm_medium=newsletter).

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!

---



<Sponsorships>

[**Treblle**](https://www.treblle.com/?utm_source=MailInf&utm_medium=Milan) is a lightweight SDK that helps engineering and product teams build,
ship & maintain REST-based APIs faster.
Simple integration for all popular languages & frameworks, including .NET 6.
[**Check it out here.**](https://www.treblle.com/?utm_source=MailInf&utm_medium=Milan)

[**ABP Commercial**](https://commercial.abp.io/?utm_source=milanw&utm_medium=w51) is a complete web development platform built on ABP Framework, perfect for enterprise-grade ASP.NET Core based web applications.
Pre-built application modules, advanced startup templates, rapid application development tooling, professional UI themes and premium support.
[**Get instant access here.**](https://commercial.abp.io/?utm_source=milanw&utm_medium=w51)

</Sponsorships>

**Rate limiting** is about restricting the number of requests to your application.
It's usually applied within a specific time window or based on other criteria.

It's helpful for a few reasons:

- Improves security
- Guards against DDoS attacks
- Prevents overloading of application servers
- Reduces costs by preventing unnecessary resource consumption

**.NET 7** shipped with a **built-in rate limiter**, but you need to know how to implement it correctly.
Or you could grind your system to a halt - and we don't want that.

In this week's newsletter, I'll teach you:

- How to rate limit users by **IP address**
- How to rate limit users by their **identity**
- How to apply **rate limiting** on the **reverse proxy**

So let's dive in!

## Built-In Rate Limiting In .NET 7

Starting with .NET 7, we have access to built-in **rate limiting middleware** in the `Microsoft.AspNetCore.RateLimiting` namespace.
The API is straightforward, and you can create a rate limit policy with a few lines of code.

We can use one of the four **rate limiting algorithms**:

- Fixed window
- Sliding window
- Token bucket
- Concurrency

Here's how to define a **rate limit policy** by calling the `AddTokenBucketLimiter` method:

```csharp
builder.Services.AddRateLimiter(rateLimiterOptions =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;

    rateLimiterOptions.AddTokenBucketLimiter("token", options =>
    {
        options.TokenLimit = 1000;
        options.ReplenishmentPeriod = TimeSpan.FromHours(1);
        options.TokensPerPeriod = 700;
        options.AutoReplenishment = true;
    });
});
```

Now you can reference the `token` rate limit policy on your endpoint or controller.

You also have to add the `RateLimitingMiddleware` to the request pipeline:

```csharp
app.UseRateLimiter();
```

You can learn more about [**rate limiting in .NET 7 here,**](how-to-use-rate-limiting-in-aspnet-core) so I won't go deeper into the fundamentals.

## Rate Limiting Users By IP Address

The approach I just showed you has a **problem** - the **rate limit policy** is global and **applies to all users**.

Most of the time, you don't want to do this.
Rate limiting should be granular and apply to **individual users**.

Luckily, you can achieve this by creating a `RateLimitPartition`.

The `RateLimitPartition` has two components:

- Partition key
- Rate limiter policy

Here's how to define a rate limiter with a fixed window policy, and the **partition key** is the user's **IP address**.

```csharp {5}
builder.Services.AddRateLimiter(options =>
{
    options.AddPolicy("fixed-by-ip", httpContext =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: httpContext.Connection.RemoteIpAddress?.ToString(),
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = 10,
                Window = TimeSpan.FromMinutes(1)
            }));
});
```

Rate limiting by **IP address** can be a good layer of security for **unauthenticated users**.
You don't know who is accessing your system and can't apply more granular rate limiting.
This can help protect your system from malicious users trying to perform a DDoS attack.

You can also [**create chained limiters**](https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit?view=aspnetcore-7.0#create-chained-limiters) using the `CreateChained` API.
It allows you to pass in multiple `PartitionedRateLimiter`, which are combined into one `PartitionedRateLimiter`.
The chained limiter runs all the input limiters in sequence (one by one).

If your application is running behind a **reverse proxy**, you need to make sure not to rate limit the proxy IP address.
Reverse proxies usually **forward** the original IP address with the `X-Forwarded-For` header.
So you can use it as the **partition key**:

```csharp {5}
builder.Services.AddRateLimiter(options =>
{
    options.AddPolicy("fixed-by-ip", httpContext =>
        RateLimitPartition.GetFixedWindowLimiter(
            httpContext.Request.Headers["X-Forwarded-For"].ToString(),
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = 10,
                Window = TimeSpan.FromMinutes(1)
            }));
});
```

## Rate Limiting Users By Identity

If you require users to **authenticate** with your API, you can determine who the current is.
Then you can use the user's **identity** as the **partition key** for a `RateLimitPartition`.

Here's how you would create such a rate limit policy:

```csharp {5}
builder.Services.AddRateLimiter(options =>
{
    options.AddPolicy("fixed-by-user", httpContext =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: httpContext.User.Identity?.Name?.ToString(),
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = 10,
                Window = TimeSpan.FromMinutes(1)
            }));
});
```

I'm using the `User.Identity` value on the `HttpContext` to get the current user's `Name` claim.
This usually corresponds to the `sub` claim inside a JWT - which is the user identifier.

## Applying Rate Limting On The Reverse Proxy

In a robust implementation, you want to **rate limit** on the **reverse proxy** level before the request hits your API.
And if you have a distributed system, this is a requirement.
Otherwise, your system wouldn't function correctly.

There are many reverse proxy implementations to choose from.

**YARP** is a reverse proxy with excellent .NET integration.
Not surprising since it was written in C#.
You can learn more about [**building an API Gateway with YARP here.**](implementing-an-api-gateway-for-microservices-with-yarp)

To implement rate limiting on the reverse proxy with **YARP** you need to:

- Define a rate limit policy (covered in previous examples)
- Configure the `RateLimiterPolicy` for the route in YARP settings

```json
"products-route": {
  "ClusterId": "products-cluster",
  "RateLimiterPolicy": "sixty-per-minute-fixed",
  "Match": {
    "Path": "/products/{**catch-all}"
  },
  "Transforms": [
    { "PathPattern": "{**catch-all}" }
  ]
}
```

The built-in rate limiter middleware uses an **in-memory** store to track the number of requests.
If you want to run your reverse proxy in a high-availability setup, you will need to use a **distributed cache**.
A nice option to look into is using a [**Redis backplane for rate limiting.**](https://github.com/cristipufu/aspnetcore-redis-rate-limiting)

## Closing Thoughts

With the `PartitionedRateLimiter` you can easily create granular rate limit policies.

The two common approaches are:

- Rate limiting by **IP address**
- Rate limiting by the **user identifier**

I was really excited to see the .NET team ship rate limiting.
But, the current implementation has its shortcomings.
The main issue is that it only works **in memory**.
For a **distributed** solution, you need to implement something yourself or use an external library.

You can use the **YARP** reverse proxy to build robust and scalable distributed systems.
And it only takes a few lines of code to add **rate limiting** on the reverse proxy level.
I'm using it extensively in my systems.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**Optimize SQL write operations**](https://dapper-plus.net/?utm_source=milanjovanovic&utm_medium=newsletter) for speed, scale, and minimal server load.
Insert and update your data up to 75x faster — and reduce save time by 99% compared to Dapper.
Discover [**Dapper Plus**](https://dapper-plus.net/?utm_source=milanjovanovic&utm_medium=newsletter) — Bulk Insert, Update, Delete & Merge.

[**JetBrains Rider**](https://www.jetbrains.com/rider/?utm_source=milan&utm_medium=newsletter&utm_campaign=rider)
is a fast and powerful cross-platform .NET IDE that helps you develop ASP.NET Core and
.NET desktop apps, services, libraries, Unity and Unreal Engine games, Xamarin and MAUI apps, and more.
Watch the [**Rider Essentials**](https://www.jetbrains.com/dotnet/guide/tutorials/rider-essentials/?utm_source=milan&utm_medium=newsletter&utm_campaign=rider)
video series with tips and tricks to get more out of the IDE.

</Sponsorships>

**Dapper** is a lightweight **object-relational mapper** in .NET.
It's popular because it's easy to use and fast at the same time.

Dapper extends the `IDbConnection` interface with methods for sending SQL queries to the database.

But, because of the nature of SQL, mapping the result into an object model can be tricky.

So in this week's newsletter, I'll teach you how to map:

- Simple queries
- One-to-one relationships
- One-to-many relationships
- Many-to-many relationships

Let's dive in!

## Simple Mapping

Let's first see how to do a **simple mapping** using Dapper.

Writing a query with Dapper has three parts:

- Creating an `IDbConnection` instance
- Writing the SQL query
- Calling a method that Dapper exposes

We will write a SQL query to load a set of `LineItem` objects for a specific `Order`.

```csharp
public class LineItem
{
    public long LineItemId { get; init; }

    public long OrderId { get; init; }

    public decimal Price { get; init; }

    public string Currency { get; init; }

    public decimal Quantity { get; init; }
}
```

Here's the SQL query returning the result we need:

```sql
SELECT Id AS LineItemId, OrderId, Price, Currency, Quantity
FROM LineItems
WHERE OrderId = @OrderId
```

I'm parameterizing the `Order` identifier using the `@OrderId` syntax.
This is a Dapper convention.
It's important that you use **parameterized queries** to **avoid SQL injection attacks**.

The mapping is straightforward in this case because we are only returning one type from the database.

We call the `QueryAsync` method and specify `LineItem` as the return type.
Make sure to pass in the arguments for this method, the SQL query, and the `OrderId` parameter.
I prefer creating anonymous objects for Dapper parameters.

```csharp
using var connection = new SqlConnection();

var lineItems = await connection.QueryAsync<LineItem>(
    sql,
    new { OrderId = orderId });
```

That's everything you need for a simple mapping.

## Dapper One To One Relationship Mapping

What if the object we want to return from the SQL query contains a **nested object**?

Here's an updated `LineItem` type that also contains a `Product` inside.

```csharp
public class LineItem
{
    public long LineItemId { get; init; }

    public long OrderId { get; init; }

    public decimal Price { get; init; }

    public string Currency { get; init; }

    public decimal Quantity { get; init; }

    public Product Product { get; init; }
}

public class Product
{
    public long ProductId { get; init; }

    public string Name { get; init; }
}
```

Now you need to return two types in the same query.

Here's the updated SQL query with a join on the `Products` table:

```sql
SELECT li.Id AS LineItemId, li.OrderId, li.Price, li.Currency, li.Quantity,
       p.Id AS ProductId, p.Name
FROM LineItems li
JOIN Products p ON p.Id = li.ProductId
WHERE li.OrderId = @OrderId
```

This query is more complicated because we need to use Dapper's **multi-mapping** feature.

In the `QueryAsync` method, we specify both `LineItem` and `Product` as return types and `LineItem` as the final return type for the method.

We must also tell Dapper how to map the `LineItem` and `Product` from the result set into a single `LineItem` object.

And we need to specify the `splitOn` argument, which tells Dapper where one object ends and the next begins.

```csharp
using var connection = new SqlConnection();

var lineItems = await connection.QueryAsync<LineItem, Product, LineItem>(
    sql,
    (lineItem, product) =>
    {
        lineItem.Product = product;

        return lineItem;
    },
    new { OrderId = orderId },
    splitOn: "ProductId");
```

We write more code to make this work, but it should be easy to wrap your head around it.

## Dapper One To Many Relationship Mapping

Another frequent situation is mapping a **one-to-many relationship** from SQL into an object model.

Because you are joining two tables, the result set will contain duplicate data on the "one" side of the relationship.

For this example, let's use an `Order` with a list of `LineItem` objects.

```csharp
public class Order
{
    public long OrderId { get; init; }

    public List<LineItem> LineItems { get; init; } = new();
}

public class LineItem
{
    public long LineItemId { get; init; }

    public long OrderId { get; init; }

    public decimal Price { get; init; }

    public string Currency { get; init; }

    public decimal Quantity { get; init; }
}
```

Here's the SQL query returning the data we need from the database:

```sql
SELECT o.Id AS OrderId,
       li.Id AS LineItemId, li.OrderId, li.Price, li.Currency, li.Quantity
FROM Orders o
JOIN LineItems li ON li.OrderId = o.Id
WHERE o.Id = @OrderId
```

We're going to get back duplicate `Order` data because of the `JOIN`.
But we only want to return one `Order` with all the line items.

The Dapper mapping function only gives us the `Order` and `LineItem` for the current row in the result set.

One way to solve this is to use a `Dictionary` to store the `Order` and reuse it inside the mapping.

- Store the `Order` in the dictionary if it's not there
- If it is there, add the `LineItem` to the existing `Order` instance

```csharp
using var connection = new SqlConnection();

var ordersDictionary = new Dictionary<long, Order>();

await connection.QueryAsync<Order, LineItem, Order>(
    sql,
    (order, lineItem) =>
    {
        if (ordersDictionary.TryGetValue(order.OrderId, out var existingOrder))
        {
            order = existingOrder;
        }
        else
        {
            ordersDictionary.Add(order.OrderId, order);
        }

        order.LineItems.Add(lineItem);

        return order;
    },
    new { OrderId = orderId },
    splitOn: "LineItemId");

var mappedOrder = ordersDictionary[orderId];
```

A **many-to-many relationship** would use the same idea, except you'll need two dictionaries for each side of the relationship.

## In Summary

**Dapper** is a fantastic library for writing fast database queries using SQL.

Because of how SQL works, mapping into an object model is sometimes complicated.

There are four common scenarios:

- Simple mapping - a flat structure mapped directly from SQL to an object
- One-to-one mapping - provide a mapping function to connect two objects
- One-to-many mapping - manage a dictionary for the "one" side of the relationship
- Many-to-many mapping - same as above, except you need a dictionary for both sides of the relationship

Now you have a cheat sheet for mapping relationships with Dapper.

Hope this was helpful.

I'll see you next week!

---



<Sponsorships>

[**Workshop: How to migrate a legacy app to Blazor:**](https://www.telerik.com/campaigns/blazor-workshop-migration?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-workshop-mnm-na-awareness)
Join Ed Charbeneau for a live application-building workshop, where you'll migrate an existing .NET Web Forms application to Blazor in real time.
Learn how to avoid potential roadblocks and master the basic concepts behind .NET 7 and Blazor.
[**Join the workshop here.**](https://www.telerik.com/campaigns/blazor-workshop-migration?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-workshop-mnm-na-awareness)

[**Treblle**](https://www.treblle.com/?utm_source=MailInf&utm_medium=Milan) is a lightweight SDK that helps engineering and product teams build, ship & maintain REST-based APIs faster.
Simple integration for all popular languages & frameworks, including .NET 6.
[**Check it out here.**](https://www.treblle.com/?utm_source=MailInf&utm_medium=Milan)

</Sponsorships>

**Modular monoliths** are becoming more popular in the software engineering community.

The allure of **Microservices** is becoming less compelling.
We also have seasoned veterans of our industry saying you should reconsider:

> You shouldn't start a new project with microservices, even if you're sure your application will be big enough to make it worthwhile.

_&mdash; [Martin Fowler](https://martinfowler.com/bliki/MonolithFirst.html)_

Modular monoliths give you the **logical architecture** of Microservices without the operational complexity.
You can safely determine the boundaries between modules.
And refactoring is straightforward and less risky.
They can also be easily migrated into Microservices if you decide to do so.

I've built and maintained several large **Modular monolith** systems in the past years.

In this week's newsletter, I want to focus on the **communication patterns** in the Modular monolith architecture.

But first, let me explain what is a **Modular monolith**.

## What Is a Modular Monolith?

Here's one definition of what a **Modular monolith** is:

> A Modular Monolith is a software design approach in which a monolith is designed with an emphasis on interchangeable (and potentially reusable) modules.

The problem with most monolith systems is that they become **tightly coupled** over time.
Components are deeply intertwined.
Making a change in one component impacts many others.
Introducing new features is difficult and error-prone.

Modular monoliths aim to solve these problems.

<Image
  src="blogs/mnw_049/modular_monolith_diagram.png"
  width={3876}
  height={1880}
/>

A Modular monolith consists of many **loosely coupled** modules.
Modules represent cohesive sets of functionalities.
Modules are also **independent** of each other.

Here are a few examples:

- Payments module
- Shipping module
- Booking module
- Reviews module

If this concept reminds you of Microservices, that's because it should.

Microservices represent self-contained services encapsulating a set of functionalities of the larger system, much like modules in a Modular monolith.

For a Modular monolith to be loosely coupled, you need to solve how modules will communicate.

Modules cannot reference each other directly except through their public APIs.

There are two widely used communication patterns.
Both have pros and cons and a set of tradeoffs that you need to understand.

## Synchronous Communication With Method Calls

The first and easiest communication pattern is simple **method calls** between modules.
Method calls are **synchronous** and very fast because they're in memory.

Module A calls a method declared on the **public API** of Module B and waits until it receives a result.

Each module exposes a **public API**, which can be an `interface` in .NET.

The module will implement this interface internally and hide any implementation details.
You can use the `internal` keyword to make the implementation inaccessible outside the module.

Modules depend on the interfaces at compile-time.
At runtime, **dependency injection** will provide the respective implementation.

<Image
  src="blogs/mnw_049/modular_monolith_sync_communication.png"
  width={3220}
  height={1192}
/>

The benefits of this approach are:

- Speed of in-memory calls
- Easy to implement
- No indirection

But, the drawback of this approach is **strong coupling**.

**Synchronous communication** means that the modules will be tightly coupled.
If one of the modules is unavailable, it will affect any dependent modules.
You can introduce a retry mechanism, but this only goes so far.

## Asynchronous Communication With Messaging

The second communication pattern is asynchronous **messaging** between modules.

Module A sends a message to the message broker in a fire-and-forget fashion.
Module B subscribes to relevant messages and handles them accordingly.

Modules don't need to know about each other, but they do need to know about the message contracts.

**Message contracts** are the **public API** of a module in this scenario.

<Image
  src="blogs/mnw_049/modular_monolith_async_communication.png"
  width={5384}
  height={1569}
/>

The benefits of this approach are:

- High availability
- Loose coupling

**Asynchronous communication** gives us loose coupling because modules communicate using messages.
Module B doesn't need to be available for Module A to send a message.

The obvious drawback of this approach is **increased complexity**.

We're introducing a **message broker** to the system.
This is another infrastructure component we have to manage.
It's also a single point of failure.
If the message broker fails, so does communication between the modules.

You can prevent message loss by storing messages in an [**Outbox**](outbox-pattern-for-reliable-microservices-messaging) before publishing them.
We can always send the messages again from the database in case of a message broker failure.

## Takeaway

**Synchronous communication** between modules is easy to implement, and it's performant. But it comes at the cost of tight coupling between modules.

**Asynchronous communication** using a message broker is loosely coupled. But it's more complex to implement.

So which **communication pattern** should you be using?

It depends.

Asynchronous communication can help you build **loosely coupled** and **independent** modules.
Migrating a **Modular monolith** using messaging into a **distributed system** is much easier.

You extract a module into its own deployment unit.
And the communication between modules remains the same.
Because you are using messaging, you don't need to reimplement anything.

**Synchronous method calls** are an excellent choice to increase development velocity and reduce operational complexity.

I'll let the software architect in you decide.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**Software Design Simplified .NET Edition**](https://softwaredesignsimplified.com/?utm_source=newsletter&utm_medium=email&utm_campaign=dotnet-newsletter-29-07-2023)
is a short and practical book for junior and mid-level engineers.
You will learn encapsulation, cohesion, polymorphism, and more in one afternoon.
[**Check it out here.**](https://softwaredesignsimplified.com/?utm_source=newsletter&utm_medium=email&utm_campaign=dotnet-newsletter-29-07-2023)

[**IcePanel**](https://u.icepanel.io/1eec0e6f) realigns your engineering & product teammates on the technical decisions made across the business.
[**Explain your complex software systems**](https://u.icepanel.io/1eec0e6f) with an interactive map that teammates can drill down to the level of detail they need.

</Sponsorships>

I've been using **Clean Architecture** for 6+ years on large-scale applications serving thousands of customers and millions of requests.
Today I want to talk about why it's a great approach for structuring your applications.

I'm aware that Clean Architecture isn't a silver bullet, so I will discuss what types of systems can benefit from this architecture.

Clean architecture isn't revolutionary.

But it's **prescriptive** about how you should structure the code.

It's an evolution of layered architecture, focusing on the core domain and the direction of dependencies.
All dependencies should point inwards, applying **dependency inversion**.

Here are some of the promises of Clean Architecture:

- Maintainability
- Testability
- Loose coupling
- Separation of concerns

It's **independent** of UI, databases, or external services - but you also need to be **pragmatic** (more on this later).

Let's dive in!

## What Is Clean Architecture?

Clean Architecture was created by [**Robert C. Martin**](https://en.wikipedia.org/wiki/Robert_C._Martin), aka Uncle Bob.

Clean Architecture is an approach to organizing a software system to **separate the concerns** of the various components.
Making the system easier to understand and maintain.

You can think about Clean Architecture as a domain-centric approach to organizing dependencies.

There are similar architectures that follow the same domain-centric idea.
You may know them as the Hexagonal and Onion architectures.
They are more or less interchangeable with each other.
And they all place the core domain at the center of the architecture.

This is my high-level interpretation of **Clean Architecture**:

<Image src="blogs/mnw_048/clean_architecture.png" width={3268} height={2006} />

There are four layers inside:

- Domain
- Application
- Infrastructure
- Presentation

Let's see what should live inside each layer.

## Clean Architecture Layers

Here's a breakdown of what should live inside each **layer** of the **Clean Architecture**.

**Domain**

- Contains the core business rules & logic
- It should be independent of other layers in the system
- Should be persistence ignorant - the persistence mechanism shouldn't influence your domain model
- **Examples:** Entities, Value Objects, Domain services, Domain events, Enums, Repository interfaces

**Application**

- Contains the application use cases
- Contains application-specific business rules
- Orchestrates the domain entities to perform business operations
- It should be independent of external concerns (but it doesn't have to be)
- **Examples:** Application services, Commands, Queries, External service interfaces, Exceptions

**Infrastructure**

- Contains anything related to external concerns
- Implements interfaces defined in the layers below
- **Examples:** PostgreSQL, Keycloak, AWS S3, RabbitMQ, Kafka, SendGrid

**Presentation**

- Represents the entry point to the system
- Accepts data from the outside and passes it to the use cases
- Acts as the composition root for dependency injection
- **Examples:** ASP.NET Core, gRPC

[**Here's an example**](clean-architecture-folder-structure) of how to structure the Clean Architecture on a solution level.
You can also group related components together by feature.
It leads to better cohesion and is an excellent option if your project is more complex.

I also made a few videos covering the Clean Architecture project setup:

- [**Clean Architecture walkthrough**](https://youtu.be/tLk4pZZtiDY) (100k+ views)
- [**Clean Architecture project setup from scratch**](https://youtu.be/fe4iuaoxGbA) (40k+ views)

## Where Should You Use Clean Architecture?

**Clean Architecture** is very versatile and applies to various domains and systems.

But, you should play to its strengths and use it only when there's a tangible benefit.

I use the **Clean Architecture** when I want to:

- Apply Domain-Driven Design
- Solve complex business logic
- Build highly testable projects
- Enforce design policies via the architecture

If the above is true for your project, then Clean Architecture is an excellent option.

You should also consider the [**benefits of Clean Architecture.**](clean-architecture-and-the-benefits-of-structured-software-design)

## The Case For Being Pragmatic

I try to be **pragmatic** when using **Clean Architecture**.

Applying what I like and having the freedom of "breaking" Clean Architecture if it will simplify things.

Can this be called Clean Architecture, then?
No, not in the purest sense.

But, I still get **most** of the **benefits** of Clean Architecture.

Here's an example, when I'm applying CQRS in Clean Architecture to implement the use cases.

On the command (write) side, it's valuable to be independent of external concerns, so I will use repositories behind an interface.
I can control the repository contract, and unit testing is straightforward.

But, on the query (read) side, I want to return the response as fast as possible.
Creating an abstraction only adds indirection and reduces performance.

A better approach is to use the EF or Dapper in the handler and query the database.
It's simple, fast, and you can use all the features offered by the ORM.
You don't need a lot of complexity or abstractions on the query side.

I should call this approach [**Pragmatic Clean Architecture**.](/pragmatic-clean-architecture)

## Closing Thoughts

**Clean Architecture** gives you a **standard** for organizing your solution.

You don't have to reinvent the wheel every time at the start of the project.

But, the layered structure and architectural constraints can increase the **complexity** of smaller projects.\
So make sure your project is complex enough to apply Clean Architecture.

Another **caveat** of Clean Architecture is the danger of **over-engineering**.

Don't follow the principles religiously without considering the specific project requirements.\
The overhead of maintaining so many layers and abstractions may not be justified.

Be **pragmatic** and try to make the best decision possible.

Sometimes that means straying from the paradigm.

Hope this was helpful.

I'll see you next week!

---



<Sponsorships>

Today's issue is sponsored by [**Pluralsight.**](https://www.linkedin.com/feed/update/urn:li:activity:7079820953911771137/)
Pluralsight's [**2023 State of Cloud report**](https://www.linkedin.com/feed/update/urn:li:activity:7079820953911771137/) comes with some surprising findings.
Did you know 70% of organizations have more than half of their infrastructure in the cloud?
Or that 44% of organizations adopt the latest cloud products as soon as they're available?
Find out where you stand in the industry - and [**how to get ahead.**](https://www.linkedin.com/feed/update/urn:li:activity:7079820953911771137/)

And by [**ABP Commercial.**](https://commercial.abp.io/?utm_source=milanw&utm_medium=w47&utm_campaign=newsletter-sponsorship)
ABP Commercial is a complete [**web development platform built on ABP Framework**](https://commercial.abp.io/?utm_source=milanw&utm_medium=w47&utm_campaign=newsletter-sponsorship),
perfect for enterprise-grade ASP.NET Core based web applications.
Pre-built application modules, advanced startup templates, rapid application development tooling, professional UI themes and premium support.

</Sponsorships>

In software engineering, "coupling" means how much different parts of a software system depend on each other.
If they are **tightly coupled**, changes to one part can affect many others.
But if they are **loosely coupled**, changes to one part won't cause big problems in the rest of the system.

**Domain events** are a **Domain-Driven Design (DDD)** tactical pattern that we can use to build **loosely coupled** systems.

You can raise a **domain event** from the domain, which represents a fact that has occurred.
And other components in the system can subscribe to this event and handle it accordingly.

Here's what you will learn in this week's newsletter:

- What are [domain events](#what-are-domain-events)
- How they're [different from integration events](#domain-events-versus-integration-events)
- How to [implement](#implementing-domain-events) & [raise domain events](#raising-domain-events)
- How to [publish domain events](#how-to-publish-domain-events-with-ef-core) with EF Core
- How to [handle domain events](#how-to-handle-domain-events) with MediatR

We have a lot to cover, so let's dive in!

## What Are Domain Events?

An **event** is something that has happened in the past.

It is a fact.

Unchangeable.

A **domain event** is something that happened in the domain, and other parts of the domain should be aware of it.

**Domain events** allow you to express side effects explicitly, and provide a better separation of concerns in the domain.
They're an ideal way to trigger side effects across multiple aggregates inside the domain.

It's your responsibility to ensure that publishing a **domain event** is transactional.
You'll see why this is easier said than done.

<Image src="blogs/mnw_047/domain_events.png" width={2704} height={1515} />

## Domain Events Versus Integration Events

You may have heard of **integration events**, and you're now wondering what's the difference between them and **domain events**.

Semantically, they're the same thing: a representation of something that occurred in the past.

However, their **intent is different** and this is important to understand.

Domain events:

- Published and consumed within a single domain
- Sent using an in-memory message bus
- Can be processed synchronously or asynchronously

Integration events:

- Consumed by other subsystems (microservices, Bounded Contexts)
- Sent with a message broker over a queue
- Processed completely asynchronously

So if you're wondering what type of event you should publish, think about the intent and who should be handling the event.

**Domain events** can also be used to **generate integration events**, which leave the domain boundary.

## Implementing Domain Events

My preferred approach to implement **domain events** is creating an `IDomainEvent` abstraction and implementing MediatR `INotification`.

The benefit is you can use **MediatR's publish-subscribe** support to publish a notification to one or multiple handlers.

```csharp
using MediatR;

public interface IDomainEvent : INotification
{
}
```

Now you can implement a concrete domain event.

Here are a few **constraints** to consider when **designing domain events**:

- Immutability - domain events are facts, and should be immutable
- Fat vs Thin domain events - how much information do you need?
- Use past tense for event naming

```csharp
public class CourseCompletedDomainEvent : IDomainEvent
{
    public Guid CourseId { get; init; }
}
```

## Raising Domain Events

After you create your domain events, you want to raise them from the domain.

My approach is creating an `Entity` base class, because only entities are allowed to raise domain events.
You can further encapsulate raising domain events by making the `RaiseDomainEvent` method `protected`.

We're storing domain events in an internal collection, to prevent anyone else from accessing it.
The `GetDomainEvents` method is there to get a snapshot of the collection, and the `ClearDomainEvents` method to clear the internal collection.

```csharp
public abstract class Entity : IEntity
{
    private readonly List<IDomainEvent> _domainEvents = new();

    public IReadOnlyList<IDomainEvent> GetDomainEvents()
    {
        return _domainEvents.ToList();
    }

    public void ClearDomainEvents()
    {
        _domainEvents.Clear();
    }

    protected void RaiseDomainEvent(IDomainEvent domainEvent)
    {
        _domainEvents.Add(domainEvent);
    }
}
```

Now you're entities can inherit from the `Entity` base class and raise domain events:

```csharp
public class Course : Entity
{
    public Guid Id { get; private set; }

    public CourseStatus Status { get; private set; }

    public DateTime? CompletedOnUtc { get; private set; }

    public void Complete()
    {
        Status = CourseStatus.Completed;
        CompletedOnUtc = DateTime.UtcNow;

        RaiseDomainEvent(new CourseCompletedDomainEvent { CourseId = this.Id });
    }
}
```

And all that's left to do is **publish** the **domain events**.

## How To Publish Domain Events With EF Core

An elegant solution for publishing domain events is using **EF Core**.

Since EF Core acts as a **Unit of Work**, you can use it to gather all **domain events** in the current transaction and publish them.

I don't like to complicate things, and simply override the `SaveChangesAsync` method to publish the domain events after persisting the changes in the database.
But you could also use an interceptor.

```csharp
public class ApplicationDbContext : DbContext
{
    public override async Task<int> SaveChangesAsync(
        CancellationToken cancellationToken = default)
    {
        // When should you publish domain events?
        //
        // 1. BEFORE calling SaveChangesAsync
        //     - domain events are part of the same transaction
        //     - immediate consistency
        // 2. AFTER calling SaveChangesAsync
        //     - domain events are a separate transaction
        //     - eventual consistency
        //     - handlers can fail

        var result = await base.SaveChangesAsync(cancellationToken);

        await PublishDomainEventsAsync();

        return result;
    }
}
```

The most **important decision** you will have to make here is **when to publish the domain events**.

I think it makes the most sense to publish after calling `SaveChangesAsync`.
In other words, after saving changes to the database.

This comes with a few tradeoffs:

- Eventual consistency - because messages are processed after the original transactions
- Database inconsistency risk - because handling domain events can fail

Eventual consistency is something I can live with, so I choose to make this tradeoff.

However, introducing a risk of database inconsistency is a big concern.

You can solve this with the [**Outbox pattern,**](outbox-pattern-for-reliable-microservices-messaging)
where you persist your changes to the database and the domain events (as outbox messages) in a single transaction.
Now you have a guaranteed atomic transaction, and the domain events are processed asynchronously using a background job.

If you're wondering what's inside the `PublishDomainEventsAsync` method:

```csharp
private async Task PublishDomainEventsAsync()
{
    var domainEvents = ChangeTracker
        .Entries<Entity>()
        .Select(entry => entry.Entity)
        .SelectMany(entity =>
        {
            var domainEvents = entity.GetDomainEvents();

            entity.ClearDomainEvents();

            return domainEvents;
        })
        .ToList();

    foreach (var domainEvent in domainEvents)
    {
        await _publisher.Publish(domainEvent);
    }
}
```

## How To Handle Domain Events

With all of the plumbing we created so far, we're ready to implement a handler for the domain events.
Luckily, this is the simplest step in the process.

All you have to do is define a class implementing `INotificationHandler<T>` and specify your domain event type as the generic argument.

Here's a handler for the `CourseCompletedDomainEvent`, which takes the domain event and publishes a `CourseCompletedIntegrationEvent` to notify other systems.

```csharp
public class CourseCompletedDomainEventHandler
    : INotificationHandler<CourseCompletedDomainEvent>
{
    private readonly IBus _bus;

    public CourseCompletedDomainEventHandler(IBus bus)
    {
        _bus = bus;
    }

    public async Task Handle(
        CourseCompletedDomainEvent domainEvent,
        CancellationToken cancellationToken)
    {
        await _bus.Publish(
            new CourseCompletedIntegrationEvent(domainEvent.CourseId),
            cancellationToken);
    }
}
```

## In Summary

**Domain events** can help you build a loosely coupled system.
You can use them to separate the core domain logic from the side effects, which can be handled asynchronously.

There's no need to reinvent the wheel for implementing domain events, and you can use the **EF Core** and **MediatR** libraries to build this.

You will have to make the decision when you want to publish domain events.
Publishing before or after saving changes to the database both have their set of **tradeoffs**.

I prefer **publishing** domain events **after saving changes** to the database, and I use the [**Outbox pattern**](outbox-pattern-for-reliable-microservices-messaging)
to add transactional guarantees.
This approach introduces eventual consistency, but it's also more reliable.

Hope this was helpful.

See you next week!

**Today's action step:**
Take a look at [**this video,**](https://youtu.be/AHzWJ_SMqLo) where I explain how to implement domain events to build a decoupled system that scales.

---


Previous issues of The .NET Weekly