
<Sponsorships>

Learn about Postman with [**Postman Intergalactic sessions.**](https://www.postman.com/events/intergalactic)
Whether you're a developer or a tester, there's something for you.
Collaborate on API development with workspaces.
Sync your data across devices.
And it's free.
[**Get Postman here!**](https://www.postman.com/downloads)

Introducing [**Shesha**](https://shesha.io?utm_source=milan&utm_medium=email&utm_campaign=20240106), a brand new, open-source, low-code framework for .NET developers.
Create business applications faster and with >80% less code! [**Find out more here.**](https://shesha.io?utm_source=milan&utm_medium=email&utm_campaign=20240106)

</Sponsorships>

[MassTransit](https://masstransit.io/) is an open-source distributed application framework for .NET.
It provides a messaging abstraction on top of the supported message transports.
MassTransit lets you focus on adding business value instead of worrying about messaging complexity.

MassTransit supports many message transport technologies.
Here are a few that are popular:

- RabbitMQ
- Azure Service Bus
- Amazon SQS
- Kafka

In today's newsletter, I'll show you how to install and configure MassTransit in .NET.
We'll connect MassTransit to a few message brokers - RabbitMQ and Azure Service Bus.
And we will also cover how to publish and consume messages with MassTransit.

## Why Use MassTransit?

MassTransit solves many challenges of building distributed applications.
You (almost) don't have to think about the underlying message transport.
This allows you to focus on providing business value.

Here are a few things MassTransit does for you:

- **Message routing** - Type-based publish/subscribe, automatic broker topology configuration
- **Exception handling** - Messages can be retried or moved to an error queue
- **Dependency injection** - Service collection configuration and scope service provider
- **Request-Response** - Handle requests with automatic response routing
- **Observability** - Native [Open Telemetry (OTEL)](https://opentelemetry.io/) support
- **Scheduling** - Schedule message delivery using transport delay, Quartz.NET, or Hangfire
- **Sagas** - Reliable, durable, event-driven workflow orchestration

Let's see how to start using MassTransit.

## Installing and Configuring MassTransit with RabbitMQ

You need to install the `MassTransit` library.
If you already have a message transport, you can install the respective transport library.
Let's add the `MassTransit.RabbitMQ` library to configure [RabbitMQ](https://www.rabbitmq.com/) as the transport mechanism.

```powershell
Install-Package MassTransit

Install-Package MassTransit.RabbitMQ
```

Then, you can configure the required services for `MassTransit`.
The `AddMassTransit` method accepts a delegate where you can configure many settings.
For example, you can set the messaging endpoints to use kebab case naming by calling `SetKebabCaseEndpointNameFormatter`.
This is also where you configure the transport mechanism.
Calling `UsingRabbitMq` allows you to connect RabbitMQ as the transport mechanism.

```csharp
builder.Services.AddMassTransit(busConfigurator =>
{
    busConfigurator.SetKebabCaseEndpointNameFormatter();

    busConfigurator.UsingRabbitMq((context, configurator) =>
    {
        configurator.Host("localhost", "/", h =>
        {
            h.Username("guest");
            h.Password("guest");
        });

        configurator.ConfigureEndpoints(context);
    });
});
```

MassTransit takes care of setting up the required broker topology.
RabbitMQ supports exchanges and queues, so messages are sent or published to exchanges.
RabbitMQ routes those messages through exchanges to the appropriate queues.

You can start RabbitMQ locally inside a Docker container:

```csharp
docker run -d --name rabbitmq -p 5672:5672
```

## Configuring MassTransit with Azure Service Bus

[Azure Service Bus](https://azure.microsoft.com/en-us/products/service-bus)
is a cloud-based message broker with support for queues and topics.
MassTransit fully supports Azure Service Bus, including many advanced features and capabilities.
However, you must be on the Standard or Premium tier of the Microsoft Azure Service Bus service.

To configure MassTransit to work with Azure Service Bus, you need to install the required transport library:

```powershell
Install-Package MassTransit.Azure.ServiceBus.Core
```

Then, you can connect to Azure Service Bus by calling `UsingAzureServiceBus` and providing the connection string.
Everything else remains the same.
MassTransit takes care of configuring the broker topology.
MassTransit sends messages to topics, and Azure Service Bus routes those messages to the appropriate queues.

```csharp
builder.Services.AddMassTransit(busConfigurator =>
{
    busConfigurator.SetKebabCaseEndpointNameFormatter();

    busConfigurator.UsingAzureServiceBus((context, configurator) =>
    {
        configurator.Host("<CONNECTION_STRING>");

        configurator.ConfigureEndpoints(context);
    });
});
```

## Using the MassTransit In Memory Transport

You can also configure MassTransit to use an in-memory transport.
It's useful for testing, because it doesn't require a message broker to be running.
Another advantage is that it's fast.

However, there's a big problem with the in-memory transport - **it's not durable.**

If the message bus is stopped, all messages are lost.
Don't use the in-memory transport for production systems.

It will only work on a single machine.
So, it doesn't make sense for distributed applications.

```csharp
builder.Services.AddMassTransit(busConfigurator =>
{
    busConfigurator.SetKebabCaseEndpointNameFormatter();

    busConfigurator.UsingInMemory((context, configurator) =>
    {
        configurator.ConfigureEndpoints(context);
    });
});
```

## Message Types

MassTransit requires message types to be [reference types.](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/reference-types)
So, you can use a `class`, `record` or `interface` to define a message.

You'll often create two types of messages: commands and events.

A command is an instruction to perform some action.
Commands are intended to have exactly one consumer.
Commands are expressed using verbs first: `CreateArticle`, `PublishArticle`, `ShareArticle`.

An event represents that something of significance happened.
Events can have one or many consumers.
Events should have a name in the past tense: `ArticleCreated`, `ArticlePublished`, `ArticleShared`.

Here's an example `ArticleCreated` message containing information about an article:

```csharp
public record ArticleCreated
{
    public Guid Id { get; init; }
    public string Title { get; init; }
    public string Content { get; init; }
    public DateTime CreatedOnUtc { get; init; }
}
```

Using `public set` or `public init` properties is recommended to avoid serialization problems with `System.Text.Json`.

## Publishing and Consuming Messages

You can use the `IPublishEndpoint` service to publish messages with MassTransit.
The framework routes the message to the appropriate queue or topic based on the message type.

```csharp {3,5}
app.MapPost("article", async (
    CreateArticleRequest request,
    IPublishEndpoint publishEndpoint) =>
{
    await publishEndpoint.Publish(new ArticleCreated
    {
        Id = Guid.NewGuid(),
        Title = request.Title,
        Content = request.Content,
        CreatedOnUtc = DateTime.UtcNow
    });

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

To consume an `ArticleCreated` message, you need to implement the `IConsumer` interface.
The `IConsumer` has one `Consume` method where you place your business logic.
The consumer also gives you access to the `ConsumeContext`, which you can use to send further messages.

```csharp
public class ArticleCreatedConsumer(ApplicationDbContext dbContext)
    : IConsumer<ArticleCreatedEvent>
{
    public async Task Consume(ConsumeContext<ArticleCreatedEvent> context)
    {
        ArticleCreated message = context.Message;

        var article = new Article
        {
            Id = message.Id,
            Title = message.Title,
            Content = message.Content,
            CreatedOnUtc = message.CreatedOnUtc
        };

        dbContext.Add(article);

        await dbContext.SaveChangesAsync();
    }
}
```

MassTransit doesn't automatically know that the `ArticleCreatedConsumer` exists.
You have to configure the consumer when calling `AddMassTransit`.
The `AddConsumer` method registers the consumer type with the bus.

```csharp {5}
builder.Services.AddMassTransit(busConfigurator =>
{
    busConfigurator.SetKebabCaseEndpointNameFormatter();

    busConfigurator.AddConsumer<ArticleCreatedConsumer>();

    // ...
});
```

## Next Steps

**MassTransit** is an excellent messaging library I often use when building distributed applications.
The setup is straightforward, and there are only a few important abstractions.
You need to know abstraction for publishing messages (`IPublishEndpoint`) and consuming messages (`IConsumer`).
MassTransit takes care of doing the heavy lifting for you.

If you aren't already using it, I highly recommend adding MassTransit to your toolbox.

Here are some more practical **MassTransit learning resources**:

- [Request-Response pattern with MassTransit](https://youtu.be/NjsoykEOkrk)
- [RabbitMQ and MassTransit tutorial](https://youtu.be/CTKWFMZVIWA)
- [Microservices with RabbitMQ](https://youtu.be/MzC0PgYocmk)
- [Saga pattern with RabbitMQ](implementing-the-saga-pattern-with-rebus-and-rabbitmq)
- [Orchestration vs Choreography](orchestration-vs-choreography)
- [Messaging with Azure Service Bus](messaging-made-easy-with-azure-service-bus)

That's all for today.

See you next week.

---



<Sponsorships>

[**ABP Framework**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w70)
is a platform for building enterprise-grade ASP.NET Core applications.
It comes with production-ready components, modular architecture, and Domain-Driven Design.
[**Get started here.**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w70)

[**IcePanel**](https://u.icepanel.io/1eec0e6f) is a C4 model diagramming tool for complex software systems.
Align your software engineering & product teams on technical decisions across the business.
[**Learn more here.**](https://u.icepanel.io/1eec0e6f)

</Sponsorships>

In the past year, I built and maintained a large public API.
The API has dozens of integrations, serving mainly mobile applications.

When your API is serving so many clients, breaking changes are expensive.

So, everything I implemented on the public API had to be planned.

Adding a new field? Forget about it.

Renaming existing fields? Forget about it.

If I wanted to introduce breaking changes, I had to version the API.

Today, I'll show you how to implement API versioning in ASP.NET Core.

## Why You Need API Versioning

API versioning allows your API to evolve independently from the clients using it.

Introducing breaking changes to your API is a bad user experience.
API versioning gives you a mechanism to avoid exposing breaking changes to clients.
Instead of making a breaking change, you introduce a new API version.

What's the definition of a breaking change?

This isn't an exhaustive list, but a few examples of breaking changes are:

- Removing or renaming APIs or API parameters
- Changing the behavior of existing APIs
- Changing the API response contract
- Changing the API error codes

You can decide what a breaking change means for your API.
For example, adding a new field to the response doesn't have to be a breaking change.

Let's see how to implement API versioning.

## Implementing API Versioning in ASP.NET Core

Let's start by installing three NuGet packages that we'll need to implement API versioning:

- `Asp.Versioning.Http`
- `Asp.Versioning.Mvc`
- `Asp.Versioning.Mvc.ApiExplorer`

```powershell
Install-Package Asp.Versioning.Http # This is needed for Minimal APIs
Install-Package Asp.Versioning.Mvc # This is needed for Controllers
Install-Package Asp.Versioning.Mvc.ApiExplorer
```

This allows us to call `AddApiVersioning` and provide a delegate to configure the `ApiVersioningOptions`.

```csharp
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Api-Version"));
})
.AddMvc() // This is needed for controllers
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'V";
    options.SubstituteApiVersionInUrl = true;
});
```

Here's the explanation for the `ApiVersioningOptions` properties:

- `DefaultApiVersion` - Sets the default API version. Typically, this will be `v1.0`.
- `ReportApiVersions` - Reports the supported API versions in the `api-supported-versions` response header.
- `AssumeDefaultVersionWhenUnspecified` - Uses the `DefaultApiVersion` when the client didn't provide an explicit version.
- `ApiVersionReader` - Configures how to read the API version specified by the client. The default value is `QueryStringApiVersionReader`.

The `AddApiExplorer` method is helpful if you are using Swagger.
It will fix the endpoint routes and substitute the API version route parameter.

## Different Types of API Versioning

The most common ways to implement API versioning are:

- URL versioning: `https://localhost:5001/api/v1/workouts`
- Header versioning: `https://localhost:5001/api/workouts -H 'X-Api-Version: 1'`
- Query parameter versioning: `https://localhost:5001/api/workouts?api-version=1`

There are a few other ways to implement API versioning.
For example, using the `accept` or `content-type` headers.
But they aren't used often.

The `Asp.Versioning.Http` library has a few `IApiVersionReader` implementations:

- `UrlSegmentApiVersionReader`
- `HeaderApiVersionReader`
- `QueryStringApiVersionReader`
- `MediaTypeApiVersionReader`

[Microsoft's API versioning guidelines](https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#12-versioning)
suggest using URL or query string parameter versioning.

I use URL versioning almost exclusively in the applications I'm developing.

## Versioning Controllers

To implement API versioning in ASP.NET controllers, you have to decorate the controller with the `ApiVersion` attribute.

The `ApiVersion` attribute allows you to specify which API versions that `WorkoutsController` supports.
In this case, the controller supports both `v1` and `v2`.
You use the `MapToApiVersion` attribute on the endpoints to specify the concrete API version.

The route parameter `v{v:apiVersion}` lets you specify the API version using `v1` or `v2` in the URL.

```csharp {1,2,7,14}
[ApiVersion(1)]
[ApiVersion(2)]
[ApiController]
[Route("api/v{v:apiVersion}/workouts")]
public class WorkoutsController : ControllerBase
{
    [MapToApiVersion(1)]
    [HttpGet("{workoutId}")]
    public IActionResult GetWorkoutV1(Guid workoutId)
    {
        return Ok(new GetWorkoutByIdQuery(workoutId).Handle());
    }

    [MapToApiVersion(2)]
    [HttpGet("{workoutId}")]
    public IActionResult GetWorkoutV2(Guid workoutId)
    {
        return Ok(new GetWorkoutByIdQuery(workoutId).Handle());
    }
}
```

## Deprecating API Versions

If you want to deprecate an old API version, you can set the `Deprecated` property on the `ApiVersion` attribute.
The deprecated API versions will be reported using the `api-deprecated-versions` response header.

```csharp {1}
[ApiVersion(1, Deprecated = true)]
[ApiVersion(2)]
[ApiController]
[Route("api/v{v:apiVersion}/workouts")]
public class WorkoutsController : ControllerBase
{
}
```

## Versioning Minimal APIs

Versioning Minimal APIs requires you to define an `ApiVersionSet`, which you'll pass to the endpoints.

- `NewApiVersionSet` - Creates a new `ApiVersionSetBuilder` that you can use to configure the `ApiVersionSet`.
- `HasApiVersion` - Indicates that the `ApiVersionSet` supports the specified `ApiVersion`.
- `ReportApiVersions`- Indicates that all APIs in the `ApiVersionSet` will report their versions.

After creating the `ApiVersionSet`, you must pass it to a Minimal API endpoint by calling `WithApiVersionSet`.
You can map to an explicit API version by calling `MapToApiVersion`.

```csharp {1,18,19}
ApiVersionSet apiVersionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1))
    .HasApiVersion(new ApiVersion(2))
    .ReportApiVersions()
    .Build();

app.MapGet("api/v{version:apiVersion}/workouts/{workoutId}", async (
    Guid workoutId,
    ISender sender,
    CancellationToken ct) =>
{
    var query = new GetWorkoutByIdQuery(workoutId);

    Result<WorkoutResponse> result = await sender.Send(query, ct);

    return result.Match(Results.Ok, CustomResults.Problem);
})
.WithApiVersionSet(apiVersionSet)
.MapToApiVersion(1);
```

Specifying the `ApiVersionSet` for each Minimal API endpoint can be cumbersome.
So you can define a route group and set the `ApiVersionSet` only once.
Route groups are also practical because they allow you to specify the route prefix.

```csharp {7,8}
ApiVersionSet apiVersionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1))
    .ReportApiVersions()
    .Build();

RouteGroupBuilder group = app
    .MapGroup("api/v{version:apiVersion}")
    .WithApiVersionSet(apiVersionSet);

group.MapGet("workouts", ...);
group.MapGet("workouts/{workoutId}", ...);
```

## Takeaway

API versioning is one of the best practices for designing modern APIs.
Consider implementing API versioning from the first release.
This makes it easier for clients to support future API versions.
And it gets your team used to managing breaking changes and versioning the API.

You can use the `Asp.Versioning.Http` library to add API versioning in ASP.NET Core.
Define the supported API versions, and start using them in your endpoints.

Remember to agree as a team what represents a breaking change.
This should be well documented in the team's API design guidelines.

My preferred way to implement API versioning is using URL versioning. It's simple and explicit.

And since this is the last issue for the year, I wish you a happy and prosperous new year.

Thanks for reading, and stay awesome!

---



<Sponsorships>

[**Telerik UI for Blazor**](https://www.telerik.com/blogs/net-8-support-aspnet-core-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)
and [**Telerik UI ASP.NET Core**](https://www.telerik.com/blogs/net-8-support-aspnet-core-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)
libraries allow developers to immediately utilize the advanced features and performance benefits of .NET 8.
[**Check out the key .NET 8 new features here.**](https://www.telerik.com/blogs/net-8-support-aspnet-core-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)

[**IcePanel**](https://u.icepanel.io/1eec0e6f) is a C4 model diagramming tool for complex software systems.
Align your software engineering & product teams on technical decisions across the business.
[**Learn more here.**](https://u.icepanel.io/1eec0e6f)

</Sponsorships>

**Value Objects** are one of the building blocks of Domain-Driven Design.
DDD is a software development approach for solving problems in complex domains.

Value objects encapsulate a set of primitive values and related invariants.
A few examples of value objects are money and date range objects.
Money consists of an amount and currency.
A date range consists of start and end dates.

Today, I'll show you some best practices for implementing Value Objects.

## What are Value Objects?

Let's start with the definition from the Domain-Driven Design book:

> An object that represents a descriptive aspect of the domain with no conceptual identity is called a Value Object.
> Value Objects are instantiated to represent elements of the design that we care about only for what they are, not who or which they are.

_&mdash; [Eric Evans](http://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)_

Value objects are different from entities - they don't have a concept of identity.
They encapsulate primitive types in the domain and solve [primitive obsession.](https://refactoring.guru/smells/primitive-obsession)

There are two main qualities of Value Objects:

- They are immutable
- They have no identity

Another quality of value objects is structural equality.
Two value objects are equal if their values are the same.
This quality is the least important in practice.
However, there are cases where you want only some values to determine equality.

## Implementing Value Objects

The most important quality of value objects is immutability.
The values of a value object can't change once an object is created.
If you want to change an individual value, you need to replace the entire value object.

Here's a `Booking` entity with primitive values representing an address and the start and end dates of the booking.

```csharp
public class Booking
{
    public string Street { get; init; }
    public string City { get; init; }
    public string State { get; init; }
    public string Country { get; init; }
    public string ZipCode { get; init; }

    public DateOnly StartDate { get; init; }
    public DateOnly EndDate { get; init; }
}
```

You can replace these primitive values with `Address` and `DateRange` value objects.

```csharp
public class Booking
{
    public Address Address { get; init; }

    public DateRange Period { get; init; }
}
```

But how do you implement value objects?

### C# Records

You can use C# [records](records-anonymous-types-non-destructive-mutation) to represent value objects.
Records are immutable by design, and they have structural equality.
We want both of these qualities for our value objects.

For example, you can represent an `Address` value object using a `record` with a [primary constructor.](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/instance-constructors#primary-constructors)
The advantage of this approach is conciseness.

```csharp
public record Address(
    string Street,
    string City,
    string State,
    string Country,
    string ZipCode);
```

However, you lose this advantage when defining a private constructor.
This will happen when you want to enforce invariants while creating the value object.
Another issue with using records is avoiding value object invariants using the `with` expression.

```csharp
public record Address
{
    private Address(
        string street,
        string city,
        string state,
        string country,
        string zipCode)
    {
        Street = street;
        City = city;
        State = state;
        Country = country;
        ZipCode = zipCode;
    }

    public string Street { get; init; }
    public string City { get; init; }
    public string State { get; init; }
    public string Country { get; init; }
    public string ZipCode { get; init; }

    public static Result<Address> Create(
        string street,
        string city,
        string state,
        string country,
        string zipCode)
    {
        // Check if the address is valid

        return new Address(street, city, state, country, zipCode);
    }
}
```

### Base Class

The alternative way to implement value objects is with a `ValueObject` base class.
The base class handles structural equality with the `GetAtomicValues` abstract method.
`ValueObject` implementations have to implement this method and define the equality components.

The advantage of using a `ValueObject` base class is that it's explicit.
It's clear which classes in your domain represent value objects.
Another advantage is being able to control the equality components.

Here's a `ValueObject` base class I use in my projects:

```csharp
public abstract class ValueObject : IEquatable<ValueObject>
{
    public static bool operator ==(ValueObject? a, ValueObject? b)
    {
        if (a is null && b is null)
        {
            return true;
        }

        if (a is null || b is null)
        {
            return false;
        }

        return a.Equals(b);
    }

    public static bool operator !=(ValueObject? a, ValueObject? b) =>
        !(a == b);

    public virtual bool Equals(ValueObject? other) =>
        other is not null && ValuesAreEqual(other);

    public override bool Equals(object? obj) =>
        obj is ValueObject valueObject && ValuesAreEqual(valueObject);

    public override int GetHashCode() =>
        GetAtomicValues().Aggregate(
            default(int),
            (hashcode, value) =>
                HashCode.Combine(hashcode, value.GetHashCode()));

    protected abstract IEnumerable<object> GetAtomicValues();

    private bool ValuesAreEqual(ValueObject valueObject) =>
        GetAtomicValues().SequenceEqual(valueObject.GetAtomicValues());
}
```

The `Address` value object implementation would look like this:

```csharp
public sealed class Address : ValueObject
{
    public string Street { get; init; }
    public string City { get; init; }
    public string State { get; init; }
    public string Country { get; init; }
    public string ZipCode { get; init; }

    protected override IEnumerable<object> GetAtomicValues()
    {
        yield return Street;
        yield return City;
        yield return State;
        yield return Country;
        yield return ZipCode;
    }
}
```

## When To Use Value Objects?

I use value objects to solve primitive obsession and encapsulate domain invariants.
Encapsulation is an important aspect of any domain model.
You shouldn't be able to create a value object in an invalid state.

Value objects also give you type safety.
Take a look at this method signature:

```csharp
public interface IPricingService
{
    decimal Calculate(Apartment apartment, DateOnly start, DateOnly end);
}
```

Then, compare it to this method signature, where we added value objects.
You can see how the `IPricingService` with value objects is much more explicit.
You also get the benefit of type safety.
When compiling the code, value objects reduce the chance of errors creeping in.

```csharp
public interface IPricingService
{
    PricingDetails Calculate(Apartment apartment, DateRange period);
}
```

Here are a few more things you should consider to decide if you need value objects:

- **Complexity of invariants** - If enforcing complex invariants, consider using value objects
- **Number of primitives** - Value objects make sense when encapsulating many primitive values
- **Number of duplications** - If you need to enforce invariants only in a few places in the code, you can manage without value objects

## Persisting Value Objects With EF Core

Value objects are part of domain entities, and you need to save them in the database.

I'll show you how to use EF [Owned Types](https://learn.microsoft.com/en-us/ef/core/modeling/owned-entities)
and [Complex Types](https://devblogs.microsoft.com/dotnet/announcing-ef8-rc1/#complex-types-as-value-objects)
to persist value objects.

### Owned Types

[Owned Types](https://learn.microsoft.com/en-us/ef/core/modeling/owned-entities) can be configured by calling the `OwnsOne` method when configuring the entity.
This tells EF to persist the `Address` and `Price` value objects to the same table as the `Apartment` entity.
The value objects are represented with additional columns in the `apartments` table.

```csharp {5,7-13}
public void Configure(EntityTypeBuilder<Apartment> builder)
{
    builder.ToTable("apartments");

    builder.OwnsOne(property => property.Address);

    builder.OwnsOne(property => property.Price, priceBuilder =>
    {
        priceBuilder.Property(money => money.Currency)
            .HasConversion(
                currency => currency.Code,
                code => Currency.FromCode(code));
    });
}
```

A few more remarks about owned types:

- Owned types have a hidden key value
- No support for optional (nullable) owned types
- Owned collections are supported with `OwnsMany`
- Table splitting allows you to persist owned types separately

### Complex Types

[Complex Types](https://devblogs.microsoft.com/dotnet/announcing-ef8-rc1/#complex-types-as-value-objects) are a new EF feature available in .NET 8.
They aren't identified or tracked by a key value.
Complex types have to be part of an entity type.

Complex types are more appropriate for representing value objects with EF.

Here's how you can configure an `Address` value object as a complex type:

```csharp {5}
public void Configure(EntityTypeBuilder<Apartment> builder)
{
    builder.ToTable("apartments");

    builder.ComplexProperty(property => property.Address);
}
```

A few limitations for complex types:

- No support for collections
- No support for nullable values

## Takeaway

Value objects help design a rich domain model.
You can use them to solve primitive obsession and encapsulate domain invariants.
Value objects can reduce errors by preventing the instantiation of invalid domain objects.

You can use a `record` or `ValueObject` base class to represent value objects.
This should depend on your specific requirements and the complexity of your domain.
I use records by default unless I need some qualities of a `ValueObject` base class.
For example, a base class is practical when you want to control equality components.

More learning material about value objects:

- [Solving primitive obsession with value objects](https://youtu.be/P5CRea21R2E)
- [Using EF 8 Complex types for value objects](https://youtu.be/LhCD5CUSP6g)

Hope this was helpful.

See you next week.

---



<Sponsorships>

Do you need to [**export PDF/UA documents in C#?**](https://ironpdf.com/how-to/pdfa/?utm_source=milan&utm_medium=email&utm_campaign=milan)
PDF compliance in highly regulated industries can be extremely time-consuming.
Solution: [**IronPDF free trial.**](https://ironpdf.com/how-to/pdfa/?utm_source=milan&utm_medium=email&utm_campaign=milan)
Test your use case with full IronPDF functionality and access to documentation.

[**Product for Engineers**](https://newsletter.posthog.com/) from PostHog is a newsletter helping engineers improve their product skills.
You will get practical advice on building great products, lessons (and mistakes) from PostHog, and deep dives on top startups.
[**Subscribe here for FREE.**](https://newsletter.posthog.com/)

</Sponsorships>

[Serilog](https://serilog.net/) is a [structured logging](structured-logging-in-asp-net-core-with-serilog) library for .NET.

It's also my preferred logging library in the projects I'm developing.

Serilog supports many logging destinations called [Sinks.](https://github.com/serilog/serilog/wiki/Provided-Sinks)
The log destinations range from console and file sinks to managed logging services such as [Application Insights.](https://github.com/serilog-contrib/serilog-sinks-applicationinsights)

Today, I want to share 5 practical tips for better structured logging with Serilog.

## Use The Configuration System

There are two ways you can configure Serilog in ASP.NET Core:

- Fluent API
- Configuration system

The Fluent API allows you to write code and easily configure Serilog.
The downside is you are hardcoding your configuration.
Any configuration changes require deploying a new version.

I prefer using the ASP.NET configuration system to set up Serilog.
The benefit is you can change the logging configuration without redeploying your application.

You'll need to install the `Serilog.Settings.Configuration` library.

This allows you to configure Serilog using the configuration system:

```csharp
builder.Host.UseSerilog((context, loggerConfig) =>
    loggerConfig.ReadFrom.Configuration(context.Configuration));
```

Here's a Serilog configuration with [Console](https://github.com/serilog/serilog-sinks-console) and [Seq](https://github.com/datalust/serilog-sinks-seq) sinks.
We also configure a few [Serilog enrichers](https://github.com/serilog/serilog/wiki/Enrichment) to enrich application logs with extra information.

```json
{
  "Serilog": {
    "Using": ["Serilog.Sinks.Console", "Serilog.Sinks.Seq"],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Information"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "Seq",
        "Args": { "serverUrl": "http://localhost:5341" }
      }
    ],
    "Enrich": ["FromLogContext", "WithMachineName", "WithThreadId"]
  }
}
```

## Use Serilog Request Logging

You can install the `Serilog.AspNetCore` library to add Serilog logging for the ASP.NET Core request pipeline.
It adds ASP.NET's internal operations to the same Serilog sinks as your application events.

All you need to do is call the `UseSerilogRequestLogging` method:

```csharp
app.UseSerilogRequestLogging();
```

The `SourceContext` for these structured logs is `Serilog.AspNetCore.RequestLoggingMiddleware`.

Here's an example structured log produced by this middleware:

```json
{
  "@t": "2023-12-16T00:00:00.0000000Z",
  "@mt": "HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms",
  "@m": "HTTP POST /api/users responded 409 in 24.7928 ms",
  "@i": "37aa1435",
  "@r": ["24.7928"],
  "@tr": "61a449a8606fdb64e88d6c64b7b7354e",
  "@sp": "163ed90674cb12f6",
  "ConnectionId": "0HMVSP0L8FVEN",
  "CorrelationId": "0HMVSP0L8FVEN:0000000B",
  "Elapsed": 24.792778,
  "RequestId": "0HMVSP0L8FVEN:0000000B",
  "RequestMethod": "POST",
  "RequestPath": "/api/users",
  "SourceContext": "Serilog.AspNetCore.RequestLoggingMiddleware",
  "StatusCode": 409
}
```

## Enrich Your Logs With CorrelationId

How can you track all the logs belonging to the same request?

You can add a `CorrelationId` property to your structured logs.

This also works across multiple applications.
You need to pass the `CorrelationId` using an HTTP header.
For example, you could use a custom `X-Correlation-Id` header.

In the `RequestContextLoggingMiddleware`, I'm adding the `CorrelationId` to the Serilog [`LogContext`](https://github.com/serilog/serilog/wiki/Enrichment#the-logcontext).
This will make it available to all logs created during this application request.

```csharp
public class RequestContextLoggingMiddleware
{
    private const string CorrelationIdHeaderName = "X-Correlation-Id";
    private readonly RequestDelegate _next;

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

    public Task Invoke(HttpContext context)
    {
        string correlationId = GetCorrelationId(context);

        using (LogContext.PushProperty("CorrelationId", correlationId))
        {
            return _next.Invoke(context);
        }
    }

    private static string GetCorrelationId(HttpContext context)
    {
        context.Request.Headers.TryGetValue(
            CorrelationIdHeaderName, out StringValues correlationId);

        return correlationId.FirstOrDefault() ?? context.TraceIdentifier;
    }
}
```

I like to create an extension method for adding the [middleware.](3-ways-to-create-middleware-in-asp-net-core)
The `UseRequestContextLogging` method will add the `RequestContextLoggingMiddleware` to the request pipeline.
Note that the order of registering middleware is important.
If you want the `CorrelationId` in all your logs, you want to place this middleware at the start.

```csharp
public static IApplicationBuilder UseRequestContextLogging(
    this IApplicationBuilder app)
{
    app.UseMiddleware<RequestContextLoggingMiddleware>();

    return app;
}
```

## Log Important Application Events

In general, I try to log important events in my application.
This includes current request information, errors, failures, unexpected values, branching points, etc.

I'm a proponent of using the [Result pattern](functional-error-handling-in-dotnet-with-the-result-pattern) to express application failures.
So, having a custom middleware to log request processing results is important.

Some developers prefer using exceptions to achieve the same functionality.
I disagree with this.
Using exceptions for flow control is a bad practice.
But still, don't forget to add a [global exception handler](global-error-handling-in-aspnetcore-8) for unhandled exceptions.

If you're using the [CQRS pattern with MediatR](cqrs-pattern-with-mediatr), you can easily add logging for all application requests.

In the `RequestLoggingPipelineBehavior` I'm pushing the `Error` property to the `LogContext`.
The error object is deconstructed into a JSON value in the structured log.
This lets me filter my logs based on the error details.

```csharp
internal sealed class RequestLoggingPipelineBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : class
    where TResponse : Result
{
    private readonly ILogger _logger;

    public RequestLoggingPipelineBehavior(ILogger logger)
    {
        _logger = logger;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        string requestName = typeof(TRequest).Name;

        _logger.LogInformation(
            "Processing request {RequestName}", requestName);

        TResponse result = await next();

        if (result.IsSuccess)
        {
            _logger.LogInformation(
                "Completed request {RequestName}", requestName);
        }
        else
        {
            using (LogContext.PushProperty("Error", result.Error, true))
            {
                _logger.LogError(
                    "Completed request {RequestName} with error", requestName);
            }
        }

        return result;
    }
}
```

## Use Seq for Local Development

[Seq](https://datalust.co/seq) is a self-hosted search, analysis, and alerting server built for structured log data.
It's free to use for local development.
It offers advanced search and filtering capabilities on the structured log data.

You can spin up a Seq instance in a [Docker](https://www.docker.com/) container:

```yaml
version: '3.4'

services:
  seq:
    image: datalust/seq:latest
    container_name: seq
    environment:
      - ACCEPT_EULA=Y
    ports:
      - 5341:5341
      - 8081:80
```

You can start filtering data when you configure Serilog to write application logs to the Seq instance.

<Image src="blogs/mnw_068/seq.png" width={1920} height={910} />

## Summary

Structured logs follow follow the same structure.
And since structured logs are machine-readable, you can search them for specific information.
Structured logs provide more context and details about application errors.
They make it easier to identify and fix problems.

You can use Serilog's powerful `LogContext` to enrich your logs with a `CorrelationId`.
This lets you easily track all logs related to a single application request.

When you have structured logging set up, you'll want to search and analyze your logs.
Seq is an excellent tool for this that you can use for local development.

If you want to get started with Seq, check out my [beginner Seq tutorial.](https://youtu.be/mT8ZkXafuZk)

Thanks for reading, and stay awesome!

---



<Sponsorships>

Every [**Blazor application**](https://www.telerik.com/blogs/how-to-toggle-between-light-dark-modes-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)
needs dark mode.
But how do you toggle between light and dark modes?
Find out how to install a dark/light mode switch easily with [**Telerik UI for Blazor.**](https://www.telerik.com/blogs/how-to-toggle-between-light-dark-modes-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)

[**ABP Framework**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w67)
is a platform for building enterprise-grade ASP.NET Core applications.
It comes with production-ready components, modular architecture, and Domain-Driven Design.
[**Get started here.**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w67)

</Sponsorships>

Modular monoliths are an architectural approach that's becoming very popular.
They combine the benefits of modularity and monolithic design.

Modular monoliths try to solve the shortcomings of monolithic and microservice architectures.

One problem I often see with monolithic architectures is tight coupling between components.

This leads to dependencies between different parts of the system.

Modular monoliths enforce better architectural practices with well-defined module boundaries and [**communication patterns.**](modular-monolith-communication-patterns)

But one aspect you can't overlook is data isolation between modules.

Data isolation ensures that modules are independent and loosely coupled.

Today, I will show you four data isolation approaches for modular monoliths:

- Separate table
- Separate schema
- Separate database
- Different persistence

## Why Is Data Isolation Important?

Let's first understand why data isolation is important in a modular monolith architecture.

A modular monolith has strict rules for data integrity:

- Each module can only access its own tables
- No sharing of tables or objects between modules
- Joins are only allowed between tables of the same module

Modules inside a modular monolith should be self-contained.
Each module handles its own data.
Other modules can access that data using the module's public API.

What are the benefits of this design?

Keeping modules isolated from each other promotes modularity and loose coupling.
It makes it easier to introduce new changes to the system.
There are fewer unintended side effects when components are loosely coupled.

If you are using a relational database, you can still maintain referential integrity.
Removing the foreign keys when extracting tables is not a problem.

<Image src="blogs/mnw_067/monolith_components.png" width={1748} height={991} />

## Level 1 - Separate Table

The simplest solution is to have no isolation at the database level.
Tables for all modules live inside one database.
It's not easy to determine which tables belong to which module.

I'm only mentioning this approach for the sake of completeness.

But this approach works fine up to a particular application size.

However, the more tables you have, the harder it becomes to keep them isolated between modules.

You can improve this by adding logical isolation between tables.

<Image src="blogs/mnw_067/separate_table.png" width={1758} height={848} />

## Level 2 - Separate Schema

Grouping related tables in the database is a way to introduce logical isolation.
You can implement this using database schemas.
Each module has a unique schema containing the module's tables.

Now, it becomes easy to distinguish which module contains which tables.

An easy way to implement this is using [**multiple EF Core database contexts.**](using-multiple-ef-core-dbcontext-in-single-application)

You can also introduce rules to prevent querying data from other modules.
For example, you could implement this using [**architecture tests.**](enforcing-software-architecture-with-architecture-tests)

I always start with logical data isolation when building a modular monolith.

But what if this isn't enough?

<Image src="blogs/mnw_067/separate_schema.png" width={1748} height={848} />

## Level 3 - Separate Database

The next data isolation level is moving each module's data into separate databases.
This approach has more constraints than data isolation using schemas.

This is the way to go if you need strict data isolation rules between modules.
But, the downside is more operational complexity.
You have to manage infrastructure for multiple databases.

However, this is an excellent step toward [**extracting modules.**](monolith-to-microservices-how-a-modular-monolith-helps)

First, you move the tables of the module you want to extract into a separate database.
This also forces you to solve any database coupling problems between your modules.
You're ready to extract the module once you move the tables into a separate database.

Can we take the module data isolation further?

<Image src="blogs/mnw_067/separate_db.png" width={1742} height={848} />

## Level 4 - Different Persistence

Who says you have to use the same database type for all modules?

I work with relational (SQL) databases most of the time.
Relational databases are amazing and solve a wide range of problems.
But sometimes, a document or graph database is a much better solution.

The idea here is similar: you're doing data isolation using separate databases.

However, you can introduce a different database type to solve specific problems.
For example, you can use a relational database for one module.
And a graph or column-store database for another module.
You also have to maintain different persistence models in your application.

This could be a worthwhile tradeoff for your use case.
But it takes careful planning.

<Image src="blogs/mnw_067/separate_db_type.png" width={1742} height={848} />

## Summary

Modular monoliths are excellent if you don't need microservices right away.
You develop your application as a monolith with distinct boundaries inside the system.
You still have the flexibility to [**extract modules and move to microservices.**](monolith-to-microservices-how-a-modular-monolith-helps)
But you have faster development speed with a modular monolith.

Modules have to comply with a few rules.
They can only access their own tables.
They can't share tables with other modules.
And they can't directly query tables of other modules.
These rules help to enforce data isolation between modules.

But you still have to implement data isolation at the database level.

There are four options you can choose from:

- Separate table
- Separate schema
- Separate database
- Different persistence

I always go for logical isolation using schemas.
It's easy to implement and helps me understand my boundaries better.
Depending on the requirements, I can introduce separate databases later.

Hope this was helpful.

See you next week.

---



<Sponsorships>

[**Product for Engineers**](https://newsletter.posthog.com/) from PostHog is a newsletter helping engineers improve their product skills.
[**Subscribe for free**](https://newsletter.posthog.com/) to get curated advice on building great products, lessons (and mistakes) from PostHog, and deep dives on top startups.

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

Exceptions are for exceptional situations.
I even wrote about [**avoiding exceptions entirely.**](functional-error-handling-in-dotnet-with-the-result-pattern)

But they will inevitably happen in your applications, and you need to handle them.

You can implement a global exception handling mechanism or handle only specific exceptions.

ASP.NET Core gives you a few options on how to implement this. So which one should you choose?

Today, I want to show you an _old_ and _new_ way to handle exceptions in ASP.NET Core 8.

## Old Way: Exception Handling Midleware

The standard to implement exception handling in ASP.NET Core is using middleware.
Middleware allows you to introduce logic before or after executing HTTP requests.
You can easily extend this to implement exception handling.
Add a `try-catch` statement in the middleware and return an error HTTP response.

There are [**3 ways to create middleware**](3-ways-to-create-middleware-in-asp-net-core) in ASP.NET Core:

- Using [**request delegates**](3-ways-to-create-middleware-in-asp-net-core#adding-middleware-with-request-delegates)
- By [**convention**](3-ways-to-create-middleware-in-asp-net-core#adding-middleware-by-convention)
- [`IMiddleware`](3-ways-to-create-middleware-in-asp-net-core#adding-factory-based-middleware)

The convention-based approach requires you to define an `InvokeAsync` method.

Here's an `ExceptionHandlingMiddleware` defined by convention:

```csharp
public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(
        RequestDelegate next,
        ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception exception)
        {
            _logger.LogError(
                exception, "Exception occurred: {Message}", exception.Message);

            var problemDetails = new ProblemDetails
            {
                Status = StatusCodes.Status500InternalServerError,
                Title = "Server Error"
            };

            context.Response.StatusCode =
                StatusCodes.Status500InternalServerError;

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

The `ExceptionHandlingMiddleware` will catch any unhandled exception and return a [Problem Details](https://www.rfc-editor.org/rfc/rfc7807.html) response.
You can decide how much information you want to return to the caller.
In this example, I'm hiding the exception details.

You also need to add this middleware to the ASP.NET Core request pipeline:

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

## New Way: IExceptionHandler

[ASP.NET Core 8](https://learn.microsoft.com/en-us/aspnet/core/introduction-to-aspnet-core?view=aspnetcore-8.0)
introduces a new [`IExceptionHandler`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler?view=aspnetcore-8.0)
abstraction for managing exceptions.
The built-in exception handler middleware uses `IExceptionHandler` implementations to handle exceptions.

This interface has only one `TryHandleAsync` method.

`TryHandleAsync` attempts to handle the specified exception within the ASP.NET Core pipeline.
If the exception can be handled, it should return `true`.
If the exception can't be handled, it should return `false`.
This allows you to implement custom exception-handling logic for different scenarios.

Here's a `GlobalExceptionHandler` implementation:

```csharp
internal sealed class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

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

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        _logger.LogError(
            exception, "Exception occurred: {Message}", exception.Message);

        var problemDetails = new ProblemDetails
        {
            Status = StatusCodes.Status500InternalServerError,
            Title = "Server error"
        };

        httpContext.Response.StatusCode = problemDetails.Status.Value;

        await httpContext.Response
            .WriteAsJsonAsync(problemDetails, cancellationToken);

        return true;
    }
}
```

## Configuring IExceptionHandler Implementations

You need two things to add an `IExceptionHandler` implementation to the ASP.NET Core request pipeline:

1. Register the `IExceptionHandler` service with dependency injection
2. Register the [`ExceptionHandlerMiddleware`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.diagnostics.exceptionhandlermiddleware?view=aspnetcore-8.0)
   with the request pipeline

You call the `AddExceptionHandler` method to register the `GlobalExceptionHandler` as a service.
It's registered with a [**singleton lifetime**](improving-aspnetcore-dependency-injection-with-scrutor).
So be careful about injecting services with a different lifetime.

I'm also calling `AddProblemDetails` to generate a [Problem Details](https://www.rfc-editor.org/rfc/rfc7807.html) response for common exceptions.

```csharp
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();
```

You also need to call `UseExceptionHandler` to add the `ExceptionHandlerMiddleware` to the request pipeline:

```csharp
app.UseExceptionHandler();
```

## Chaining Exception Handlers

You can add multiple `IExceptionHandler` implementations, and they're called in the order they are registered.
A possible use case for this is using exceptions for flow control.

You can define custom exceptions like `BadRequestException` and `NotFoundException`.
They correspond with the HTTP status code you would return from the API.

Here's a `BadRequestExceptionHandler` implementation:

```csharp
internal sealed class BadRequestExceptionHandler : IExceptionHandler
{
    private readonly ILogger<BadRequestExceptionHandler> _logger;

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

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        if (exception is not BadRequestException badRequestException)
        {
            return false;
        }

        _logger.LogError(
            badRequestException,
            "Exception occurred: {Message}",
            badRequestException.Message);

        var problemDetails = new ProblemDetails
        {
            Status = StatusCodes.Status400BadRequest,
            Title = "Bad Request",
            Detail = badRequestException.Message
        };

        httpContext.Response.StatusCode = problemDetails.Status.Value;

        await httpContext.Response
            .WriteAsJsonAsync(problemDetails, cancellationToken);

        return true;
    }
}
```

And here's a `NotFoundExceptionHandler` implementation:

```csharp
internal sealed class NotFoundExceptionHandler : IExceptionHandler
{
    private readonly ILogger<NotFoundExceptionHandler> _logger;

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

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        if (exception is not NotFoundException notFoundException)
        {
            return false;
        }

        _logger.LogError(
            notFoundException,
            "Exception occurred: {Message}",
            notFoundException.Message);

        var problemDetails = new ProblemDetails
        {
            Status = StatusCodes.Status404NotFound,
            Title = "Not Found",
            Detail = notFoundException.Message
        };

        httpContext.Response.StatusCode = problemDetails.Status.Value;

        await httpContext.Response
            .WriteAsJsonAsync(problemDetails, cancellationToken);

        return true;
    }
}
```

You also need to register both exception handlers by calling `AddExceptionHandler`:

```csharp
builder.Services.AddExceptionHandler<BadRequestExceptionHandler>();
builder.Services.AddExceptionHandler<NotFoundExceptionHandler>();
```

The `BadRequestExceptionHandler` will execute first and try to handle the exception.
If the exception isn't handled, `NotFoundExceptionHandler` will execute next and attempt to handle the exception.

## Takeaway

Using middleware for exception handling is an excellent solution in ASP.NET Core.
However, it's great that we have new options using the `IExceptionHandler` interface.
I will use the new approach in ASP.NET Core 8 projects.

I'm very much against using exceptions for flow control.
Exceptions are a last resort when you can't continue normal application execution.
The [**Result pattern**](functional-error-handling-in-dotnet-with-the-result-pattern) is a better alternative.

Exceptions are also [extremely expensive](https://github.com/dotnet/aspnetcore/issues/46280#issuecomment-1527898867),
as David Fowler noted:

<Image src="blogs/mnw_066/fowler_comment.png" width={1360} height={500} />

If you want to get rid of exceptions in your code, [**check out this video.**](https://youtu.be/WCCkEe_Hy2Y)

Thanks for reading, and stay awesome!

---



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

---


Previous issues of The .NET Weekly