
<Sponsorships>

[**API Collaboration**](https://learning.postman.com/docs/collaborating-in-postman/working-with-your-team/discussing-your-work/)
has never been easier with comments on collections, folders, and requests using Postman!
Launch into hyper-efficiency using comments to discuss your work with your teammates in Postman.
[**Learn more here**](https://learning.postman.com/docs/collaborating-in-postman/working-with-your-team/discussing-your-work/).

Build automations with [**UiPath Autopilot™**](https://rebrand.ly/dev-dives-webinar).
Join this free webinar to learn how to build automation workflows, generate code, and create ready-to-use apps by simply describing your needs to the AI-powered Autopilot.
[Register today](https://rebrand.ly/dev-dives-webinar)!

</Sponsorships>

Redis is a popular choice for [**caching data**](caching-in-aspnetcore-improving-application-performance), but its capabilities go far beyond that.
One of its lesser-known features is Pub/Sub support.
Redis channels offer an interesting approach for implementing real-time messaging in your .NET applications.
However, as you'll soon see, channels also have some drawbacks.

In this week's newsletter, we'll explore:

- Basics of Redis channels
- Practical use cases for channels
- Implementing a Pub/Sub example in .NET
- Cache invalidation in distributed systems

Let's dive in.

## Redis Channels

Redis channels are named communication channels that implement the [Publish/Subscribe messaging paradigm](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern).
Each channel is identified by a unique name (e.g., `notifications`, `updates`).
Channels facilitate message delivery from publishers to subscribers.

Publishers use the `PUBLISH` command to send messages to a specific channel.
Subscribers use the `SUBSCRIBE` command to register interest in receiving messages from a channel.

<Image
  src="blogs/mnw_100/redis_channel.png"
  width={2094}
  height={1294}
  alt="Redis channel with publisher and three subscribers."
/>

Redis channels follow a topic-based publish-subscribe model.
Multiple publishers can send messages to a channel, and multiple subscribers can receive messages from that channel.

However, it's crucial to note that Redis channels do not store messages.
If there are no subscribers for a channel when a message is published, that message is immediately discarded.

Redis channels have an **at-most-once delivery** semantics.

## Practical Use Cases

Given that Redis channels operate with **at-most-once delivery** (messages might be lost if there are no subscribers),
they are well-suited for scenarios where occasional message loss is acceptable and real-time or near-real-time communication is desired.

Here are a few possible use cases:

- **Social media feeds**: Broadcasting new posts or updates to users.
- **Live score updates**: Sending live game scores or sports updates to subscribers.
- **Chat applications**: Delivering chat messages in real-time to active participants.
- **Collaborative editing**: Propagating changes in collaborative editing environments.
- **Distributed cache updates**: Invalidating cache entries across multiple servers when data changes. We'll cover this in detail later in the article.

Redis channels aren't the best choice for critical data where message loss is unacceptable.
In such cases, you should consider a more reliable messaging system.

Let's see how we can use Redis channels in .NET.

## Pub/Sub With Redis Channels

We will use the `StackExchange.Redis` library to send messages with Redis channels.

Let's start by installing it:

```powershell
Install-Package StackExchange.Redis
```

You can run [Redis](https://redis.io/) locally in a Docker container.
The default port is `6379`.

```
docker run -it -p 6379:6379 redis
```

Here's a simple background service that'll act as our message `Producer`.

We're creating a `ConnectionMultiplexer` by connecting to our Redis instance.
This allows us to obtain an `ISubscriber` that we can use for pub/sub messaging.
The `ISubscriber` will enable us to publish a message to a channel by specifying the channel name.

```csharp {11,19}
public class Producer(ILogger<Producer> logger) : BackgroundService
{
    private static readonly string ConnectionString = "localhost:6379";
    private static readonly ConnectionMultiplexer Connection =
        ConnectionMultiplexer.Connect(ConnectionString);

    private const string Channel = "messages";

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var subscriber = Connection.GetSubscriber();

        while (!stoppingToken.IsCancellationRequested)
        {
            var message = new Message(Guid.NewGuid(), DateTime.UtcNow);

            var json = JsonSerializer.Serialize(message);

            await subscriber.PublishAsync(Channel, json);

            logger.LogInformation(
                "Sending message: {Channel} - {@Message}",
                message);

            await Task.Delay(5000, stoppingToken);
        }
    }
}
```

Let's also introduce a separate background service for consuming messages.

The `Consumer` connects to the same Redis instance and obtains an `ISubscriber`.
The `ISubscriber` exposes a `SubscribeAsync` method that we can use to subscribe to messages from a given channel.
This method accepts a callback delegate that we can use to handle the message.

```csharp
public class Consumer(ILogger<Consumer> logger) : BackgroundService
{
    private static readonly string ConnectionString = "localhost:6379";
    private static readonly ConnectionMultiplexer Connection =
        ConnectionMultiplexer.Connect(ConnectionString);

    private const string Channel = "messages";

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var subscriber = Connection.GetSubscriber();

        await subscriber.SubscribeAsync(Channel, (channel, message) =>
        {
            var message = JsonSerializer.Deserialize<Message>(message);

            logger.LogInformation(
                "Received message: {Channel} - {@Message}",
                channel,
                message);
        });
    }
}
```

Finally, here's what we get when we run both the `Producer` and `Consumer` services:

<Image
  src="blogs/mnw_100/redis_pub_sub.gif"
  width={1920}
  height={500}
  alt="Redis channels publish/subscribe demo."
/>

## Cache Invalidation in Distributed Systems

In a recent project, I tackled a common challenge in distributed systems: keeping the caches in sync.
We were using a two-level caching approach.
First, we had an in-memory cache on each web server for super-fast access.
Second, we had a shared Redis cache to avoid hitting our database too often.

The problem was that when data changed in the database, we needed a way to quickly tell all the web servers to clear their in-memory caches.
This is where Redis Pub/Sub came to the rescue.
We set up a Redis channel specifically for cache invalidation messages.

Each application would run a `CacheInvalidationBackgroundService` that subscribes to messages from the cache invalidation channel.

```csharp
public class CacheInvalidationBackgroundService(
    IServiceProvider serviceProvider)
    : BackgroundService
{
    public const string Channel = "cache-invalidation";

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await subscriber.SubscribeAsync(Channel, (channel, key) =>
        {
            var cache = serviceProvider.GetRequiredService<IMemoryCache>();

            cache.Remove(key);

            return Task.CompletedTask;
        });
    }
}
```

Whenever data changes in the database, we publish a message on this channel with the cache key of the updated data.
All the web servers are subscribed to this channel, so they instantly know to remove the old data from their in-memory caches.
Since the in-memory cache is wiped if the application isn't running, losing cache invalidation messages isn't a problem.
This keeps our caches consistent and ensures our users always see the most up-to-date information.

## In Summary

Redis Pub/Sub is not a silver bullet for every messaging need, but its simplicity and speed make it a valuable tool.
Channels allow us to easily implement communication between loosely coupled components.

Redis channels have at-most-once delivery semantics, so they're best suited for cases where the occasional dropped message is acceptable.

I used it to solve the challenge of synchronizing caches across multiple servers.
This allowed our system to serve up-to-date data without sacrificing performance.

**P.S.** When you're ready to dive deeper into creating message-driven systems, check out [**Modular Monolith Architecture**](/modular-monolith-architecture).
I have an entire module dedicated to building reliable distributed messaging and event-driven architecture.

Good luck out there, and see you next week.

---



<Sponsorships>

Streamline API development with [**Package Libary in Postman**](https://learning.postman.com/docs/tests-and-scripts/write-scripts/package-library/).
Add commonly-used scripts and tests to packages in your team's Package Library, and reuse them in your personal, private, and team workspaces using Postman.
[**Learn more here**](https://learning.postman.com/docs/tests-and-scripts/write-scripts/package-library/).

The [**IronOCR C# library**](https://ironsoftware.com/csharp/ocr/how-to/read-specific-document/?utm_source=milan&utm_medium=email&utm_campaign=milan)
has hit a new milestone with 2 million NuGet downloads!
To celebrate, we're offering a 20% discount on IronOCR team licenses (Lite, Plus, Pro).
Plus, we're excited to introduce AdvancedScan, a powerful new feature that enhances OCR accuracy and Multiple-Language Support.
[**Try it Today**](https://ironsoftware.com/csharp/ocr/how-to/read-specific-document/?utm_source=milan&utm_medium=email&utm_campaign=milan).

</Sponsorships>

Modular monoliths strike a balance between the simplicity of monolithic architecture and the flexibility of microservices.
By breaking down applications into cohesive modules, modular monoliths enable easier development and maintenance.
However, they still have a single codebase and deployment unit.

A critical aspect of the success of a modular monolith is the interaction between its modules.

**System integration testing (SIT)** is an approach to verifying the collaboration of these modules.
It involves testing the integration points and communication mechanisms between modules.

System integration testing allows us to validate the entire system's behavior.
This allows us to catch problems early before they become big headaches.

In this article, we'll learn how to test a modular monolith using system integration testing.

We'll look at real-world examples and discuss why this testing approach is useful.

## What Is System Integration Testing?

System integration testing (SIT) is an approach to testing the interactions between various modules within a single system.
The system could contain many external services, which should also be included during testing.

System integration testing is the perfect testing approach for modular monoliths.
It allows you to mimic the real-world execution of your application (as you'll see later).

The key benefits of system integration testing are:

- **Detecting integration issues**: Discover problems from module integrations that unit testing might miss.
- **Validating business logic**: Confirm that end-to-end business processes function correctly across modules.
- **Ensuring data integrity**: Verify that data flows accurately and consistently between modules.
- **Improving system stability**: Identify and resolve issues early, leading to a more reliable system.
- **Building confidence**: Ensure that the system is well-integrated and ready for deployment.

## Modular Monolith System Example

A modular monolith consists of multiple modules, each with a distinct responsibility.
Modules represent high-level components with well-defined boundaries.
The modules essentially group together related functionalities (use cases).
If you want to learn more about this software architecture, check out this [**introduction to modular monoliths**](what-is-a-modular-monolith).

Let's consider a hypothetical ticketing system that consists of several modules:

- **Users Module**: Handles user administration and authentication.
- **Events Module**: Manages events, scheduling, and ticket availability.
- **Ticketing Module**: Allows users to purchase tickets for various events.
- **Attendance Module**: Allows users to check into events using their tickets.

<figure>
  <Image
    src="blogs/mnw_099/modular_monolith.png"
    width={2506}
    height={1282}
    alt="Modular monolith UML diagram."
  />
  <figcaption>
    Source: [Modular Monolith Architecture](/modular-monolith-architecture)
  </figcaption>
</figure>

During system integration testing, we want to ensure that all these modules interact correctly and
fulfill the business requirements of the ticketing system.

## Testing Modular Monoliths: User Registration

The modules in our ticketing system represent different [**bounded contexts**](monolith-to-microservices-how-a-modular-monolith-helps).
The **Users Module** uses the term `User` as its core entity.
However, the **Ticketing Module** uses the term `Customer` because it's more aligned with its core responsibility of selling tickets.
Conceptually, both entities represent the same person within our system.

Here's the scenario we want to test:

- A user registers with our application through the **Users Module**
- The **Users Module** publishes an integration event to notify other modules
- The **Ticketing Module** handles the integration event and creates a customer record

<Image
  src="blogs/mnw_099/user_registration.png"
  width={2866}
  height={877}
  alt="User registration flow diagram."
/>

If you haven't figured it out by now, our [**modules communicate asynchronously**](modular-monolith-communication-patterns) using messaging.

Why is this important for our tests?

There is a time delay from when something occurs in one module until the other modules are notified and handle the integration events.
Our system integration tests will have to take into account this delay.

Here's the test for this scenario:

```csharp
public class RegisterUserTests : BaseIntegrationTest
{
    public RegisterUserTests(IntegrationTestWebAppFactory factory)
        : base(factory)
    {
    }

    [Fact]
    public async Task RegisterUser_Should_PropagateToTicketingModule()
    {
        // [Users Module] - Register user
        var command = new RegisterUserCommand(
            Faker.Internet.Email(),
            Faker.Internet.Password(6),
            Faker.Name.FirstName(),
            Faker.Name.LastName());

        Result<Guid> userResult = await Sender.Send(command);

        userResult.IsSuccess.Should().BeTrue();

        // [Ticketing Module] - Get customer
        Result<CustomerResponse> customerResult = await Poller.WaitAsync(
            TimeSpan.FromSeconds(15),
            async () =>
            {
                var query = new GetCustomerQuery(userResult.Value);

                var customerResult = await Sender.Send(query);

                return customerResult;
            });

        // Assert
        customerResult.IsSuccess.Should().BeTrue();
        customerResult.Value.Should().NotBeNull();
    }
}
```

A lot is going on here, so let's unpack the steps:

- We're using the `WebApplicationFactory` to run an in-memory application instance
- Any external dependencies run in a Docker container using [**Testcontainers**](testcontainers-integration-testing-using-docker-in-dotnet)
- We send the `RegisterUserCommand` to register a user in the **Users Module**
- Then, we have to poll the **Ticketing Module** by sending a `GetCustomerQuery`
- The `Poller` allows us to wait until the system eventually becomes consistent

You can learn more about [**integration testing with Testcontainers in this article**](testcontainers-integration-testing-using-docker-in-dotnet).

System integration tests take longer to execute than integration tests for one module.
This is a side effect of testing a bigger slice of the overall system in each test case.

The `Poller` class allows you to execute a delegate until you receive a successful result or a timeout occurs.
You can customize the timeout duration based on the scenario you are testing.

```csharp
internal static class Poller
{
    private static readonly Error Timeout =
        Error.Failure("Poller.Timeout", "The poller has time out");

    internal static async Task<Result<T>> WaitAsync<T>(
        TimeSpan timeout,
        Func<Task<Result<T>>> func)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(1));

        DateTime endTimeUtc = DateTime.UtcNow.Add(timeout);
        while (DateTime.UtcNow < endTimeUtc &&
               await timer.WaitForNextTickAsync())
        {
            Result<T> result = await func();

            if (result.IsSuccess)
            {
                return result;
            }
        }

        return Result.Failure<T>(Timeout);
    }
}
```

## Testing Modular Monoliths: Adding Ticket to Cart

Here's a more complex scenario testing adding a ticket to the customer's cart:

- A user registers with our application through the **Users Module**
- The **Users Module** publishes an integration event to notify other modules
- The **Ticketing Module** handles the integration event and creates a customer record
- The **Ticketing Module** creates a dummy event and adds a ticket to the customer's cart

This scenario mimics a user registering with our system, finding a ticket they want to purchase, and adding it to their cart.
We can extend this scenario with more test cases, like ticket purchases.

```csharp
public sealed class AddItemToCartTests : BaseIntegrationTest
{
    private const decimal Quantity = 10;

    public AddItemToCartTests(IntegrationTestWebAppFactory factory)
        : base(factory)
    {
    }

    [Fact]
    public async Task Customer_ShouldBeAbleTo_AddItemToCart()
    {
        // [Users Module] - Register user
        var command = new RegisterUserCommand(
            Faker.Internet.Email(),
            Faker.Internet.Password(6),
            Faker.Name.FirstName(),
            Faker.Name.LastName());

        Result<Guid> userResult = await Sender.Send(command);

        userResult.IsSuccess.Should().BeTrue();

        // [Ticketing Module] - Get customer
        Result<CustomerResponse> customerResult = await Poller.WaitAsync(
            TimeSpan.FromSeconds(15),
            async () =>
            {
                var query = new GetCustomerQuery(userResult.Value);
                var customerResult = await Sender.Send(query);
                return customerResult;
            });

        customerResult.IsSuccess.Should().BeTrue();

        // [Ticketing Module] - Add item to cart
        CustomerResponse customer = customerResult.Value;
        var ticketTypeId = Guid.NewGuid();

        await Sender.CreateEventAsync(Guid.NewGuid(), ticketTypeId, Quantity);

        Result result = await Sender.Send(
            new AddItemToCartCommand(customer.Id, ticketTypeId, Quantity));

        // Assert
        result.IsSuccess.Should().BeTrue();
    }
}
```

What I like about system integration testing is that the test cases aren't complicated to write.
The tests execute the use cases of our system and verify the side effects.
Building your system around [**use cases**](building-your-first-use-case-with-clean-architecture) has a few advantages,
the main one being that you can focus on the core business logic.
But it also makes (integration) testing easier.
The use case runs by sending a command or a query.
We can execute the use cases in some logical order and check that we get the expected result.

## In Conclusion

System integration testing is a crucial step in creating a successful modular monolith.
By testing how different modules work together, you can find and fix problems before they become bigger issues.
This makes your software more reliable and saves you time and resources in the long run.

If you want to dive deeper into building modular systems, check out [**Modular Monolith Architecture**](/modular-monolith-architecture).
There's an entire chapter dedicated to testing,
including advanced techniques like system integration testing, using Testcontainers for external services, and automated testing with CI/CD pipelines.

That's all for today.

See you next week.

---



<Sponsorships>

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

Collaborate directly with your external partners in Postman!
You can use [**Partner Workspaces**](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/partner-workspaces/) to help your partners consume your team's APIs and work together on API projects.
Check out Postman's Partner Workspaces, now available for Professional and Enterprise plans in [**Postman v11**](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/partner-workspaces/).

</Sponsorships>

This is a question I often hear: how do I design my use case with Clean Architecture?

I understand the confusion.
Figuring out what to place in the Domain, Application, and Infrastructure layer can seem complicated.
If that's not enough, we also have to decide what makes up a use case and what should be abstracted away.

However, things become simpler if we adhere to the main rule in Clean Architecture — **the Dependency Rule**.
This rule states that source code dependencies can only point inwards.

In this newsletter, we'll explore a practical example of how to apply Clean Architecture principles by building a user registration feature.

## Clean Architecture

[**Clean Architecture**](why-clean-architecture-is-great-for-complex-projects) has emerged as a guiding principle for crafting maintainable, scalable, and testable applications.
At its core, Clean Architecture emphasizes the **separation of concerns** and the **dependency rule**.
The dependency rule dictates that dependencies should point inward toward higher-level modules.
By following this rule, you create a system where the core business logic of your application is decoupled from external dependencies.
This makes it more adaptable to changes and easier to test.

<Image
  src="blogs/mnw_098/clean_architecture.png"
  width={1280}
  height={714}
  alt="Clean Architecture diagram."
/>

The Domain layer encapsulates enterprise-wide business rules.
It contains domain entities, where an entity is typically an object with methods.

The Application layer contains application-specific business rules and encapsulates all of the system's use cases.
A use case orchestrates the flow of data to and from the domain entities and calls the methods exposed by the entities
to achieve its goals.

The Infrastructure and Presentation layers deal with external concerns.
Here, you will implement any abstractions defined in the inner layers.

## Describing The Use Case

What does it mean for a user to register with our application?
It means they reserve an email address (or username) to identify themselves and be able to interact with our system.
The user could provide other information, such as a first and last name, an address, and a phone number.

The first step in building any feature is clearly defining the desired result.

For user registration, this is what the required operations are:

- The user provides an email and password for registration
- Verify that the email was not reserved previously by an existing account
- Hash the password using some cryptographic hash function (e.g., SHA-256, SHA-512)
- Store the user in the database and (optionally) return an access token to the client

We could also consider any domain-specific rules or validations that we must enforce.
A good example is password strength, where we could implement minimum length and complexity requirements.

Now that we have our requirements let's see how to translate them into a use case.

## Implementing the Use Case

With our requirements in place, we can now define the user registration use case.
In [**Clean Architecture**](clean-architecture-and-the-benefits-of-structured-software-design), use cases live in the Application layer and orchestrate the interactions between domain entities and external dependencies.

Let's name our use case `RegisterUser`.
Its input will be a `RegistrationRequest` object containing the user's registration data,
and its output will be a `RegistrationResult` object indicating the outcome of the registration attempt.
Notice that we are using a feature-driven name for the use case.

What about any external dependencies?
If the use case needs to interact with an external system or infrastructure component, we abstract that behind an interface.
Remember, your application's core business logic should be decoupled from external dependencies.

The `RegisterUser` class will use dependency injection to get the necessary dependencies:

- `IUserRepository`: An interface for accessing user data from the database.
- `IPasswordHasher`: An interface for hashing passwords securely.

The `RegisterUser` use case will follow these steps:

1. Validate input data
2. Check for existing `User`
3. Hash the password
4. Create a new `User` entity
5. Save the `User` to the database
6. Return the result

Finally, here's the code for our `RegisterUser` use case:

```csharp
public class RegisterUser(
    IUserRepository userRepository,
    IPasswordHasher passwordHasher)
{
    public async Task<RegistrationResult> Handle(RegistrationRequest request)
    {
        // Validation omitted for brevity

        if (await userRepository.ExistsAsync(request.Email))
        {
            return RegistrationResult.EmailNotUnique;
        }

        var passwordHash = passwordHasher.Hash(request.Password);

        var user = User.Create(
            request.FirstName, request.LastName, request.Email, passwordHash);

        await userRepository.InsertAsync(user);

        return RegistrationResult.Success;
    }
}
```

A big benefit of this approach is that we can immediately write tests for the `RegisterUser` use case.
We can provide mocks for external dependencies in the tests.
We don't need the implementations to exist for this code to compile.
With mocks, we can test our business rules and validate our implementation.

**Action step**: How would you extend the `RegisterUser` use case with more functionality?

Here are two examples:

- Adding an external identity provider
- Implementing email verification

## Where Clean Architecture Becomes Muddled

By designing our application with Clean Architecture, we produce a system independent of external concerns.
We define abstractions in the Application layer and implement them in the Infrastructure layer.
So far, so good.

However, this doesn't mean you can disregard how you integrate with external dependencies.

In theory, we should be able to "swap" the implementation for any external concern and call it a day.
In practice, this couldn't be further from the truth.

Let me give you two practical examples using the user registration flow.

### Race Conditions

The `RegisterUser` use case has a race condition.
Concurrent requests could pass the check for email uniqueness and proceed to register the user.

We could prevent this race condition by introducing a lock before checking for email uniqueness.
That way, only one request will pass the check and proceed to save the user in the database.

```csharp
if (await userRepository.ExistsAsync(request.Email))
{
    return RegistrationResult.EmailNotUnique;
}
```

However, there is a much more elegant way to solve this.
We can introduce a unique index on the `Email` column in the database.
A unique index guarantees that only one transaction can write the unique value to the database.
The losing transaction will return an error.

We can handle this exception on the application side and return an appropriate error message to the user.
The `IUserRepository.InsertAsync` method implementation can encapsulate this logic.

### Changing Hash Functions

Let's say we found a security flaw in the hash function used in the `IPasswordHasher` implementation.
So, we spend a few minutes switching to a more secure hash function.
The tests for the `RegisterUser` use case are all green, and everything seems fine.

The problem? All existing users can no longer log in to the system.

When an existing user tries to log in with their email and password, the new `IPasswordHasher.Hash` implementation
returns a different password hash from the one stored in the database.

The correct approach is to phase out the old password hash for existing users.
We can add a column in the database that says which hash function produced the hash.
We will verify the user's password using the correct hashing function during the login process.

If the user's password hash still uses the old hashing function, we will verify their password first.
Then, we can use the password (which we have in memory) to produce a hash using the new hash function.
We will store the hash in the database and update the hash function column to the new algorithm.

Slowly, we will phase out passwords using the old hash function.

## Conclusion

I hope this was helpful in understanding how to apply Clean Architecture principles to a real-world scenario.
By focusing on the core business logic first (what it means for a user to register), we can define the requirements for our use case.
Translating these requirements into a series of steps within the use case is the easy part.

But Clean Architecture won't save you from bad engineering.
If you don't understand what you are abstracting away, it will become a problem in the long term.

If you want to go deeper, my flagship course, [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture),
takes the guesswork out of structuring your project the right way.
I share my entire framework for building robust applications from the ground up -
from building a rich domain model to creating use cases to getting your application ready for production.

And that's all for this week.

See you next Saturday.

---



<Sponsorships>

Build and test automations with [**UiPath**](https://rebrand.ly/dev-dives-uipath).
Join this free webinar to learn how the UiPath Platform enables you to build C# coded automations and quickly test them using GenAI.
[**Save your seat here**](https://rebrand.ly/dev-dives-uipath)!

Design and mock APIs with [**Postman Mock Servers**](https://learning.postman.com/docs/designing-and-developing-your-api/mocking-data/setting-up-mock/)!
Build higher-quality APIs faster with Postman mock API servers which simplify design and planning, support split-stack development,
and help you ensure that your API will run the way it's supposed to in production.
[**Learn more here**](https://learning.postman.com/docs/designing-and-developing-your-api/mocking-data/setting-up-mock/).

</Sponsorships>

Microservices have revolutionized how we build and scale applications.
By breaking down larger systems into smaller, independent services, we gain flexibility, agility, and the ability to adapt to changing requirements quickly.
However, microservices systems are also very dynamic.
Services can come and go, scale up or down, and even move around within your infrastructure.

This dynamic nature presents a significant challenge. How do your services find and communicate with each other reliably?

Hardcoding IP addresses and ports is a recipe for fragility.
If a service instance changes location or a new instance spins up, your entire system could grind to a halt.

Service discovery acts as a central directory for your microservices.
It provides a mechanism for services to register themselves and discover the locations of other services.

In this week's issue, we'll see how to implement service discovery in your .NET microservices with Consul.

## What is Service Discovery?

Service discovery is a pattern that allows developers to use logical names to refer to external services instead of physical IP addresses and ports.
It provides a centralized location for services to register themselves.
Clients can query the service registry to find out the service's physical address.
This is a common pattern in large-scale distributed systems, such as Netflix and Amazon.

Here's what the service discovery flow looks like:

1. The service will register itself with the service registry
2. The client must query the service registry to get the physical address
3. The client sends the request to the service using the resolved physical address

<Image
  src="blogs/mnw_097/service_discovery_flow.png"
  width={1377}
  height={983}
  alt="Service discovery flow."
/>

The same concept applies when we have multiple services we want to call.
Each service would register itself with the service registry.
The client uses a logical name to reference a service and resolves the physical address from the service registry.

<Image
  src="blogs/mnw_097/service_discovery_microservices.png"
  width={2074}
  height={883}
  alt="Service discovery with multiple microservices."
/>

The most popular solutions for service discovery are Netflix [Eureka](https://github.com/Netflix/eureka) and HashiCorp [Consul](https://www.consul.io/).

There is also a lightweight solution from Microsoft in the `Microsoft.Extensions.ServiceDiscovery` library.
It uses application settings to resolve the physical addresses for services, so some manual work is still required.
However, you can store service locations in [Azure App Configuration](https://azure.microsoft.com/en-us/products/app-configuration) for a centralized service registry.
I will explore this service discovery library in some future articles.

But now I want to show you how to integrate Consul with .NET applications.

## Setting Up the Consul Server

The simplest way to run the Consul server locally is using a Docker container.
You can create a container instance of the `hashicorp/consul` image.

Here's an example of configuring the Consul service as part of the `docker-compose` file:

```yml
consul:
  image: hashicorp/consul:latest
  container_name: Consul
  ports:
    - '8500:8500'
```

If you navigate to `localhost:8500`, you will be greeted by the Consul Dashboard.

<Image
  src="blogs/mnw_097/consul_dashboard.png"
  width={1902}
  height={907}
  alt="Consul dashboard."
/>

Now, let's see how to register our services with Consul.

## Service Registration in .NET With Consul

We'll use the [Steeltoe Discovery](https://docs.steeltoe.io/api/v3/discovery/) library to implement service discovery with Consul.
The Consul client implementation lets your applications register services with a Consul server and discover services registered by other applications.

Let's install the `Steeltoe.Discovery.Consul` library:

```powershell
Install-Package Steeltoe.Discovery.Consul
```

We have to configure some services by calling `AddServiceDiscovery` and explicitly configuring the Consul service discovery client.
The alternative is calling `AddDiscoveryClient` which uses reflection at runtime to determine which service registry is available.

```csharp {6}
using Steeltoe.Discovery.Client;
using Steeltoe.Discovery.Consul;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddServiceDiscovery(o => o.UseConsul());

var app = builder.Build();

app.Run();
```

Finally, our service can register with Consul by configuring the logical service name through application settings.
When the application starts, the `reporting-service` logical name will be added to the Consul service registry.
Consul will store the respective physical address of this service.

```json
{
  "Consul": {
    "Host": "localhost",
    "Port": 8500,
    "Discovery": {
      "ServiceName": "reporting-service",
      "Hostname": "reporting-api",
      "Port": 8080
    }
  }
}
```

When we start the application and open the Consul dashboard, we should be able to see the `reporting-service` and its respective physical address.

<Image
  src="blogs/mnw_097/consul_dashboard_with_service.png"
  width={1902}
  height={907}
  alt="Consul dashboard with registered service."
/>

## Using Service Discovery

We can use service discovery when making HTTP calls with an `HttpClient`.
Service discovery allows us to use a logical name for the service we want to call.
When sending a network request, the service discovery client will replace the logical name with a correct physical address.

In this example, we're configuring the base address of the `ReportingServiceClient` typed client to `http://reporting-service`
and adding service discovery by calling `AddServiceDiscovery`.

Load balancing is an optional step, and we can configure it by calling `AddRoundRobinLoadBalancer` or `AddRandomLoadBalancer`.
You can also configure a custom load balancing strategy by providing an `ILoadBalancer` implementation.

```csharp
builder.Services
    .AddHttpClient<ReportingServiceClient>(client =>
    {
        client.BaseAddress = new Uri("http://reporting-service");
    })
    .AddServiceDiscovery()
    .AddRoundRobinLoadBalancer();
```

We can use the `ReportingServiceClient` typed client like a regular `HttpClient` to make requests.
The service discovery client sends the request to the external service's IP address.

```csharp
app.MapGet("articles/{id}/report",
    async (Guid id, ReportingServiceClient client) =>
    {
        var response = await client
            .GetFromJsonAsync<Response>($"api/reports/article/{id}");

        return response;
    });
```

## Takeaway

Service discovery simplifies the management of microservices by automating service registration and discovery.
This eliminates the need for manual configuration updates, reducing the risk of errors.

Services can discover each other's locations on demand, ensuring that communication channels remain open even as the service landscape evolves.
By enabling services to discover alternative service instances in case of outages or failures, service discovery enhances the overall resilience of the microservices system.

Mastering service discovery gives you a powerful tool to build modern distributed applications.

You can grab the [source code for this example here](https://github.com/m-jovanovic/service-discovery-consul).

Thanks for reading, and I'll see you next week!

---



<Sponsorships>

Store secrets in your [**Postman Vault**](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/)!
Postman Vault enables you to store sensitive data as vault secrets in your local instance of Postman.
This enables you to securely reuse sensitive data in your HTTP collections and requests.
[**Learn more and get started using Vault**](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/)!

[**IronPDF**](https://ironpdf.com/?utm_source=milan&utm_medium=email&utm_campaign=milan):
Your essential C# PDF library for converting modern HTML templates into PDFs effortlessly.
With advanced CSS styling preservation and seamless integration with ASP.NET Core MVC and Razor, IronPDF ensures pixel-perfect results.
[**Try it today**](https://ironpdf.com/?utm_source=milan&utm_medium=email&utm_campaign=milan)!

</Sponsorships>

I'll never forget when I was working on a project that required generating weekly sales reports for a client.
The initial solution involved a clunky process of exporting data, manipulating it in spreadsheets, and manually creating PDFs.
It was tedious, error-prone, and it sucked up way too much of my time.
I knew there had to be a better way.

That's when I discovered the power of combining Razor views with HTML-to-PDF conversion.
You have more control over formatting the document.
You can use modern CSS to style the HTML markup, which will be applied when exporting to a PDF document.
It's also simple to implement in ASP.NET Core.

Here's what we'll cover:

- Understanding Razor views
- Converting Razor views to HTML
- HTML to PDF conversion in .NET
- Putting it all together with Minimal APIs

Let's dive in!

## Razor Views

Razor [views](https://learn.microsoft.com/en-us/aspnet/core/mvc/views)
are an HTML template with embedded [Razor](https://learn.microsoft.com/en-us/aspnet/core/mvc/views/razor) markup.
Razor allows you to write and execute .NET code inside a web page.
Views have a special `.cshtml` file extension.
They're commonly used in [ASP.NET Core MVC](https://learn.microsoft.com/en-us/aspnet/core/mvc/overview),
[Razor Pages](https://learn.microsoft.com/en-us/aspnet/core/razor-pages),
and [Blazor](https://learn.microsoft.com/en-us/aspnet/core/blazor).

However, you can define Razor views in a class library or ASP.NET Core Web API project.

You can use the `Model` object to pass in data to a Razor view.
Inside the `.cshtml` file, you'll specify the model type with the `@model` keyword.
In the example below, I'm specifying that the `Invoice` class is the model for this view.
You can access the model instance with the `Model` property in the view.

This is the `InvoiceReport.cshtml` view we'll use to generate a PDF invoice.

You can write CSS in the Razor view inline or reference a stylesheet.
I'm using the [Tailwind CSS](https://tailwindcss.com/) utility framework, which uses inline CSS.
I usually delegate this to a front-end engineer on my team so they can stylize the report as needed.

```csharp {4}
@using System.Globalization
@using HtmlToPdf.Contracts

@model HtmlToPdf.Contracts.Invoice

@{
    IFormatProvider cultureInfo = CultureInfo.CreateSpecificCulture("en-US");
    var subtotal = Model.LineItems.Sum(li => li.Price * li.Quantity).ToString("C", cultureInfo);
    var total = Model.LineItems.Sum(li => li.Price * li.Quantity).ToString("C", cultureInfo);
}

<script src="https://cdn.tailwindcss.com"></script>

<div class="min-w-7xl flex flex-col bg-gray-200 space-y-4 p-10">
    <h1 class="text-2xl font-semibold">Invoice #@Model.Number</h1>

    <p>Issued date: @Model.IssuedDate.ToString("dd/MM/yyyy")</p>
    <p>Due date: @Model.DueDate.ToString("dd/MM/yyyy")</p>

    <div class="flex justify-between space-x-4">
        <div class="bg-gray-100 rounded-lg flex flex-col space-y-1 p-4 w-1/2">
            <p class="font-medium">Seller:</p>
            <p>@Model.SellerAddress.CompanyName</p>
            <p>@Model.SellerAddress.Street</p>
            <p>@Model.SellerAddress.City</p>
            <p>@Model.SellerAddress.State</p>
            <p>@Model.SellerAddress.Email</p>
        </div>
        <div class="bg-gray-100 rounded-lg flex flex-col space-y-1 p-4 w-1/2">
            <p class="font-medium">Bill to:</p>
            <p>@Model.CustomerAddress.CompanyName</p>
            <p>@Model.CustomerAddress.Street</p>
            <p>@Model.CustomerAddress.City</p>
            <p>@Model.CustomerAddress.State</p>
            <p>@Model.CustomerAddress.Email</p>
        </div>
    </div>

    <div class="flex flex-col bg-white rounded-lg p-4 space-y-2">
        <h2 class="text-xl font-medium">Items:</h2>
        <div class="">
            <div class="flex space-x-4 font-medium">
                <p class="w-10">#</p>
                <p class="w-52">Name</p>
                <p class="w-20">Price</p>
                <p class="w-20">Quantity</p>
            </div>

            @foreach ((int index, LineItem item) in Model.LineItems.Select((li, i) => (i + 1, li)))
            {
                <div class="flex space-x-4">
                    <p class="w-10">@index</p>
                    <p class="w-52">@item.Name</p>
                    <p class="w-20">@item.Price.ToString("C", cultureInfo)</p>
                    <p class="w-20">@item.Quantity.ToString("N2")</p>
                </div>
            }
        </div>
    </div>

    <div class="flex flex-col items-end bg-gray-50 space-y-2 p-4 rounded-lg">
        <p>Subtotal: @subtotal</p>
        <p>Total: <span class="font-semibold">@total</span></p>
    </div>
</div>
```

## Converting Razor Views to HTML

The next thing we'll need is a way to convert the Razor view into HTML.
We can do this with the [`Razor.Templating.Core`](https://github.com/soundaranbu/Razor.Templating.Core) library.
It provides a simple API to render a `.cshtml` file into a `string`.

```powershell
Install-Package Razor.Templating.Core
```

You can use the `RazorTemplateEngine` static class to call the `RenderAsync` method.
It accepts the path to the Razor view and the model instance that will be passed to the view.

Here's what that will look like:

```csharp
Invoice invoice = invoiceFactory.Create();

string html = await RazorTemplateEngine.RenderAsync(
    "Views/InvoiceReport.cshtml",
    invoice);
```

Alternatively, you can use the `IRazorTemplateEngine` instead of the static class.
In that case, you must call `AddRazorTemplating` to register the required services with DI.
This is also required if you want to use dependency injection inside the Razor views with `@inject`.
It's recommended that you call `AddRazorTemplating` after registering all dependencies.

```csharp
services.AddRazorTemplating();
```

## HTML to PDF conversion

Now that we've converted our Razor view into HTML, we can use it to generate a PDF report.
Many libraries offer this functionality.
The library I've used most often is [IronPDF](https://ironpdf.com/).
It's a paid library (and well worth it), but I know developers also want free options, so I'll list some alternatives at the end.

We can use IronPDF's `ChromePdfRenderer`, which uses an embedded Chrome browser.
The renderer exposes the `RenderHtmlAsPdf` method, which generates a `PdfDocument`.
Once you have the document, you can store it on the file system or export it as binary data.

```csharp
var renderer = new ChromePdfRenderer();

using var pdfDocument = renderer.RenderHtmlAsPdf(html);

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

If you're looking for free options, check out [Puppeteer Sharp](https://github.com/hardkoded/puppeteer-sharp).
It's a .NET port of the [Puppeteer](https://github.com/puppeteer/puppeteer) library, which allows you to run a headless Chrome browser.

Another (conditionally) free option to consider is [NReco.PdfGenerator](https://www.nuget.org/packages/NReco.PdfGenerator/).
However, it's only free for single-server deployments.

## Putting It All Together

Let's use everything we discussed to create a Minimal API endpoint to generate an invoice PDF report and return it as a file response.
Here's the code snippet:

```csharp
app.MapGet("invoice-report", async (InvoiceFactory invoiceFactory) =>
{
    Invoice invoice = invoiceFactory.Create();

    var html = await RazorTemplateEngine.RenderAsync(
        "Views/InvoiceReport.cshtml",
        invoice);

    var renderer = new ChromePdfRenderer();

    using var pdfDocument = renderer.RenderHtmlAsPdf(html);

    return Results.File(
        pdfDocument.BinaryData,
        "application/pdf",
        $"invoice-{invoice.Number}.pdf");
});
```

This is what the generated PDF report looks like:

<Image
  src="blogs/mnw_096/invoice.png"
  width={1273}
  height={1937}
  alt="Invoice report."
/>

You can grab the source code for this sample [here](https://github.com/m-jovanovic/razor-view-html-to-pdf).
Feel free to try out a different library for HTML to PDF conversion.

## Summary

In this article, we've explored the power of using Razor views for flexible PDF reporting in .NET.
We've seen how to create report templates with Razor views, convert them to HTML, and then transform that HTML into beautifully formatted PDF documents.

Whether you need to generate invoices, sales reports, or any other kind of structured document, this approach offers a simple and customizable solution.

Here's what you can explore next:

- [PDF Reporting in .NET Using IronPDF and Razor Views](https://youtu.be/XYdcdVWsWos)
- [Creating PDF Reports With QuestPDF](how-to-easily-create-pdf-documents-in-aspnetcore)

That's all for this week. Stay awesome!

---



<Sponsorships>

Free eBook: [**Blazor Hybrid and Web in One Solution**](https://www.telerik.com/campaigns/blazor/ebook-blazor-hybrid?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-hybrid-ebook).
Dive into Blazor cross-platform apps, potential roadblocks, testing with Razor components, and more.
[**Get the eBook here**](https://www.telerik.com/campaigns/blazor/ebook-blazor-hybrid?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-hybrid-ebook)!

[**Postman v11**](https://blog.postman.com/announcing-postman-v11/): The future of API development is here.
Collaborate on APIs and supercharge your development workflow with AI.
AI features with Postbot.
Comment improvements in Postman Collections.
Postman Package Library.
[**Check it out here**](https://blog.postman.com/announcing-postman-v11/)!

</Sponsorships>

When you're dealing with thousands or even millions of records, efficiency is king.
That's where [**EF Core bulk update**](how-to-use-the-new-bulk-update-feature-in-ef-core-7) capabilities come into play.

EF Core 7 introduced two powerful new methods, `ExecuteUpdate` and `ExecuteDelete`.
They're designed to simplify bulk updates in your database.
Both methods have their respective async overloads - `ExecuteUpdateAsync` and `ExecuteDeleteAsync`.
[EF bulk updates](https://learn.microsoft.com/en-us/ef/core/saving/execute-insert-update-delete) offer significant performance advantages over traditional approaches.

However, there's an **important caveat**: these bulk operations bypass the EF Core **Change Tracker**.
This disconnect can lead to unexpected behavior if you're not aware of it.

In this week's issue, we'll dive into the details of bulk updates in EF Core.

## Understanding the EF Core ChangeTracker

When you load entities from the database with EF Core, the `ChangeTracker` starts tracking them.
As you update properties, delete entities, or add new ones, the `ChangeTracker` records these changes.

```csharp
using (var context = new AppDbContext())
{
    // Load a product
    var product = context.Products.FirstOrDefault(p => p.Id == 1);
    product.Price = 99.99; // Modify a property

    // At this point, the ChangeTracker knows that 'product' has been modified

    // Add a new product
    var newProduct = new Product { Name = "New Gadget", Price = 129.99 };
    context.Products.Add(newProduct);

    // Delete a product
    context.Products.Remove(product);

    context.SaveChanges(); // Persist all changes to the database
}
```

When you call `SaveChanges`, EF Core uses the `ChangeTracker` to determine which SQL commands to execute.
This ensures that the database is perfectly synchronized with your modifications.
The `ChangeTracker` acts as a bridge between your in-memory object model and your database.

If you're already familiar with how EF Core works, this serves mostly as a reminder.

## Bulk Updates and the ChangeTracker Disconnect

Now, let's focus on how [**bulk updates in EF Core**](how-to-use-the-new-bulk-update-feature-in-ef-core-7)
interact with the `ChangeTracker` - or rather, how they don't interact with it.
This design decision might seem counterintuitive, but there's a solid reason behind it: **performance**.

By directly executing SQL statements against the database, EF Core eliminates the overhead of tracking individual entity modifications.

```csharp
using (var context = new AppDbContext())
{
    // Increase price of all electronics by 10%
    context.Products
        .Where(p => p.Category == "Electronics")
        .ExecuteUpdate(
            s => s.SetProperty(p => p.Price, p => p.Price * 1.10));

    // In-memory Product instances with Category == "Electronics"
    // will STILL have their old price
}
```

In this example, we're increasing the price of all products in the `Electronics` category by 10%.
The `ExecuteUpdate` method efficiently translates the operation into a single SQL `UPDATE` statement.

```sql
UPDATE [p]
SET [p].[Price] = [p].[Price] * 1.10
FROM [Products] as [p];
```

However, if you inspect the `Product` instances that EF Core has already loaded into memory, you'll find that their `Price` properties haven't changed.
This might seem surprising if you aren't aware of how bulk updates interact with the change tracker.

Everything we discussed up to this point also applies to the `ExecuteDelete` method.

[**EF Core interceptors**](how-to-use-ef-core-interceptors) do not trigger for `ExecuteUpdate` and `ExecuteDelete` operations.
If you need to track or modify bulk update operations, you can create database triggers that fire whenever a relevant table is updated or deleted.
This allows you to log details and perform additional actions.

## The Problem: Maintaining Consistency

If `ExecuteUpdate` completes successfully, the changes are directly committed to the database.
This is because bulk operations bypass the `ChangeTracker` and don't participate in the usual transaction managed by `SaveChanges`.

If `SaveChanges` subsequently fails due to an error (e.g., validation error, database constraint violation, connection issue),
you'll be in an inconsistent state.
The changes made by `ExecuteUpdate` are already persisted.
Any changes made "in memory" are lost.

The most reliable way to ensure consistency is to wrap both `ExecuteUpdate` and the operations that lead to `SaveChanges` in a transaction:

```csharp {2}
using (var context = new AppDbContext())
using (var transaction = context.Database.BeginTransaction())
{
    try
    {
        context.Products
            .Where(p => p.Category == "Electronics")
            .ExecuteUpdate(
                s => s.SetProperty(p => p.Price, p => p.Price * 1.10));

        // ... other operations that modify entities

        context.SaveChanges();

        transaction.Commit();
    }
    catch (Exception ex)
    {
        // You could also let the transaction go out of scope.
        // This would automatically rollback any changes.
        transaction.Rollback();

        // Proceed to handle the exception...
    }
}
```

If `SaveChanges` fails, the transaction will be rolled back, reverting the changes made by both `ExecuteUpdate` and any other operations within the transaction.
This keeps your database in a consistent state.

## Summary

EF Core bulk update features, `ExecuteUpdate` and `ExecuteDelete`, are invaluable tools for optimizing performance.
By bypassing the `ChangeTracker` and executing raw SQL directly, they deliver significant speed improvements compared to traditional methods.

However, it's crucial to be mindful of the potential pitfalls associated with this approach.
The disconnect between in-memory entities and the database state can lead to unexpected results if not handled correctly.

My rule of thumb is to create an explicit [**database transaction**](working-with-transactions-in-ef-core) when I want to make additional entity changes.
We can be confident that all the changes will persist in the database or none of them will.

I hope this was helpful, and I'll see you next week.

**P.S.** Get the [source code](https://github.com/m-jovanovic/ef-bulk-updates) and try out the examples from this issue.

---



<Sponsorships>

Supercharge your [**API development with AI**](https://blog.postman.com/announcing-postman-v11/).
Postman v11 introduces many new features for collaboration, AI, and security.
Try out the new features like the VS Code extension, Partner Workspaces, and Postman Vault.
[**Learn more here**](https://blog.postman.com/announcing-postman-v11/).

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

</Sponsorships>

I once led the development of a fitness tracking app.
We started with Transaction Scripts to handle features like workout creation and exercise logging.
It was a simple and effective approach for the app's early stages.

However, as we added more complex features, our business logic became bloated.
New business rules intertwined with existing logic, making the code difficult to maintain.
Each change could introduce unintended consequences.

We solved our problem by introducing a Domain Model.
The domain model shifts the focus from procedures to domain objects.
Our code became more expressive, easier to reason about, and less prone to errors.

This experience taught me a valuable lesson, that I want to share in this newsletter.

## Transaction Script

At its core, business applications operate through distinct interactions (transactions) with their users.
These transactions can range from simple data retrieval to complex operations involving multiple validations, calculations, and updates to the system's database.

The Transaction Script pattern provides a simple way to encapsulate the logic behind each transaction.
It organizes all the necessary steps, from data access to business rules, into a single, self-contained procedure.

> Organizes business logic by procedures where each procedure handles a single request from the presentation.

_&mdash; [Transaction Script](https://martinfowler.com/eaaCatalog/transactionScript.html), Patterns of Enterprise Application Architecture_

Here's an example of adding exercises to a workout:

```csharp
internal sealed class AddExercisesCommandHandler(
    IWorkoutRepository workoutRepository,
    IUnitOfWork unitOfWork)
    : ICommandHandler<AddExercisesCommand>
{
    public async Task<Result> Handle(
        AddExercisesCommand request,
        CancellationToken cancellationToken)
    {
        Workout? workout = await workoutRepository.GetByIdAsync(
            request.WorkoutId,
            cancellationToken);

        if (workout is null)
        {
            return Result.Failure(WorkoutErrors.NotFound(request.WorkoutId));
        }

        List<Error> errors = [];
        foreach (ExerciseRequest exerciseDto in request.Exercises)
        {
            if (exerciseDto.TargetType == TargetType.Distance &&
                exerciseDto.DistanceInMeters is null)
            {
                errors.Add(ExerciseErrors.MissingDistance);

                continue;
            }

            if (exerciseDto.TargetType == TargetType.Time &&
                exerciseDto.DurationInSeconds is null)
            {
                errors.Add(ExerciseErrors.MissingDuration);

                continue;
            }

            var exercise = new Exercise(
                Guid.NewGuid(),
                workout.Id,
                exerciseDto.ExerciseType,
                exerciseDto.TargetType,
                exerciseDto.DistanceInMeters,
                exerciseDto.DurationInSeconds);

            workouts.Exercises.Add(exercise);
        }

        if (errors.Count != 0)
        {
            return Result.Failure(new ValidationError(errors.ToArray()));
        }

        await unitOfWork.SaveChangesAsync(cancellationToken);

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

There isn't much logic here. We're just checking whether the workout exists and whether the exercises are valid.

What happens when we start to add more logic?

Let's add another business rule.
We must enforce a limit on the number of exercises allowed in a single workout (e.g., no more than 10 exercises).

```csharp {47-52}
internal sealed class AddExercisesCommandHandler(
    IWorkoutRepository workoutRepository,
    IUnitOfWork unitOfWork)
    : ICommandHandler<AddExercisesCommand>
{
    public async Task<Result> Handle(
        AddExercisesCommand request,
        CancellationToken cancellationToken)
    {
        Workout? workout = await workoutRepository.GetByIdAsync(
            request.WorkoutId,
            cancellationToken);

        if (workout is null)
        {
            return Result.Failure(WorkoutErrors.NotFound(request.WorkoutId));
        }

        List<Error> errors = [];
        foreach (ExerciseRequest exerciseDto in request.Exercises)
        {
            if (exerciseDto.TargetType == TargetType.Distance &&
                exerciseDto.DistanceInMeters is null)
            {
                errors.Add(ExerciseErrors.MissingDistance);

                continue;
            }

            if (exerciseDto.TargetType == TargetType.Time &&
                exerciseDto.DurationInSeconds is null)
            {
                errors.Add(ExerciseErrors.MissingDuration);

                continue;
            }

            var exercise = new Exercise(
                Guid.NewGuid(),
                workout.Id,
                exerciseDto.ExerciseType,
                exerciseDto.TargetType,
                exerciseDto.DistanceInMeters,
                exerciseDto.DurationInSeconds);

            workouts.Exercises.Add(exercise);

            if (workouts.Exercise.Count > 10)
            {
                return Result.Failure(
                    WorkoutErrors.MaxExercisesReached(workout.Id));
            }
        }

        if (errors.Count != 0)
        {
            return Result.Failure(new ValidationError(errors.ToArray()));
        }

        await unitOfWork.SaveChangesAsync(cancellationToken);

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

We can continue adding more business logic to the transaction script.
For example, we can introduce exercise type restrictions or enforce a specific exercise order.
You can imagine how the complexity will keep increasing over time.

Another concern is code duplication between transaction scripts.
This could happen if we need similar logic in multiple transaction scripts.
You may be tempted to solve this by calling one transaction script from the other, but this will introduce a different set of problems.

So, how can we solve these problems?

## Refactoring to Domain Model

What is a domain model?

> An object model of the domain that incorporates both behavior and data.

_&mdash; [Domain Model](https://martinfowler.com/eaaCatalog/domainModel.html), Patterns of Enterprise Application Architecture_

A domain model lets you encapsulate domain logic (behavior) and state changes (data) inside an object.
In Domain-Driven Design terminology, we would call this an aggregate.

An aggregate in DDD is a cluster of objects treated as a single unit for data changes.
The aggregate represents a consistency boundary.
It helps maintain consistency by ensuring that certain invariants always hold true for the entire aggregate.
In our workout example, the `Workout` class can be treated as an aggregate root that encompasses all the exercises within it.

What does this have to do with a transaction script?

We can move the domain logic and state changes from the transaction script into the aggregate.
This is often called "pushing logic down" into the domain.

Here's what the domain model will look like when we extract the domain logic:

```csharp
public sealed class Workout
{
    private readonly List<Exercise> _exercises = [];

    // Omitting the constructor and other propreties for brevity.

    public Result AddExercises(ExerciseModel[] exercises)
    {
        List<Error> errors = [];
        foreach (var exerciseModel in exercises)
        {
            if (exerciseModel.TargetType == TargetType.Distance &&
                exerciseModel.DistanceInMeters is null)
            {
                errors.Add(ExerciseErrors.MissingDistance);

                continue;
            }

            if (exerciseModel.TargetType == TargetType.Time &&
                exerciseModel.DurationInSeconds is null)
            {
                errors.Add(ExerciseErrors.MissingDuration);

                continue;
            }

            var exercise = new Exercise(
                Guid.NewGuid(),
                workout.Id,
                exerciseDto.ExerciseType,
                exerciseDto.TargetType,
                exerciseDto.DistanceInMeters,
                exerciseDto.DurationInSeconds);

            workouts.Exercises.Add(exercise);

            if (workouts.Exercise.Count > 10)
            {
                return Result.Failure(
                    WorkoutErrors.MaxExercisesReached(workout.Id));
            }
        }

        if (errors.Count != 0)
        {
            return Result.Failure(new ValidationError(errors.ToArray()));
        }

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

With the domain logic inside of the domain model, we can easily share it between transaction scripts.
Testing the domain model is simpler than testing the transaction script.
With a transaction script, we must provide any dependencies (possibly as mocks) for testing.
However, we can test the domain model in isolation.

The updated transaction script becomes much more straightforward and focused on its primary task:

```csharp
internal sealed class AddExercisesCommandHandler(
    IWorkoutRepository workoutRepository,
    IUnitOfWork unitOfWork)
    : ICommandHandler<AddExercisesCommand>
{
    public async Task<Result> Handle(
        AddExercisesCommand request,
        CancellationToken cancellationToken)
    {
        Workout? workout = await workoutRepository.GetByIdAsync(
            request.WorkoutId,
            cancellationToken);

        if (workout is null)
        {
            return Result.Failure(WorkoutErrors.NotFound(request.WorkoutId));
        }

        var exercises = request.Exercises.Select(e => e.ToModel()).ToArray();

        var result = workout.AddExercises(exercises);

        if (result.IsFailure)
        {
            return result;
        }

        await unitOfWork.SaveChangesAsync(cancellationToken);

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

## Takeaway

Transaction Scripts are a practical starting point for simple applications.
They offer a straightforward approach to implementing use cases.
Transaction scripts are the recommended approach to start building [vertical slices](vertical-slice-architecture-structuring-vertical-slices).
However, transaction scripts can become difficult to maintain as the application grows.

[Refactoring toward a Domain Model](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model) allows you to encapsulate business logic in domain objects.
This promotes code reusability and makes your application more adaptable to changes.
Pushing logic down also improves testability and maintainability.

Should you use a Transaction Script or a Domain Model?

Here's a pragmatic approach you should consider.
Start with a transaction script, but pay attention to growing complexity.
When you notice a transaction script has too many concerns, consider adding a domain model.
Remember, the domain model should encapsulate some of the complexity of the domain logic.

Thanks for reading, and I'll see you next week!

---



<Sponsorships>

[**dotConnect**](https://www.devart.com/dotconnect/?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=dotconnect-general) is a feature-rich ADO.NET provider for developing data-related .NET applications.
It's fast, reliable, and works for all major databases and cloud services.
dotConnect is compatible with all Entity Framework and EF Core versions.
[**Start FREE trial today**](https://www.devart.com/dotconnect/?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=dotconnect-general)!

Use [**Postman V11 collaboration features**](https://learning.postman.com/docs/collaborating-in-postman/collaborate-in-postman-overview/)
to collaborate with your team and API Consumers.
Features include changing your workspace visibility, assigning roles to collaborators, sharing workspaces, and using Postman's API version control.
[**Learn more here**](https://learning.postman.com/docs/collaborating-in-postman/collaborate-in-postman-overview/)!

</Sponsorships>

Caching is one of the simplest techniques to significantly improve your application's performance.
It's the process of temporarily storing data in a faster access location.
You will typically cache the results of expensive operations or frequently accessed data.

Caching allows subsequent requests for the same data to be served from the cache instead of fetching the data from its source.

ASP.NET Core offers several types of caches, such as `IMemoryCache`, `IDistributedCache`, and the upcoming `HybridCache` (.NET 9).

In this newsletter, we will explore how to implement [caching in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/performance/caching/memory) applications.

## How Caching Improves Application Performance

Caching improves your application's performance by reducing latency and server load while enhancing scalability and user experience.

- **Faster data retrieval**: Cached data can be accessed much faster than retrieving it from the source (like a database or an API).
  Caches are typically stored in memory (RAM).
- **Fewer database queries**: Caching frequently accessed data reduces the number of database queries.
  This reduces the load on the database server.
- **Lower CPU usage**: Rendering web pages or processing API responses can consume significant CPU resources.
  Caching the results reduces the need for repetitive CPU-intensive tasks.
- **Handling increased traffic**: By reducing the load on backend systems, caching allows your application to handle
  more concurrent users and requests.
- **Distributed caching**: Distributed cache solutions like [Redis](https://redis.io/) enable scaling the cache across multiple servers,
  further improving performance and resilience.

In a recent project I worked on, we used Redis to scale to more than 1,000,000 users.
We only had one SQL Server instance with a read-replica for reporting.
The power of caching, eh?

## Caching Abstractions in ASP.NET Core

ASP.NET Core provides two primary abstractions for working with caches:

- `IMemoryCache`: Stores data in the memory of the web server.
  Simple to use but not suitable for distributed scenarios.
- `IDistributedCache`: Offers a more robust solution for distributed applications.
  It allows you to store cached data in a distributed cache like Redis.

We have to register these services with DI to use them.
`AddDistributedMemoryCache` will configure the in-memory implementation of `IDistributedCache`, which isn't distributed.

```csharp
builder.Services.AddMemoryCache();

builder.Services.AddDistributedMemoryCache();
```

Here's how you can use the `IMemoryCache`.
We will first check if the cached value is present and return it directly if it's there.
Otherwise, we must fetch the value from the database and cache it for subsequent requests.

```csharp
app.MapGet(
    "products/{id}",
    (int id, IMemoryCache cache, AppDbContext context) =>
    {
        if (!cache.TryGetValue(id, out Product product))
        {
            product = context.Products.Find(id);

            var cacheEntryOptions = new MemoryCacheEntryOptions()
                .SetAbsoluteExpiration(TimeSpan.FromMinutes(10))
                .SetSlidingExpiration(TimeSpan.FromMinutes(2));

            cache.Set(id, product, cacheEntryOptions);
        }

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

Cache expiration is another important topic to discuss.
We want to remove cache entries that aren't used and become stale.
You can pass in the `MemoryCacheEntryOptions`, allowing you to configure cache expiration.
For example, we can set the `AbsoluteExpiration` and `SlidingExpiration` values to control when the cache entry will expire.

## Cache-Aside Pattern

The cache-aside pattern is the most common caching strategy. Here's how it works:

1. **Check the cache**: Look for the requested data in the cache.
2. **Fetch from source (if cache miss)**: If the data isn't in the cache, fetch it from the source.
3. **Update the cache**: Store the fetched data in the cache for subsequent requests.

<Image
  src="blogs/mnw_093/cache_aside.png"
  width={1301}
  height={826}
  alt="Cache-aside pattern."
/>

Here's how you can implement the cache-aside pattern as an extension method for `IDistributedCache`:

```csharp
public static class DistributedCacheExtensions
{
    public static DistributedCacheEntryOptions DefaultExpiration => new()
    {
        AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(2)
    };

    public static async Task<T> GetOrCreateAsync<T>(
        this IDistributedCache cache,
        string key,
        Func<Task<T>> factory,
        DistributedCacheEntryOptions? cacheOptions = null)
    {
        var cachedData = await cache.GetStringAsync(key);

        if (cachedData is not null)
        {
            return JsonSerializer.Deserialize<T>(cachedData);
        }

        var data = await factory();

        await cache.SetStringAsync(
            key,
            JsonSerializer.Serialize(data),
            cacheOptions ?? DefaultExpiration);

        return data;
    }
}
```

We're using `JsonSerializer` to manage serialization to and from a JSON string.
The `SetStringAsync` method also accepts a `DistributedCacheEntryOptions` argument to control cache expiration.

Here's how we would use this extension method:

```csharp
app.MapGet(
    "products/{id}",
    (int id, IDistributedCache cache, AppDbContext context) =>
    {
        var product = cache.GetOrCreateAsync($"products-{id}", async () =>
        {
            var productFromDb = await context.Products.FindAsync(id);

            return productFromDb;
        });

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

## Pros and Cons of In-Memory Caching

Pros:

- Extremely fast
- Simple to implement
- No external dependencies

Cons:

- Cache data is lost if the server restarts
- Limited to the memory (RAM) of a single server
- Cache data is not shared across multiple instances of your application

## Distributed Caching With Redis

[Redis](https://redis.io/) is a popular in-memory data store often used as a high-performance distributed cache.
To use Redis in your ASP.NET Core application, you can use the `StackExchange.Redis` library.

However, there's also the `Microsoft.Extensions.Caching.StackExchangeRedis` library,
allowing you to integrate Redis with `IDistributedCache`.

```powershell
Install-Package Microsoft.Extensions.Caching.StackExchangeRedis
```

Here's how you can configure it with DI by providing a connection string to Redis:

```csharp
string connectionString = builder.Configuration.GetConnectionString("Redis");

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = connectionString;
});
```

An alternative approach is to register an `IConnectionMultiplexer` as a service.
Then, we will use it to provide a function for the `ConnectionMultiplexerFactory`.

```csharp
string connectionString = builder.Configuration.GetConnectionString("Redis");

IConnectionMultiplexer connectionMultiplexer =
    ConnectionMultiplexer.Connect(connectionString);

builder.Services.AddSingleton(connectionMultiplexer);

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.ConnectionMultiplexerFactory =
        () => Task.FromResult(connectionMultiplexer);
});
```

Now, when you inject `IDistributedCache`, it will use Redis under the hood.

## Cache Stampede and HybridCache

The in-memory cache implementations in ASP.NET Core are susceptible to race conditions, which can cause a cache stampede.
A [cache stampede](https://en.wikipedia.org/wiki/Cache_stampede) happens when concurrent requests encounter a cache miss and try to fetch the data from the source.
This can overload your application and negate the benefits of caching.

Locking is one solution for the cache stampede problem.
.NET offers many options for [locking and concurrency control](introduction-to-locking-and-concurrency-control-in-dotnet-6).
The most commonly used locking primitives are the `lock` statement and the `Semaphore` (or `SemaphoreSlim`) class.

Here's how we could use `SemaphoreSlim` to introduce locking before fetching data:

```csharp {3,13,24}
public static class DistributedCacheExtensions
{
    private static readonly SemaphoreSlim Semaphore = new SemaphoreSlim(1, 1);

    // Arguments omitted for brevity
    public static async Task<T> GetOrCreateAsync<T>(...)
    {
        // Fetch data from cache, and return if present

        // Cache miss
        try
        {
            await Semaphore.WaitAsync();

            var data = await factory();

            await cache.SetStringAsync(
                key,
                JsonSerializer.Serialize(data),
                cacheOptions ?? DefaultExpiration);
        }
        finally
        {
            Semaphore.Release();
        }

        return data;
    }
}
```

The previous implementation has a lock contention issue since all requests have to wait for the semaphore.
A much better solution would be locking based on the `key` value.

.NET 9 introduces a new caching abstraction called `HybridCache`, which aims to solve the shortcomings of `IDistributedCache`.
Learn more about this in the [Hybrid cache documentation](https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid).

## Summary

Caching is a powerful technique for improving web application performance.
ASP.NET Core's caching abstractions make it easy to implement various caching strategies.

We can choose from `IMemoryCache` for in-memory cache and `IDistributedCache` for distributed caching.

Here are a few guidelines to wrap up this week's issue:

- Use `IMemoryCache` for simple, in-memory caching
- Implement the cache aside pattern to minimize database hits
- Consider Redis as a high-performance distributed cache implementation
- Use `IDistributedCache` for sharing cached data across multiple applications

That's all for today.

See you next week.

---



<Sponsorships>

APIs are the Future.
Learn more about the [**API Lifecycle and API Documentation**](https://www.postman.com/api-platform/api-documentation/) by checking out this resource
as part of an introduction to the Postman API Platform.
[**Check it out here**](https://www.postman.com/api-platform/api-documentation/).

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

</Sponsorships>

Are you tired of organizing your project across layers?

Vertical Slice Architecture is a compelling alternative to traditional layered architectures.
[VSA](vertical-slice-architecture) flips the script on how we structure code.

Instead of horizontal layers (Presentation, Application, Domain), VSA organizes code by feature.
Each feature encompasses everything it needs, from API endpoints to data access.

In this newsletter, we will explore how you can structure vertical slices in VSA.

## Understanding Vertical Slices

At its core, a vertical slice represents a self-contained unit of functionality.
It's a slice through the entire application stack.
It encapsulates all the code and components necessary to fulfill a specific feature.

In traditional layered architectures, code is organized horizontally across the various layers.
One feature implementation can be scattered across many layers.
Changing a feature requires modifying the code in multiple layers.

VSA addresses this by grouping all the code for a feature into a single slice.

This shift in perspective brings several advantages:

- **Improved cohesion**: Code related to a specific feature resides together, making it easier to understand, modify, and test.
- **Reduced complexity**: VSA simplifies your application's mental model by avoiding the need to navigate multiple layers.
- **Focus on business logic**: The structure naturally emphasizes the business use case over technical implementation details.
- **Easier maintenance**: Changes to a feature are localized within its slice, reducing the risk of unintended side effects.

<Image
  src="blogs/mnw_092/vertical_slices.png"
  width={2159}
  height={1276}
  alt="Vertical slices."
/>

## Implementing Vertical Slice Architecture

Here's an example vertical slice representing the `CreateProduct` feature.
We use a static class to represent the feature and group the related types.
Each feature can have a respective `Request` and `Response` class.
The use case with the business logic can be in a [Minimal API endpoint](automatically-register-minimal-apis-in-aspnetcore).

A vertical slice is likely either a command or a query.
This approach gives us [CQRS](cqrs-pattern-with-mediatr) out of the box.

```csharp
public static class CreateProduct
{
    public record Request(string Name, decimal Price);
    public record Response(int Id, string Name, decimal Price);

    public class Endpoint : IEndpoint
    {
        public void MapEndpoint(IEndpointRouteBuilder app)
        {
            app.MapPost("products", Handler).WithTags("Products");
        }

        public static IResult Handler(Request request, AppDbContext context)
        {
            var product = new Product
            {
                Name = request.Name,
                Price = request.Price
            };

            context.Products.Add(product);

            context.SaveChanges();

            return Results.Ok(
                new Response(product.Id, product.Name, product.Price));
        }
    }
}
```

I want to mention a few benefits of structuring your application like this.

The code for the entire `CreateProduct` feature is tightly grouped within a single file.
This makes it extremely easy to locate, understand, and modify everything related to this functionality.
We don't need to navigate multiple layers (like controllers, services, repositories, etc.).

Directly using `AppDbContext` within the endpoint might tightly couple the slice to your database technology.
Depending on your project's size and requirements, you could consider abstracting data access (using a repository pattern)
to make the slice more adaptable to changes in the persistence layer.

## Introducing Validation in Vertical Slices

Vertical slices usually need to solve some [cross-cutting concerns](balancing-cross-cutting-concerns-in-clean-architecture), one of which is validation.
Validation is the gatekeeper, preventing invalid or malicious data from entering your system.
We can easily implement [validation with the FluentValidation library](cqrs-validation-with-mediatr-pipeline-and-fluentvalidation).

Within your slice, you'd define a `Validator` class that encapsulates the rules specific to your feature's request model.
It also supports dependency injection, so we can run complex validations here.

```csharp
public class Validator : AbstractValidator<Request>
{
    public Validator()
    {
        RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
        RuleFor(x => x.Price).GreaterThanOrEqualTo(0);
        // ... other rules
    }
}
```

This validator can then be injected into your endpoint using dependency injection, allowing you to perform validation before processing the request.

```csharp {6,20-24}
public static class CreateProduct
{
    public record Request(string Name, decimal Price);
    public record Response(int Id, string Name, decimal Price);

    public class Validator : AbstractValidator<Request> // { ... }

    public class Endpoint : IEndpoint
    {
        public void MapEndpoint(IEndpointRouteBuilder app)
        {
            app.MapPost("products", Handler).WithTags("Products");
        }

        public static IResult Handler(
            Request request,
            IValidator<Request> validator,
            AppDbContext context)
        {
            var validationResult = await validator.Validate(request);
            if (!validationResult.IsValid)
            {
                return Results.BadRequest(validationResult.Errors);
            }

            // ... (Create product and return response)
        }
    }
}
```

## Handling Complex Features and Shared Logic

The previous examples were simple.
But what do we do with complex features and shared logic?

VSA excels at managing self-contained features.
However, real-world applications often involve complex interactions and shared logic.

Here are a few strategies you can consider to address this:

- **Decomposition**: Break down complex features into smaller, more manageable vertical slices.
  Each slice should represent a cohesive piece of the overall feature.
- **Refactoring**: When a vertical slice becomes difficult to maintain, you can apply some refactoring techniques.
  The most common ones I use are `Extract method ` and `Extract class`.
- **Extract shared logic**: Identify common logic that's used across multiple features.
  Create a separate class (or extension method) to reference it from your vertical slices as needed.
- **Push logic down**: Write vertical slices using procedural code, like a [Transaction Script](https://martinfowler.com/eaaCatalog/transactionScript.html).
  Then, you can identify parts of the business logic that naturally belong to the domain entities.

You and your team will need to understand code smells and refactorings to make the most of VSA.

## Summary

Vertical Slice Architecture is more than just a way to structure your code.
By focusing on features, VSA allows you to create cohesive and maintainable applications.
Vertical slices are self-contained, making unit and integration testing more straightforward.

VSA brings benefits in terms of code organization and development speed, making it a valuable tool in your toolbox.
Code is grouped by feature, making it easier to locate and understand.
The structure aligns with the way business users think about features.
Changes are localized, reducing the risk of regressions and enabling faster iterations.

Consider embracing [Vertical Slice Architecture](vertical-slice-architecture) in your next project.
It's a big mindset shift from [Clean Architecture](/pragmatic-clean-architecture).
However, they both have their place and even share similar ideas.

That's all for this week. Stay awesome!

---



<Sponsorships>

Access the largest network of public APIs on the planet with the [**Postman Public API Network**](https://learning.postman.com/docs/collaborating-in-postman/public-api-network/verify-your-team/)
and [**Verified Teams**](https://learning.postman.com/docs/collaborating-in-postman/public-api-network/verify-your-team/).
Find public APIs faster and expand your API reach.
Those who have verified have seen API traffic increase by as much as 100%! [**Try it out today**](https://learning.postman.com/docs/collaborating-in-postman/public-api-network/verify-your-team/).

Looking to build interactive [**Blazor apps with WebAssembly**](https://www.telerik.com/blogs/building-interactive-blazor-apps-webassembly?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)?
Explore the latest features introduced in .NET 8, dive into the mechanics of Blazor WebAssembly, and create your first Blazor interactive WASM app.
[**Get started here**](https://www.telerik.com/blogs/building-interactive-blazor-apps-webassembly?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-general-awareness)!

</Sponsorships>

Picture this: You're part of a team building a shiny new .NET application.
You've carefully chosen your software architecture.
It could be microservices, a [**modular monolith**](/modular-monolith-architecture), or something else entirely.
You've decided which database you will use and all the other tools you need.
Everyone's excited, the code is flowing, and features are getting shipped.

Fast forward a few months (or years), and things might look different.

The codebase has grown, and new features have been added.
Maybe your team has even changed, with new developers coming on board.
Adding new features becomes a pain, and bugs are popping up left and right.

And slowly but surely, the neat architecture you started with has turned into a [big ball of mud](https://deviq.com/antipatterns/big-ball-of-mud).
What went wrong? And more importantly, what can we do about it?

Today, I want to show you how architecture testing can prevent this problem.

## Technical Debt

Technical debt is the consequence of prioritizing development speed over well-designed code.
It happens when teams cut corners to meet deadlines, make quick fixes, or don't understand the architecture clearly.

Each shortcut or hack adds to the pile, making the code harder to understand, change, and maintain.
But why do developers take these shortcuts in the first place?

Don't developers care about keeping the code clean?

Well, the truth is, most developers do care.
If you're reading this newsletter, odds are you also care.
But, developers are often under pressure to deliver features quickly.
Sometimes, the quickest way to do that is to take a shortcut.

Plus, not everyone has a deep understanding of software architecture, or they might disagree on what the "right" architecture is.
And let's be honest: some developers want to get their code working and move on to the next thing.

## Architecture Testing

Luckily, there's a way to enforce software architecture on your project before things get out of hand.
It's called [**architecture testing**](enforcing-software-architecture-with-architecture-tests).
These are automated tests that check whether your code follows the architectural rules you've set up.

With architecture testing, you can ["shift left"](https://en.wikipedia.org/wiki/Shift-left_testing).
This enables you to find and fix problems early in the development process when they're much easier and cheaper to deal with.

Think of it like a safety net for your software architecture and design rules.
If someone accidentally breaks a rule, the test will catch it and alert you.
Bonus points if you integrate architecture testing into your [**CI pipeline**](how-to-build-ci-cd-pipeline-with-github-actions-and-dotnet).

There are a few libraries you can use for architecture testing.
I prefer working with the [NetArchTest](https://github.com/BenMorris/NetArchTest) library, which I'll use for the examples.

You can check out this article to learn the [**fundamentals of architecture testing**](enforcing-software-architecture-with-architecture-tests).

Let's see how to write some architecture tests.

## Architecture Testing: Modular Monolith

You built an application using the [**modular monolith architecture**](what-is-a-modular-monolith).
But how can you maintain the constraints between the modules?

- Modules aren't allowed to reference each other
- Modules can only call the public API of other modules

Here's an architecture test that enforces these module constraints.
The `Ticketing` module is not allowed to reference the other modules directly.
However, it can reference the public API of other modules (integration events in this example).
The entry point is the `Types` class, which exposes a fluent API to build the rules you want to enforce.
NetArchTest allows us to enforce the direction of dependencies between modules.

```csharp
[Fact]
public void TicketingModule_ShouldNotHaveDependencyOn_AnyOtherModule()
{
    string[] otherModules = [
        UsersNamespace,
        EventsNamespace,
        AttendanceNamespace];

    string[] integrationEventsModules = [
        UsersIntegrationEventsNamespace,
        EventsIntegrationEventsNamespace,
        AttendanceIntegrationEventsNamespace];

    List<Assembly> ticketingAssemblies =
    [
        typeof(Order).Assembly,
        Modules.Ticketing.Application.AssemblyReference.Assembly,
        Modules.Ticketing.Presentation.AssemblyReference.Assembly,
        typeof(TicketingModule).Assembly
    ];

    Types.InAssemblies(ticketingAssemblies)
        .That()
        .DoNotHaveDependencyOnAny(integrationEventsModules)
        .Should()
        .NotHaveDependencyOnAny(otherModules)
        .GetResult()
        .ShouldBeSuccessful();
}
```

If you want to learn how to build robust and scalable systems using this architectural approach, check out [**Modular Monolith Architecture**](/modular-monolith-architecture).

## Architecture Testing: Clean Architecture

We can also write architecture tests for [**Clean Architecture**](why-clean-architecture-is-great-for-complex-projects).
The inner layers aren't allowed to reference the outer layers.
Instead, the inner layers define abstractions and the outer layers implement these abstractions.

For example, the `Domain` layer isn't allowed to reference the `Application` layer.
Here's an architecture test enforcing this rule:

```csharp
[Fact]
public void DomainLayer_ShouldNotHaveDependencyOn_ApplicationLayer()
{
    Types.InAssembly(DomainAssembly)
        .Should()
        .NotHaveDependencyOn(ApplicationAssembly.GetName().Name)
        .GetResult()
        .ShouldBeSuccessful();
}
```

It's also simple introduce a rule that the `Application` layer isn't allowed to reference the `Infrastructure` layer.
The architecture test will fail whenever someone in the team breaks the dependency rule.

```csharp
[Fact]
public void ApplicationLayer_ShouldNotHaveDependencyOn_InfrastructureLayer()
{
    Types.InAssembly(ApplicationAssembly)
        .Should()
        .NotHaveDependencyOn(InfrastructureAssembly.GetName().Name)
        .GetResult()
        .ShouldBeSuccessful();
}
```

We can introduce more architecture tests for the `Infrastructure` and `Presentation` layers, if needed.

Ready to learn more about building production-ready applications using this architectural approach?
You should check out [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture).

## Architecture Testing: Design Rules

Architecture testing is also useful for enforcing design rules in your code.
If your team has coding standards everyone should follow, architecture testing can help you enforce them.

For example, we want to ensure that all domain events are sealed types.
You can use the `BeSealed` method to enforce a design rule that types implementing `IDomainEvent` or `DomainEvent` should be sealed.

```csharp
[Fact]
public void DomainEvents_Should_BeSealed()
{
    Types.InAssembly(DomainAssembly)
        .That()
        .ImplementInterface(typeof(IDomainEvent))
        .Or()
        .Inherit(typeof(DomainEvent))
        .Should()
        .BeSealed()
        .GetResult()
        .ShouldBeSuccessful();
}
```

An interesting design rule could be requiring all domain entities not to have a public constructor.
Instead, you would create an `Entity` instance through a static factory method.
This approach improves the encapsulation of your `Entity`.

Here's an architecture test enforcing this design rule:

```csharp
[Fact]
public void Entities_ShouldOnlyHave_PrivateConstructors()
{
    IEnumerable<Type> entityTypes = Types.InAssembly(DomainAssembly)
        .That()
        .Inherit(typeof(Entity))
        .GetTypes();

    var failingTypes = new List<Type>();
    foreach (Type entityType in entityTypes)
    {
        ConstructorInfo[] constructors = entityType
            .GetConstructors(BindingFlags.Public | BindingFlags.Instance);

        if (constructors.Any())
        {
            failingTypes.Add(entityType);
        }
    }

    failingTypes.Should().BeEmpty();
}
```

Another thing you can do with architecture tests is enforce naming conventions in your code.
Here's an example of requiring all command handlers to have a name ending with `CommandHandler`:

```csharp
[Fact]
public void CommandHandler_ShouldHave_NameEndingWith_CommandHandler()
{
    Types.InAssembly(ApplicationAssembly)
        .That()
        .ImplementInterface(typeof(ICommandHandler<>))
        .Or()
        .ImplementInterface(typeof(ICommandHandler<,>))
        .Should()
        .HaveNameEndingWith("CommandHandler")
        .GetResult()
        .ShouldBeSuccessful();
}
```

## Summary

Even the most well-planned software projects decay because of technical debt.
Most developers have good intentions.
However, time pressure, misunderstandings, and resistance to rules all contribute to this problem.

[**Architecture testing**](enforcing-software-architecture-with-architecture-tests) acts as a safeguard.
It prevents your codebase from turning into a big ball of mud.
By catching architectural violations early on, you can shift left.
Short feedback loops avoid costly rework and improve developer productivity.
It also ensures the long-term health of your project.

A few key takeaways:

- **Technical debt is inevitable**: It slows down development, introduces bugs, and frustrates developers.
- **Architecture testing is your safety net**: It helps you catch architectural violations before they become problematic.
- **Start small and iterate**: You don't have to test everything at once. Focus on the most critical rules first.
- **Make it part of your workflow**: Integrate architecture tests into your CI/CD pipeline so they run automatically.

**Action point**: Start by exploring popular .NET architecture testing libraries like [ArchUnitNET](https://github.com/BenMorris/NetArchTest)
or [NetArchTest](https://github.com/TNG/ArchUnitNET).
Experiment with writing tests for common architectural rules and gradually integrate them into your development workflow.

That's all for today.

See you next week.

---


Previous issues of The .NET Weekly