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

[**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.

[**Workshop: How to Migrate to .NET MAUI? →**](https://www.telerik.com/campaigns/maui-workshop-migration?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=maui-workshop-mnm-na-awareness)
Master the basic concepts behind .NET MAUI and learn about the possibilities of sharing code between web and native mobile and desktop applications.
[**Join the workshop here.**](https://www.telerik.com/campaigns/maui-workshop-migration?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=maui-workshop-mnm-na-awareness)

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

---



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

</Sponsorships>

**Clean code** is code that's easy to read, maintain, and understand.

I consider writing **clean code** a skill.

And it's a **skill** that **you can learn** and improve with deliberate practice.

My favorite approach for practicing **clean coding** is doing **refactoring exercises**.

So I prepared one for you today, and we're going to improve it one step at a time by applying **clean code principles**.

Let's dive in!

## Starting Point

I like starting with a problem when trying to learn new concepts.

And the more illustrative the problem, the better.

So we'll use some poorly written code as the starting point for our refactoring.

And in each step, I will highlight what the current issue is and how we will fix it.

Here's what I see when I look at the `Process` method:

- Deep nesting of code - 4 levels, to be precise
- Precondition checks are applied one after the other
- Throwing exceptions to represent a failure

How can we turn this into **clean code**?

```csharp
public void Process(Order? order)
{
    if (order != null)
    {
        if (order.IsVerified)
        {
            if (order.Items.Count > 0)
            {
                if (order.Items.Count > 15)
                {
                    throw new Exception(
                        "The order " + order.Id + " has too many items");
                }

                if (order.Status != "ReadyToProcess")
                {
                    throw new Exception(
                        "The order " + order.Id + " isn't ready to process");
                }

                order.IsProcessed = true;
            }
        }
    }
}
```

## #1: Early Return Principle

It should be painfully obvious by now that the initial version is deeply nested because of the `if` statements applying precondition checks.

We'll solve this using the **early return principle**, which states that we should return from a method as soon as the conditions for that have been met.

In the case of the `Process` method, this means moving from a deeply nested structure to a set of **guard clauses**.

```csharp {3-6,8-11,13-16}
public void Process(Order? order)
{
    if (order is null)
    {
        return;
    }

    if (!order.IsVerified)
    {
        return;
    }

    if (order.Items.Count == 0)
    {
        return;
    }

    if (order.Items.Count > 15)
    {
        throw new Exception(
            "The order " + order.Id + " has too many items");
    }

    if (order.Status != "ReadyToProcess")
    {
        throw new Exception(
            "The order " + order.Id + " isn't ready to process");
    }

    order.IsProcessed = true;
}
```

## #2: Merge If Statements To Improve Readability

The **early return principle** makes the `Process` method more readable.

But there's no need to have one **guard clause** after another.

So we can merge all of them into one `if` statement.

The behavior of the `Process` method remains unchanged, but we remove a lot of excess code.

```csharp {3-8}
public void Process(Order? order)
{
    if (order is null ||
        !order.IsVerified ||
        order.Items.Count == 0)
    {
        return;
    }

    if (order.Items.Count > 15)
    {
        throw new Exception(
            "The order " + order.Id + " has too many items");
    }

    if (order.Status != "ReadyToProcess")
    {
        throw new Exception(
            "The order " + order.Id + " isn't ready to process");
    }

    order.IsProcessed = true;
}
```

## #3: Use LINQ For More Concise Code

A quick improvement can be using **LINQ** to make the code more concise and expressive.

Instead of checking for `Items.Count == 0`, I prefer using the LINQ `Any` method.

You could argue that LINQ has worse performance, but I always optimize for readability.

There are far more expensive operations in an application than a simple method call.

```csharp {5}
public void Process(Order? order)
{
    if (order is null ||
        !order.IsVerified ||
        !order.Items.Any())
    {
        return;
    }

    if (order.Items.Count > 15)
    {
        throw new Exception(
            "The order " + order.Id + " has too many items");
    }

    if (order.Status != "ReadyToProcess")
    {
        throw new Exception(
            "The order " + order.Id + " isn't ready to process");
    }

    order.IsProcessed = true;
}
```

## #4: Replace Boolean Expression With Descriptive Method

Merging multiple conditions into one `if` statement means writing less code, but it can **decrease readability** with **complex conditions**.

However, you can fix this and improve readability by using a variable or method with a **descriptive name**.

I prefer using methods, so I will introduce the `IsProcessable` method to represent the precondition check.

```csharp {3, 23-28}
public void Process(Order? order)
{
    if (!IsProcessable(order))
    {
        return;
    }

    if (order.Items.Count > 15)
    {
        throw new Exception(
            "The order " + order.Id + " has too many items");
    }

    if (order.Status != "ReadyToProcess")
    {
        throw new Exception(
            "The order " + order.Id + " isn't ready to process");
    }

    order.IsProcessed = true;
}

static bool IsProcessable(Order? order)
{
    return order is not null &&
           order.IsVerified &&
           order.Items.Any();
}
```

## #5: Prefer Throwing Custom Exceptions

Now let's talk about throwing exceptions.
I like to use exceptions for _"exceptional"_ situations only, and I don't use them for flow control in my code.

Having said that, if you _do_ want to use exceptions for flow control, it's better to use **custom exceptions**.

You can introduce valuable contextual information and better describe the reason for throwing the exception.

And if you want to handle these exceptions globally, you can create a base class to be able to catch specific exceptions.

```csharp {10,15}
public void Process(Order? order)
{
    if (!IsProcessable(order))
    {
        return;
    }

    if (order.Items.Count > 15)
    {
        throw new TooManyLineItemsException(order.Id);
    }

    if (order.Status != "ReadyToProcess")
    {
        throw new NotReadyForProcessingException(order.Id);
    }

    order.IsProcessed = true;
}

static bool IsProcessable(Order? order)
{
    return order is not null &&
           order.IsVerified &&
           order.Items.Any();
}
```

## #6: Fix Magic Numbers With Constants

A common **code smell** I see is the use of **magic numbers**.

They are usually easy to spot because they're used to check if numeric some condition applies.

The problem with **magic numbers** is that they **carry no meaning**.

The code is harder to reason about, and more error-prone.

Fixing **magic numbers** should be straightforward, and one solution is introducing a constant.

```csharp {1,10}
const int MaxNumberOfLineItems = 15;

public void Process(Order? order)
{
    if (!IsProcessable(order))
    {
        return;
    }

    if (order.Items.Count > MaxNumberOfLineItems)
    {
        throw new TooManyLineItemsException(order.Id);
    }

    if (order.Status != "ReadyToProcess")
    {
        throw new NotReadyForProcessingException(order.Id);
    }

    order.IsProcessed = true;
}

static bool IsProcessable(Order? order)
{
    return order is not null &&
           order.IsVerified &&
           order.Items.Any();
}
```

## #7: Fix Magic Strings With Enums

Similar to **magic numbers**, we have the **magic strings** **code smell**.

A typical use case for **magic strings** is to represent some sort of state.

You'll notice that we're comparing the `Order.Status` value to a **magic string** to check if the order is ready to process.

A few **problems** with **magic strings**:

- Easy to make mistakes (typo)
- Lack of strong typing
- Not refactoring proof

Let's create an `OrderStatus` `enum` to represent the possible states:

```csharp
enum OrderStatus
{
    Pending = 0,
    ReadyToProcess = 1,
    Processed = 2
}
```

And now we have to use the appropriate `OrderStatus` in the check:

```csharp {15,21}
const int MaxNumberOfLineItems = 15;

public void Process(Order? order)
{
    if (!IsProcessable(order))
    {
        return;
    }

    if (order.Items.Count > MaxNumberOfLineItems)
    {
        throw new TooManyLineItemsException(order.Id);
    }

    if (order.Status != OrderStatus.ReadyToProcess)
    {
        throw new NotReadyForProcessingException(order.Id);
    }

    order.IsProcessed = true;
    order.Status = OrderStatus.Processed;
}

static bool IsProcessable(Order? order)
{
    return order is not null &&
           order.IsVerified &&
           order.Items.Any();
}
```

## #8: Use The Result Object Pattern

I said I don't prefer using exceptions for flow control. But how can we fix this?

One solution is using the **result object pattern**.

You can use a generic `Result` class to represent all types of results or a specific one like `ProcessOrderResult`.

To make your result objects encapsulated, expose a set of factory methods to create the concrete result type.

```csharp
public class ProcessOrderResult
{
    private ProcessOrderResult(
        ProcessOrderResultType type,
        long orderId,
        string message)
    {
        Type = type;
        OrderId = orderId;
        Message = message;
    }

    public ProcessOrderResultType Type { get; }

    public long OrderId { get; }

    public string? Message { get; }

    public static ProcessOrderResult NotProcessable() =>
      new(ProcessOrderResultType.NotProcessable, default, "Not processable");

    public static ProcessOrderResult TooManyLineItems(long oderId) =>
      new(ProcessOrderResultType.TooManyLineItems, orderId, "Too many items");

    public static ProcessOrderResult NotReadyForProcessing(long oderId) =>
      new(ProcessOrderResultType.NotReadyForProcessing, oderId, "Not ready");

    public static ProcessOrderResult Success(long oderId) =>
      new(ProcessOrderResultType.Success, oderId, "Success");
}
```

Using an `enum` like `ProcessOrderResultType` will make consuming the result object easier with switch expressions.
Here's the `enum` to represent the `ProcessOrderResult.Type`:

```csharp
public enum ProcessOrderResultType
{
    NotProcessable = 0,
    TooManyLineItems = 1,
    NotReadyForProcessing = 2,
    Success = 3
}
```

And now the `Process` method becomes:

```csharp {7,12,17,23}
const int MaxNumberOfLineItems = 15;

public ProcessOrderResult Process(Order? order)
{
    if (!IsProcessable(order))
    {
        return ProcessOrderResult.NotProcessable();
    }

    if (order.Items.Count > MaxNumberOfLineItems)
    {
        return ProcessOrderResult.TooManyLineItems(order);
    }

    if (order.Status != OrderStatus.ReadyToProcess)
    {
        return ProcessOrderResult.NotReadyForProcessing(order);
    }

    order.IsProcessed = true;
    order.Status = OrderStatus.Processed;

    return ProcessOrderResult.Success(order);
}

static bool IsProcessable(Order? order)
{
    return order is not null &&
           order.IsVerified &&
           order.Items.Any();
}
```

Here's how using an `enum` for the `ProcessOrderResult.Type` allows you to write a switch expression:

```csharp
var result = Process(order);

result.Type switch
{
    ProcessOrderResultType.TooManyLineItems =>
        Console.WriteLine($"Too many line items: {result.OrderId}"),

    ProcessOrderResultType.NotReadyForProcessing =>
        Console.WriteLine($"Not ready for processing {result.OrderId}"),

    ProcessOrderResultType.Success =>
        Console.WriteLine($"Processed successfully {result.OrderId}"),

    _ => Console.WriteLine("Failed to process: {OrderId}", result.OrderId),
};
```

## Takeaway

That's it, 8 tips to write **clean code**:

- [Early return principle](#1-early-return-principle)
- [Merge multiple if statements](#2-merge-if-statements-to-improve-readability)
- [Use LINQ for conciseness](#3-use-linq-for-more-concise-code)
- [Replace boolean expression with method](#4-replace-boolean-expression-with-descriptive-method)
- [Prefer throwing custom exceptions](#5-prefer-throwing-custom-exceptions)
- [Replace magic numbers with constants](#6-fix-magic-numbers-with-constants)
- [Replace magic string with enums](#7-fix-magic-strings-with-enums)
- [Use the result object pattern](#8-use-the-result-object-pattern)

Writing **clean code** is a matter of deliberate practice and experience.

Most people will read about **clean coding principles**, but few will strive to apply them daily.

This is where you can set yourself apart.

I also made a video about these **clean code** tips, you can watch it [here.](https://youtu.be/McDvyFglkvU)

Hope this was helpful.

See you next week!

**Today's action step:**
Take a look at your project and see if you're making some of the mistakes I highlighted here.
And then fix them using the clean code tips I shared with you.

---



<Sponsorships>

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

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

</Sponsorships>

Large **Microservice-based** systems can consist of tens or even hundreds of individual services.
A client application needs to have all of this information to be able to make requests to the relevant **microservice** directly.

However, this has numerous issues, such as security concerns, increased complexity, and coupling.

We can solve this by introducing an **API gateway** that acts as a **reverse proxy** to accept API calls from the client application and forward them to the appropriate service.

The **API gateway** also enforces security and ensures scalability and high availability.

In this week's newsletter, I'll show you how to implement an **API gateway** for your **microservices system** using the **YARP reverse proxy**.

Here's what we will cover:

- Difference between **API gateway** and **reverse proxy**
- Installing and configuring **YARP**
- Creating an **API gateway** with **YARP**
- **Authentication** and **rate limiting** on the **API gateway**

Let's dive in.

## What's The Difference Between an API Gateway And a Reverse Proxy?

A **reverse proxy** and an **API gateway** are similar concepts, but they serve different purposes.

A **reverse proxy** acts as an intermediary between clients and servers.
The clients can only call the backend servers through the **reverse proxy**, which forwards the request to the appropriate server.
It hides the implementation details of individual servers inside the internal network.

A **reverse proxy** is commonly used for:

- Load balancing
- Caching
- Security
- SSL termination

<Image src="blogs/mnw_045/reverse_proxy.png" width={2602} height={1502} />

An **API gateway** is a specific type of **reverse proxy** designed for managing APIs.
It acts as a single entry point for API consumers to the various backend services.

The key characteristics of an **API gateway** are:

- Request routing and composition
- Request/response transformations
- Authentication and authorization
- Rate limiting
- Monitoring

Also, note that an **API gateway** can perform **load balancing** and other functionalities mentioned for reverse proxies.

Now let's see how to use a **reverse proxy** to implement an **API gateway**.

## Installing And Configuring YARP

**YARP** (Yet Another Reverse Proxy) is a library developed by Microsoft to address the needs of various teams needing to build a **reverse proxy**.
It's open source and built with .NET, so it integrates nicely with the existing ecosystem.

Let's install `Yarp.ReverseProxy` **NuGet** package to get started:

```powershell
Install-Package Yarp.ReverseProxy
```

Next, we're going to call:

- `AddReverseProxy` to add the required services for **YARP**
- `LoadFromConfig` to load the **reverse proxy** configuration from application settings
- `MapReverseProxy` to introduce the **reverse proxy** middleware

```csharp {3-4,8}
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();

app.Run();
```

We need to tell the **YARP** reverse proxy how to route the incoming requests to the individual microservices.

**YARP** uses the concept of `Routes` to represent request patterns for the proxy and `Clusters` to represent the services to forward those requests.

```json {3,6}
{
    "ReverseProxy": {
        "Routes": {
            ...
        },
        "Clusters": {
            ...
        }
    }
}
```

Here's an example **YARP configuration** with a `{**catch-all}` pattern that will route all incoming requests to the one destination server.

```json
{
  "ReverseProxy": {
    "Routes": {
      "ROUTE_NAME": {
        "ClusterId": "CLUSTER_NAME",
        "Match": {
          "Path": "{**catch-all}"
        }
      }
    },
    "Clusters": {
      "CLUSTER_NAME": {
        "Destinations": {
          "destination1": {
            "Address": "https://www.milanjovanovic.tech/"
          }
        }
      }
    }
  }
}
```

## Implementing an API Gateway With YARP

We can use **YARP** to build an **API gateway** by providing the configuration for the services we want to route traffic to.

I created a sample [API gateway implementation with YARP](https://github.com/m-jovanovic/yarp-api-gateway-sample) on GitHub, so you can give it a try.
The system has two services, the `Users.Api` and `Products.Api`, which are .NET 7 applications.

If a request comes in matching the `/users-service/{**catch-all}`, for example `/users-service/users`, it will be routed to the `users-cluster`.
The same logic applies for the `products-cluster`. We can apply more advanced transformations through the `Transforms` section.

```json
{
  "ReverseProxy": {
    "Routes": {
      "users-route": {
        "ClusterId": "users-cluster",
        "Match": {
          "Path": "/users-service/{**catch-all}"
        },
        "Transforms": [{ "PathPattern": "{**catch-all}" }]
      },
      "products-route": {
        "ClusterId": "products-cluster",
        "Match": {
          "Path": "/products-service/{**catch-all}"
        },
        "Transforms": [{ "PathPattern": "{**catch-all}" }]
      }
    },
    "Clusters": {
      "users-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:5201/"
          }
        }
      },
      "products-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:5101/"
          }
        }
      }
    }
  }
}
```

We now have a functioning **API gateway** built with **YARP**, routing requests to two individual services.

But what else can we do with **YARP**?

## Adding Authentication

The **API gateway** can enforce **authentication** and **authorization** at the entry point to the system before letting authenticated requests proceed.

And **YARP** supports integrating with the existing authentication & authorization middleware.

You first need to define an **authorization policy**:

```csharp
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("authenticated", policy =>
        policy.RequireAuthenticatedUser());
});
```

And call `UseAuthentication` and `UseAuthorization` to add the respective middleware to the request pipeline.
It's important to add them before calling `MapReverseProxy`.

```csharp {1,3}
app.UseAuthentication();

app.UseAuthorization();

app.MapReverseProxy();
```

Now all you have to do is add the `AuthorizationPolicy` section to the reverse proxy configuration:

```json {3}
"users-route": {
  "ClusterId": "users-cluster",
  "AuthorizationPolicy": "authenticated",
  "Match": {
    "Path": "/users-service/{**catch-all}"
  },
  "Transforms": [
    { "PathPattern": "{**catch-all}" }
  ]
}
```

**YARP** will forward most credentials to the proxied services, such as cookies or bearer tokens because it might be important to identify the user in the individual microservices.

## Adding Rate Limiting

You can also use an **API gateway** to introduce **rate limiting** to your system.
It's a technique to limit the number of requests to your API to **improve security** and reduce the load on the servers.

You can learn more about [how to use rate limiting in .NET here.](how-to-use-rate-limiting-in-aspnet-core)

As you can already guess, **YARP** supports the native **rate limiting** mechanism added in .NET 7.

All you need to do is define a **rate limit policy**:

```csharp
builder.Services.AddRateLimiter(rateLimiterOptions =>
{
    rateLimiterOptions.AddFixedWindowLimiter("fixed", options =>
    {
        options.Window = TimeSpan.FromSeconds(10);
        options.PermitLimit = 5;
    });
});
```

Then you need to call `UseRateLimiter` to add the rate limiter middleware to the request pipeline.
It's important to do it before calling `MapReverseProxy`.

```csharp {1}
app.UseRateLimiter();

app.MapReverseProxy();
```

And then, you can apply rate limiting to the desired route using the `RateLimiterPolicy` section in the reverse proxy configuration:

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

## In Summary

An **API gateway** is a critical component for a robust **microservices system** implementation.

And **YARP** is an excellent option if you want to build an **API gateway** with .NET.

I created a sample API gateway implementation with YARP, which you can find [here.](https://github.com/m-jovanovic/yarp-api-gateway-sample)
The system consists of two APIs, and the API gateway is configured to route requests between them.
It also implements:

- [Authentication](https://microsoft.github.io/reverse-proxy/articles/authn-authz.html)
- [Rate limiting](how-to-use-rate-limiting-in-aspnet-core)

In this newsletter, we only scratched the surface of what's possible with **YARP**.

Here are some useful resources if you want to learn more:

- [YARP docs](https://microsoft.github.io/reverse-proxy/articles/index.html)
- [Load balancing](https://microsoft.github.io/reverse-proxy/articles/load-balancing.html)
- [Session affinity](https://microsoft.github.io/reverse-proxy/articles/session-affinity.html)
- [Request/response transformations](https://microsoft.github.io/reverse-proxy/articles/transforms.html)

That's all for today.

Hope it was helpful.

**Today's action step:**
Download the [source code](https://github.com/m-jovanovic/yarp-api-gateway-sample) for the sample application implementing an API gateway with YARP, and take it for a spin.
You can challenge yourself by creating multiple instances of a single service and configuring load balancing with the various load balancing algorithms.

---



<Sponsorships>

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

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

</Sponsorships>

Reducing the size of your API responses can noticeably improve the performance of your application.

And since network bandwidth is a limited resource, you should at least consider the benefits of **response compression**.

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

- How to configure **response compression** in .NET
- Server-based vs. application-based compression
- Possible **security risks** and **mitigation strategies**
- How to configure the available compression providers
- How much network bandwidth you could be saving

Let's get started!

## Configuring Response Compression

Using **response compression** in an .NET applications is remarkably easy.

You only have to call these two methods:

- `AddResponseCompression` - to configure the default services for response compression
- `UseResponseCompression` - to add the response compression middleware to the request pipeline

The `UseResponseCompression` method should be called before any middleware that compresses responses.

**Response compression** isn't turned on by default for HTTPS, so you have to enable it by setting `EnableForHttps` to `true`.

```csharp {3-6,10}
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
});

var app = builder.Build();

app.UseResponseCompression();

app.MapGet("/", () => "This response will be compressed 📦");

app.Run();
```

It really is that simple.

But...

## When Should You Use Response Compression?

Ideally, you want to be using **server-based response compression** if your application server supports it.

Because the middleware performs **response compression** at the **application level**, it will typically have worse performance.

If you are hosting your application and you can't use server-based compression, then using the response compression middleware is justified.

One more concern should be **security**, because using **response compression over HTTPS** can expose you to [CRIME](https://en.wikipedia.org/wiki/CRIME) and [BREACH](https://en.wikipedia.org/wiki/BREACH) attacks

Here's what you can do to improve security:

- You can mitigate CRIME and BREACH attacks by introducing **anti-forgery tokens** in ASP.NET Core
- Don't send application secrets as part of the request body
- Implement a [**rate limiter**](how-to-use-rate-limiting-in-aspnet-core)

## Configuring Compression Providers

There are two compression providers added by default when you call `AddResponseCompression`:

- `BrotliCompressionProvider`
- `GzipCompressionProvider`

You can further customize the available providers by adding custom compression providers if you want to.

Compression will default to **Brotli** compression when it's supported by the client.
Otherwise, it will default to **Gzip** if that is the supported compression format.

```csharp {4,5,6}
builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
    options.MimeTypes = ResponseCompressionDefaults.MimeTypes;
});
```

The interesting thing is you can configure the `CompressionLevel` for the **Brotli** and **Gzip** compression providers.

There are four possible values:

- `Optimal` - tries to balance response size and compression speed
- `Fastest` - sacrifices optimal compression for improved speed
- `NoCompression` - self explanatory
- `SmallestSize` - sacrifices compression speed to make the output as small as possible

The default value is `CompressionLevel.Fastest`.

```csharp
builder.Services.Configure<BrotliCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.Optimal;
});

builder.Services.Configure<GzipCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.SmallestSize;
});
```

## How Much Can You Save?

Let's find out how much network bandwidth we can save by using **response compression**.

Here's a minimal API endpoint returning a list of `Message` objects:

```csharp
app.MapGet("/", () => Results.Ok(
    Enumerable
        .Range(1, 100)
        .Select(num => new Message
        {
            Id = num,
            Content = $"This is the message #{num}"
        })));
```

And here are the results with different providers and compression levels:

- No compression - 4.5kB
- **Gzip** + `CompressionLevel.Fastest` - 569B
- **Gzip** + `CompressionLevel.SmallestSize` - 539B
- **Gzip** + `CompressionLevel.Optimal` - 554B
- **Brotli** + `CompressionLevel.Fastest` - 400B
- **Brotli** + `CompressionLevel.SmallestSize` - 296B
- **Brotli** + `CompressionLevel.Optimal` - 319B

**Brotli** is the clear winner, which is why it's the **default compression provider**.

In the best case scenario, you can reduce the response size by ~93.5%.
Multiply this by the number of requests you're serving daily, and then you can begin to estimate the possible network savings.

One more thing I noticed is that using `CompressionLevel.SmallestSize` has a noticeable **negative impact** on response time.
I can't say this was surprising, so I suggest to simply keep using the default compression level.

## In Summary

[Response compression](https://learn.microsoft.com/en-us/aspnet/core/performance/response-compression?view=aspnetcore-7.0)
is an interesting technique to improve API performance and reduce network costs.

Ideally, you'd want to be using **server-based response compression** if it's supported by your application server.
If that's not the case, **application-based compression** is available in .NET with the response compression middleware.

What's the cost of response compression?

It will increase the CPU load, and can expose some security risks over HTTPS, but there are ways to mitigate this.

In my experience, the **default configuration values** for the compression provider and compression level give excellent results.

That's all for this week.

See you next Saturday.

**Today's action step:**
To see the value of response compression, I suggest enabling it in your application and examining the changes in response size.
You can try the different compression providers by varying the `Accept-Encoding` header, and also configure different compression levels in your application.

---



<Sponsorships>

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

And by [**Fiverr.**](https://go.fiverr.com/visit/?bta=738595&brand=fiverrcpa&landingPage=https%3A%2F%2Fwww.fiverr.com%2Fcategories%2Fprogramming-tech%2Fsoftware-development%2Fweb-application%3Fref%3Dprogramming_language%253Aasp_net%252Cc)
Fiverr is your one-stop solution for finding skilled [**Web application developers.**](https://go.fiverr.com/visit/?bta=738595&brand=fiverrcpa&landingPage=https%3A%2F%2Fwww.fiverr.com%2Fcategories%2Fprogramming-tech%2Fsoftware-development%2Fweb-application%3Fref%3Dprogramming_language%253Aasp_net%252Cc)
Build your custom Web application from scratch with help from skilled freelance coders.
[**Check it out here!**](https://go.fiverr.com/visit/?bta=738595&brand=fiverrcpa&landingPage=https%3A%2F%2Fwww.fiverr.com%2Fcategories%2Fprogramming-tech%2Fsoftware-development%2Fweb-application%3Fref%3Dprogramming_language%253Aasp_net%252Cc)

</Sponsorships>

Today's modern applications must deliver the latest information without refreshing the user interface.

If you need to introduce **real-time** functionality to your application in .NET, there's one library you will most likely reach for - **SignalR**.

**SignalR** allows you to push content from your server-side code to any connected clients as changes happen in real-time.

Here's what I'll teach you in this week's newsletter:

- Creating your first **SignalR** `Hub`
- Testing **SignalR** from **Postman**
- Creating strongly typed hubs
- Sending messages to a specific user

Let's see why **SignalR** is so powerful and how easy it is to build **real-time** applications with it.

## Installing And Configuring SignalR

To start using **SignalR** you'll need to:

- Install the NuGet package
- Create the `Hub` class
- Register the SignalR services
- Map and expose the hub endpoint so clients can connect to it

Let's start by installing the `Microsoft.AspNetCore.SignalR.Client` NuGet package:

```powershell
Install-Package Microsoft.AspNetCore.SignalR.Client
```

Then you need a SignalR `Hub`, which is the central component in your application responsible for managing clients and sending messages.

Let's create a `NotificationsHub` by inheriting from the base `Hub` class:

```csharp
public sealed class NotificationsHub : Hub
{
    public async Task SendNotification(string content)
    {
        await Clients.All.SendAsync("ReceiveNotification", content);
    }
}
```

The SignalR `Hub` exposes a few useful properties:

- `Clients` - used to invoke methods on the clients connected to this hub
- `Groups` - an abstraction for adding and removing connections from groups
- `Context` - used for accessing information about the hub caller connection

You can learn more about the `Hub` class [here](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.signalr.hub?view=aspnetcore-7.0).

Lastly, you need to register the SignalR services by calling the `AddSignalR` method.
You also need to call the `MapHub<T>` method, where you specify the `NotificationsHub` class and the path clients will use to connect to the hub.

```csharp {3, 7}
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR();

var app = builder.Build();

app.MapHub<NotificationsHub>("notifications-hub");

app.Run();
```

Now let's see how we can test the `NotificationsHub`.

## Connecting To SignalR Hub From Postman

To test SignalR, you need a client that will connect to the `Hub` instance.
You could create a simple application with Blazor or JavaScript, but I will show you a different approach.

We will use Postman's **WebSocket Request** to connect to the `NotificationsHub`.

<Image
  src="blogs/mnw_043/postman_websocket_request.png"
  width={1011}
  height={747}
/>

Here's what we need to do:

- Connect to the `NotificationsHub`
- Set the communication protocol to JSON
- Send messages to call the `NotificationsHub` methods

All messages need to end with a null termination character, which is just the ASCII character `0x1E`.

Let's start off by sending this message to set the communication protocol to JSON:

```json
{
  "protocol": "json",
  "version": 1
}?
```

You'll receive this response from the hub.

<Image
  src="blogs/mnw_043/postman_set_protocol_request.png"
  width={1731}
  height={890}
/>

We need a slightly different message format to call a message on the `Hub`.
The key is specifying the `arguments` and `target`, which is the actual hub method we want to call.

Let's say we want to call the `SendNotification` method on the `NotificationsHub`:

```json
{
  "arguments": ["This is the notification message."],
  "target": "SendNotification",
  "type": 1
}?
```

This will be the response we get back from the `NotificationsHub`:

<Image
  src="blogs/mnw_043/postman_send_notification_request.png"
  width={1726}
  height={816}
/>

## Strongly Typed Hubs

The base `Hub` class uses the `SendAsync` method to send messages to connected clients.
Unfortunately, we have to use strings to specify client-side methods to invoke, and it's easy to make a mistake.
There's also nothing enforcing which parameters are used.

SignalR supports **strongly typed hubs** that aim to solve this.

First, you need to define a client interface, so let's create a simple `INotificationsClient` abstraction:

```csharp
public interface INotificationsClient
{
    Task ReceiveNotification(string content);
}
```

The arguments don't have to be primitive types and can also be objects. SignalR will take care of serialization on the client side.

After that, you need to update the `NotificationsHub` class to inherit from the `Hub<T>` class to make it strongly typed:

```csharp
public sealed class NotificationsHub : Hub<INotificationsClient>
{
    public async Task SendNotification(string content)
    {
        await Clients.All.ReceiveNotification(content);
    }
}
```

You will lose access to the `SendAsync` method, and only the methods defined in your client interface will be available.

## Sending Server-Side Messages With `HubContext`

What good is a `NotificationsHub` if we can't send notifications from the backend to connected clients?\
Not much.

You can use the `IHubContext<THub>` interface access to the `Hub` instance in your backend code.

And you can use `IHubContext<THub, TClient>` for a strongly typed hub.

Here's a simple Minimal API endpoint that injects an `IHubContext<NotificationsHub, INotificationsClient>` for our strongly typed hub and uses it
to send a notification to all connected clients:

```csharp {3}
app.MapPost("notifications/all", async (
    string content,
    IHubContext<NotificationsHub, INotificationsClient> context) =>
{
    await context.Clients.All.ReceiveNotification(content);

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

## Sending Messages To a Specific User

The real value of SignalR is being able to **send messages**, or notifications in this example, to a **specific user**.

I've seen some complicated implementations that manage a dictionary with a user identifier and a map of active connections.
Why would you do that when SignalR already supports this functionality?

You can call the `User` method and pass it the `userId` to scope the `ReceiveNotification` message to that specific user.

```csharp {2,6}
app.MapPost("notifications/user", async (
    string userId,
    string content,
    IHubContext<NotificationsHub, INotificationsClient> context) =>
{
    await context.Clients.User(userId).ReceiveNotification(content);

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

How does **SignalR** know which user to send the message to?

It uses the `DefaultUserIdProvider` internally to extract the user identifier from the claims.
To be specific, it's using the `ClaimTypes.NameIdentifier` claim.
This also implies that you should be authenticated when connecting to the `Hub`, for example, by passing a JWT.

```csharp
public class DefaultUserIdProvider : IUserIdProvider
{
    public virtual string? GetUserId(HubConnectionContext connection)
    {
        return connection.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    }
}
```

By default, all the methods in a hub can be called by unauthenticated users.
So you need to decorate it with an `Authorize` attribute to only allow authenticated clients to access the hub.

```csharp {1}
[Authorize]
public sealed class NotificationsHub : Hub<INotificationsClient>
{
    public async Task SendNotification(string content)
    {
        await Clients.All.ReceiveNotification(content);
    }
}
```

## In Summary

Adding **real-time functionality** to your application creates room for innovation and adds value to your users.

With **SignalR**, you can start building real-time apps in .NET in minutes.

You need to grasp one concept - the `Hub` class.
SignalR abstracts away the message transport mechanism, so you don't have to worry about it.

Make sure to send authenticated requests to **SignalR** hubs and turn on authentication on the `Hub`.
SignalR will internally track the users connecting to your hubs, allowing you to send them messages based on the user identifier.

That's all for today.

Thanks for reading, and have an awesome Saturday.

**Today's action step:**
Look at your project and try to find an opportunity to add real-time functionality.
Commit 30 min. to build a simple proof of concept with SignalR and see if it can improve your project.

---



<Sponsorships>

Today's issue is sponsored by [**IcePanel.**](https://u.icepanel.io/1eec0e6f)
IcePanel 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.

And by [**ABP Commercial.**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w42&utm_campaign=newsletter-sponsorship)
ABP Commercial is a complete [**web development platform built on ABP Framework**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w42&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>

Is the **anemic domain model** an **antipattern**?

It's a domain model without any behavior and only data properties.

Anemic domain models work great in simple applications, but they are difficult to maintain and evolve if you have rich business logic.

The important parts of your business logic and rules end up being scattered all over the application.
It reduces cohesiveness and reusability, and makes adding new features more difficult.

**Rich domain model** attempts to solve this by encapsulating as much of the business logic as possible.

But how can you design a **rich domain model**?

This is a never-ending process of moving business logic into the domain and refining your domain model.

Let's see how to **refactor** from an **anemic domain model** to a **rich domain model**.

## Working With Anemic Domain Model

To understand what working with an **anemic domain model** looks like, I'll use an example of handling a `SendInvitationCommand`.

I omitted the class and its dependencies so that we can focus on the `Handle` method.
It loads some entities from the database, performs validation, executes the business logic, and finally persists the changes in the database and sends an email.

It already implements some good practices like using repositories and returning result objects.

However, it's working with an **anemic domain model**.

A few things indicating this:

- Parameterless constructors
- Public property setters
- Exposed collections

In other words - the classes representing domain entities contain only data properties and no behavior.

The **problems** of an **anemic domain model** are:

- Discoverability of operations
- Potential code duplication
- Lack of encapsulation

We'll apply a few techniques to push logic down into the domain, and try to make the model more domain-driven.
I hope you'll be able to see the value and benefits this will bring.

```csharp
public async Task<Result> Handle(SendInvitationCommand command)
{
    var member = await _memberRepository.GetByIdAsync(command.MemberId);

    var gathering = await _gatheringRepository.GetByIdAsync(command.GatheringId);

    if (member is null || gathering is null)
    {
        return Result.Failure(Error.NullValue);
    }

    if (gathering.Creator.Id == member.Id)
    {
        throw new Exception("Can't send invitation to the creator.");
    }

    if (gathering.ScheduledAtUtc < DateTime.UtcNow)
    {
        throw new Exception("Can't send invitation for the past.");
    }

    var invitation = new Invitation
    {
        Id = Guid.NewGuid(),
        Member = member,
        Gathering = gathering,
        Status = InvitationStatus.Pending,
        CreatedOnUtc = DateTime.UtcNow
    };

    gathering.Invitations.Add(invitation);

    _invitationRepository.Add(invitation);

    await _unitOfWork.SaveChangesAsync();

    await _emailService.SendInvitationSentEmailAsync(member, gathering);

    return Result.Success();
}
```

## Moving Business Logic Into The Domain

The goal is to move as much of the business logic as possible into the domain.

Let's start with the `Invitation` entity and defining a constructor for it.
I can simplify the design by setting the `Status` and `CreatedOnUtc` properties inside the constructor.
I'm also going to make it `internal` so that an `Invitation` instance can only be created within the domain.

```csharp {3-10}
public sealed class Invitation
{
    internal Invitation(Guid id, Gathering gathering, Member member)
    {
        Id = id;
        Member = member;
        Gathering = gathering;
        Status = InvitationStatus.Pending;
        CreatedOnUtc = DateTime.Now;
    }

    // Data properties omitted for brevity.
}
```

The reason I made the `Invitation` constructor `internal` is so that I can introduce a new method on the `Gathering` entity.
Let's call it `SendInvitation` and it will be responsible for instantiating a new `Invitation` instance and adding it to the internal collection.

Currently, the `Gathering.Invitations` collection is `public`, which means anyone can obtain a reference and modify the collection.

We don't want to allow this, so what we can do is encapsulate this collection behind a `private` field.
This moves the responsibility for managing the `_invitations` collection to the `Gathering` class.

Here's how the `Gathering` class looks like now:

```csharp {3,7-12}
public sealed class Gathering
{
    private readonly List<Invitation> _invitations;

    // Other members omitted for brevity.

    public void SendInvitation(Member member)
    {
        var invitation = new Invitation(Guid.NewGuid(), gathering, member);

        _invitations.Add(invitation);
    }
}
```

## Moving Validation Rules Into The Domain

The next thing we can do is move the validation rules into the `SendInvitation` method, further enriching the domain model.

Unfortunately, this is still a bad practice because of throwing "expected" exceptions when a validation fails.
If you want to use exceptions to enforce your validation rules you should at least do it right, and use specific exceptions instead of generic ones.

But it would be even better to use a **result object** to express validation errors.

```csharp {7-10,12-15}
public sealed class Gathering
{
    // Other members omitted for brevity.

    public void SendInvitation(Member member)
    {
        if (gathering.Creator.Id == member.Id)
        {
            throw new Exception("Can't send invitation to the creator.");
        }

        if (gathering.ScheduledAtUtc < DateTime.UtcNow)
        {
            throw new Exception("Can't send invitation for the past.");
        }

        var invitation = new Invitation(Guid.NewGuid(), gathering, member);

        _invitations.Add(invitation);
    }
}
```

Here's how using **result objects** would look like:

```csharp {5,9,14,21}
public sealed class Gathering
{
    // Other members omitted for brevity.

    public Result SendInvitation(Member member)
    {
        if (gathering.Creator.Id == member.Id)
        {
            return Result.Failure(DomainErrors.Gathering.InvitingCreator);
        }

        if (gathering.ScheduledAtUtc < DateTime.UtcNow)
        {
            return Result.Failure(DomainErrors.Gathering.AlreadyPassed);
        }

        var invitation = new Invitation(Guid.NewGuid(), gathering, member);

        _invitations.Add(invitation);

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

The benefit of this approach is we can introduce constants for possible domain errors.
The catalog of domain errors will act as **documentation** for your domain, and make it more expressive.

Finally, here's how the `Handle` method looks like with all the changes so far:

```csharp {12-17}
public async Task<Result> Handle(SendInvitationCommand command)
{
    var member = await _memberRepository.GetByIdAsync(command.MemberId);

    var gathering = await _gatheringRepository.GetByIdAsync(command.GatheringId);

    if (member is null || gathering is null)
    {
        return Result.Failure(Error.NullValue);
    }

    var result = gathering.SendInvitation(member);

    if (result.IsFailure)
    {
        return Result.Failure(result.Errors);
    }

    await _unitOfWork.SaveChangesAsync();

    await _emailService.SendInvitationSentEmailAsync(member, gathering);

    return Result.Success();
}
```

If you take a closer look at the `Handle` method you'll notice it's doing two things:

- Persisting changes to the database
- Sending an email

This means it's **not atomic**.

There's a potential for the database transaction to complete, and the email sending to fail.
Also, sending the email will slow down the method which could affect performance.

How can make this method atomic?

By sending the email in the background. It's not important for our business logic, so this is safe to do.

## Expressing Side Effects With Domain Events

You can use **domain events** to express that something occurred in your domain that might be interesting to other components in your system.

I often use **domain events** to trigger actions in the background, like sending a notification or email.

Let's introduce an `InvitationSentDomainEvent`:

```csharp
public record InvitationSentDomainEvent(Invitation Invitation) : IDomainEvent;
```

We're going to raise this **domain event** inside the `SendInvitation` method:

```csharp {23}
public sealed class Gathering
{
    private readonly List<Invitation> _invitations;

    // Other members omitted for brevity.

    public Result SendInvitation(Member member)
    {
        if (gathering.Creator.Id == member.Id)
        {
            return Result.Failure(DomainErrors.Gathering.InvitingCreator);
        }

        if (gathering.ScheduledAtUtc < DateTime.UtcNow)
        {
            return Result.Failure(DomainErrors.Gathering.AlreadyPassed);
        }

        var invitation = new Invitation(Guid.NewGuid(), gathering, member);

        _invitations.Add(invitation);

        Raise(new InvitationSentDomainEvent(invitation));

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

The goal is to remove the code responsible for sending the email from the `Handle` method:

```csharp
public async Task<Result> Handle(SendInvitationCommand command)
{
    var member = await _memberRepository.GetByIdAsync(command.MemberId);

    var gathering = await _gatheringRepository.GetByIdAsync(command.GatheringId);

    if (member is null || gathering is null)
    {
        return Result.Failure(Error.NullValue);
    }

    var result = gathering.SendInvitation(member);

    if (result.IsFailure)
    {
        return Result.Failure(result.Errors);
    }

    await _unitOfWork.SaveChangesAsync();

    return Result.Success();
}
```

We only want to worry about executing the business logic and persisting any changes to the database.
Part of those changes will also be the **domain event**, which the system will publish in the background.

Of course, we need a respective **handler** for the **domain event**:

```csharp
public sealed class InvitationSentDomainEventHandler
    : IDomainEventHandler<InvitationSentDomainEvent>
{
    private readonly IEmailService _emailService;

    public InvitationSentDomainEventHandler(IEmailService emailService)
    {
        _emailService = emailService;
    }

    public async Task Handle(InvitationSentDomainEvent domainEvent)
    {
        await _emailService.SendInvitationSentEmailAsync(
            domainEvent.Invitation.Member,
            domainEvent.Invitation.Gathering);
    }
}
```

We achieved two things:

- Handling the `SendInvitationCommand` is now atomic
- Email is sent in the background, and can be safely retried in case of an error

## Takeaway

Designing a **rich domain model** is a gradual process, and you can slowly evolve the domain model over time.

The first step could be making your domain model more defensive:

- Hiding constructors with the `internal` keyword
- Encapsulating collection access

The benefit is your domain models will have a fine-grained public API (methods) which act as an entry point for executing the business logic.

It's easy to test behavior when it's encapsulated in a class without having to mock external dependencies.

You can raise **domain events** to notify the system that something of important occurred, and any interested components can subscribe to that domain event.
Domain events allow you to develop a **decoupled** system, where you focus on the core domain logic, and don't have to worry about the side effects.

However, this doesn't mean that every system needs a **rich domain model**.

You should be pragmatic and decide when the complexity is worth it.

That's all for this week.

See you next Saturday.

---


Previous issues of The .NET Weekly