
<Sponsorships>

Are you seeking a more user-friendly Git experience?
Try [**Tower,**](https://www.git-tower.com/windows?utm_source=newsletter&utm_medium=sponsor&utm_campaign=milans-net-weekly)
the most powerful Git client for Windows.
Currently on sale for Black Friday at a 50% discount!
[**Get Tower here.**](https://www.git-tower.com/windows?utm_source=newsletter&utm_medium=sponsor&utm_campaign=milans-net-weekly)

[**Iron Software**](https://buzz.ironsoftware.com/cyber-rally-2023?utm_source=milan&utm_medium=email&utm_campaign=milan)
are hosting a Cyber Rally.
If you buy a Plus (or above) single product license you might walk away with a full Iron Suite at no extra cost.
[**Find out more here.**](https://buzz.ironsoftware.com/cyber-rally-2023?utm_source=milan&utm_medium=email&utm_campaign=milan)

</Sponsorships>

Refactoring is a technique for restructuring existing code without changing its behavior.
You can think of refactoring as a series of small code transformations.

One change (refactoring) does little.
But a sequence of refactors produces a significant transformation.

There's no better way to learn refactoring than practicing.

So I prepared a refactoring exercise for you.

Today I'm going to refactor some poorly written code.

And I'll show you 5 awesome refactoring techniques along the way:

- Extract method
- Extract interface
- Extract class
- Functional code
- Pushing logic down

## Starting Point

We will refactor the `CustomerService` below to try to improve the code.

I want to achieve three goals with this refactor.

Or rather, I want to improve three qualities of the `CustomerService`:

- Testability
- Readability
- Maintainability

To improve these qualities, we need to figure out what's preventing us from attaining them.

So, let's first understand what the `CustomerService` is doing on a high level:

- Validation of the input arguments
- Fetching the `Company` and creating a new `Customer`
- Calculating if the `Customer` has a credit limit and the amount
- Saving the `Customer` to the database if they meet a specific condition

You can see quite a few things are happening inside the `AddCustomer` method.

It's almost 100 lines of code, which reduces readability.

It's difficult to test because we can't control any external dependencies.

It's impossible to extend the behavior of the `CustomerService` without changing the code.

But we can fix all these problems.
Let me show you how.

```csharp
public class CustomerService
{
    public bool AddCustomer(
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        int companyId)
    {
        if (string.IsNullOrEmpty(firstName) || string.IsNullOrEmpty(lastName))
        {
            return false;
        }

        if (!email.Contains('@') && !email.Contains('.'))
        {
            return false;
        }

        var now = DateTime.Now;
        var age = now.Year - dateOfBirth.Year;
        if (dateOfBirth.Date > now.AddYears(-age))
        {
            age -= 1;
        }

        if (age < 21)
        {
            return false;
        }

        var companyRepository = new CompanyRepository();
        var company = companyRepository.GetById(companyId);

        var customer = new Customer
        {
            Company = company,
            DateOfBirth = dateOfBirth,
            EmailAddress = email,
            Firstname = firstName,
            Surname = lastName
        };

        if (company.Type == "VeryImportantClient")
        {
            // Skip credit check
            customer.HasCreditLimit = false;
        }
        else if (company.Type == "ImportantClient")
        {
            // Do credit check and double credit limit
            customer.HasCreditLimit = true;
            using var creditService = new CustomerCreditServiceClient();

            var creditLimit = creditService.GetCreditLimit(
                customer.Firstname,
                customer.Surname,
                customer.DateOfBirth);

            creditLimit *= 2;
            customer.CreditLimit = creditLimit;
        }
        else
        {
            // Do credit check
            customer.HasCreditLimit = true;
            using var creditService = new CustomerCreditServiceClient();

            var creditLimit = creditService.GetCreditLimit(
                customer.Firstname,
                customer.Surname,
                customer.DateOfBirth);

            customer.CreditLimit = creditLimit;
        }

        if (customer.HasCreditLimit && customer.CreditLimit < 500)
        {
            return false;
        }

        var customerRepository = new CustomerRepository();
        customerRepository.AddCustomer(customer);

        return true;
    }
}
```

## Refactoring the Validation

The first part of the code validating input parameters is pretty concise.
It also follows the early return principle.

The validation consists of simple input validation and a calculation for the customer's age.

I would start with an **extract method** refactor to move the validation into one place.

```csharp
if (string.IsNullOrEmpty(firstName) || string.IsNullOrEmpty(lastName))
{
    return false;
}

if (!email.Contains('@') && !email.Contains('.'))
{
    return false;
}

var now = DateTime.Now;
var age = now.Year - dateOfBirth.Year;
if (dateOfBirth.Date > now.AddYears(-age))
{
    age -= 1;
}

if (age < 21)
{
    return false;
}
```

Calculating the age isn't part of the validation flow, so I'll extract that into the `CalculateAge` method.

```csharp
int CalculateAge(DateTime dateOfBirth, DateTime now)
{
    var age = now.Year - dateOfBirth.Year;
    if (dateOfBirth.Date > now.AddYears(-age))
    {
        age -= 1;
    }

    return age;
}
```

Then, I'll create the `IsValid` method to encapsulate all the validation rules.
Instead of writing many `if-else` statements, I can write a single `bool` expression.

I also introduced a `minimumAge` constant to improve readability.

You can see how the `CalculateAge` method helps simplify the validation check.

```csharp
bool IsValid(
    string firstName,
    string lastName,
    string email,
    DateTime dateOfBirth)
{
    const int minimumAge = 21;

    return !string.IsNullOrEmpty(firstName) &&
           !string.IsNullOrEmpty(lastName) &&
           (email.Contains('@') || email.Contains('.')) &&
           CalculateAge(dateOfBirth, DateTime.Now) >= minimumAge;
}
```

This simplifies the validation code in `AddCustomer` to:

```csharp
if (!IsValid(firstName, lastName, email, dateOfBirth))
{
    return false;
}
```

## Refactoring Towards Dependency Injection

The next problem I want to solve is introducing [dependency injection](improving-aspnetcore-dependency-injection-with-scrutor) to the `CustomerService`.

Dependency injection allows us to achieve **Inversion of Control (IoC).**
We depend only on interfaces at compile time and on implementations at run time.

The dependency injection pattern has a few important benefits.

You don't have to know how to initialize or dispose of external dependencies.

It also improves testability since you now depend on interfaces.
Interfaces can be mocked to make unit testing easier.

So let's update the `CustomerService` not to initialize the dependencies directly:

```csharp
var companyRepository = new CompanyRepository();

using var creditService = new CustomerCreditServiceClient();

var customerRepository = new CustomerRepository();
```

Instead, we will inject them as constructor arguments.
You can even use the [C# 12 primary constructor](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/tutorials/primary-constructors) feature.

```csharp {2-4}
public class CustomerService(
    CompanyRepository companyRepository,
    CustomerRepository customerRepository,
    CustomerCreditServiceClient creditService)
{
    // ...
}
```

The next step would be introducing interfaces for these dependencies.
This comes down to an **extract interface** refactor.

## Refactoring the Credit Limit Calculation

The credit limit calculation is the most complicated part of the code.
There are different business rules based on the company type.

I try to notice patterns in the code before refactoring.
So here are a few of my observations.

Multiple `if-else` statements based on the `Type` property make me wonder if I'll need to extend this in the future.
Adding a new rule would mean another `if-else` check.
The [strategy pattern](https://refactoring.guru/design-patterns/strategy) could be an alternative, but a `switch` statement will also work fine.

Another thing that stands out is the **code duplication** in the last two blocks.
This usually means I can do an **extract method** refactoring to reduce code duplication.

```csharp
if (company.Type == "VeryImportantClient")
{
    // Skip credit check
    customer.HasCreditLimit = false;
}
else if (company.Type == "ImportantClient")
{
    // Do credit check and double credit limit
    customer.HasCreditLimit = true;
    using var creditService = new CustomerCreditServiceClient();

    var creditLimit = creditService.GetCreditLimit(
        customer.Firstname,
        customer.Surname,
        customer.DateOfBirth);

    creditLimit *= 2;
    customer.CreditLimit = creditLimit;
}
else
{
    // Do credit check
    customer.HasCreditLimit = true;
    using var creditService = new CustomerCreditServiceClient();

    var creditLimit = creditService.GetCreditLimit(
        customer.Firstname,
        customer.Surname,
        customer.DateOfBirth);

    customer.CreditLimit = creditLimit;
}
```

The first thing I want to do is introduce an `enum` for the `CompanyType`.

This is a [clean coding principle](8-tips-to-write-clean-code) I often use.
It improves the readability and extensibility of the code.

```csharp
public enum CompanyType
{
    Regular = 0,
    ImportantClient = 1,
    VeryImportantClient = 2
}
```

The next thing that bothers me is that the credit limit calculation doesn't belong to the `CustomerService`.
It violates the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle).

So I want to introduce a dedicated `CreditLimitCalculator` using an **extract class** refactoring.
I replaced the `if-else` statements with a [switch expression](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/switch-expression) that I can easily extend in the future.

```csharp
public class CreditLimitCalculator(
    CustomerCreditServiceClient customerCreditServiceClient)
{
    public (bool HasCreditLimit, decimal? CreditLimit) Calculate(
        Customer customer,
        Company company)
    {
        return company.Type switch
        {
            CompanyType.VeryImportantClient => (false, null),
            CompanyType.ImportantClient => (true, GetCreditLimit(customer) * 2),
            _ => (true, GetCreditLimit(customer))
        };
    }

    private decimal GetCreditLimit(Customer customer)
    {
        return customerCreditServiceClient.GetCreditLimit(
            customer.FirstName,
            customer.LastName,
            customer.DateOfBirth);
    }
}
```

## Reviewing the Refactoring (So Far)

Let's pause momentarily and review the refactored version of the `CustomerService`.
I'm confident you will find it more readable and easier to understand.
We can easily test this class and verify that the behavior is correct.

I would usually stop the refactoring at this point, since I'm happy with the results.

But can we take this further?

```csharp
public class CustomerService(
    CompanyRepository companyRepository,
    CustomerRepository customerRepository,
    CreditLimitCalculator creditLimitCalculator)
{
    public bool AddCustomer(
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        int companyId)
    {
        if (!IsValid(firstName, lastName, email, dateOfBirth))
        {
            return false;
        }

        var company = companyRepository.GetById(companyId);

        var customer = new Customer
        {
            Company = company,
            DateOfBirth = dateOfBirth,
            EmailAddress = email,
            FirstName = firstName,
            LastName = lastName
        };

        (customer.HasCreditLimit, customer.CreditLimit) =
            creditLimitCalculator.Calculate(customer, company);

        if (customer is { HasCreditLimit: true, CreditLimit: < 500 })
        {
            return false;
        }

        customerRepository.AddCustomer(customer);

        return true;
    }
}
```

## Taking It Further - Pushing Logic Down

This part is optional, but I want to show you how to simplify the `CustomerService` by pushing logic into the domain.

What if we moved the responsibility of creating a `Customer` into the class?

I often use the **static factory** pattern to implement this.
The caveat is I have to take a dependency on `CreditLimitCalculator`.
I'm trading off domain model purity to get business rules completeness.

I also added the `IsUnderCreditLimit` method to wrap the credit limit check.

```csharp
public class Customer
{
    // Properties omited

    public static Customer Create(
        Company company,
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        CreditLimitCalculator creditLimitCalculator)
    {
        var customer = new Customer
        {
            Company = company,
            DateOfBirth = dateOfBirth,
            EmailAddress = email,
            FirstName = firstName,
            LastName = lastName
        };

        (customer.HasCreditLimit, customer.CreditLimit) =
            creditLimitCalculator.Calculate(customer, company);

        return customer;
    }

    public bool IsUnderCreditLimit() => HasCreditLimit && CreditLimit < 500;
}
```

This is what the `CustomerService` looks like now:

```csharp
public class CustomerService(
    CompanyRepository companyRepository,
    CustomerRepository customerRepository,
    CreditLimitCalculator creditLimitCalculator)
{
    public bool AddCustomer(
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        int companyId)
    {
        if (!IsValid(firstName, lastName, email, dateOfBirth))
        {
            return false;
        }

        var company = companyRepository.GetById(companyId);

        var customer = Customer.Create(
            company,
            firstName,
            lastName,
            email,
            dateOfBirth,
            creditLimitCalculator);

        if (customer.IsUnderCreditLimit())
        {
            return false;
        }

        customerRepository.AddCustomer(customer);

        return true;
    }
}
```

What do you think about this implementation?

## Next Steps

First of all, congrats on making it to the end.
This was a much longer newsletter issue than usual.
What do you think of this format?

Writing unit tests before starting the refactoring would be a great idea.
Unit tests will help detect any changes in behavior.

Remember, refactoring is transforming the existing code without changing the behavior.

Here are a few ideas on how you could further refactor the code:

- [**Strategy pattern**](https://refactoring.guru/design-patterns/strategy) for the credit limit calculation
- [**Result object**](functional-error-handling-in-dotnet-with-the-result-pattern) to represent the method status

If you want to try this refactoring exercise, you can find the complete [**source code here.**](https://github.com/m-jovanovic/refactoring-katas)

Hope this was helpful.

See you next week.

---



<Sponsorships>

[**Telerik UI for Blazor**](https://www.telerik.com/blogs/basic-themes-customization-telerik-ui-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-blazor-content-exposure)
makes it easy to tailor your app to your design specifications.
Its wide range of high-quality components, such as Grid, Charts, Forms, and Scheduler, speed up development significantly.
[**Learn more in this post.**](https://www.telerik.com/blogs/basic-themes-customization-telerik-ui-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-blazor-content-exposure)

[**ABP Commercial**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w64)
is a complete platform built on ABP Framework for enterprise-grade ASP.NET Core based web applications.
It comes with pre-built application modules, advanced startup templates, and premium support.
[**Check it out here.**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w64)

</Sponsorships>

EF Core is my favorite ORM for .NET applications.
Yet, its many fantastic features sometimes go unnoticed.
For example, [**query splitting**](how-to-improve-performance-with-ef-core-query-splitting),
[**query filters**](how-to-use-global-query-filters-in-ef-core),
and interceptors.

EF interceptors are interesting because you can do powerful things with them.
For example, you can hook into materialization, handle optimistic concurrency errors, or add query hints.

The most practical use case is adding behavior when saving changes to the database.

Today I want to show you three unique use cases for EF Core interceptors:

- Audit logging
- Publishing domain events
- Persisting Outbox messages

## What are EF Interceptors?

[EF Core interceptors](https://learn.microsoft.com/en-us/ef/core/logging-events-diagnostics/interceptors)
allow you to intercept, change, or suppress EF Core operations.
Every interceptor implements the `IInterceptor` interface.
A few common derived interfaces include `IDbCommandInterceptor`, `IDbConnectionInterceptor`, and `IDbTransactionInterceptor`.

The most popular one is the `ISaveChangesInterceptor`. It allows you to add behavior before or after saving changes.

Interceptors are registered for each `DbContext` instance when configuring the context.

```csharp
public interface IInterceptor
{
}
```

You don't have to implement these interfaces directly.
It's better to use concrete implementations and override the needed methods.

For example, I'll show you how to use the `SaveChangesInterceptor`.

## Audit Logging With EF Interceptors

An audit log of entity changes is a valuable feature in some applications.
You write additional audit information every time an entity is created or modified.
The audit log could also contain the complete before/after values, depending on your requirements.

However, let's use a simple example to make it easy to understand.

I have an `IAuditable` interface with two properties representing when an entity was created or modified.

```csharp
public interface IAuditable
{
    DateTime CreatedOnUtc { get; }

    DateTime? ModifiedOnUtc { get; }
}
```

Next, I'll implement an `UpdateAuditableInterceptor` interceptor to write the audit values.
It uses the `ChangeTracker` to find all `IAuditable` instances and sets the respective property value.

I want to highlight that I'm overriding the `SavingChangesAsync` method here.
`SavingChangesAsync` runs before the changes are saved in the database and any updates applied inside the `UpdateAuditableInterceptor`
are also part of the current database transaction.

This implementation can be easily extended to include the information about the current user.

```csharp
internal sealed class UpdateAuditableInterceptor : SaveChangesInterceptor
{
    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is not null)
        {
            UpdateAuditableEntities(eventData.Context);
        }

        return base.SavingChangesAsync(eventData, result, cancellationToken);
    }

    private static void UpdateAuditableEntities(DbContext context)
    {
        DateTime utcNow = DateTime.UtcNow;
        var entities = context.ChangeTracker.Entries<IAuditable>().ToList();

        foreach (EntityEntry<IAuditable> entry in entities)
        {
            if (entry.State == EntityState.Added)
            {
                SetCurrentPropertyValue(
                    entry, nameof(IAuditable.CreatedOnUtc), utcNow);
            }

            if (entry.State == EntityState.Modified)
            {
                SetCurrentPropertyValue(
                    entry, nameof(IAuditable.ModifiedOnUtc), utcNow);
            }
        }

        static void SetCurrentPropertyValue(
            EntityEntry entry,
            string propertyName,
            DateTime utcNow) =>
            entry.Property(propertyName).CurrentValue = utcNow;
    }
}
```

## Publish Domain Events With EF Interceptors

Another use case for EF interceptors is [**publishing domain events.**](how-to-use-domain-events-to-build-loosely-coupled-systems)
Domain events are a DDD tactical pattern to create loosely coupled systems.

Domain events allow you to express side effects explicitly and provide a better separation of concerns in the domain.

You can create an `IDomainEvent` interface, which derives from `MediatR.INotification`.
This allows you to use the `IPublisher` to publish domain events and handle them asynchronously.

```csharp
using MediatR;

public interface IDomainEvent : INotification
{
}
```

Then, I'll create a `PublishDomainEventsInterceptor` that also inherits from `SaveChangesInterceptor`.
However, this time, we're using the `SavedChangesAsync` to publish the domain events _after_ saving changes in the database.

This has two important implications:

1. The entire workflow is now eventually consistent. Domain event handlers will save changes to the database after the original transaction.
2. If any domain event handlers fail, we risk failing the request even though the initial transaction was completed successfully.

You can make this process more reliable by using an [**Outbox.**](outbox-pattern-for-reliable-microservices-messaging)

```csharp
internal sealed class PublishDomainEventsInterceptor : SaveChangesInterceptor
{
    private readonly IPublisher _publisher;

    public PublishDomainEventsInterceptor(IPublisher publisher)
    {
        _publisher = publisher;
    }

    public override async ValueTask<int> SavedChangesAsync(
        SaveChangesCompletedEventData eventData,
        int result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is not null)
        {
            await PublishDomainEventsAsync(eventData.Context);
        }

        return result;
    }

    private async Task PublishDomainEventsAsync(DbContext context)
    {
        var domainEvents = context
            .ChangeTracker
            .Entries<Entity>()
            .Select(entry => entry.Entity)
            .SelectMany(entity =>
            {
                List<IDomainEvent> domainEvents = entity.DomainEvents;

                entity.ClearDomainEvents();

                return domainEvents;
            })
            .ToList();

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

## Store Outbox Messages With EF Interceptors

Instead of [**publishing domain events**](how-to-use-domain-events-to-build-loosely-coupled-systems) as part of the EF transaction, you can convert them to Outbox messages.

Here's an `InsertOutboxMessagesInterceptor` that does precisely this.

It overrides the `SavingChangesAsync` method.
Which means it runs inside the current EF transaction before saving changes.

The `InsertOutboxMessagesInterceptor` converts any domain events into an `OutboxMessage` and adds it to the respective `DbSet<OutboxMessage>`.
This means they will be saved to the database with any existing changes inside the same transaction.

This is an atomic operation.

Either everything succeeds or everything fails.

There's no in-between state like in the `PublishDomainEventsInterceptor`.

You can then create a background worker that will process the Outbox messages.

And this is how you implement the [**Outbox pattern**](outbox-pattern-for-reliable-microservices-messaging) with EF Core.

```csharp
using Newtonsoft.Json;

public sealed class InsertOutboxMessagesInterceptor : SaveChangesInterceptor
{
    private static readonly JsonSerializerSettings Serializer = new()
    {
        TypeNameHandling = TypeNameHandling.All
    };

    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is not null)
        {
            InsertOutboxMessages(eventData.Context);
        }

        return base.SavingChangesAsync(eventData, result, cancellationToken);
    }

    private static void InsertOutboxMessages(DbContext context)
    {
        context
            .ChangeTracker
            .Entries<Entity>()
            .Select(entry => entry.Entity)
            .SelectMany(entity =>
            {
                List<IDomainEvent> domainEvents = entity.DomainEvents;

                entity.ClearDomainEvents();

                return domainEvents;
            })
            .Select(domainEvent => new OutboxMessage
            {
                Id = domainEvent.Id,
                OccurredOnUtc = domainEvent.OccurredOnUtc,
                Type = domainEvent.GetType().Name,
                Content = JsonConvert.SerializeObject(domainEvent, Serializer)
            })
            .ToList();

        context.Set<OutboxMessage>().AddRange(outboxMessages);
    }
}
```

## Configuring EF Interceptors Using Dependency Injection

EF interceptors should be lightweight and stateless.
You can add them to the `DbContext` by calling `AddInterceptors` and passing in the interceptor instances.

I like to configure the interceptors with Dependency Injection for two reasons:

- It allows me also to use DI in the interceptors (be mindful that they are singletons)
- To simplify adding the interceptors to the `DbContext` using `AddDbContext`

Here's how you can configure the `UpdateAuditableInterceptor` and `InsertOutboxMessagesInterceptor` with the `ApplicationDbContext`:

```csharp
services.AddSingleton<UpdateAuditableInterceptor>();
services.AddSingleton<InsertOutboxMessagesInterceptor>();

services.AddDbContext<IApplicationDbContext, ApplicationDbContext>(
    (sp, options) => options
        .UseSqlServer(connectionString)
        .AddInterceptors(
            sp.GetRequiredService<UpdateAuditableInterceptor>(),
            sp.GetRequiredService<InsertOutboxMessagesInterceptor>()));
```

## Closing Thoughts

Interceptors allow you to do almost anything with an EF Core operation.
But with great power comes great responsibility.
You should be mindful that interceptors have an impact on performance.
Calls to external services or handling events will slow down the operation.

Remember, you don't necessarily have to use EF interceptors.
You can achieve the same behavior by overriding the `SaveChangesAsync` method on the `DbContext` and adding your custom logic there.

I showed you a few practical use cases for EF interceptors in this week's issue.

But, if you want to see more examples, I have a few videos about:

- [**Auditing logging**](https://youtu.be/mAlO3OuoQvo)
- [**Publishing domain events**](https://youtu.be/AHzWJ_SMqLo)
- [**Implementing the Outbox pattern**](https://youtu.be/XALvnX7MPeo)

Thanks for reading, and stay awesome!

---



<Sponsorships>

[**Progress**](https://www.telerik.com/campaigns/discover-the-magic-of-dot-net-8-and-beyond-webinar?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=devcraft-webinar-standardization-dot-net-8)
is holding a free webinar: [**Discover the Magic of .NET 8 and Beyond!**](https://www.telerik.com/campaigns/discover-the-magic-of-dot-net-8-and-beyond-webinar?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=devcraft-webinar-standardization-dot-net-8)
Join the webinar and find out all the hot news in .NET 8.
[**Register today for FREE!**](https://www.telerik.com/campaigns/discover-the-magic-of-dot-net-8-and-beyond-webinar?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=devcraft-webinar-standardization-dot-net-8)

How do you [**choose the right PDF library?**](https://ironpdf.com/blog/case-studies/jeff-fritz-pdf-library-comparison/?utm_source=milan&utm_medium=email&utm_campaign=milan)
Microsoft MVP Jeff Fritz compared the most popular HTML-to-PDF libraries: iTextSharp, Syncfusion, Aspose, and IronPDF.
Take a look at his findings and [**find out which PDF library is the best.**](https://ironpdf.com/blog/case-studies/jeff-fritz-pdf-library-comparison/?utm_source=milan&utm_medium=email&utm_campaign=milan)

</Sponsorships>

Reporting is essential for business applications like e-commerce, shipping, fintech, etc.

One of the most popular document formats for reporting purposes is [PDF.](https://en.wikipedia.org/wiki/PDF)

PDF stands for Portable Document Format.
It's a file format to present documents (including text formatting and images) independently of application software, hardware, and operating systems.

Some common problems .NET developers will face when working with PDF files:

- Creating dynamic PDF documents
- Designing a consistent page layout
- Customizing fonts on printed documents

Today I want to show you a few interesting ways to generate PDF files in .NET.

## Creating PDF Files With QuestPDF

[QuestPDF](https://www.questpdf.com/) is an open-source .NET library for generating PDF documents.
It exposes a fluent API you can use to compose together many simple elements to create complex documents.
Unlike other libraries, it does not rely on HTML-to-PDF conversion.

Let's install the QuestPDF NuGet package:

```powershell
Install-Package QuestPDF
```

Here's how you can generate a simplified invoice with QuestPDF:

```csharp
using QuestPDF.Fluent;
using QuestPDF.Helpers;
using QuestPDF.Infrastructure;

Document.Create(container =>
{
    container.Page(page =>
    {
        page.Margin(50);
        page.Size(PageSizes.A4);
        page.PageColor(Colors.White);
        page.DefaultTextStyle(x => x.FontSize(16));

        page.Header()
            .AlignCenter()
            .Text("Invoice #: 2023-77")
            .SemiBold().FontSize(24).FontColor(Colors.Grey.Darken4);

        page.Content()
            .Table(table =>
            {
                table.ColumnsDefinition(columns =>
                {
                    columns.ConstantColumn(20);
                    columns.RelativeColumn();
                    columns.RelativeColumn();
                });

                table.Header(header =>
                {
                    header.Cell().Text("#");
                    header.Cell().Text("Product");
                    header.Cell().AlignRight().Text("Price");
                });

                foreach (var lineItem in lineItems)
                {
                    table.Cell().Text(lineItem.Index.ToString());
                    table.Cell().Text(lineItem.Name);
                    table.Cell().Text($"${lineItem.Price}");
                }
            });
    });
})
.GeneratePdf("invoice.pdf");;
```

What I like about QuestPDF:

- Fluent API
- Easy to use
- Good [documentation](https://www.questpdf.com/introduction.html)

What I don't like about QuestPDF:

- Having to write a lot of code to create documents
- Limited scope of features
- No HTML-to-PDF support

**Licensing**

QuestPDF is free for small companies and development use.
There's also a commercial license for larger companies.
You can check out the licensing details [here.](https://www.questpdf.com/license/)

## HTML to PDF Conversion With IronPDF

The more common approach for generating PDF files is using an HTML template.

My favorite library that supports this is [IronPDF.](https://ironpdf.com/)

IronPDF is a C# PDF library that allows for fast and efficient manipulation of PDF files.
It also has many valuable features, like [exporting to PDF/A format](https://ironpdf.com/how-to/pdfa/)
and [digitally signing PDF documents.](https://ironpdf.com/how-to/signing/)

But what's the idea behind using an HTML template?

First of all, you have more control over formatting the document.
You can use CSS to style the HTML markup, which will be applied when exporting to a PDF document.

An interesting implementation approach is using [ASP.NET Core MVC views](https://learn.microsoft.com/en-us/aspnet/core/mvc/views/overview?view=aspnetcore-7.0)
and the [Razor syntax.](https://learn.microsoft.com/en-us/aspnet/core/mvc/views/razor?view=aspnetcore-7.0)
You can pass an object to the view at runtime to render dynamic HTML content.

I've used this approach with MVC views on a few projects with excellent results.

Let's start by installing the IronPDF NuGet package:

```powershell
Install-Package IronPdf
```

I'm using a strongly typed Razor view to define my markup.
The `InoviceViewModel` class is the model, and it's used to create dynamic content.

```tsx
@model ViewModels.InoviceViewModel

<div>Invoice number: @Model.InvoiceNumber</div>
<div>Invoice date: @Model.InvoiceDate</div>
<br/>
<span>Line items:</span>
<ul>
    @foreach(var lineItem in Model.LineItems)
    {
        <li>@lineItem.Name | @lineItem.Price</li>
    }
</ul>
```

Now, you need to use the IronPDF `ChromePdfRenderer` to convert the HTML to a PDF document.

```csharp
var html = ConvertRazorViewToHtml(invoice);

var renderer = new ChromePdfRenderer();

var pdf = renderer.RenderHtmlAsPdf(html);

pdf.SaveAs($"invoice-{invoice.InvoiceNumber}.pdf");
```

It really is that simple.

**Licensing**

IronPDF is free for development use and has multiple pricing tiers for commercial use that you can check out [here.](https://ironpdf.com/licensing/)

## Merging Multiple PDF Files

Another common requirement I've seen is merging multiple PDF files.
For example, you could implement a feature to merge the monthly receipts for the accounting department.

You can use the `PdfDocument.Merge` method to implement this.
It accepts a `PdfDocument` collection as the argument.
You'll first have to load the PDF documents into memory before merging them.

Here's an example:

```csharp
var pdfs = new List<PdfDocument>();

pdfs.Add(PdfDocument.FromFile("google-invoice.pdf"));
pdfs.Add(PdfDocument.FromFile("google-ads-invoice.pdf"));
pdfs.Add(PdfDocument.FromFile("converkit-invoice.pdf"));

PdfDocument mergedPdfDocument = PdfDocument.Merge(pdfs);

mergedPdfDocument.SaveAs("merged-invoices.pdf");
```

## Exporting PDF Files From an API

It's pretty straightforward to return a PDF file from an API endpoint in ASP.NET Core.

Minimal APIs have the `Results.File` method accepting either a file path, stream, or byte array.
You also need to specify the content type and an optional file name.
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
for PDF files is `application/pdf`.

Here's how you can return a PDF file from a byte array:

```csharp
app.MapGet("newsletter/download", () =>
{
    var renderer = new ChromePdfRenderer();

    var pdf = renderer.RenderHtmlAsPdf("<h1>The .NET Weekly</h1>");

    return Results.File(pdf.BinaryData, "application/pdf", "newsletter.pdf");
});
```

## Takeaway

Choosing which PDF library you will use in .NET is an important consideration to make.
And while pricing is a significant factor, the features you want to use will also dictate your choice.

QuestPDF is an excellent choice if you're looking for a (mostly) free option with rich features.
The library is constantly improved, and new features are being added.
However, it doesn't support HTML-to-PDF conversion and modifying existing documents.

IronPDF is the library I've used most often on commercial projects.
It has fantastic features for working with PDF files, with many customization options.
The HTML-to-PDF conversion works like a charm.

The hardest part is picking the right tool for the job.

So I hope this is helpful.

See you next week.

---



<Sponsorships>

Stop wasting time and focus on the skills employers are actually looking for today with [**Julio's .NET Backend Developer Roadmap.**](https://juliocasal.com/roadmap?utm_campaign=Milan-Sponsorship&utm_source=Milan-Newsletter&utm_medium=email)
A fully interactive guide with 110+ topics that link to the best videos or articles on the web.
[**Get it for free here.**](https://juliocasal.com/roadmap?utm_campaign=Milan-Sponsorship&utm_source=Milan-Newsletter&utm_medium=email)

[**Acorn**](https://www.acorn.io/) offers a free cloud sandbox environment where you can deploy applications with the power of Kubernetes.
Try it out by launching your own [**.NET App**](https://acorn.io/run/ghcr.io/infracloudio/dotnetcore-acorn:v7.%23.%23?ref=smw355&name=.Net+Development+Application&_gl=1*6tonkz*_ga*MTUzMDk5NjAwNC4xNjkwMzk2NTI2*_ga_JEWPGB0DW9*MTY5ODk0MDgxMy42OS4xLjE2OTg5NDI5NjIuMC4wLjA.)
in the cloud with Acorn.
Check out their [**.NET tutorial**](https://www.acorn.io/tutorials/developing-a-net-app-in-the-cloud-with-acorn)
and see where your first Acorn takes you!

</Sponsorships>

Layered architectures are the foundation of many software systems.
However, layered architectures organize the system around technical layers.
And the cohesion between layers is low.

What if you wanted to organize the system around features instead?

Minimize coupling between unrelated features and maximize coupling in a single feature.

Today I want to talk about **Vertical Slice Architecture**, which does precisely that.

## The Problem With Layered Architectures

Layered architectures organize the software system into layers or tiers.
Each of the layers is typically one project in your solution.
Some of the popular implementations are N-tier architecture or Clean architecture.

Layered architectures focus on separating the concerns of the various components.
This makes it easier to understand and maintain the software system.
And there are many benefits of [**structured software design,**](clean-architecture-and-the-benefits-of-structured-software-design)
such as maintainability, flexibility, and loose coupling.

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

However, layered architectures also impose constraints or rigid rules on your system.
The direction of dependencies between layers is pre-determined.

For example, in Clean Architecture:

- Domain should have no dependencies
- Application layer can reference the Domain
- Infrastructure can reference both Application and Domain
- Presentation can reference both Application and Domain

You end up having high coupling inside a layer and low coupling between layers.
This doesn't mean layered architectures are bad.
But it does mean you will have many abstractions between individual layers.
And more abstractions mean increased complexity because there are more components to maintain.

## What is Vertical Slice Architecture?

I first heard about [Vertical Slice Architecture](https://www.jimmybogard.com/vertical-slice-architecture) from Jimmy Bogard.
He's also the creator of some popular open-source libraries like [MediatR](https://github.com/jbogard/MediatR) and [Automapper.](https://github.com/AutoMapper/AutoMapper)

Vertical Slice Architecture was born from the pain of working with layered architectures.
They force you to make changes in many different layers to implement a feature.

Let's imagine what adding a new feature looks like in a layered architecture:

- Updating the domain model
- Modifying validation logic
- Creating a use case with MediatR
- Exposing an API endpoint from a controller

The cohesion is low because you are creating many files in different layers.

Vertical slices take a different approach:

> Minimize coupling between slices, and maximize coupling in a slice.

Here's how you can visualize vertical slices:

<Image
  src="blogs/mnw_062/vertical_slice_architecture.png"
  width={1920}
  height={1080}
/>

All the files for a single use case are grouped inside one folder.
So, the cohesion for a single use case is very high.
This simplifies the development experience.
It's easy to find all the relevant components for each feature since they are close together.

## Implementing Vertical Slices

If you're building an API, the system already breaks down into commands (POST/PUT/DELETE) and queries (GET).
By splitting the requests into commands and queries, you're getting the benefits of the [**CQRS pattern.**](cqrs-pattern-with-mediatr)

Vertical slices narrowly focus on a single feature.
This allows you to treat each use case separately and tailor the implementation to the specific requirements.
One vertical slice can use EF Core to implement a GET request.
Another vertical slice can use Dapper with raw SQL queries.

<Image src="blogs/mnw_062/vertical_slices.png" width={1920} height={1080} />

Another benefit of implementing vertical slices like this is:

> New features only add code, you're not changing shared code and worrying about side effects.

However, vertical slices have their own set of challenges.
Because you are implementing much of the business logic inside a single use case, you need to be able to spot code smells.
As the use case grows, it can end up doing too much.
You will have to refactor the code by [**pushing logic to the domain.**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model)

## Solution Structure With REPR Pattern

Layered architectures, such as Clean architecture, organize the solution across layers.
This results in a [**folder structure grouped by technical concerns.**](clean-architecture-folder-structure)

Vertical slice architecture, on the other hand, organizes the code around features or use cases.

An interesting approach to structuring APIs around features is using the [REPR pattern.](https://deviq.com/design-patterns/repr-design-pattern)
It stands for Request-EndPoint-Response.
This aligns perfectly with the idea of vertical slices.
You can achieve this with the MediatR library, for example.

The REPR pattern defines that web API endpoints should have three components:

- Request
- Endpoint
- Response

Here's an example solution structure in .NET.
You'll notice the `Features` folder, which contains the vertical slices.
Each vertical slice implements one API request (or use case).

```
🔗 RunTracker.API
|__ 📁 Database
|__ 📁 Entities
    |__ #️⃣ Activity.cs
    |__ #️⃣ Workout.cs
    |__ #️⃣ ...
|__ 📁 Features
    |__ 📁 Activities
        |__ 📁 GetActivity
            |__ #️⃣ ActivityResponse.cs
            |__ #️⃣ GetActivityEndpoint.cs
            |__ #️⃣ GetActivityQuery.cs
            |__ #️⃣ GetActivityQueryHandler.cs
        |__ 📁 CreateActivity
            |__ #️⃣ CreateActivity.cs
                |__ #️⃣ CreateActivity.Command.cs
                |__ #️⃣ CreateActivity.Endpoint.cs
                |__ #️⃣ CreateActivity.Handler.cs
                |__ #️⃣ CreateActivity.Validator.cs
    |__ 📁 Workouts
    |__ 📁 ...
|__ 📁 Middleware
|__ 📄 appsettings.json
|__ 📄 appsettings.Development.json
|__ #️⃣ Program.cs
```

A few more libraries for implementing the REPR pattern:

- [FastEndpoints](https://github.com/FastEndpoints/FastEndpoints)
- [ApiEndpoints](https://github.com/ardalis/ApiEndpoints)

## Next Steps

Some of you may not like the idea of grouping all the files related to a feature in a single folder.

However, there's a lot of value in grouping by features in general.
You don't have to implement vertical slices.
But you can apply this concept to your domain by grouping files around aggregates, for example.
This is the approach I show in [**Pragmatic Clean Architecture.**](pragmatic-clean-architecture)

I made a video about [**Vertical Slice Architecture,**](https://youtu.be/msjnfdeDCmo)
showing how to implement the concepts discussed in today's issue. Check it out [**here.**](https://youtu.be/msjnfdeDCmo)

Thanks for reading, and stay awesome!

---



<Sponsorships>

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

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

</Sponsorships>

How should you handle errors in your code?

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

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

Exceptions are for exceptional situations.

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

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

## Exceptions For Flow Control

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

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

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

Another common use case is throwing exceptions for validation errors.

Here's an example in the `FollowerService`:

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

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

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

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

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

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

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

## Use Exceptions for Exceptional Situations

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

You can group all application errors into two groups:

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

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

What about the errors you know how to handle?

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

## Expressing Errors Using the Result Pattern

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

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

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

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

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

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

        IsSuccess = isSuccess;
        Error = error;
    }

    public bool IsSuccess { get; }

    public bool IsFailure => !IsSuccess;

    public Error Error { get; }

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

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

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

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

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

## Applying the Result Pattern

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

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

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

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

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

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

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

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

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

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

        _followerRepository.Insert(follower);

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

## Documenting Application Errors

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

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

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

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

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

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

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

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

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

## Converting Results Into API Responses

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

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

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

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

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

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

Here's the implementation of `Match`:

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

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

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

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

Much more concise. Don't you think so?

## Summary

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

Using the `Result` class allows you to:

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

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

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

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

See you next week.

---



<Sponsorships>

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

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

</Sponsorships>

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

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

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

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

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

But first, we have to understand what CQRS is.

## What Exactly is CQRS?

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

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

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

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

## How Is It Different From CQS?

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

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

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

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

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

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

## Many Flavors of CQRS

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

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

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

There are many flavors of this approach:

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

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

## Logical CQRS Architecture

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

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

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

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

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

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

## Implementing CQRS With MediatR

Implementing CQRS with MediatR has two components:

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

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

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

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

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

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

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

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

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

        return NoContent();
    }
}

```

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

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

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

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

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

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

        if (result.IsFailure)
        {
            return result;
        }

        await _unitOfWork.SaveChangesAsync(cancellationToken);

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

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

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

    private readonly ISqlConnectionFactory _sqlConnectionFactory;

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

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

        using var connection = _sqlConnectionFactory.CreateConnection();

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

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

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

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

## Closing Thoughts

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

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

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

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

Stay awesome!

---



<Sponsorships>

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

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

</Sponsorships>

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

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

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

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

## What is Dependency Injection?

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

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

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

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

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

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

        return Ok(activities);
    }
}
```

## Service Lifetimes in ASP.NET Core

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

ASP.NET Core provides three main lifetimes:

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

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

## What is Scrutor?

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

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

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

```powershell
Install-Package Scrutor
```

## Assembly Scanning With Scrutor

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

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

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

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

Let's unpack what's happening here:

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

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

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

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

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

## Service Decoration With Scrutor

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

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

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

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

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

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

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

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

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

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

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

## Takeaway

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

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

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

Hope this was valuable.

Stay awesome!

---



<Sponsorships>

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

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

</Sponsorships>

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

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

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

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

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

Let's dive in!

## What is NServiceBus?

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

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

Why is this significant?

Message-driven architectures offer several advantages:

- Asynchronous communication
- Loose coupling
- Reliability

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

## Configuring the NServiceBus Endpoint

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

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

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

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

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

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

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

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

    endpointConfiguration.EnableInstallers();

    return endpointConfiguration;
});

var app = builder.Build();

app.Run();
```

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

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

## Publishing Messages in NServiceBus

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

NServiceBus supports three types of messages:

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

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

Let's create our first message contract:

```csharp
using NServiceBus;

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

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

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

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

    await context.SaveChangesAsync();

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

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

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

## Handling Messages With NServiceBus

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

Here's an implementation of the `WorkoutCreatedHandler`:

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

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

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

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

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

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

## In Summary

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

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

Further reading:

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

Hope this was helpful.

I'll see you next week!

---



<Sponsorships>

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

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

</Sponsorships>

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

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

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

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

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

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

Let's dive in.

## The Standard Command Validation Approach

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

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

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

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

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

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

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

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

What if we can separate command validation and command handling?

## Input Validation and Business Validation

I mentioned input and _business_ validation in the previous section.

Here's how I consider them to be different:

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

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

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

## Input Validation With FluentValidation

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

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

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

    public string ShippingMethod { get; set; }

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

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

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

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

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

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

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

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

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

## Running Validation From the Use Case

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

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

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

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

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

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

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

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

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

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

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

## MediatR Validation Pipeline

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

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

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

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

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

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

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

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

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

        var response = await next();

        return response;
    }
}
```

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

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

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

## Handling Validation Exceptions

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

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

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

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

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

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

            context.Response.StatusCode = StatusCodes.Status400BadRequest;

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

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

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

## Takeaway

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

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

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

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

Hope this was valuable.

Stay awesome!

---



<Sponsorships>

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

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

</Sponsorships>

You start building a beautiful monolith system.
Maybe a modular monolith.

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

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

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

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

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

That is the topic of this week's newsletter.

Let's dive in!

## Decoupling Using Bounded Contexts

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

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

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

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

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

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

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

- Database dependencies
- Communication between modules

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

## How a Modular Monolith Solves Coupling

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

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

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

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

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

Here are two principles to solve database coupling:

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

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

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

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

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

## Adding a Message Broker To The System

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

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

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

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

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

What is the purpose of messaging inside a modular monolith?

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

## Extracting Modules to Microservices

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

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

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

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

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

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

## Closing Thoughts

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

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

Which is why a Modular monolith is an excellent approach.

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

Migrating to microservices comes down to extracting the modules into individual services.

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

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

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

Until then, I hope this was valuable.

See you next week!

---


Previous issues of The .NET Weekly