
<Sponsorships>

[**Blending AI with UI:**](https://www.telerik.com/blogs/blending-ai-ui-crafting-llm-uis-blazor-angular-react-vue?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=dt_devcraft_wp_productivity_choose_component_library)
Crafting LLM UIs in Blazor, Angular, React and Vue.
See how user interfaces are benefitting from LLMs and how you can start to implement them into your Blazor, Angular, React or Vue app.
[**Learn more here.**](https://www.telerik.com/blogs/blending-ai-ui-crafting-llm-uis-blazor-angular-react-vue?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=dt_devcraft_wp_productivity_choose_component_library)

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

</Sponsorships>

The applications you build serve your users (customers) to help them solve some problems.
It's a common requirement that you will need to know who the current application user is.

How do you get the current user's information in a Clean Architecture use case?

Use cases live in the Application layer, where you can't introduce external concerns.
Otherwise, you will be breaking the dependency rule.

Let's say you want to know who the current user is to determine if they can access some resource.
This is your typical resource-based authorization check.
But you have to interact with the identity provider to get this information.
This breaks the [dependency rule in Clean Architecture.](clean-architecture-and-the-benefits-of-structured-software-design)

I've seen this problem confuse developers who are new to Clean Architecture.

In today's issue, I'll show you how to access the current user's information in a clean way.

## Start With an Abstraction

The inner layers in Clean Architecture define abstractions for external concerns.
From the Application layer's perspective, authentication and user identity are external concerns.

The Infrastructure layer deals with external concerns, including authentication and identity management.
This is where you would implement the abstraction.

My preferred approach is creating an `IUserContext` abstraction.
The main information I need is the `UserId` of the current user.
But you can expand the `IUserContext` with any other data you think is necessary.

```csharp
public interface IUserContext
{
    bool IsAuthenticated { get; }

    Guid UserId { get; }
}
```

Let's see how to implement the `IUserContext`.

## Implementing the UserContext

The `UserContext` class is the `IUserContext` implementation in the Infrastructure layer.
We need to inject the `IHttpContextAccessor`, which allows us to access the [`ClaimsPrincipal`](https://learn.microsoft.com/en-us/dotnet/api/system.security.claims.claimsprincipal?view=net-8.0)
through the `User` property.
The `ClaimsPrincipal` gives you access to the current user's claims, containing the required information.

In this example, I'm throwing an exception if any of the properties evaluate to `null`.
You can decide if throwing an exception makes sense for you.

I also want to share an important remark here about `IHttpContextAccessor`.
We're using it to access the `HttpContext` instance — **which only exists during an API request**.
Outside an API request, the `HttpContext` will be null, and the `UserContext` will throw an exception when accessing its properties.

```csharp
internal sealed class UserContext(IHttpContextAccessor httpContextAccessor)
    : IUserContext
{
    public Guid UserId =>
        httpContextAccessor
            .HttpContext?
            .User
            .GetUserId() ??
        throw new ApplicationException("User context is unavailable");

    public bool IsAuthenticated =>
        httpContextAccessor
            .HttpContext?
            .User
            .Identity?
            .IsAuthenticated ??
        throw new ApplicationException("User context is unavailable");
}
```

Here's the `GetUserId` extension method that's used in the `UserContext.UserId` property.
It's looking for a claim with the `ClaimTypes.NameIdentifier` name, and parsing that value into a `Guid`.
You can replace this with a different type to match the user identity in your system.

```csharp
internal static class ClaimsPrincipalExtensions
{
    public static Guid GetUserId(this ClaimsPrincipal? principal)
    {
        string? userId = principal?.FindFirstValue(ClaimTypes.NameIdentifier);

        return Guid.TryParse(userId, out Guid parsedUserId) ?
            parsedUserId :
            throw new ApplicationException("User id is unavailable");
    }
}
```

## Using The Current User Information

Now that you have the `IUserContext`, you can use it from the Application layer.

A common requirement is checking if the current user can access some resources.

Here's an example using the `GetInvoiceQueryHandler`, which queries the database for an invoice.
After projecting the result to an `InvoiceResponse` object, we check if the current user is the one to whom the invoice was issued.
You can also apply this check as part of the database query.
But performing it in memory lets you return a different response to the user when they aren't authorized.
For example, a [403 Forbidden](https://www.rfc-editor.org/rfc/rfc7231#section-6.5.3) might be appropriate.

```csharp {16}
class GetInvoiceQueryHandler(IAppDbContext dbContext, IUserContext userContext)
    : IQueryHandler<GetInvoiceQuery, InvoiceResponse>
{
    public async Task<Result<InvoiceResponse>> Handle(
        GetInvoiceQuery request,
        CancellationToken cancellationToken)
    {
        InvoiceResponse? invoiceResponse = await dbContext
            .Invoices
            .ProjectTo<InvoiceResponse>()
            .FirstOrDefaultAsync(
                invoice => invoice.Id == request.InvoiceId,
                cancellationToken);

        if (invoiceResponse is null ||
            invoiceResponse.IssuedToUserId != userContext.UserId)
        {
            return Result.Failure<InvoiceResponse>(InvoiceErrors.NotFound);
        }

        return invoiceResponse;
    }
}
```

## Takeaway

Incorporating user identity and authentication into [Clean Architecture](why-clean-architecture-is-great-for-complex-projects)
doesn't have to compromise the integrity of your design.
The Application layer should remain decoupled from external concerns such as identity management.

We respect the [Clean Architecture dependency rule](clean-architecture-and-the-benefits-of-structured-software-design) by
abstracting user-related information through the `IUserContext` interface and implementing it within the Infrastructure layer.

With this strategy, you can effectively manage user information, support authorization checks, and ensure your application remains robust and adaptable to future changes.

Remember, the key is in defining clear abstractions and respecting the architecture's boundaries.

Hope this was helpful.

See you next week.

---



<Sponsorships>

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

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

</Sponsorships>

[EF Core](https://learn.microsoft.com/en-us/ef/core/) is a fantastic ORM if you're building .NET applications.

But it's a tool like any other. And you can end up using it in a suboptimal way.

Today, I'll show you a simple idea I used to get an almost **4x performance improvement**.

I'm not saying you'll see the same result, but understanding the idea will make your queries faster.

## Why This Query is Suboptimal

Here's the example I want to use to explain this powerful idea.
It's taken from a production app I was working on, but I simplified it for this example.

We're using an `InvoiceService` to get a collection of invoices for a given company.
The invoices could come from a third-party API or some other persistence store.
We're lacking detailed line item information, so we're querying the database to fill in the missing data.

The highlighted [LINQ query](https://learn.microsoft.com/en-us/ef/core/querying/) below isn't bad by itself.
It returns all the line items in one database query (round trip).

But it's missing one important realization that can unlock further performance gains.

Because we're iterating over the invoices, we're **querying the database many times**.

```csharp {21-32}
app.MapGet("invoices/{companyId}", (
    long companyId,
    InvoiceService invoiceService,
    AppDbContext dbContext) =>
{
    IEnumerable<Invoice> invoices = invoiceService.GetForCompanyId(
        companyId,
        take: 10);

    var invoiceDtos = new List<InvoiceDto>();
    foreach (var invoice in invoices)
    {
        var invoiceDto = new InvoiceDto
        {
            Id = invoice.Id,
            CompanyId = invoice.CompanyId,
            IssuedDate = invoice.IssuedDate,
            DueDate = invoice.DueDate,
            Number = invoice.Number
        };

        var lineItemDtos = await dbContext
            .LineItems
            .Where(li => invoice.LineItemIds.Contains(li.Id))
            .Select(li => new LineItemDto
            {
                Id = li.Id,
                Name = li.Name,
                Price = li.Price,
                Quantity = li.Quantity
            })
            .ToArrayAsync();

        invoiceDto.LineItems = lineItemDtos;

        invoiceDtos.Add(invoiceDto);
    }

    return invoiceDtos;
});
```

Once you figure this out, the solution comes down to applying a simple idea.

Instead of fetching the line items for each invoice, we can query all the line items ahead of time.

## Batching to the Rescue

Here's the same query, but refactored to only query the line items once.
This means there's just a single round trip to the database.

There are three components to the final design:

- Querying all the `LineItems` in a single database round-trip
- Creating a `LineItemDto` dictionary for fast lookup

Once we have the dictionary, we can loop through the invoices and assign the line items.
Populating a line item becomes a dictionary lookup (cheap) instead of a database query (expensive).

Before deciding if this solution makes sense, you should consider a few more things.

How many records can you load from the database at once?

Each invoice contains ~20 line items on average, and we're only fetching ten invoices.
So, we're loading ~200 line items from the database.
Most applications can handle this load.
But things could be different if you're fetching thousands of rows.

```csharp {10-12,26-28,41}
app.MapGet("invoices/{companyId}", (
    long companyId,
    InvoiceService invoiceService,
    AppDbContext dbContext) =>
{
    IEnumerable<Invoice> invoices = invoiceService.GetForCompanyId(
        companyId,
        take: 10);

    long[] lineItemIds = invoices
        .SelectMany(invoice => invoice.LineItemIds)
        .ToArray();

    var lineItemDtos = await dbContext
        .LineItems
        .Where(li => lineItemIds.Contains(li.Id))
        .Select(li => new LineItemDto
        {
            Id = li.Id,
            Name = li.Name,
            Price = li.Price,
            Quantity = li.Quantity
        })
        .ToListAsync();

    Dictionary<long, LineItemDto> lineItemsDictionary =
        lineItemDtos.ToDictionary(keySelector: li => li.Id);

    var invoiceDtos = new List<InvoiceDto>();
    foreach (var invoice in invoices)
    {
        var invoiceDto = new InvoiceDto
        {
            Id = invoice.Id,
            CompanyId = invoice.CompanyId,
            IssuedDate = invoice.IssuedDate,
            DueDate = invoice.DueDate,
            Number = invoice.Number,
            LineItems = invoice
                .LineItemIds
                .Select(li => lineItemsDictionary[li])
                .ToArray()
        };

        invoiceDtos.Add(invoiceDto);
    }

    return invoiceDtos;
})
```

## How Much Faster?

It seems plausible that the batch variant would be faster. Right?

We have N queries (one per invoice) in the first version and a single query in the batched version.

Here are the benchmark results I got using [BenchmarkDotNet](https://github.com/dotnet/BenchmarkDotNet):

<Image src="blogs/mnw_075/benchmark.png" width={1613} height={286} alt="" />

The foreach version takes **1913.3 us** (microseconds) on average.\
The batched version takes **558.6 us** on average.

That's **3.42x faster** with the batched version. This is with a local SQL database.

The batched version should be even faster if you're querying a remote database because of the impact of network round-trip time.
It quickly adds up when you have N queries (foreach version).

## Takeaway

The power of this approach lies in its simplicity and efficiency.
By batching database queries, we significantly reduce the number of round trips to the database.
This is often one of the biggest performance bottlenecks.

But it's crucial to understand that this approach is not a one-size-fits-all solution.

EF Core offers many features and optimizations, but it's up to the developer to use them effectively.

Finally, always remember to measure and benchmark.
The improvements we saw in this case were quantified through benchmarks.
Without proper measurement, it's easy to make changes that inadvertently degrade performance.

Thanks for reading, and stay awesome!

---



<Sponsorships>

Introducing [**Shesha**](https://shesha.io?utm_source=milan&utm_medium=email&utm_campaign=20240127), 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=20240127)

Free eBook: [**How to Choose a Component Library?**](https://www.telerik.com/campaigns/devcraft/how-to-choose-a-component-library?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=dt_devcraft_wp_productivity_choose_component_library)
Practical advice for choosing the right component libraries for your business requirements.
[**Try the expert-curated solutions now!**](https://www.telerik.com/campaigns/devcraft/how-to-choose-a-component-library?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=dt_devcraft_wp_productivity_choose_component_library)

</Sponsorships>

A **URL shortener** is a simple yet powerful tool that converts long URLs into more manageable, shorter versions.
This is particularly useful for sharing links on platforms with character limits or improving user experience by reducing clutter.
Two popular URL shorteners are [Bitly](https://bitly.com/) and [TinyURL](https://tinyurl.com/app).
Designing a URL shortener is an interesting challenge with fun problems to solve.

But how would you build a URL shortener in .NET?

URL shorteners have two core functionalities:

- Generating a unique code for a given URL
- Redirecting users who access the short link to the original URL

Today, I'll guide you through the design, implementation, and considerations for creating your URL shortener.

## URL Shortener System Design

Here's the high-level system design for our URL shortener.
We want to expose two endpoints.
One to shorten a long URL and the other to redirect users based on a shortened URL.
The shortened URLs are stored in a [PostgreSQL](https://www.postgresql.org/) database in this example.
We can introduce a distributed cache like [Redis](https://redis.io/) to the system to improve read performance.

<Image
  src="blogs/mnw_074/url_shortener.png"
  width={2856}
  height={1617}
  alt="URL shortener system design. It contains two API endpoints, a PostgreSQL database, and a Redis cache."
/>

We first need to ensure a large number of short URLs.
We're going to assign a unique code to each long URL, and use it to generate the shortened URL.
The unique code length and set of characters determine how many short URLs the system can generate.
We will discuss this in more detail when we implement unique code generation.

We're going to use the random code generation strategy.
It's straightforward to implement and has an acceptably low rate of collisions.
The trade-off we're making is increased latency, but we will also explore other options.

## The Data Model

Let's start by figuring out what we will store in the database.
Our data model is straightforward.
We have a `ShortenedUrl` class representing the URLs stored in our system:

```csharp
public class ShortenedUrl
{
    public Guid Id { get; set; }

    public string LongUrl { get; set; } = string.Empty;

    public string ShortUrl { get; set; } = string.Empty;

    public string Code { get; set; } = string.Empty;

    public DateTime CreatedOnUtc { get; set; }
}
```

This class includes properties for the original URL (`LongUrl`), the shortened URL (`ShortUrl`), and a unique code (`Code`) that represents the shortened URL.
The `Id` and `CreatedOnUtc` fields are used for database and tracking purposes.
The users will send the unique `Code` to our system, which will try to find a matching `LongUrl` and redirect them.

In addition, we will also define an EF `ApplicationDbContext` class, which is responsible for configuring our entity and setting up our database context.
I'm doing two things here to improve performance:

- Configuring the `Code` maximum length with `HasMaxLength`
- Defining a unique index on the `Code` column

A unique index shields us from concurrency conflicts, so we will never have duplicate `Code` values persisted in the database.
Setting the maximum length for this column saves storage space, and it's a requirement for indexing string columns in some databases.

Note that some databases treat strings in a case-insensitive way.
This severely reduces the number of available short URLs.
You want to configure the database to treat the unique code in a case-sensitive way.

```csharp
public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions options)
        : base(options)
    {
    }

    public DbSet<ShortenedUrl> ShortenedUrls { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<ShortenedUrl>(builder =>
        {
            builder
                .Property(shortenedUrl => shortenedUrl.Code)
                .HasMaxLength(ShortLinkSettings.Length);

            builder
                .HasIndex(shortenedUrl => shortenedUrl.Code)
                .IsUnique();
        });
    }
}
```

## Unique Code Generation

The most crucial part of our URL shortener is generating a unique code for each URL.
There are a few different algorithms you can choose to implement this.
We want an even distribution of unique codes across all possible values.
This helps to reduce potential collisions.

I will implement a random, unique code generator with a predefined alphabet.
It's simple to implement, and the chance of collision is relatively low.
Still, there are more performant solutions than this, but more on this later.

Let's define a `ShortLinkSettings` class that contains two constants.
One is for defining the length of the unqualified code we will generate.
The other constant is the alphabet we will use to generate the random code.

```csharp
public static class ShortLinkSettings
{
    public const int Length = 7;
    public const string Alphabet =
        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
}
```

The alphabet has `62` characters, which gives us `62^7` possible unique code combinations.

If you're wondering, this is `3,521,614,606,208` combinations.

Spelled out: three trillion, five hundred twenty-one billion, six hundred fourteen million, six hundred six thousand, two hundred eight.

Those are quite a few unique codes, which will be enough for our URL shortener.

Now, let's implement our `UrlShorteningService`, which handles generating unique codes.
This service generates a random string of the specified length using our predefined alphabet.
It checks against the database to ensure uniqueness.

```csharp
public class UrlShorteningService(ApplicationDbContext dbContext)
{
    private readonly Random _random = new();

    public async Task<string> GenerateUniqueCode()
    {
        var codeChars = new char[ShortLinkSettings.Length];
        const int maxValue = ShortLinkSettings.Alphabet.Length;

        while (true)
        {
            for (var i = 0; i < ShortLinkSettings.Length; i++)
            {
                var randomIndex = _random.Next(maxValue);

                codeChars[i] = ShortLinkSettings.Alphabet[randomIndex];
            }

            var code = new string(codeChars);

            if (!await dbContext.ShortenedUrls.AnyAsync(s => s.Code == code))
            {
                return code;
            }
        }
    }
}
```

**Downsides and Improvement Points**

The downside of this implementation is increased latency because we're checking each code we generate against the database.
An improvement point could be generating the unique codes in the database ahead of time.

Another improvement point could be using a fixed number of iterations instead of an infinite loop.
In case of multiple collisions in a row, the current implementation would continue until a unique value is found.
Consider throwing an exception instead after a few collisions in a row.

## URL Shortening

Now that our core business logic is ready, we can expose an endpoint to shorten URLs.
We can use a simple Minimal API endpoint.

This endpoint accepts a URL, validates it, and then uses the `UrlShorteningService` to create a shortened URL, which is then saved to the database.
We return the full shortened URL to the client.

```csharp
public record ShortenUrlRequest(string Url);

app.MapPost("shorten", async (
    ShortenUrlRequest request,
    UrlShorteningService urlShorteningService,
    ApplicationDbContext dbContext,
    HttpContext httpContext) =>
{
    if (!Uri.TryCreate(request.Url, UriKind.Absolute, out _))
    {
        return Results.BadRequest("The specified URL is invalid.");
    }

    var code = await urlShorteningService.GenerateUniqueCode();

    var request = httpContext.Request;

    var shortenedUrl = new ShortenedUrl
    {
        Id = Guid.NewGuid(),
        LongUrl = request.Url,
        Code = code,
        ShortUrl = $"{request.Scheme}://{request.Host}/{code}",
        CreatedOnUtc = DateTime.UtcNow
    };

    dbContext.ShortenedUrls.Add(shortenedUrl);

    await dbContext.SaveChangesAsync();

    return Results.Ok(shortenedUrl.ShortUrl);
});
```

There is a minor [race condition](solving-race-conditions-with-ef-core-optimistic-locking) here, as we generate a unique code first and then insert it into the database.
A concurrent request could generate the same unique code and insert it into the database before we complete our transaction.
However, the chances of this happening are low, so I decided not to handle that case.

Remember that the unique index in the database is still guarding us against duplicate values.

## URL Redirection

The second use case for a URL shortener is redirection when accessing a shortened URL.

We will expose another Minimal API endpoint for this feature.
The endpoint will accept a unique code, find the respective shortened URL, and redirect the user to the original long URL.
You can implement additional validation for the specified code before checking if there's a shortened URL in the database.

```csharp
app.MapGet("{code}", async (string code, ApplicationDbContext dbContext) =>
{
    var shortenedUrl = await dbContext
        .ShortenedUrls
        .SingleOrDefaultAsync(s => s.Code == code);

    if (shortenedUrl is null)
    {
        return Results.NotFound();
    }

    return Results.Redirect(shortenedUrl.LongUrl);
});
```

This endpoint looks up the code in the database and, if found, redirects the user to the original long URL.
The response will have a [302 (Found) status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6.4.3) per the HTTP standards.

## URL Shortener Improvement Points

While our basic URL shortener is functional, there are several areas we can improve:

- **Caching**: Implement caching to reduce database load for frequently accessed URLs.
- **Horizontal Scaling**: Design the system to scale horizontally to handle increased load.
- **Data Sharding**: Implement data sharding to distribute data across multiple databases.
- **Analytics**: Introduce analytics to track URL usage and expose reports to users.
- **User Accounts**: Allow users to create accounts to manage their URLs.

We've covered the key components of building a URL shortener using .NET.
You can take this further and implement the improvements points for a more robust solution.

If you want to see me build this from scratch, here's a [video tutorial on YouTube.](https://youtu.be/2UoA_PoEvuA)

That's all for today.

See you next week.

---



<Sponsorships>

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

Become a Postman master with [**Postman Intergalactic sessions.**](https://www.postman.com/events/intergalactic)
Test your APIs with ease and collaborate on API development with workspaces.
And it's free.
[**Get Postman here!**](https://www.postman.com/downloads)

</Sponsorships>

Cross-cutting concerns are software aspects that affect the entire application.
These are your common application-level functionalities that span several layers and tiers.
Cross-cutting concerns should be centralized in one location.
This prevents code duplication and tight coupling between components.

A few examples of cross-cutting concerns are:

- Authentication & Authorization
- Logging and tracing
- Exception handling
- Validation
- Caching

In today's newsletter, I'll show you how to integrate cross-cutting concerns in Clean Architecture.

## Cross-Cutting Concerns in Clean Architecture

In Clean Architecture, [cross-cutting concerns](https://en.wikipedia.org/wiki/Cross-cutting_concern)
play an essential role in ensuring the maintainability and scalability of your system.
Ideally, these concerns should be handled separately from the core business logic.
This aligns with Clean Architecture's principles, emphasizing the decoupling of concerns and modularity.
Your core business rules remain uncluttered, and the architecture stays clean and adaptable.

Ideally, you want to implement cross-cutting concerns in the Infrastructure layer.
You can use ASP.NET Core middleware, [decorators](decorator-pattern-in-asp-net-core), or MediatR pipeline behaviors.
Whichever approach you decide to use, the guiding idea remains the same.

<Image
  src="blogs/mnw_073/clean_architecture_cross_cutting_concerns.png"
  width={2673}
  height={1947}
  alt="Cross-cutting concerns in Clean Architecture"
/>

Let's see how to implement logging, validation, and caching as cross-cutting concerns.

## Cross-Cutting Concern #1 - Logging

Logging is a fundamental aspect of software development, allowing you to look into an application's behavior.
It's vital for debugging, monitoring application health, and tracking user activities and system anomalies.
In the context of Clean Architecture, logging must be implemented in a way that maintains the separation of concerns.

An elegant way to achieve this is with [MediatR's](cqrs-pattern-with-mediatr) `IPipelineBehavior`.
By encapsulating the logging logic inside a pipeline behavior, we ensure that logging is treated as a distinct concern, separate from business logic.
This approach enables us to capture detailed information about requests flowing through the application.

Effective logging should be consistent, context-rich, and non-intrusive.
Using [Serilog's](5-serilog-best-practices-for-better-structured-logging) structured logging
capabilities, we can create logs that are not only informative but also easily queryable.
This is essential for understanding the state of the application at any given moment.

When done correctly, [structured logging](structured-logging-in-asp-net-core-with-serilog)
provides invaluable insights into your application without cluttering the core logic.
It's a balance of granularity and clarity, ensuring that your logs are a helpful tool rather than a source of noise.

```csharp
using Serilog.Context;

internal sealed class RequestLoggingPipelineBehavior<TRequest, TResponse>(
    ILogger<RequestLoggingPipelineBehavior<TRequest, TResponse>> logger)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : class
    where TResponse : Result
{
    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;
    }
}
```

## Cross-Cutting Concern #2 - Validation

Validation is a critical cross-cutting concern in software engineering.
It serves as the first line of defense against incorrect data entering your system.
Validation guards the application against inconsistent data states and potential security vulnerabilities.

In the example below, I'm creating a [validation pipeline behavior](cqrs-validation-with-mediatr-pipeline-and-fluentvalidation).
This setup allows for a clean separation of validation logic from business logic.
The pipeline behavior ensures that each request is validated before it reaches the core processing logic.

In approaching validation, it's crucial to distinguish between two types:

- Input validation
- Business rule validation

Input validation checks for the correctness and format of the data (like string length, number ranges, and date formats), ensuring it meets the basic criteria before processing.

On the other hand, business rule validation is more about ensuring that the data adheres to your domain's specific rules and logic.

Effective validation practices significantly contribute to the resilience and reliability of an application.
By enforcing validation rules, you can maintain a high data quality standard and ensure a better user experience.

```csharp
internal sealed class ValidationPipelineBehavior<TRequest, TResponse>(
    IEnumerable<IValidator<TRequest>> validators)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : class
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        ValidationFailure[] validationFailures = await ValidateAsync(request);

        if (validationFailures.Length != 0)
        {
            throw new ValidationException(validationFailures);
        }

        return await next();
    }

    private async Task<ValidationFailure[]> ValidateAsync(TRequest request)
    {
        if (!validators.Any())
        {
            return [];
        }

        var context = new ValidationContext<TRequest>(request);

        ValidationResult[] validationResults = await Task.WhenAll(
            validators.Select(validator => validator.ValidateAsync(context)));

        ValidationFailure[] validationFailures = validationResults
            .Where(validationResult => !validationResult.IsValid)
            .SelectMany(validationResult => validationResult.Errors)
            .ToArray();

        return validationFailures;
    }
}
```

## Cross-Cutting Concern #3: Caching

Caching is an essential cross-cutting concern in software development.
It's primarily aimed at enhancing performance and scalability.
Caching involves temporarily storing data in a fast-access layer.
This reduces the need to fetch or calculate the same information repeatedly.

The caching pipeline behavior, which you see below, implements the [Cache Aside pattern.](https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside)
This pattern involves checking the cache before processing the request and updating the cache with new data as needed.
It's a popular caching strategy due to its simplicity and effectiveness.
Here's a [video tutorial](https://youtu.be/LOEYZRE72wE) if you want to see how I implemented this.

When implementing caching, it's crucial to consider:

- **What to Cache:** Identify data that is expensive to compute or retrieve and stable enough to be cached.
- **Cache Invalidations:** Determine when and how cached data should be invalidated.
- **Cache Configuration:** Configure cache settings like expiration and size appropriately.

Effective caching improves response times and reduces the load on your system, making it a critical strategy for building scalable .NET applications.

```csharp
internal sealed class QueryCachingPipelineBehavior<TRequest, TResponse>(
    ICacheService cacheService,
    ILogger<QueryCachingPipelineBehavior<TRequest, TResponse>> logger)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : ICachedQuery
    where TResponse : Result
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        TResponse? cachedResult = await cacheService.GetAsync<TResponse>(
            request.CacheKey,
            cancellationToken);

        string requestName = typeof(TRequest).Name;
        if (cachedResult is not null)
        {
            logger.LogInformation("Cache hit for {RequestName}", requestName);

            return cachedResult;
        }

        logger.LogInformation("Cache miss for {RequestName}", requestName);

        TResponse result = await next();

        if (result.IsSuccess)
        {
            await cacheService.SetAsync(
                request.CacheKey,
                result,
                request.Expiration,
                cancellationToken);
        }

        return result;
    }
}
```

## What To Do Next

Managing cross-cutting concerns such as logging, caching, validation, and exception handling is not just about technical implementation.
It's about aligning these aspects with the core principles of [Clean Architecture.](clean-architecture-and-the-benefits-of-structured-software-design)
By adopting the decoupling techniques we discussed, you can ensure that your .NET projects are robust and maintainable.

Each step you take towards refining your handling of cross-cutting concerns is a step towards a better software architecture.
I encourage you to experiment with these strategies in your own .NET projects.
If you want a structured guide covering these aspects in-depth, take a look at [Pragmatic Clean Architecture.](/pragmatic-clean-architecture)

Remember, the beauty of software development lies in the continuous evolution and relentless pursuit of improvement.

Hope this was helpful.

See you next week.

---



<Sponsorships>

Is [**Blazor the future**](https://www.telerik.com/blogs/is-blazor-future-everything-web?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)
of everything Web?
With the .NET 8 release, a collection of new features take Blazor from a "niche .NET framework" to a "modern web framework - and beyond."
[**Learn more here.**](https://www.telerik.com/blogs/is-blazor-future-everything-web?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)

[**Case Study: Discover Agorus'**](https://ironsoftware.com/customers/case-studies/agorus-build-uses-iron-suite/?utm_source=milan&utm_medium=email&utm_campaign=milan)
use of IronPDF, IronOCR, and IronBarcode in C#.
Tackle complex data effortlessly with automated PDF generation, text extraction from blueprints, and barcode processing.
[**Get started here.**](https://ironsoftware.com/suite/#trial-license?utm_source=milan&utm_medium=email&utm_campaign=milan)

</Sponsorships>

[Delegating handlers](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.delegatinghandler?view=net-8.0) are like [ASP.NET Core middleware](3-ways-to-create-middleware-in-asp-net-core).
Except they work with the [`HttpClient`](the-right-way-to-use-httpclient-in-dotnet).
The ASP.NET Core request pipeline allows you to introduce custom behavior with [middleware.](3-ways-to-create-middleware-in-asp-net-core)
You can solve many cross-cutting concerns using middleware — logging, tracing, validation, authentication, authorization, etc.

But, an important aspect here is that middleware works with incoming HTTP requests to your API.
Delegating handlers work with outgoing requests.

[`HttpClient`](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient?view=net-8.0) is my preferred way of sending HTTP requests in ASP.NET Core.
It's straightforward to use and solves most of my use cases.
You can use delegating handlers to extend the `HttpClient` with behavior before or after sending an HTTP request.

Today, I want to show you how to use a [`DelegatingHandler`](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.delegatinghandler?view=net-8.0) to introduce:

- Logging
- Resiliency
- Authentication

## Configuring an HttpClient

Here's a very simple application that:

- Configures the `GitHubService` class as a typed HTTP client
- Sets the `HttpClient.BaseAddress` to point to the GitHub API
- Exposes an endpoint that retrieves a GitHub user by their username

We're going to extend the `GitHubService` behavior using delegating handlers.

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

builder.Services.AddHttpClient<GitHubService>(httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com");
});

var app = builder.Build();

app.MapGet("api/users/{username}", async (
    string username,
    GitHubService gitHubService) =>
{
    var content = await gitHubService.GetByUsernameAsync(username);

    return Results.Ok(content);
});

app.Run();
```

The `GitHubService` class is a [typed client](the-right-way-to-use-httpclient-in-dotnet#replacing-named-clients-with-typed-clients) implementation.
Typed clients allow you to expose a strongly typed API and hide the `HttpClient`.
The runtime takes care of providing a configured `HttpClient` instance through dependency injection.
You also don't have to think about disposing of the `HttpClient`.
It's resolved from an underlying `IHttpClientFactory` that manages the `HttpClient` lifetime.

```csharp
public class GitHubService(HttpClient client)
{
    public async Task<GitHubUser?> GetByUsernameAsync(string username)
    {
        var url = $"users/{username}";

        return await client.GetFromJsonAsync<GitHubUser>(url);
    }
}
```

## Logging HTTP Requests Using Delegating Handlers

Let's start with a simple example.
We will add logging before and after sending an HTTP request.
For this, we will to create a custom delegating handler - `LoggingDelegatingHandler`.

The custom delegating handler implements the `DelegatingHandler` base class.
Then, you can override the `SendAsync` method to introduce additional behavior.

```csharp
public class LoggingDelegatingHandler(ILogger<LoggingDelegatingHandler> logger)
    : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        try
        {
            logger.LogInformation("Before HTTP request");

            var result = await base.SendAsync(request, cancellationToken);

            result.EnsureSuccessStatusCode();

            logger.LogInformation("After HTTP request");

            return result;
        }
        catch (Exception e)
        {
            logger.LogError(e, "HTTP request failed");

            throw;
        }
    }
}
```

You also need to register the `LoggingDelegatingHandler` with dependency injection.
Delegating handlers must be registered as **transient** services.

The `AddHttpMessageHandler` method adds the `LoggingDelegatingHandler` as a delegating handler for the `GitHubService`.
Any HTTP request sent using the `GitHubService` will first go through the `LoggingDelegatingHandler`.

```csharp {1,7}
builder.Services.AddTransient<LoggingDelegatingHandler>();

builder.Services.AddHttpClient<GitHubService>(httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com");
})
.AddHttpMessageHandler<LoggingDelegatingHandler>();
```

Let's see what else we can do.

## Adding Resiliency With Delegating Handlers

Building [resilient](https://learn.microsoft.com/en-us/dotnet/core/resilience/?tabs=dotnet-cli) applications is an important requirement for cloud development.

The `RetryDelegatingHandler` class uses [Polly](https://github.com/App-vNext/Polly) to create an `AsyncRetryPolicy`.
The retry policy wraps the HTTP request and retries it in case of a transient failure.

```csharp
public class RetryDelegatingHandler : DelegatingHandler
{
    private readonly AsyncRetryPolicy<HttpResponseMessage> _retryPolicy =
        Policy<HttpResponseMessage>
            .Handle<HttpRequestException>()
            .RetryAsync(2);

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        var policyResult = await _retryPolicy.ExecuteAndCaptureAsync(
            () => base.SendAsync(request, cancellationToken));

        if (policyResult.Outcome == OutcomeType.Failure)
        {
            throw new HttpRequestException(
                "Something went wrong",
                policyResult.FinalException);
        }

        return policyResult.Result;
    }
}
```

You also need to register the `RetryDelegatingHandler` with dependency injection.
Also, remember to configure it as a message handler.
In this example, I'm chaining two delegating handlers together, and they will run one after another.

```csharp {1,8}
builder.Services.AddTransient<RetryDelegatingHandler>();

builder.Services.AddHttpClient<GitHubService>(httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com");
})
.AddHttpMessageHandler<LoggingDelegatingHandler>()
.AddHttpMessageHandler<RetryDelegatingHandler>();
```

## Solving Authentication With Delegating Handlers

Authentication is a cross-cutting concern you will have to solve in any microservices application.
A common use case for delegating handlers is adding the `Authorization` header before sending an HTTP request.

For example, the GitHub API requires an access token to be present for authenticating incoming requests.
The `AuthenticationDelegatingHandler` class adds the `Authorization` header value from the `GitHubOptions`.
Another requirement is specifying the `User-Agent` header, which is set from the app configuration.

```csharp
public class AuthenticationDelegatingHandler(IOptions<GitHubOptions> options)
    : DelegatingHandler
{
    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        request.Headers.Add("Authorization", options.Value.AccessToken);
        request.Headers.Add("User-Agent", options.Value.UserAgent);

        return base.SendAsync(request, cancellationToken);
    }
}
```

Don't forget to configure the `AuthenticationDelegatingHandler` with the `GitHubService`:

```csharp {1,9}
builder.Services.AddTransient<AuthenticationDelegatingHandler>();

builder.Services.AddHttpClient<GitHubService>(httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com");
})
.AddHttpMessageHandler<LoggingDelegatingHandler>()
.AddHttpMessageHandler<RetryDelegatingHandler>()
.AddHttpMessageHandler<AuthenticationDelegatingHandler>();
```

Here's a more involved authentication example using the `KeyCloakAuthorizationDelegatingHandler`.
This is a delegating handler that acquires the access token from [Keycloak](https://www.keycloak.org/).
Keycloak is an open-source identity and access management service.

I used Keycloak as the identity provider in my [Pragmatic Clean Architecture](/pragmatic-clean-architecture) course.

The delegating handler in this example uses an [OAuth 2.0](https://oauth.net/2/) [client credentials](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) grant flow to obtain an access token.
This grant is used when applications request an access token to access their own resources, not on behalf of a user.

```csharp
public class KeyCloakAuthorizationDelegatingHandler(
    IOptions<KeycloakOptions> keycloakOptions)
    : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        var authToken = await GetAccessTokenAsync();

        request.Headers.Authorization = new AuthenticationHeaderValue(
            JwtBearerDefaults.AuthenticationScheme,
            authToken.AccessToken);

        var httpResponseMessage = await base.SendAsync(
            request,
            cancellationToken);

        httpResponseMessage.EnsureSuccessStatusCode();

        return httpResponseMessage;
    }

    private async Task<AuthToken> GetAccessTokenAsync()
    {
        var params = new KeyValuePair<string, string>[]
        {
            new("client_id", _keycloakOptions.Value.AdminClientId),
            new("client_secret", _keycloakOptions.Value.AdminClientSecret),
            new("scope", "openid email"),
            new("grant_type", "client_credentials")
        };

        var content = new FormUrlEncodedContent(params);

        var authRequest = new HttpRequestMessage(
            HttpMethod.Post,
            new Uri(_keycloakOptions.TokenUrl))
        {
            Content = content
        };

        var response = await base.SendAsync(authRequest, cancellationToken);

        response.EnsureSuccessStatusCode();

        return await response.Content.ReadFromJsonAsync<AuthToken>() ??
               throw new ApplicationException();
    }
}
```

## Takeaway

Delegating handlers give you a powerful mechanism to extend the behavior when sending requests with an `HttpClient`.
You can use delegating handlers to solve cross-cutting concerns, similar to how you would use middleware.

Here are a few ideas on how you could use delegating handlers:

- Logging before and after sending HTTP requests
- Introducing resilience policies (retry, fallback)
- Validating the HTTP request content
- Authenticating with an external API

I'm sure you can come up with a few use cases yourself.

I made a video showing how to [implement delegating handlers](https://youtu.be/_u6v4D6qgDI), and you can [watch it here.](https://youtu.be/_u6v4D6qgDI)

Thanks for reading, and stay awesome!

---



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

---


Previous issues of The .NET Weekly