
<Sponsorships>

Don't miss your last chance to [**join ABP training with 33% OFF**](https://abp.io/?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_mar8)!
Join a live, expert-led training covering ABP fundamentals, best practices, and real-world scenarios.
[**Master modular architecture & microservices**](https://abp.io/?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_mar8)
with ABP experts and boost your framework skills—offer ends March 14!

NET devs, your app's performance is trying to tell you something.
Are you listening?
[**Trace Explorer**](https://blog.sentry.io/find-and-fix-performance-bottlenecks-with-sentrys-trace-explorer/?utm_source=dotnetweekly&utm_medium=paid-community&utm_campaign=tracing-fy26q1-traceexplorer&utm_content=newsletter-dotnettracing-checkitout)
makes it easy to spot trends, find bottlenecks, and debug slow spans—without drowning in logs.
Search, filter, and aggregate to find what actually matters, like your slowest URLs, APIs & assets, jump straight to the culprit,
and get back to shipping cool stuff.
[**Check it out**](https://sentry.io/product/tracing/?utm_source=dotnetweekly&utm_medium=paid-community&utm_campaign=tracing-fy26q1-traceexplorer&utm_content=newsletter-dotnettracing-checkitout).

</Sponsorships>

When building web applications, knowing what's happening behind the scenes is crucial.
In ASP.NET Core, we can make our lives easier by adding user context to our request tracing.
This helps us track issues, understand user behavior, and improve our applications.

Let me show you how to enhance your request tracing by adding user context in ASP.NET Core applications.

## Why Add User Context to Request Tracing?

When something goes wrong in your application, having the user's ID in your logs makes it much easier to figure out what happened.
Instead of searching through thousands of log entries, you can filter by user ID and see only the relevant logs.

Adding user context also helps with:

- Tracking user journeys through your application
- Identifying patterns in user behavior
- Troubleshooting issues for specific users
- Monitoring performance for different user segments

## Implementing User Context Enrichment

The core of our solution is a middleware component that extracts the user ID from the current user's claims and adds it to the current **activity** and **logging scope**.

A **logging scope** in ASP.NET Core lets you attach additional data to all log messages created within that scope.
[**Structured logging**](structured-logging-in-asp-net-core-with-serilog) frameworks like [**Serilog**](5-serilog-best-practices-for-better-structured-logging)
and the built-in logger support this feature.
For example, if you add a user ID to a logging scope, every log message within that scope will include that user ID,
even if the log message itself doesn't mention the user.
This makes it easy to correlate logs for a specific user across different parts of your application.

The `Activity` class is part of the .NET diagnostics infrastructure.
It represents a unit of work or operation and is designed for distributed tracing across service boundaries.
When you add a tag to `Activity.Current`, that information becomes part of the trace and can be used to filter and analyze requests in your monitoring systems.

Here's the code:

```csharp {15,22}
using System.Diagnostics;
using System.Security.Claims;

namespace MyApp.Middleware;

public sealed class UserContextEnrichmentMiddleware(
    RequestDelegate next,
    ILogger<UserContextEnrichmentMiddleware> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        string? userId = context.User?.FindFirstValue(ClaimTypes.NameIdentifier);
        if (userId is not null)
        {
            Activity.Current?.SetTag("user.id", userId);

            var data = new Dictionary<string, object>
            {
                ["UserId"] = userId
            };

            using (logger.BeginScope(data))
            {
                await next(context);
            }
        }
        else
        {
            await next(context);
        }
    }
}
```

Let's break down what this middleware does:

1. It extracts the user ID from the authenticated user's claims using `context.User?.FindFirstValue(ClaimTypes.NameIdentifier)`
2. If a user ID is found, it adds the ID as a tag to the current activity with `Activity.Current?.SetTag("user.id", userId)`
3. It creates a logging scope using `ILogger.BeginScope` with the user ID, which means all log entries within this scope will include the user ID
4. It calls the next middleware in the pipeline
5. If no user ID is found (for anonymous requests), it simply calls the next middleware

## Logging Scopes and OpenTelemetry

If you're using [**OpenTelemetry**](introduction-to-distributed-tracing-with-opentelemetry-in-dotnet) to export logs,
you have to configure the provider to include the log scopes on the generated log records.

Here's how:

```csharp {3}
builder.Logging.AddOpenTelemetry(options =>
{
    options.IncludeScopes = true;
    options.IncludeFormattedMessage = true;
});
```

## Adding the Middleware to Your Application

To use this [**middleware**](3-ways-to-create-middleware-in-asp-net-core) in your ASP.NET Core application, add it to your pipeline in the `Program.cs` file:

```csharp {5}
app.UseAuthentication();
app.UseAuthorization();

// Add the user context enrichment middleware after authentication
app.UseMiddleware<UserContextEnrichmentMiddleware>();

app.MapControllers();

app.Run();
```

Make sure to place it after the authentication and authorization middleware so that the user identity is available.

## Handling PII Concerns

When adding user IDs to your logs and traces, you need to be careful about [Personally Identifiable Information](https://en.wikipedia.org/wiki/Personal_data) (PII).
Here are some important points to consider:

- User IDs should be opaque identifiers (like GUIDs) that don't reveal personal information
- Avoid logging email addresses, names, or other personal data
- Make sure your logging configuration doesn't send PII to systems where it shouldn't go

If you need to comply with data protection regulations, consider implementing log retention policies and the ability to purge user data from logs when needed.

## Expanding Context Enrichment

User IDs are just the beginning.
We can add more context to make our logs and traces even more useful:

### Feature Flags

[**Feature flags**](feature-flags-in-dotnet-and-how-i-use-them-for-ab-testing) help us roll out new features gradually or enable them for specific users.
Adding feature flag information to our context gives us valuable insights:

```csharp
// Inside the middleware
if (featureFlagService.IsEnabled("NewFeature", userId))
{
    Activity.Current?.SetTag("features.newfeature", "enabled");
    // Add to logging scope as well
}
```

### Tenant Information for Multi-tenant Applications

If your application serves [**multiple tenants**](multi-tenant-applications-with-ef-core), adding tenant IDs is extremely helpful:

```csharp
string? tenantId = context.User?.FindFirstValue("TenantId");
if (tenantId is not null)
{
    Activity.Current?.SetTag("tenant.id", tenantId);
    // Add to logging scope
}
```

## Takeaway

Adding user context to your request tracing in ASP.NET Core is a simple but powerful technique.
By implementing the middleware we've explored, you'll see several important benefits:

1. Faster troubleshooting - when users report issues, you can quickly find relevant logs
2. Better understanding of usage patterns - see which features are being used and by whom
3. Improved performance monitoring - identify slow requests for specific user segments
4. More effective A/B testing - track metrics for users with different feature flags

Understanding logging scopes and the `Activity` class helps you get the most out of this technique.
Logging scopes ensure your log entries contain consistent contextual information,
while activities enable distributed tracing across service boundaries.
Remember to be careful with PII and make sure your logging practices comply with relevant regulations.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**Get every Dometrain Course at 40% off**](https://dometrain.com/dometrain-pro/?ref=milan-jovanovic&promo=newsletter-20250301&coupon_code=MILAN03)!
Dometrain is an educational courses platform by Nick Chapsas.
With 79 courses, 20 authors and more than 55.000 students, there is no better place to invest in your learning as a .NET engineer.
Use code MILAN03 to get 40% off your first year of Dometrain Pro.
[**Get every course 40% off**](https://dometrain.com/dometrain-pro/?ref=milan-jovanovic&promo=newsletter-20250301&coupon_code=MILAN03)!

[**Archera**](https://fnf.dev/4hX4jrG) is unique among cloud cost management products for a simple reason: they insure your cloud commitments.
That means if you underutilize, say, an AWS Savings Plan or Microsoft Azure Consumption Commitment, they will write you an actual check to cover the difference.
They also allow you to achieve the cost savings of native cloud savings plans with a commitment as low as 30 days, instead of 1 to 3 years.
[**Check out their Azure offerings here**](https://fnf.dev/4hUI71r).

</Sponsorships>

Building distributed systems has never been more important—or more challenging.
As .NET developers, we're constantly juggling [service discovery](service-discovery-in-microservices-with-net-and-consul),
state management,
[messaging](simple-messaging-in-dotnet-with-redis-pubsub),
[resilience patterns](building-resilient-cloud-applications-with-dotnet),
and various infrastructure SDKs.
Our business logic gets buried under mountains of plumbing code, and we become tightly coupled to specific technologies.

What if there was a better way?

Enter [Dapr](https://dapr.io/) (Distributed Application Runtime), an open-source project that handles the complex infrastructure challenges so you can focus on what matters most:
your application's business logic.

In this article, we'll explore how Dapr transforms microservice development for .NET developers by:

- Abstracting away infrastructure-specific code behind consistent APIs
- Providing standardized building blocks for common distributed system patterns
- Enabling you to use the same code from local development to production
- Integrating seamlessly with .NET and ASP.NET Core applications

Whether you're building your first microservice or evolving a complex system, Dapr offers a simpler path forward.
Let's explore how it works.

## What is Dapr?

[Dapr](https://dapr.io/) is a portable, event-driven runtime that simplifies building microservices.
As a graduated project within the [Cloud Native Computing Foundation](https://www.cncf.io/) (CNCF), Dapr has proven its value in production environments.

At its core, Dapr provides standardized building blocks that abstract away the complexity of common microservice patterns.
Rather than wrestling with infrastructure-specific code, you can focus on your business logic while Dapr handles the rest.

Before Dapr, building a microservice architecture in .NET might require direct integration with multiple infrastructure components:

```csharp
// Pre-Dapr approach - direct infrastructure dependencies
builder.Services.AddStackExchangeRedisCache(options => { options.Configuration = "redis:6379"; });

builder.Services.AddSingleton<IMessageBroker>(provider => new KafkaMessageBroker("kafka:9092"));

builder.Services.AddSingleton<ISecretManager>(provider =>
    new AzureKeyVaultClient(new Uri("https://myvault.vault.azure.net")));
```

This approach tightly couples your application to specific technologies.

With Dapr, you gain flexibility through standardized APIs:

```csharp
// Dapr approach - simple, consistent APIs
builder.Services.AddDaprClient();

// Later in code:
// State management (could be Redis, Cosmos DB, etc.)
await daprClient.SaveStateAsync("statestore", "customer-123", customerData);

// Pub/sub (could be Kafka, RabbitMQ, etc.)
await daprClient.PublishEventAsync("pubsub", "orders", orderData);

// Secrets (could be Azure Key Vault, HashiCorp Vault, etc.)
var secret = await daprClient.GetSecretAsync("secretstore", "api-keys");
```

The underlying providers can be swapped without code changes - just by updating Dapr component configuration files.

## The Sidecar Pattern: How Dapr Works

Dapr uses the [sidecar](https://learn.microsoft.com/en-us/azure/architecture/patterns/sidecar) architectural pattern,
where it runs as a separate process alongside your application:

<figure className="figure-center">
  <Image
    src="blogs/mnw_131/dapr_sidecar.png"
    width={1482}
    height={842}
    alt="Dapr sidecar diagram with the building blocks and services."
  />
  <figcaption>Source: [Dapr](https://dapr.io/)</figcaption>
</figure>

Your application communicates with the Dapr sidecar through HTTP or gRPC, and Dapr handles communication with infrastructure services.
This separation brings several benefits:

- **Language Agnostic**: Dapr works with any programming language, including all .NET variants
- **Cross-cutting Concerns**: Security, observability, and resiliency are handled by Dapr, not your code
- **Infrastructure Abstraction**: Your application remains decoupled from specific technologies
- **Simplified Development**: Clean, maintainable code focused on business logic
- **Production Ready**: Built-in features that improve reliability in production environments

## Building Blocks: Dapr's Core Capabilities

Dapr offers several [building blocks](https://docs.dapr.io/concepts/building-blocks-concept/) that solve common microservice challenges.
Each provides a standardized API that abstracts away infrastructure complexity:

1. **Service Invocation**: Enables reliable service-to-service communication with automatic service discovery, load balancing, and retries.
2. **State Management**: Provides a unified way to store and retrieve state with features like concurrency control and transactions.
3. **Pub/Sub**: Implements asynchronous messaging between services, allowing for loosely-coupled, event-driven architectures.
4. **Workflows**: Enables you to define long running, persistent processes that span multiple microservices.
5. **Bindings**: Connects your applications to external systems, either for triggering your app from external events or invoking external services.
6. **Actors**: Implements the virtual actor pattern, making it easy to build stateful microservices with encapsulated state and behavior.
7. **Secrets**: Offers secure access to sensitive configuration like connection strings and API keys from various secret stores.
8. **Configuration**: Centralizes application settings with support for dynamic updates across multiple services.
9. **Distributed Lock**: Provides mutually exclusive access to shared resources in a distributed environment.
10. **Cryptography**: Offers encryption and decryption operations while handling key management.
11. **Jobs**: Allows you to schedule and orchestrate jobs (e.g., schedule batch processing jobs to run every business day)
12. **Conversation**: Lets you supply prompts to converse with different large language models (LLMs). Includes prompt caching and PII obfuscation.

Here's an overview of Dapr's building blocks and the most popular services they interact with:

<figure className="figure-center">
  <Image
    src="blogs/mnw_131/dapr_components.png"
    width={1806}
    height={1118}
    alt="Dapr components diagram with the base building blocks and services."
  />
  <figcaption>Source: [Dapr](https://dapr.io/)</figcaption>
</figure>

Let's explore the most commonly used building blocks in depth.

## Service Invocation

The [service invocation](https://docs.dapr.io/developing-applications/building-blocks/service-invocation/service-invocation-overview/)
building block enables reliable service-to-service communication with automatic mTLS encryption, retries, and observability.

This solves several challenging microservice problems:

- **Service Discovery**: Finding where services are located
- **Resilient Communication**: Handling transient failures gracefully
- **Load Balancing**: Distributing requests across multiple instances
- **Observability**: Tracking requests across service boundaries
- **Security**: Encrypting traffic between services

<figure className="figure-center">
  <Image
    src="blogs/mnw_131/dapr_service_invocation.png"
    width={1580}
    height={710}
    alt="Diagram showing how the service invocation flow looks like with Dapr."
  />
  <figcaption>Source: [Dapr](https://dapr.io/)</figcaption>
</figure>

Here's a simple example of invoking a service using Dapr's .NET SDK:

```csharp
// Client application making a request
using Dapr.Client;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprClient();

var app = builder.Build();

app.MapGet("/checkout/{itemId}", async (int itemId, DaprClient daprClient) =>
{
    // Create order data
    var orderData = new OrderData(itemId, DateTime.UtcNow);

    // Invoke the order-processing service
    var result = await daprClient.InvokeMethodAsync<OrderData, string>(
        "order-processor",
        "process-order",
        orderData);

    return Results.Ok(new { Message = $"Order {itemId} processed: {result}" });
});

await app.RunAsync();

public record OrderData(int ItemId, DateTime OrderedAt);
```

And the corresponding service handling the request:

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

app.MapPost("/process-order", (OrderData order) =>
{
    Console.WriteLine($"Processing order {order.ItemId} placed at {order.OrderedAt}");
    return $"Order {order.ItemId} confirmation: #{Guid.NewGuid().ToString()[..8]}";
});

await app.RunAsync();

public record OrderData(int ItemId, DateTime OrderedAt);
```

What's happening here:

- The `checkout` service calls `InvokeMethodAsync` using the `DaprClient` to send a request to the `order` service
- The Dapr sidecar for the checkout service receives this request
- The Dapr sidecar looks up the location of the order service
- The request is forwarded to the Dapr sidecar of the order service
- The order service's Dapr sidecar forwards the request to the order service
- The response follows the reverse path

This process provides automatic service discovery, encryption, retries, and distributed tracing without any additional code.

## Publish & Subscribe

The [publish and subscribe](https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-overview/)
building block provides asynchronous messaging between services with at-least-once delivery guarantees.
This pattern is essential for building resilient, loosely-coupled microservices that can:

- Process operations asynchronously without blocking the user
- Continue functioning when downstream services are unavailable
- Scale independently based on workload

<figure className="figure-center">
  <Image
    src="blogs/mnw_131/dapr_publish_subscribe.png"
    width={1280}
    height={720}
    alt="Diagram showing how the publish subscribe flow looks like with Dapr."
  />
  <figcaption>Source: [Dapr](https://dapr.io/)</figcaption>
</figure>

Pub/Sub in Dapr follows this flow:

- A publisher service sends a message to a topic via the Dapr sidecar
- The publisher Dapr sidecar converts the message to the [CloudEvent](https://cloudevents.io/) format and forwards it to the configured message broker
- Subscriber services receive the message through their Dapr sidecars
- The subscriber application processes the message

Dapr uses component configuration files to define the pub/sub message broker. Here's a typical Redis pub/sub component:

```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: order-events
spec:
  type: pubsub.redis
  version: v1
  metadata:
    - name: redisHost
      value: localhost:6379
    - name: redisPassword
      value: ''
```

The key parts of this configuration are:

- `metadata.name`: The component name (`order-events`) that your application will reference when publishing/subscribing
- `spec.type`: The type of component (`pubsub.redis` in this case)
- `spec.metadata`: Configuration specific to the component type

This file should be placed in a `components` directory where Dapr can discover it.
When running locally, this is typically `./components/` relative to your application.

What if you want to switch from Redis to RabbitMQ?
You'd replace the `spec.type` with `pubsub.rabbitmq` and update the `metadata` section accordingly.
This change doesn't require any code modifications in your application.
Isn't this flexibility amazing?

Here's how to publish events using Dapr:

```csharp
// Publisher service
using Dapr.Client;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprClient();

var app = builder.Build();

app.MapPost("/create-order", async (OrderRequest request, DaprClient daprClient) =>
{
    var orderEvent = new OrderCreatedEvent(
        request.OrderId,
        request.CustomerId,
        request.Items,
        DateTime.UtcNow
    );

    // Publish event to "orders" topic
    await daprClient.PublishEventAsync("order-events", "orders", orderEvent);

    return Results.Accepted();
});

await app.RunAsync();

public record OrderRequest(Guid OrderId, string CustomerId, List<string> Items);
public record OrderCreatedEvent(Guid OrderId, string CustomerId, List<string> Items, DateTime CreatedAt);
```

And here's how a subscriber would handle these events:

```csharp
// Subscriber service
using Dapr;
using Microsoft.AspNetCore.OutputCaching;

var builder = WebApplication.CreateBuilder(args);

// Add Dapr event handling
builder.Services.AddDapr();
builder.Services.AddControllers();

var app = builder.Build();

// Required for Dapr pub/sub
app.UseCloudEvents();
app.MapSubscribeHandler();

// Subscribe to "orders" topic
app.MapPost("/events/orders", [Topic("order-events", "orders")] async (OrderCreatedEvent orderEvent) =>
{
    Console.WriteLine($"Processing order {orderEvent.OrderId} for customer {orderEvent.CustomerId}");
    await ProcessOrderAsync(orderEvent);
    return Results.Ok();
});

await app.RunAsync();

async Task ProcessOrderAsync(OrderCreatedEvent orderEvent)
{
    // Process the order
    await Task.Delay(100); // Simulate work
}

public record OrderCreatedEvent(Guid OrderId, string CustomerId, List<string> Items, DateTime CreatedAt);
```

The key components:

- The publisher uses Dapr to send events to a topic
- Dapr handles the interaction with the message broker (Kafka, Redis, etc.)
- The subscriber decorates endpoints with `[Topic]` attributes
- Dapr delivers the messages to the appropriate subscribers

Note that the `name` defined in the component file (`order-events` in our example) must match the first parameter used in
`PublishEventAsync("order-events", ...)` and `[Topic("order-events", ...)]`.
If these names don't match exactly, messages won't flow correctly between services.

## Dapr and .NET Aspire: Better Together

[Dapr works seamlessly with .NET Aspire](https://www.diagrid.io/blog/net-aspire-dapr-what-are-they-and-how-they-complement-each-other),
Microsoft's new cloud-ready stack for building distributed applications.
While Aspire focuses on .NET-specific application orchestration, Dapr provides language-agnostic building blocks.

Here's how to integrate Dapr with a .NET Aspire application:

```csharp
using CommunityToolkit.Aspire.Hosting.Dapr;

// Program.cs in the Aspire AppHost project
var builder = DistributedApplication.CreateBuilder(args);

// Add Aspire service and configure Dapr
var orderService = builder.AddProject<Projects.OrderService>("orderservice")
    .WithDaprSidecar(new DaprSidecarOptions
    {
        AppId = "order-api",
        Config = "./dapr/config.yaml",
        ResourcesPaths = ["./dapr/components"]
    });

// Add another service that can communicate with the order service via Dapr
var checkoutService = builder.AddProject<Projects.CheckoutService>("checkoutservice")
    .WithDaprSidecar(new DaprSidecarOptions
    {
        AppId = "checkout-api",
        Config = "./dapr/config.yaml",
        ResourcesPaths = ["./dapr/components"]
    })
    // Reference the order service by its Dapr app ID
    .WithReference(orderService);

builder.Build().Run();
```

Note that I'm using the `CommunityToolkit.Aspire.Hosting.Dapr` package, which is the official Dapr integration for .NET Aspire.
The `Aspire.Hosting.Dapr` library is now deprecated.

Here's an example of how a message flow might look in the Aspire dashboard:

<Image
  src="blogs/mnw_131/dapr_aspire_distributed_trace.png"
  width={1920}
  height={570}
  alt="A distributed trace from the Aspire dashboard showing a message flow from the checkout service to the order service."
/>

## Learning with Dapr University

If you're looking for a structured way to learn Dapr, I highly recommend checking out [**Dapr University**](https://diagrid.ws/41oIYRX).
You can run the hands-on lessons completely for free.

As someone who started with limited Dapr experience, I found the "Dapr 101" course particularly valuable.
It provides hands-on exercises for State Management, Service Invocation, and Pub/Sub—exactly what you need to get started quickly.

<Image
  src="blogs/mnw_131/dapr_university.png"
  width={1920}
  height={1079}
  alt="Dapr university learning platform."
/>

## Conclusion

Dapr simplifies microservice development for .NET developers by providing standardized building blocks that handle infrastructure complexity.
With its sidecar pattern, Dapr lets you focus on business logic while it manages cross-cutting concerns.
As you build distributed applications, consider how Dapr can help you:

- Accelerate development with ready-made patterns
- Build more resilient systems with fewer lines of code
- Avoid vendor lock-in through abstraction (building blocks)
- Improve production reliability with built-in best practices

Ready to dive deeper?
Check out [**Dapr University**](https://diagrid.ws/41oIYRX) for comprehensive courses and hands-on learning.

That's all for today. Hope this was helpful.

---



<Sponsorships>

[**Deliver data-heavy Blazor Apps in half the time**](https://demos.telerik.com/blazor-ui?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=blazor-general-awareness-demos).
UI Library With 110+ Native Components for Building Modern and Feature-Rich Applications.
Featuring the Fastest Blazor Grid, Charts, Scheduler, Editor, Dropdown list and many more.
[**See demos here**](https://demos.telerik.com/blazor-ui?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=blazor-general-awareness-demos).

Using [**MassTransit with RabbitMQ or Azure Service Bus**](https://go.particular.net/mt_error_management-mj-1)?
Stop wasting valuable time click-click-clicking through **dead-letter & error queues** or writing (and maintaining) custom scripts to fix and reprocess failed messages.
[**Try the MassTransit Error Management platform today**](https://go.particular.net/mt_error_management-mj-1)!

</Sponsorships>

I've been meaning to write this article for a while now.
This problem has been bugging me, and I finally found the time to address it.

What problem is that?

Well, it's about MediatR's [notification publishing](how-to-publish-mediatr-notifications-in-parallel) mechanism.

MediatR supports simple in-process publish/subscribe capabilities.
This lets you broadcast notifications to multiple handlers without coupling them directly to the publisher.

While MediatR's notification system appears asynchronous at first glance, **it's not**.

By asynchronous, I mean that the publishing thread should not wait for all handlers to complete.
Instead, it should return immediately after queuing the notification for processing.

In this article, we'll understand MediatR's notification publishing mechanics.
We'll use distributed tracing to examine its execution model, and explore alternatives for true asynchronous processing.

## The Notification Publisher

[MediatR](https://github.com/jbogard/MediatR) provides two built-in implementations of its `INotificationPublisher` interface.
They each have distinct characteristics but share one crucial trait: they block the publishing thread until the handlers complete.

Here's the `INotificationPublisher` interface:

```csharp
public interface INotificationPublisher
{
    Task Publish(
        IEnumerable<NotificationHandlerExecutor> handlerExecutors,
        INotification notification,
        CancellationToken cancellationToken);
}
```

This interface provides the contract for executing notification handlers, but the execution strategy is left to the implementing classes.

By default, MediatR uses the `ForeachAwaitPublisher`:

```csharp
public class ForeachAwaitPublisher : INotificationPublisher
{
    public async Task Publish(
        IEnumerable<NotificationHandlerExecutor> handlerExecutors,
        INotification notification,
        CancellationToken cancellationToken)
    {
        foreach (var handler in handlerExecutors)
        {
            await handler.HandlerCallback(notification, cancellationToken).ConfigureAwait(false);
        }
    }
}
```

This implementation processes handlers sequentially, ensuring a predictable order of execution.

The alternative `TaskWhenAllPublisher` offers concurrent execution:

```csharp
public class TaskWhenAllPublisher : INotificationPublisher
{
    public Task Publish(
        IEnumerable<NotificationHandlerExecutor> handlerExecutors,
        INotification notification,
        CancellationToken cancellationToken)
    {
        var tasks = handlerExecutors
            .Select(handler => handler.HandlerCallback(notification, cancellationToken))
            .ToArray();

        return Task.WhenAll(tasks);
    }
}
```

While this publisher executes handlers concurrently, it's crucial to understand that "concurrent" doesn't mean ["background processing"](building-async-apis-in-aspnetcore-the-right-way).
The publishing thread still waits for all handlers to complete before continuing.

## Proving the Point with OpenTelemetry

To demonstrate the blocking nature of both publishers, let's set up a simple example with [OpenTelemetry](https://opentelemetry.io/) tracing:

```csharp {9-11}
var builder = WebApplication.CreateBuilder(args);

// This will register all handlers in the same assembly as the Program class
// We're also configuring the notifcation publisher
builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssemblyContaining<Program>();

    cfg.NotificationPublisherType = typeof(ForeachAwaitPublisher);
    // or we could say 👇
    // cfg.NotificationPublisherType = typeof(TaskWhenAllPublisher);
});

builder.Services
    .AddOpenTelemetry()
    .ConfigureResource(r => r.AddService(DiagnosticConfig.Source.Name))
    .WithTracing(tracing =>
        tracing
            .AddAspNetCoreInstrumentation()
            .AddSource(DiagnosticConfig.Source.Name))
    .UseOtlpExporter();

var app = builder.Build();

// Dummy endpoint to trigger the notification
app.MapPost("orders", async (IMediator mediator) =>
{
    using var activity = DiagnosticConfig.Source.StartActivity("CreateOrder");

    var orderId = Guid.NewGuid();
    // Just publish the notification, we don't care about doing "real" work here
    await mediator.Publish(new OrderCreatedNotification
    {
        OrderId = orderId,
        ParentId = activity?.Id // Propagating the parent activity ID
    });

    return Results.Ok(orderId);
});

app.Run();

// The simple notification class
public class OrderCreatedNotification : INotification
{
    public Guid OrderId { get; set; }
    public string? ParentId { get; set; }
}

// A slow handler to simulate blocking behavior
public class SlowOrderCreatedHandler(ILogger<SlowOrderCreatedHandler> logger)
    : INotificationHandler<OrderCreatedNotification>
{
    public async Task Handle(OrderCreatedNotification notification, CancellationToken token)
    {
        using var activity = DiagnosticConfig.Source.StartActivity(
            "SlowOrderCreatedHandler.Handle",
            ActivityKind.Internal,
            notification.ParentId);

        await Task.Delay(2000, token); // Simulate work

        logger.LogInformation(
            "Slow handler completed for order {OrderId}",
            notification.OrderId);
    }
}

// Defines the OpenTelemetry ActivitySource
internal static class DiagnosticConfig
{
    internal static readonly ActivitySource Source = new("Order.Service");
}
```

When we examine the resulting traces, we'll see that the handler execution spans are contained within the HTTP request span,
indicating that the request thread is blocked until all handlers complete.

Now, let's see how these publishers behave in practice.
I'll add a few more handlers to the mix to make the example more interesting.

### ForeachAwaitPublisher Traces

You can see the sequential execution of handlers in the trace visualization.
The request span encompasses all handler execution, demonstrating the blocking nature of the `ForeachAwaitPublisher`.

<Image
  src="blogs/mnw_130/foreachawait_publisher.png"
  width={1707}
  height={482}
  alt="Distributed trace demonstrating notification handling."
/>

### TaskWhenAllPublisher Traces

Similarly, the `TaskWhenAllPublisher` shows concurrent handler execution within the request span.
We do get a slight improvement in handler execution time, but the request thread still waits for all handlers to complete before returning.

<Image
  src="blogs/mnw_130/taskwhenall_publisher.png"
  width={1709}
  height={481}
  alt="Distributed trace demonstrating notification handling."
/>

## Building an Async Notification Publisher with Channels

How can we make MediatR's notification publishing truly asynchronous?

We'll implement a custom `INotificationPublisher` that leverages `System.Threading.Channels` for true asynchronous processing.
This implementation will queue notifications for background processing, allowing the publishing thread to return immediately.

Here's the `ChannelPublisher`:

```csharp
// The publisher just queues the notification for processing
public class ChannelPublisher(NotificationsQueue queue) : INotificationPublisher
{
    public async Task Publish(
        IEnumerable<NotificationHandlerExecutor> handlerExecutors,
        INotification notification,
        CancellationToken cancellationToken)
    {
        // Write the message to the channel, and return immediately
        await queue.Writer.WriteAsync(
            new NotificationEntry(handlerExecutors.ToArray(), notification),
            cancellationToken);
    }
}

// It's the Channel that handles the actual message passing
// We can control the capacity and backpressure handling here
public class NotificationsQueue(int capacity = 100)
{
    private readonly Channel<NotificationEntry> _queue =
        Channel.CreateBounded<NotificationEntry>(new BoundedChannelOptions(capacity)
        {
            FullMode = BoundedChannelFullMode.Wait // Backpressure handling
        });

    public ChannelReader<NotificationEntry> Reader => _queue.Reader;
    public ChannelWriter<NotificationEntry> Writer => _queue.Writer;
}

// A simple data structure to hold the notification and handlers
public record NotificationEntry(NotificationHandlerExecutor[] Handlers, INotification Notification);

// Program.cs
builder.Services.AddSingleton<NotificationsQueue>();
```

But this is just part of the solution.
We need a background service to process the queued notifications:

```csharp
// We'll use the NotificationsQueue to read and process notifications
public class ChannelPublisherWorker(NotificationsQueue queue) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Read notifications from the queue and process them
        await foreach (NotificationEntry entry in queue.Reader.ReadAllAsync(stoppingToken))
        {
            // Parallel.ForEachAsync for style points
            await Parallel.ForEachAsync(entry.Handlers, stoppingToken, async (executor, token) =>
            {
                // We're finally executing the handler
                await executor.HandlerCallback(entry.Notification, token);
            });
        }
    }
}

// Program.cs
builser.Services.AddHostedService<ChannelPublisherWorker>();
```

This implementation offers several advantages:

- True background processing - the publisher returns immediately after queueing the notification
- Backpressure handling through bounded channel capacity
- Independent handler execution

To use this publisher, register it with MediatR by setting the `NotificationPublisherType` to be `ChannelPublisher`:

```csharp
services.AddMediatR(cfg =>
{
    cfg.NotificationPublisherType = typeof(ChannelPublisher);
});
```

Let's see how this implementation performs in practice.

## Comparing Approaches With OpenTelemetry

When we examine the traces with our `ChannelPublisher`, we'll see a significant difference:

1. The HTTP request span completes quickly after queueing the notification
2. Handler execution spans appear as separate traces
3. Overall system responsiveness improves

<Image
  src="blogs/mnw_130/channel_publisher.png"
  width={1706}
  height={485}
  alt="Distributed trace demonstrating notification handling."
/>

This visualization clearly demonstrates the non-blocking nature of our implementation.

But is it worth it?

Here's what you should consider first before adopting this approach:

- The `ChannelPublisher` introduces additional complexity compared to the built-in publishers
- Error handling is your responsibility (e.g., retrying failed handlers, [dead-letter queue](https://en.wikipedia.org/wiki/Dead_letter_queue))
- And did I mention [idempotent consumers](idempotent-consumer-handling-duplicate-messages)? Yeah... you need those too
- [Channels](lightweight-in-memory-message-bus-using-dotnet-channels) aren't durable - messages are lost if the application crashes

Before you know it, you might find yourself reinventing the wheel with a custom message queueing system.

Instead, consider using a real message broker like [RabbitMQ](https://www.rabbitmq.com/).
Combine it with a library like [MassTransit](https://masstransit.io) or [NServiceBus](https://particular.net/nservicebus) for a robust, scalable, and reliable messaging solution.

## Takeaway

MediatR's notification system is great for simple in-process pub/sub scenarios.
However, the built-in publishers can become a bottleneck in high-throughput applications due to their blocking nature.

The `ChannelPublisher` implementation we explored offers true asynchronous processing.
However, it also comes with extra complexity around message handling and delivery guarantees.
Managing message persistence, error handling, retries, and idempotency quickly becomes challenging.

If your application requires these features,
you'll be better off adopting a mature solution like [RabbitMQ](using-masstransit-with-rabbitmq-and-azure-service-bus)
or [Amazon SQS](complete-guide-to-amazon-sqs-and-amazon-sns-with-masstransit).

That's all for today. Hope this was helpful.

---



<Sponsorships>

Build better with AWS, using tips and tools from the
Developer Center:

- Get hands-on with DevOps, Data & ML, and
  Generative AI
- Use any language, level up your skills
- Connect with like-minded devs all over the world on
  AWS Communities

[**The AWS Developer Center**](https://fnf.dev/3X0uNQz) has everything you need in one place. Don't miss out!

\
Great opportunity to get started and upgrade your ABP skills!
[**Enroll in live ABP training with a 33% discount**](https://abp.io/?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_feb15)!
Learn modular architecture, microservices, and best practices from ABP experts.
[**Get started today**](https://abp.io/?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_feb15).

</Sponsorships>

Pagination is crucial for efficiently handling large datasets.
While offset pagination is widely used and gets the job done, cursor-based pagination offers some interesting advantages for certain scenarios.

It's particularly valuable for real-time feeds, infinite scroll interfaces, and APIs where performance at scale matters -
like social media timelines, activity logs, or event streams where users frequently page through large datasets.

Let's explore both approaches using a simple `UserNotes` table and see how they perform with a million records.

We'll look at the implementation details, compare query performance, and discuss where each approach makes the most sense.

I've included real execution plans from [PostgreSQL](https://www.postgresql.org) to demonstrate the significant performance differences between these approaches.

## Database Schema

I created a simple table to demonstrate pagination techniques.
The table is seeded with `1,000,000` records for testing purposes, which should be enough to show the performance difference between offset and cursor pagination.

We'll use the following SQL schema for the examples:

```sql
CREATE TABLE user_notes (
    id uuid NOT NULL,
    user_id uuid NOT NULL,
    note character varying(500),
    date date NOT NULL,
    CONSTRAINT pk_user_notes PRIMARY KEY (id)
);
```

And here's the C# class representing the `UserNote` entity:

```csharp
public class UserNote
{
    public Guid Id { get; set; }
    public Guid UserId { get; set; }
    public string? Note { get; set; }
    public DateOnly Date { get; set; }
}
```

I will use PostgreSQL as the database, but the concepts also apply to other databases.

## Offset Pagination: The Traditional Approach

[Offset pagination](https://learn.microsoft.com/en-us/ef/core/querying/pagination#offset-pagination) uses `Skip` and `Take` operations.
We _skip_ a certain number of rows and _take_ a fixed number of rows.
These usually translate to `OFFSET` and `LIMIT` in SQL queries.

Here's an example of offset pagination in ASP.NET Core:

```csharp {21,22}
app.MapGet("/offset", async (
    AppDbContext dbContext,
    int page = 1,
    int pageSize = 10,
    CancellationToken cancellationToken = default) =>
{
    if (page < 1) return Results.BadRequest("Page must be greater than 0");
    if (pageSize < 1) return Results.BadRequest("Page size must be greater than 0");
    if (pageSize > 100) return Results.BadRequest("Page size must be less than or equal to 100");

    var query = dbContext.UserNotes
        .OrderByDescending(x => x.Date)
        .ThenByDescending(x => x.Id);

    // Offset pagination typically counts the total number of items
    var totalCount = await query.CountAsync(cancellationToken);
    var totalPages = (int)Math.Ceiling(totalCount / (double)pageSize);

    // Skip and take the required number of items
    var items = await query
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .ToListAsync(cancellationToken);

    return Results.Ok(new
    {
        Items = items,
        Page = page,
        PageSize = pageSize,
        TotalCount = totalCount,
        TotalPages = totalPages,
        HasNextPage = page < totalPages,
        HasPreviousPage = page > 1
    });
});
```

Note that I'm sorting the results by `Date` and `Id` in descending order.
This ensures consistent results when paginating.

Here's the generated SQL for offset pagination:

```sql
-- This query is sent first
SELECT count(*)::int FROM user_notes AS u;

-- Followed by the actual data query
SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
ORDER BY u.date DESC, u.id DESC
LIMIT @pageSize OFFSET @offset;
```

### Limitations of Offset Pagination:

1. Performance degrades as offset increases because the database must scan and discard all rows before the offset
2. Risk of missing or duplicating items when data changes between pages
3. Inconsistent results with concurrent updates

## Cursor-Based Pagination: A Faster Approach

[Cursor pagination](https://learn.microsoft.com/en-us/ef/core/querying/pagination#keyset-pagination) uses a reference point (cursor) to fetch the next set of results.
This reference point is typically a **unique identifier** or a combination of fields that define the sort order.

I'll use the `Date` and `Id` fields to create a cursor for our `UserNotes` table.
The cursor is a composite of these two fields, allowing us to paginate efficiently.

Here's an example of cursor pagination in ASP.NET Core:

```csharp {17, 24}
app.MapGet("/cursor", async (
    AppDbContext dbContext,
    DateOnly? date = null,
    Guid? lastId = null,
    int limit = 10,
    CancellationToken cancellationToken = default) =>
{
    if (limit < 1) return Results.BadRequest("Limit must be greater than 0");
    if (limit > 100) return Results.BadRequest("Limit must be less than or equal to 100");

    var query = dbContext.UserNotes.AsQueryable();

    if (date != null && lastId != null)
    {
        // Use the cursor to fetch the next set of results
        // If we were sorting in ASC order, we'd use > instead of <
        query = query.Where(x => x.Date < date || (x.Date == date && x.Id <= lastId));
    }

    // Fetch the items and determine if there are more
    var items = await query
        .OrderByDescending(x => x.Date)
        .ThenByDescending(x => x.Id)
        .Take(limit + 1)
        .ToListAsync(cancellationToken);

    // Extract the cursor and ID for the next page
    bool hasMore = items.Count > limit;
    DateOnly? nextDate = hasMore ? items[^1].Date : null;
    Guid? nextLastId = hasMore ? items[^1].Id : null;

    // Remove the extra item before returning results
    if (hasMore)
    {
        items.RemoveAt(items.Count - 1);
    }

    return Results.Ok(new
    {
        Items = items,
        NextDate = nextDate,
        NextLastId = nextLastId,
        HasMore = hasMore
    });
});
```

The sort order is the same as in the offset pagination example.
However, the sort order is critical for consistent results with cursor pagination.
Because the `Date` isn't a unique value in our table, we use the `Id` field to handle ties.
This ensures that we don't miss or duplicate items when paginating.

Here's the generated SQL for cursor pagination:

```sql
SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
WHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)
ORDER BY u.date DESC, u.id DESC
LIMIT @limit;
```

Note that there's no `OFFSET` in the query.
We're directly seeking the rows based on the cursor, which is more efficient than offset pagination.

The `COUNT` query is omitted in cursor pagination because we're not counting the total number of items.
This can be a limitation if you need to display the total number of pages upfront.
However, the performance benefits of cursor pagination often outweigh this limitation.

### Limitations of Cursor Pagination:

1. If users need to change sort fields dynamically, cursor pagination becomes significantly more complicated since the cursor must incorporate all sort conditions
2. Users can't jump to a specific page number - they must traverse sequentially through the pages
3. More complex to implement correctly compared to offset pagination, especially when handling ties and ensuring stable ordering

## Examining the SQL Execution Plans

I wanted to compare the execution plans for offset and cursor pagination.
I used the `EXPLAIN ANALYZE` command in PostgreSQL to see the [query plans](https://www.postgresql.org/docs/current/using-explain.html).

Here's the offset pagination query:

```sql
SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
ORDER BY u.date DESC, u.id DESC
LIMIT 1000 OFFSET 900000;
```

I'm intentionally skipping `900,000` rows to exaggerate the performance impact.
After that, we fetch the next `1,000` rows.

Here's the query plan for offset pagination:

```sql
EXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
ORDER BY u.date DESC, u.id DESC
LIMIT 1000 OFFSET 900000;

---
Limit  (cost=165541.59..165541.71 rows=1 width=52) (actual time=695.026..701.406 rows=1000 loops=1)
  ->  Gather Merge  (cost=68312.50..165541.59 rows=833334 width=52) (actual time=342.475..684.567 rows=901000 loops=1)
        Workers Planned: 2
        Workers Launched: 2
        ->  Sort  (cost=67312.48..68354.15 rows=416667 width=52) (actual time=327.846..450.295 rows=300841 loops=3)
              Sort Key: date DESC, id DESC
              Sort Method: external merge  Disk: 20440kB
              Worker 0:  Sort Method: external merge  Disk: 18832kB
              Worker 1:  Sort Method: external merge  Disk: 18912kB
              ->  Parallel Seq Scan on user_notes u  (cost=0.00..14174.67 rows=416667 width=52) (actual time=1.035..22.876 rows=333333 loops=3)
Planning Time: 0.050 ms
JIT:
  Functions: 8
  Options: Inlining false, Optimization false, Expressions true, Deforming true
  Timing: Generation 0.243 ms (Deform 0.111 ms), Inlining 0.000 ms, Optimization 0.270 ms, Emission 4.085 ms, Total 4.598 ms
Execution Time: 704.217 ms
```

The total execution time is `704.217 ms` for offset pagination.

Here's the query returning the same set of rows using cursor pagination.
I had to hardcode the `@date` and `@lastId` values for this comparison:

```sql
SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
WHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)
ORDER BY u.date DESC, u.id DESC
LIMIT 1000;
```

Finally, here's the query plan for cursor pagination:

```sql
EXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
WHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)
ORDER BY u.date DESC, u.id DESC
LIMIT 1000;

---
Limit  (cost=20605.63..20722.31 rows=1000 width=52) (actual time=37.993..40.958 rows=1000 loops=1)
  ->  Gather Merge  (cost=20605.63..30419.62 rows=84114 width=52) (actual time=37.992..40.921 rows=1000 loops=1)
        Workers Planned: 2
        Workers Launched: 2
        ->  Sort  (cost=19605.61..19710.75 rows=42057 width=52) (actual time=24.611..24.630 rows=811 loops=3)
              Sort Key: date DESC, id DESC
              Sort Method: top-N heapsort  Memory: 240kB
              Worker 0:  Sort Method: top-N heapsort  Memory: 239kB
              Worker 1:  Sort Method: top-N heapsort  Memory: 238kB
              ->  Parallel Seq Scan on user_notes u  (cost=0.00..17299.67 rows=42057 width=52) (actual time=0.009..21.462 rows=33333 loops=3)
                    Filter: ((date < @date::date) OR ((date = @date::date) AND (id <= @lastId::uuid)))
                    Rows Removed by Filter: 300000
Planning Time: 0.063 ms
Execution Time: 40.993 ms
```

The total execution time for cursor pagination is `40.993 ms`.

A whopping `17x` performance improvement with cursor pagination compared to offset pagination!

The performance with cursor pagination is consistent regardless of the page depth.
This is because we're directly seeking the rows based on the cursor, which is more efficient than offset pagination.
It's a huge advantage over offset pagination, especially for large datasets.

## Adding Indexes for Cursor Pagination

I also tested the impact of indexes on [cursor pagination](https://use-the-index-luke.com/blog/2013-07/pagination-done-the-postgresql-way).
I created a composite index on the `Date` and `Id` fields to speed up the queries.
Or so I thought...

Here's the SQL command to create the composite index:

```sql
CREATE INDEX idx_user_notes_date_id ON user_notes (date DESC, id DESC);
```

The index is created in descending order to match the sort order in our queries.

Let's see the query plan for cursor pagination with the composite index:

```sql
EXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
WHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)
ORDER BY u.date DESC, u.id DESC
LIMIT 1000;

---
Limit  (cost=0.42..816.55 rows=1000 width=52) (actual time=298.534..298.924 rows=1000 loops=1)
  ->  Index Scan using idx_user_notes_date_id on user_notes u  (cost=0.42..82376.42 rows=100936 width=52) (actual time=298.532..298.888 rows=1000 loops=1)
        Filter: ((date < @date::date) OR ((date = @date::date) AND (id <= @lastId::uuid)))
        Rows Removed by Filter: 900000
Planning Time: 0.068 ms
Execution Time: 298.955 ms
```

We have an `Index Scan` using the composite index.
However, the execution time is `298.955 ms`, which is slower than the previous query without the index.

This might be because the dataset is too small to benefit from the index.
I have only `1,000,000` records in the table, which might not be enough to see the performance improvement with the index.

But wait, there's more to it!

What if we were to use a tuple comparison in SQL?

```sql {3}
EXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id
FROM user_notes AS u
WHERE (u.date, u.id) <= (@date, @lastId)
ORDER BY u.date DESC, u.id DESC
LIMIT 1000;

---
Limit  (cost=0.42..432.81 rows=1000 width=52) (actual time=0.020..0.641 rows=1000 loops=1)
  ->  Index Scan using idx_user_notes_date_id on user_notes u  (cost=0.42..43817.85 rows=101339 width=52) (actual time=0.019..0.606 rows=1000 loops=1)
        Index Cond: (ROW(date, id) <= ROW(@date::date, @lastId::uuid))
Planning Time: 0.060 ms
Execution Time: 0.668 ms
```

Finally, the index is working.
The execution time is `0.668 ms`, which is significantly faster than the previous queries.

The query optimizer cannot determine whether the composite index can be used for row-level comparison.
However, the index is effectively used with a tuple comparison.

How do you translate this to EF Core?

The Postgres provider has `EF.Functions.LessThanOrEqual`, which accepts a `ValueTuple` as an argument.
We can use it to produce a `(u.date, u.id) <= (@date, @lastId)` comparison in the query.
And this will utilize the composite index.

```csharp
query = query.Where(x => EF.Functions.LessThanOrEqual(
    ValueTuple.Create(x.Date, x.Id),
    ValueTuple.Create(date, lastId)));
```

## Encoding the Cursor

Here's a small utility class for encoding and decoding the cursor.
We'll use this to encode the cursor in the URL and decode it when fetching the next set of results.

The clients will receive the cursor as a Base64-encoded string.
They don't need to know the internal structure of the cursor.

```csharp
using Microsoft.AspNetCore.Authentication; // For Base64UrlTextEncoder

public sealed record Cursor(DateOnly Date, Guid LastId)
{
    public static string Encode(DateOnly date, string lastId)
    {
        var cursor = new Cursor(date, lastId);
        string json = JsonSerializer.Serialize(cursor);
        return Base64UrlTextEncoder.Encode(Encoding.UTF8.GetBytes(json));
    }

    public static Cursor? Decode(string? cursor)
    {
        if (string.IsNullOrWhiteSpace(cursor))
        {
            return null;
        }

        try
        {
            string json = Encoding.UTF8.GetString(Base64UrlTextEncoder.Decode(cursor));
            return JsonSerializer.Deserialize<Cursor>(json);
        }
        catch
        {
            return null;
        }
    }
}
```

Here's an example of encoding and decoding the cursor:

```csharp
string encodedCursor = Cursor.Encode(
  new DateOnly(2025, 2, 15),
  Guid.Parse("019500f9-8b41-74cf-ab12-25a48d4d4ab4"));
// Result:
// eyJEYXRlIjoiMjAyNS0wMi0xNSIsIkxhc3RJZCI6IjAxOTUwMGY5LThiNDEtNzRjZi1hYjEyLTI1YTQ4ZDRkNGFiNCJ9

Cursor decodedCursor = Cursor.Decode(encodedCursor);
// Result:
// {
//     "Date": "2025-02-15",
//     "LastId": "019500f9-8b41-74cf-ab12-25a48d4d4ab4"
// }
```

## Summary

While offset pagination is simpler to implement, it suffers from significant performance degradation at scale.
My tests showed a 17x slowdown compared to cursor pagination when accessing deeper pages.

Cursor pagination maintains consistent performance regardless of page depth and works particularly well for real-time feeds and infinite scroll interfaces.

However, cursor pagination comes with tradeoffs.
It requires careful implementation, especially around cursor encoding and handling sort orders.
It also doesn't provide total page counts, making it unsuitable for interfaces that need to support paged navigation.

The choice between these approaches ultimately depends on your use case:

- Choose cursor pagination for performance-critical APIs, real-time feeds, infinite scroll, or any scenario where users frequently access deep pages
- Stick with offset pagination for admin interfaces, small datasets, or when you need upfront page counts

Another thing to consider: which page will your users typically land on?
If most users start at the first page and rarely visit other pages, offset pagination might be sufficient.
This will be the case for many applications.

Remember to use tuple comparisons and appropriate indexes to get the best performance from cursor pagination.

That's all for today.

See you next week.

---



<Sponsorships>

Step right up to the [**Generative AI Use Cases Repository**](https://fnf.dev/4aWKcr2)!
See how MongoDB powers your apps with real-time, operational data.
It integrates vector embeddings with live data, covering transactional, search, analytics, and more—all in one platform.
Resilient, scalable, and secure—perfect for your next app.
[**Explore the use cases here**](https://fnf.dev/4aWKcr2).

Have you mastered custom `HttpContent` in C#?
Subtle errors can lead to unexpected behavior, memory issues, and performance bottlenecks. Don't fall into these traps.
[Master it now before it breaks your code](https://ravendb.net/articles/beware-of-these-hidden-pitfalls-when-implementing-custom-httpcontent-in-c?utm_source=newsletter&utm_medium=influencer&utm_campaign=csharp)!

</Sponsorships>

"We need to implement CQRS? Great, let me install MediatR."

If you've heard this in your development team - or perhaps said it yourself - you're not alone.
The .NET ecosystem has gradually fused these two concepts together, creating an almost reflexive response: CQRS equals MediatR.

This mental shortcut has led countless teams down a path of unnecessary complexity.
Others have avoided CQRS entirely, fearing the overhead of yet another messaging framework.

In this article, we'll dispel some common misconceptions and highlight the benefits of each pattern.

## Understanding CQRS in Its Pure Form

[CQRS](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) is a pattern that separates read and write operations in your application.
The pattern suggests that the models used for reading data should be different from those used for writing data.

That's it.

No specific implementation details, no prescribed libraries, just a simple architectural principle.

The pattern emerged from the understanding that in many applications, especially those with complex domains,
the requirements for reading and writing data are fundamentally different.
Read operations often need to combine data from multiple sources or present it in specific formats for UI consumption.
Write operations need to enforce business rules, maintain consistency, and manage domain state.

This separation provides several benefits:

- Optimized read and write models for their specific purposes
- Simplified maintenance as read and write concerns evolve independently
- Enhanced scalability options for read and write operations
- Clearer boundary between domain logic and presentation needs

## MediatR: A Different Tool for Different Problems

[MediatR](https://github.com/jbogard/MediatR) is an implementation of the mediator pattern.
Its primary purpose is to reduce direct dependencies between components by providing a central point of communication.
Instead of knowing about each other, the mediator connects the components.

The library provides several features:

- In-process messaging between components
- Behavior pipelines for [cross-cutting concerns](balancing-cross-cutting-concerns-in-clean-architecture)
- [Notification handling](how-to-publish-mediatr-notifications-in-parallel) (publish/subscribe)

The indirection MediatR introduces is its most criticized aspect.
It can make code harder to follow, especially for newcomers to the codebase.
However, you can easily solve this problem by defining the requests in the same file as the handler.

## Why They Often Appear Together

The frequent pairing of CQRS and MediatR isn't without reason.
MediatR's [request/response model](vertical-slice-architecture) aligns well with CQRS's command/query separation.
Commands and queries can be implemented as MediatR requests, with handlers containing the actual implementation logic.

Here's an example command using MediatR:

```csharp
public record CreateHabit(string Name, string? Description, int Priority) : IRequest<HabitDto>;

public sealed class CreateHabitHandler(ApplicationDbContext dbContext, IValidator<CreateHabit> validator)
    : IRequestHandler<CreateHabit, HabitDto>
{
    public async Task<HabitDto> Handle(CreateHabit request, CancellationToken cancellationToken)
    {
        await validator.ValidateAndThrowAsync(request);

        Habit habit = request.ToEntity();

        dbContext.Habits.Add(habit);

        await dbContext.SaveChangesAsync(cancellationToken);

        return habit.ToDto();
    }
}
```

[CQRS with MediatR](cqrs-pattern-with-mediatr) offers several advantages:

- Consistent handling of both commands and queries
- Pipeline behaviors for logging, validation, and error handling
- Clear separation of concerns through handler classes
- Simplified testing through handler isolation

However, this convenience comes at the cost of additional abstraction and complexity.
We have to define the request/response classes and handlers, write code for sending the requests, and so on.
This can be overkill for simple applications.

The question isn't whether this trade-off is universally good or bad but whether it's appropriate for your specific context.

## CQRS Without MediatR

CQRS can be implemented just as easily without MediatR.
Here's a simple example of what it might look like.

You can define commands and queries as simple interfaces:

```csharp
public interface ICommandHandler<in TCommand, TResult>
{
    Task<TResult> Handle(TCommand command, CancellationToken cancellationToken = default);
}

// Same thing for IQueryHandler
```

Then, you can implement your handlers and register them with dependency injection:

```csharp
public record CreateOrderCommand(string CustomerId, List<OrderItem> Items)
    : ICommand<CreateOrderResult>;

public class CreateOrderCommandHandler : ICommandHandler<CreateOrderCommand, CreateOrderResult>
{
    public async Task<CreateOrderResult> Handle(
        CreateOrderCommand command,
        CancellationToken cancellationToken = default)
    {
        // implementation
    }
}

// DI registration...
builder.Services
    .AddScoped<ICommandHandler<CreateOrderCommand, CreateOrderResult>, CreateOrderCommandHandler>();
```

Finally, you can use the handler in your controller:

```csharp {8,10}
[ApiController]
[Route("orders")]
public class OrdersController : ControllerBase
{
    [HttpPost]
    public async Task<ActionResult<CreateOrderResult>> CreateOrder(
        CreateOrderCommand command,
        ICommandHandler<CreateOrderCommand, CreateOrderResult> handler)
    {
        var result = await handler.Handle(command);

        return Ok(result);
    }
}
```

What's the difference between this and the MediatR approach?

This approach provides the same separation of concerns but without the indirection.
It's direct, explicit, and often sufficient for many applications.

However, it lacks some of the conveniences that MediatR offers, such as pipeline behaviors and automatically registering handlers.
You also need to inject the specific handlers into your controllers, which can be cumbersome for larger applications.

## Takeaway

CQRS and MediatR are distinct tools that solve different problems.
While they can work well together, treating them as inseparable does a disservice to both.
CQRS separates read and write concerns, while MediatR decouples components through a mediator.

The key is understanding what each pattern offers and making informed decisions based on your specific context.
Sometimes, you'll want both, sometimes just one, and sometimes neither.
That's the essence of thoughtful architecture: choosing the right tools for your specific needs.

If you want to learn more about implementing CQRS effectively as part of a clean,
maintainable architecture, check out [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture).
You'll learn how to apply these patterns in real-world scenarios, avoiding common pitfalls and over-engineering while building scalable applications.

That's all for today. Hope this was helpful.

---



<Sponsorships>

Have you ever had an outage caused by your Postgres DB?
Did you max out resources?
[**Neon**](https://fyi.neon.tech/neonazure) is Postgres with autoscaling.
Connections?
Neon has pgBouncer built in for 10k connections.
Failed migration?
Neon has instant PITR and test environments.
[**Get the Free Plan on Azure here**](https://fyi.neon.tech/neonazure).

[**Bufstream**](https://fnf.dev/40Ty4nd) is the only cloud-native Kafka implementation independently validated by Jepsen,
passing the gold standard for distributed systems testing.
It's built for the modern enterprise—stateless, auto-scaling, schema-aware, and 10x cheaper than self-managed Kafka.
Designed for high-throughput workloads, Bufstream is ready for organizations that struggle with Kafka scalability,
cloud cost control, and data quality.
Find out how Bufstream can improve your Kafka implementation in this [**article**](https://fnf.dev/40Ty4nd).

</Sponsorships>

Introducing [**.NET 8 resilience packages**](building-resilient-cloud-applications-with-dotnet)
built on top of [Polly](https://github.com/App-vNext/Polly)
has made it much easier to build robust HTTP clients.
These packages provide standard resilience handlers that you can easily attach to `HttpClient` instances.
They implement common patterns like retry, circuit breaker, and timeout policies.

However, there is a significant limitation: once you configure the standard resilience handlers globally for all clients,
there is no built-in way to override them for specific cases.
This can be problematic when different endpoints require different resilience strategies.

In today's issue, I'll show you how to fix this and what the .NET team is doing about it.

## Standard Resilience Configuration

Let's say you've configured default resilience handlers in your application startup.
`ConfigureHttpClientDefaults` is a convenient way to add standard resilience handlers to all `HttpClient` instances:

```csharp {3}
builder.Services
    .AddHttpClient()
    .ConfigureHttpClientDefaults(http => http.AddStandardResilienceHandler());
```

The .NET team runs many large-scale services in production, and they've found a standard set of resilience strategies that work
well for most scenarios.

The standard resilience handler combines five strategies to create a resilience pipeline:

- Rate limiter
- Total request timeout
- Retry
- Circuit breaker
- Attempt timeout

You can customize the standard resilience pipeline by configuring the `HttpStandardResilienceOptions`.

Here's an example of how to configure it:

```csharp
builder.Services.ConfigureHttpClientDefaults(http => http.AddStandardResilienceHandler(options =>
{
    // Default is 2 seconds.
    options.Retry.Delay = TimeSpan.FromSeconds(1);

    // Default is 30 seconds.
    options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(20);

    // Default is 0.1.
    options.CircuitBreaker.FailureRatio = 0.2;
}));
```

Okay, so we have our standard resilience pipeline set up.
Now all your `HttpClient` instances will use these resilience policies.

But what if you need different retry logic for a specific API endpoint or need to turn off circuit breaking for specific calls?

## The Problem

Let's say you have a named `HttpClient` for calling the GitHub API,
and you want to configure specific resilience strategies for it:

```csharp
builder.Services
    .AddHttpClient("github")
    .ConfigureHttpClient(client =>
    {
        client.BaseAddress = new Uri("https://api.github.com");
    })
    .AddResilienceHandler("custom", pipeline =>
    {
        pipeline.AddTimeout(TimeSpan.FromSeconds(10));

        pipeline.AddRetry(new HttpRetryStrategyOptions
        {
            MaxRetryAttempts = 3,
            BackoffType = DelayBackoffType.Exponential,
            UseJitter = true,
            Delay = TimeSpan.FromMilliseconds(500)
        });

        pipeline.AddTimeout(TimeSpan.FromSeconds(1));
    });
```

The `custom` policy won't be applied because we have a global resilience pipeline that overrides it.

This is a big oversight in the current implementation of the .NET resilience packages.

## The Solution

The solution is to create an extension method that clears all handlers from the resilience pipeline.
This allows you to remove the default handlers and add your custom ones.

Here's how to implement it:

```csharp
public static class ResilienceHttpClientBuilderExtensions
{
    public static IHttpClientBuilder RemoveAllResilienceHandlers(this IHttpClientBuilder builder)
    {
        builder.ConfigureAdditionalHttpMessageHandlers(static (handlers, _) =>
        {
            for (int i = handlers.Count - 1; i >= 0; i--)
            {
                if (handlers[i] is ResilienceHandler)
                {
                    handlers.RemoveAt(i);
                }
            }
        });
        return builder;
    }
}
```

Now you can use this extension method to implement custom resilience strategies:

```csharp {7,16}
builder.Services
    .AddHttpClient("github")
    .ConfigureHttpClient(client =>
    {
        client.BaseAddress = new Uri("https://api.github.com");
    })
    .RemoveAllResilienceHandlers()
    .AddResilienceHandler("custom", pipeline =>
    {
        // Configure the custom resilience pipeline...
    });

// Or use another standard resilience pipeline...
builder.Services
    .AddHttpClient("github-hedged")
    .RemoveAllResilienceHandlers()
    .AddStandardHedgingHandler();
```

## Future Improvements

The .NET team is aware of this limitation, and better support for overriding default resilience handlers is planned for an upcoming release.
The [pull request for this API](https://github.com/dotnet/extensions/pull/5801) is merged and should be available in a future release.

Until then, this workaround using `RemoveAllResilienceHandlers` is a drop-in replacement for the missing feature.

## Conclusion

The ability to override default resilience handlers is much needed when building robust distributed systems.
While .NET's standard resilience handlers provide excellent defaults, real-world applications often require fine-tuned resilience strategies for different services.
The extension method presented here bridges this gap, allowing you to maintain both global defaults and specialized configurations where needed.

Want to dive deeper into building resilient cloud applications?
Check out my article about [**building resilient cloud applications with .NET**](building-resilient-cloud-applications-with-dotnet).

Good luck out there, and see you next week.

---



<Sponsorships>

[**Kestra**](https://fnf.dev/4jHuh3V) is a powerful open-source orchestration platform for developers, offering a declarative approach to defining workflows with minimal complexity.
With robust plugins and seamless integrations, it simplifies automating and scaling processes.
[**Check it out on GitHub**](https://fnf.dev/4jHuh3V).

Accelerate your projects with [**RavenDB Cloud**](https://ravendb.net/cloud?utm_source=influencer&utm_medium=newsletter&utm_campaign=cloud) -
an affordable NoSQL document database for developers prioritizing speed and simplicity.
Set up your database in minutes: [**start here**](https://ravendb.net/cloud?utm_source=influencer&utm_medium=newsletter&utm_campaign=cloud).

</Sponsorships>

A single exposed API key or database password can compromise your entire infrastructure.
Yet many developers still store sensitive data with basic encoding or weak encryption.

Properly implemented encryption is your last line of defense.
When other security measures fail, it ensures stolen data remains unreadable.
This is especially crucial for API keys, database credentials, and user secrets that grant direct access to your systems.

In today's issue, we will cover implementing AES encryption in .NET with practical code examples and essential security considerations.

## Symmetric vs Asymmetric Encryption

[Symmetric encryption](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) (like AES) uses the same key for encryption and decryption.
It's fast and ideal for storing data that only your application needs to read.
The main challenge is securely storing the encryption key.

[Asymmetric encryption](https://en.wikipedia.org/wiki/Public-key_cryptography) (like RSA) uses different keys for encryption and decryption.
It's slower but allows secure communication between parties who don't share secrets.
Common uses include SSL/TLS and digital signatures.

For storing API keys and application secrets, symmetric encryption with AES is the appropriate choice.

<figure>
  <Image
    src="blogs/mnw_126/aes_encryption.png"
    width={850}
    height={1020}
    alt="AES encryption algorithm."
  />
  <figcaption>AES encryption and decryption process block diagram.</figcaption>
</figure>

## AES Encryption Implementation

Let's examine a secure [AES (Advanced Encryption Standard)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) encryption implementation in C#.
This implementation uses AES-256, which provides the strongest security currently available in the AES standard.

```csharp
public class Encryptor
{
    private const int KeySize = 256;
    private const int BlockSize = 128;

    public static EncryptionResult Encrypt(string plainText)
    {
        // Generate a random key and IV
        using var aes = Aes.Create();
        aes.KeySize = KeySize;
        aes.BlockSize = BlockSize;

        // Generate a random key and IV for each encryption operation
        aes.GenerateKey();
        aes.GenerateIV();

        byte[] encryptedData;

        // Create encryptor and encrypt the data
        using (var encryptor = aes.CreateEncryptor())
        using (var msEncrypt = new MemoryStream())
        {
            using (var csEncrypt = new CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write))
            using (var swEncrypt = new StreamWriter(csEncrypt))
            {
                swEncrypt.Write(plainText);
            }

            encryptedData = msEncrypt.ToArray();
        }

        // Package everything together, storing IV with the encrypted data
        var result = EncryptionResult.CreateEncryptedData(
            encryptedData,
            aes.IV,
            Convert.ToBase64String(aes.Key)
        );

        return result;
    }
}

public class EncryptionResult
{
    // The IV is prepended to the encrypted data
    public string EncryptedData { get; set; }
    public string Key { get; set; }

    public static EncryptionResult CreateEncryptedData(byte[] data, byte[] iv, string key)
    {
        // Combine IV and encrypted data
        var combined = new byte[iv.Length + data.Length];
        Array.Copy(iv, 0, combined, 0, iv.Length);
        Array.Copy(data, 0, combined, iv.Length, data.Length);

        return new EncryptionResult
        {
            EncryptedData = Convert.ToBase64String(combined),
            Key = key
        };
    }

    public (byte[] iv, byte[] encryptedData) GetIVAndEncryptedData()
    {
        var combined = Convert.FromBase64String(EncryptedData);

        // Extract IV and data
        var iv = new byte[16]; // AES block size is 16 bytes (128 / 8)
        var encryptedData = new byte[combined.Length - 16];

        Array.Copy(combined, 0, iv, 0, 16);
        Array.Copy(combined, 16, encryptedData, 0, encryptedData.Length);

        return (iv, encryptedData);
    }
}
```

Let's break down what's happening in this implementation:

- Every encryption operation generates a new random key and IV (Initialization Vector).
  This is crucial - reusing either of these compromises security.
  The IV prevents identical plaintext from producing identical ciphertext.
- We use `CryptoStream` for efficient encryption of potentially large data.
  The stream pattern ensures we don't load everything into memory at once.
- The `EncryptionResult` class provides a way to package the encrypted data with its key and IV.
  In production, the key should be stored separately in a key management service.

## AES Decryption Implementation

Here's the corresponding decryption implementation:

```csharp
public class Decryptor
{
    private const int KeySize = 256;
    private const int BlockSize = 128;

    public static string Decrypt(EncryptionResult encryptionResult)
    {
        var key = Convert.FromBase64String(encryptionResult.Key);
        var (iv, encryptedData) = encryptionResult.GetIVAndEncryptedData();

        using var aes = Aes.Create();
        aes.KeySize = KeySize;
        aes.BlockSize = BlockSize;
        aes.Key = key;
        aes.IV = iv;

        // Create decryptor and decrypt the data
        using var decryptor = aes.CreateDecryptor();
        using var msDecrypt = new MemoryStream(encryptedData);
        using var csDecrypt = new CryptoStream(msDecrypt, decryptor, CryptoStreamMode.Read);
        using var srDecrypt = new StreamReader(csDecrypt);

        try
        {
            return srDecrypt.ReadToEnd();
        }
        catch (CryptographicException ex)
        {
            // Log the error securely - avoid exposing details
            throw new CryptographicException("Decryption failed", ex);
        }
    }
}
```

The decryption process reverses the encryption steps.
Note the error handling - we catch cryptographic exceptions but avoid exposing details that could help an attacker.
In production, you should log these errors securely for debugging while keeping security in mind.

## Usage Example

Here's an example of encrypting and decrypting sensitive data using the implementations above:

```csharp
// Encrypt sensitive data
var apiKey = "your-sensitive-api-key";
var encryptionResult = Encryptor.Encrypt(apiKey);

// Output example: DCGT9kEwPglBonWWPa7PQPbr2I+6rskJ0lSFybbicvZ+wKMTU7cbJD2s3QSF2Yu6

// Store encrypted data in database
// IV is stored with the encrypted data
SaveToDatabase(encryptionResult.EncryptedData);

// Store key in key vault
await keyVault.StoreKeyAsync("apikey_1", encryptionResult.Key);

// Later, decrypt when needed
// IV is retrieved from the encrypted data
var encryptedData = LoadFromDatabase();
var key = await keyVault.GetKeyAsync("apikey_1");

var result = new EncryptionResult
{
    EncryptedData = encryptedData,
    Key = key,
    IV = iv
};

var decrypted = Decryptor.Decrypt(result);
```

## Takeaway

AES encryption provides strong security for sensitive application data when implemented correctly.

Proper key management is very important.
Use a dedicated key storage service in production.
Popular options include [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/),
[AWS Key Management Service](https://aws.amazon.com/kms/), and
[HashiCorp Vault](https://www.vaultproject.io/).

In my [**Pragmatic REST APIs**](/pragmatic-rest-apis) course, I cover secure data storage and encryption in more detail.
These are critical aspects of building secure and robust APIs and integrating with third-party APIs.
Check it out if you're interested in learning more.

Remember that encryption is just one part of a comprehensive security strategy.
Keep your encryption keys separate from encrypted data and rotate them regularly.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**Boost your .NET development**](https://abp.io/?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_jan18) with ABP.IO's framework!
Open-source, module ready and built for rapid web app creation.
From microservices to multi-tenancy, ABP covers your needs.
Focus on your business and [**enjoy coding now**](https://abp.io/?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_jan18)!

Tired of switching contexts while building apps?
[**Hot Design™**](https://platform.uno/docs/articles/studio/Hot%20Design/hot-design-getstarted-guide.html?utm_source=milan-newsletter&utm_medium=email&utm_campaign=HotDesign-A)
combines runtime UI design, live data integration, and cross-platform development to keep you in the flow.
Compatible with Visual Studio, VS Code, and Rider, it simplifies .NET UI development, accelerates your workflow,
and enhances your developer experience—letting you deliver polished apps with ease.
[**Try Hot Design™**](https://platform.uno/waitlist/?utm_source=milan-newsletter&utm_medium=email&utm_campaign=HotDesign-A)
today and experience effortless productivity!

</Sponsorships>

Monoliths get a bad rap in our industry.
We're told they're legacy, that they don't scale, and that we need microservices to succeed.
After spending many years scaling systems from startups to enterprises, I can tell you this isn't true.
A well-designed monolith is often the right architecture choice, and it can scale remarkably well with the right approach.

In my experience building and scaling monolithic systems, I've found that the key to success isn't following trends.
It's understanding your scaling needs and applying the right solutions at the right time.
In this article, I'll share what I've learned about scaling monoliths effectively and when to use each approach.

## Understanding Scale

A monolith puts all your code in one deployable unit.
This brings significant advantages: faster development cycles, simpler debugging, and straightforward deployments.
But as your system grows, you'll face scaling challenges.

<div className="centered">
  <Image
    src="blogs/mnw_125/monolith_system.png"
    width={131}
    height={430}
    alt="Simple monolith system."
  />
</div>

Your database queries slow down as data volume grows. API endpoints that worked
fine with hundreds of users start timing out with thousands. Build times creep
up as your codebase expands. These are natural growing pains that every
successful system faces.

## Vertical Scaling

Vertical scaling means giving your application more resources on a single machine.
It's the simplest scaling strategy and often the most effective first step.
Before diving into complex distributed systems, consider whether upgrading your existing infrastructure could solve your performance problems.

<div className="centered">
  <Image
    src="blogs/mnw_125/vertical_scaling.png"
    width={643}
    height={542}
    alt="Example of vertically scaling a monolith."
  />
</div>

Vertical scaling works particularly well when there are clear resource bottlenecks.
If your CPU is consistently above 80% utilization, adding more cores will help.
If your database is I/O bound, upgrading to faster storage can dramatically improve performance.
Modern cloud platforms make this especially straightforward.
You can often upgrade with a few clicks and minimal downtime.

The benefits of vertical scaling extend beyond just performance.
It maintains your system's simplicity.
You don't need to redesign your architecture, implement new deployment patterns, or manage distributed system complexity.
Your monitoring, debugging, and operational procedures all stay the same.

However, vertical scaling does have limits.
You'll eventually hit a ceiling on what a single machine can handle.
Cloud providers have maximum instance sizes, and costs typically increase exponentially with larger instances.
More importantly, vertical scaling doesn't provide redundancy - you're still running on a single machine that represents a potential single point of failure.

Knowing when to move beyond vertical scaling is crucial.
Watch for these indicators:

- Costs are growing faster than your user base
- You need better redundancy and fault tolerance
- Your deployment downtime is impacting business operations
- Your largest available instance size is approaching 70% utilization

## Horizontal Scaling

[**Horizontal scaling**](horizontally-scaling-aspnetcore-apis-with-yarp-load-balancing) runs multiple instances of your application behind a load balancer.
It's the next step when vertical scaling reaches its limits.
It offers improved fault tolerance and nearly linear scaling capabilities.

<div className="centered">
  <Image
    src="blogs/mnw_125/horizontal_scaling.png"
    width={630}
    height={648}
    alt="Example of horizontally scaling a monolith."
  />
</div>

The key to successful horizontal scaling lies in application design.
Your application must be stateless - each request should contain all the information needed to process it.

This means:

- Authentication should use tokens (like JWTs) rather than server-side sessions
- Cached data should live in a distributed cache

Load balancers are crucial in this architecture.
Whether you call it an [**API Gateway**](implementing-an-api-gateway-for-microservices-with-yarp), Reverse Proxy, or Load Balancer, its job is to distribute traffic across your application instances.
Popular choices include:

- [nginx](https://nginx.org/en/): Powerful, open-source, great for custom configurations
- [YARP](https://microsoft.github.io/reverse-proxy/): Microsoft's .NET reverse proxy, great for .NET applications
- Cloud:
  [AWS ALB](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html),
  [Azure Application Gateway](https://learn.microsoft.com/en-us/azure/application-gateway/overview),
  [Google Cloud Load Balancing](https://cloud.google.com/load-balancing?hl=en)

Horizontal scaling provides several key benefits:

- Better fault tolerance through redundancy
- Ability to handle more concurrent users
- Rolling deployments with zero downtime
- Cost-effective scaling (scale down when traffic is low)

The main challenge in horizontal scaling isn't technical—it's architectural.
Your application needs to be designed for horizontal scaling from the start.
Converting a stateful application to a stateless one often requires significant refactoring.

## Database Scaling

Database scaling is where most monoliths first hit real limitations.
Let's explore each scaling strategy in detail.

### Read Replicas

Read replicas are often your first step in database scaling but come with significant trade-offs.
Read replicas maintain a copy of your primary database that serves read-only traffic.
When you run a query against a replica, you're not competing with writes on your primary database.

Each replica maintains an up-to-date copy of your data through replication.
Changes flow one-way: from primary to replicas.
This means any data written to your primary will eventually show up in your replicas.
That "eventually" is important - you're trading consistency for better read performance.

Most cloud providers make read replicas easy to set up.
AWS RDS and Azure SQL all support read replicas with minimal configuration.
They handle replication, monitoring, and failover for you.

<Image
  src="blogs/mnw_125/database_read_replicas.png"
  width={1854}
  height={1417}
  alt="Example of database read replication for scaling a monolith."
/>

When implementing read replicas, consider:

- Replication lag affects data freshness
- Write volume impacts replication speed
- Geographic location affects latency
- Each replica adds to your costs

### Materialized Views

Sometimes read replicas aren't enough.
Perhaps you need to reshape your data for specific use cases, or you're running complex analytical queries that are slow even on a replica.
This is where materialized views come in.

A materialized view is a pre-computed dataset stored as a table.
Unlike regular views that compute their results on each query, materialized views store their results.
This makes them much faster to query but introduces a new challenge: keeping them up to date.

Materialized views excel at:

- Complex analytical queries
- Data that updates on a schedule
- Aggregations and summaries
- Denormalized data for specific views

The key trade-off is freshness versus performance.
You need to decide how often to refresh your materialized views.
Too often, and you're putting load on your database.
Too rarely, and your data gets stale.

### Database Sharding

Sharding becomes necessary when your database grows beyond what a single instance can handle.
Sharding splits your data across multiple database instances, with each shard containing a distinct subset of your data.
The key to successful sharding lies in choosing the right sharding strategy for your use case.

**Range-based sharding** splits data based on ranges of a key value - for example, customers A-M go to Shard 1, N-Z to Shard 2.
This approach works well with data that has a natural range distribution, like dates or alphabetical order,
but can lead to hotspots if certain ranges see more activity than others.

**Hash-based sharding** applies a hash function to your sharding key to determine which shard holds the data.
The choice of hashing function is crucial.
It must distribute data evenly across your shards to prevent any single shard from becoming a bottleneck.
While this approach provides better data distribution, it makes range-based queries more complex since related data might live on different shards.

**Tenant-based sharding** gives each tenant their own database.
This approach provides natural isolation and makes tenant-specific operations straightforward.
While it makes cross-tenant queries more complex, it's often the cleanest solution for multi-tenant systems where data isolation is important.

<Image
  src="blogs/mnw_125/database_sharding.png"
  width={2945}
  height={797}
  alt="Example of database sharding for scaling a monolith."
/>

## Caching

Caching is one of the most effective ways to improve your system's performance.
A well-implemented caching strategy can dramatically reduce database load and improve response times by storing frequently accessed data in memory.

Modern caching happens at multiple levels.
Browser caching reduces unnecessary network requests.
CDN caching brings your content closer to users.
[**Application-level caching**](caching-in-aspnetcore-improving-application-performance) with tools like Redis stores frequently accessed data in memory.
Database query caching reduces expensive computations.

The key to effective caching is understanding your data access patterns.
Frequently read, rarely changed data benefits most from caching.
Tools like Redis and Memcached excel at storing such data in memory, providing sub-millisecond access times.
Cloud providers offer managed caching services like Azure Cache for Redis,
handling the operational complexity of maintaining a distributed cache.

## Message Queues

Message queues are a powerful tool for scaling your monolith.
They let you defer time-consuming operations and distribute work across multiple processors.
This keeps your API responsive while handling heavy tasks in the background.

Message queues transform your system's behavior under load.
Instead of processing everything synchronously, you can queue work for later.
This pattern works especially well for operations like:

- Processing uploaded files
- Sending emails and notifications
- Generating reports
- Updating search indexes
- Running batch operations

The real power of message queues lies in their ability to handle traffic spikes.
When your system gets hit with a surge of requests, queues act as a buffer.
They let you accept work at peak rates but process it at a sustainable pace.

## Summary

Scaling a monolith isn't about choosing between vertical scaling, horizontal scaling, caching, or any single approach.
It's about using the right tool at the right time.
Start with the simplest solution that solves your immediate problem, then add complexity only when needed.

A practical scaling journey often looks like this:

1. Optimize your code and database queries
2. Add caching where it matters most
3. Scale vertically until it's no longer cost-effective
4. Move to horizontal scaling for better redundancy
5. Implement message queues for background work
6. Consider database sharding when data size demands it

A well-designed monolith can handle significant load with just a subset of these techniques.
The key is to understand your system's actual bottlenecks and address them specifically.

If you're interested in building maintainable, scalable monoliths, my [**Modular Monolith Architecture**](/modular-monolith-architecture) course dives deeper into these concepts.
You'll learn how to structure your code for long-term maintainability and scale.

Remember: don't let perfect be the enemy of good.
Start with the simplest solution that could work, measure everything, and scale what's necessary.
A well-designed monolith can take you further than you might think.

That's all for today. Hope this was helpful.

---



<Sponsorships>

Transform your database performance with [**RavenDB**](https://ravendb.net/ravendb-vs-mongodb?utm_source=influencer_mj&utm_medium=newsletter&utm_campaign=slot1):
Struggling with database bottlenecks and slow queries?
RavenDB is a lightning-fast document database with a distributed architecture that scales effortlessly to meet your needs.
[**Try RavenDB today**](https://ravendb.net/ravendb-vs-mongodb?utm_source=influencer_mj&utm_medium=newsletter&utm_campaign=slot1).

[**AI Agents are the future of AI innovation**](https://fnf.dev/298o5bG).
And APIs will be the key to their success.
Postman CEO Abhinav Asthana predicts that AI agents could increase API utility by 10X-100X and offers some
advice for how to optimize your APIs for agentic integration in [**this insightful article**](https://fnf.dev/298o5bG).

</Sponsorships>

I've been experimenting with different approaches to integrating LLMs into .NET apps,
and I want to share what I've learned about using `Microsoft.Extensions.AI`.

Large Language Models (LLMs) have revolutionized how we approach AI-powered applications.
While many developers are familiar with cloud-based solutions like OpenAI's GPT models,
running LLMs locally has become increasingly accessible thanks to projects like [Ollama](https://ollama.com/).

In this article, we'll explore how to use LLMs in .NET applications using `Microsoft.Extensions.AI`,
a powerful abstraction that extends the [Semantic Kernel](https://github.com/microsoft/semantic-kernel) SDK.

## Understanding the Building Blocks

### Large Language Models (LLMs)

LLMs are deep learning models trained on vast amounts of data, capable of understanding and generating human-like text.
These models can perform various tasks such as text completion, summarization, classification, and engaging in conversation.
While traditionally accessed through cloud APIs, recent advances have made it possible to run them locally on standard hardware.

<figure>
  <Image
    src="blogs/mnw_124/large_language_models.png"
    width={1336}
    height={666}
    alt="Timeline of large language models."
  />
  <figcaption>
    Source: [Weights &
    Biases](https://wandb.ai/vincenttu/blog_posts/reports/A-Survey-of-Large-Language-Models--VmlldzozOTY2MDM1)
  </figcaption>
</figure>

### Ollama

Ollama is an open-source project that simplifies running LLMs locally.
It provides a Docker container that can run various open-source models like Llama,
making it easy to experiment with AI without depending on cloud services.
Ollama handles model management and optimization and provides a simple API for interactions.

### Microsoft.Extensions.AI

[Microsoft.Extensions.AI](https://www.nuget.org/packages/Microsoft.Extensions.AI) is a library that provides a unified interface for working with LLMs in .NET applications.
Built on top of Microsoft's Semantic Kernel, it abstracts away the complexity of different LLM implementations,
allowing developers to switch between providers (like Ollama, Azure, or OpenAI) without changing application code.

## Getting Started

Before diving into the examples, here's what you need to run LLMs locally:

1. Docker running on your machine
2. Ollama container running with the `llama3` model:

```bash
# Pull the Ollama container
docker run --gpus all -d -v ollama_data:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

# Pull the llama3 model
docker exec -it ollama ollama pull llama3
```

3. A few NuGet packages (I built this using a .NET 9 console application):

```powershell
Install-Package Microsoft.Extensions.AI # The base AI library
Install-Package Microsoft.Extensions.AI.Ollama # Ollama provider implementation
Install-Package Microsoft.Extensions.Hosting # For building the DI container
```

## Simple Chat Completion

Let's start with a basic example of chat completion.
Here's the minimal setup:

```csharp {3,7,9}
var builder = Host.CreateApplicationBuilder();

builder.Services.AddChatClient(new OllamaChatClient(new Uri("http://localhost:11434"), "llama3"));

var app = builder.Build();

var chatClient = app.Services.GetRequiredService<IChatClient>();

var response = await chatClient.GetResponseAsync("What is .NET? Reply in 50 words max.");

Console.WriteLine(response.Message.Text);
```

Nothing fancy here - we're just setting up dependency injection and asking a simple question.
If you're used to using raw API calls, you'll notice how clean this feels.

The `AddChatClient` extension method registers the chat client with the DI container.
This allows you to inject `IChatClient` into your services and interact with LLMs using a simple API.
The implementation uses the `OllamaChatClient` to communicate with the Ollama container running locally.

## Implementing Chat with History

Building on the previous example, we can create an interactive chat that maintains conversation history.
This is useful for context-aware interactions and real-time chat applications.
All we need is a `List<ChatMessage` to store the chat history:

```csharp {11}
var chatHistory = new List<ChatMessage>();

while (true)
{
   Console.WriteLine("Enter your prompt:");
   var userPrompt = Console.ReadLine();
   chatHistory.Add(new ChatMessage(ChatRole.User, userPrompt));

   Console.WriteLine("Response from AI:");
   var chatResponse = "";
   await foreach (var item in chatClient.GetStreamingResponseAsync(chatHistory))
   {
       // We're streaming the response, so we get each message as it arrives
       Console.Write(item.Text);
       chatResponse += item.Text;
   }
   chatHistory.Add(new ChatMessage(ChatRole.Assistant, chatResponse));
   Console.WriteLine();
}
```

The cool part here is the streaming response - you get that nice, gradual text appearance like in ChatGPT.
We're also maintaining chat history, which lets the model understand context from previous messages, making conversations feel more natural.

## Getting Practical: Article Summarization

Let's try something more useful - automatically summarizing articles.
I've been using this to process blog posts:

```csharp
var posts = Directory.GetFiles("posts").Take(5).ToArray();
foreach (var post in posts)
{
   string prompt = $$"""
         You will receive an input text and the desired output format.
         You need to analyze the text and produce the desired output format.
         You not allow to change code, text, or other references.

         # Desired response

         Only provide a RFC8259 compliant JSON response following this format without deviation.

         {
            "title": "Title pulled from the front matter section",
            "summary": "Summarize the article in no more than 100 words"
         }

         # Article content:

         {{File.ReadAllText(post)}}
         """;

   var response = await chatClient.GetResponseAsync(prompt);
   Console.WriteLine(response.Message.Text);
   Console.WriteLine(Environment.NewLine);
}
```

Pro tip: Being specific about the output format (like requesting [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259) compliant JSON) helps get consistent results.
I learned this the hard way after dealing with occasionally malformed responses!

## Taking It Further: Smart Categorization

Here's where it gets really interesting - we can get strongly typed responses directly from our LLM:

```csharp {29}
class PostCategory
{
    public string Title { get; set; } = string.Empty;
    public string[] Tags { get; set; } = [];
}

var posts = Directory.GetFiles("posts").Take(5).ToArray();
foreach (var post in posts)
{
    string prompt = $$"""
          You will receive an input text and the desired output format.
          You need to analyze the text and produce the desired output format.
          You not allow to change code, text, or other references.

          # Desired response

          Only provide a RFC8259 compliant JSON response following this format without deviation.

          {
             "title": "Title pulled from the front matter section",
             "tags": "Array of tags based on analyzing the article content. Tags should be lowercase."
          }

          # Article content:

          {{File.ReadAllText(post)}}
          """;

    var response = await chatClient.GetResponseAsync<PostCategory>(prompt);

    Console.WriteLine(
      $"{response.Result.Title}. Tags: {string.Join(",",response.Result.Tags)}");
}
```

The strongly typed approach provides compile-time safety and better IDE support, making it easier to maintain and refactor code that interacts with LLM responses.

## Flexibility with Different LLM Providers

One of the key advantages of `Microsoft.Extensions.AI` is support for different providers.
While our examples use Ollama, you can easily switch to other providers:

```csharp
// Using Azure OpenAI
builder.Services.AddChatClient(new AzureOpenAIClient(
        new Uri("AZURE_OPENAI_ENDPOINT"),
        new DefaultAzureCredential())
            .AsChatClient());

// Using OpenAI
builder.Services.AddChatClient(new OpenAIClient("OPENAI_API_KEY").AsChatClient());
```

This flexibility allows you to:

- Start development with local models
- Move to production with cloud providers
- Switch between providers without changing application code
- Mix different providers for different use cases (categorization, image recognition, etc.)

## Takeaway

`Microsoft.Extensions.AI` makes it very simple to integrate LLMs into .NET applications.
Whether you're building a chat interface, processing documents, or adding AI-powered features to your application,
the library provides a clean, consistent API that works across different LLM providers.

I've only scratched the surface here.
Since integrating this into my projects, I've found countless uses:

- Automated content moderation for user submissions
- Automated support ticket categorization
- Content summarization for newsletters

I'm also planning a small side project that will use LLMs to process images from a camera feed.
The idea is to detect anything unusual and trigger alerts in real-time.

What are you planning to build with this?
I'd love to hear about your projects and experiences.
The AI space is moving fast, but with tools like `Microsoft.Extensions.AI`, we can focus on building features rather than wrestling with infrastructure.

Good luck out there, and see you next week.

---



<Sponsorships>

Introducing [**Depot Cache**](https://fnf.dev/4gURHAm), the powerful way to make incremental builds
up to 10x faster with tools like Bazel, Turborepo, Gradle, Pants, and sccache.
Run it anywhere—from CI/CD pipelines to local development—and say goodbye to rebuilding from scratch.
To celebrate the launch, Depot is offering your [**first month on any plan completely free—sign up here**](https://fnf.dev/4gURHAm).

Postgres in Azure got easier.
Deploy a [**Neon database**](https://fyi.neon.tech/azureportal) from the Azure portal - it's ready in seconds, it autoscales, has instant dev/test environments, integrates with GitHub.
[**Did we mention there's a generous Free Plan?**](https://fyi.neon.tech/azureportal)

</Sponsorships>

Writing tests is a crucial part of my daily work.
Over the years, I've learned that good tests can make or break a project.

One project I worked on remains the best example of this.
It was a large, complex system with many moving parts.
We had a requirement that code coverage must be above 90%.

Code coverage doesn't directly translate to good tests, but it's a good starting point.
It's up to you to write quality tests that cover the most critical parts of your system.

Today, I want to share my approach to testing Clean Architecture use cases in .NET.

## Why Testing Matters

I've seen many projects fail because of poor testing practices.
The codebase grows, changes become risky, and developers lose confidence in their deployments.
This is especially true for Clean Architecture projects, where we need to ensure our use cases work correctly.

Testing isn't just about catching bugs.
It's about having confidence in your code.
When I make changes, I want to know immediately if I've broken something.
Good tests give me that confidence.

## Understanding Different Testing Approaches

Before diving into the specific examples, let's talk about testing types.
In my experience, there are three main types of tests you'll write:

1. **Unit tests** focus on testing individual components in isolation.
   They're fast, reliable, and help you catch issues early.
   I write these tests first, and they make up the majority of my test suite.

2. [**Integration tests**](testcontainers-integration-testing-using-docker-in-dotnet) verify that different components work together correctly.
   They're slower but essential for testing database operations or external services.

3. [**End-to-end tests**](testing-modular-monoliths-system-integration-testing) check the entire system flow.
   They're the slowest but provide confidence that everything works together.

For this article, we'll focus on unit tests. They're the foundation of a solid test suite and the most common type you'll write.

## Breaking Down Our Use Case

Looking at our `ReserveBookingCommandHandler` class, we have a typical Clean Architecture use case.
It handles apartment booking reservations with several business rules:

1. The apartment must exist
2. The booking dates must not overlap with existing bookings
3. A new booking should be created if all checks pass

This is a perfect example for unit testing because it has clear inputs, outputs, and dependencies we can mock.

```csharp
internal sealed class ReserveBookingCommandHandler(
    IApartmentRepository apartmentRepository,
    IBookingRepository bookingRepository,
    IDateTimeProvider dateTimeProvider) : ICommandHandler<ReserveBookingCommand, Guid>
{
    public async Task<Result<Guid>> Handle(
        ReserveBookingCommand request,
        CancellationToken cancellationToken)
    {
        var apartment = await apartmentRepository.GetByIdAsync(request.ApartmentId, cancellationToken);

        if (apartment is null)
        {
            return Result.Failure<Guid>(ApartmentErrors.NotFound);
        }

        var duration = DateRange.Create(request.StartDate, request.EndDate);

        if (await bookingRepository.IsOverlappingAsync(apartment, duration, cancellationToken))
        {
            return Result.Failure<Guid>(BookingErrors.Overlap);
        }

        var booking = Booking.Create(
            apartment,
            duration,
            dateTimeProvider.UtcNow);

        bookingRepository.Add(booking);

        return booking.Id;
    }
}
```

## Setting Up Our Test Environment

The test class setup shows the standard approach I use for all my handler tests. Let's break it down:

```csharp {16}
public class ReserveBookingCommandHandlerTests
{
    private readonly ReserveBookingCommandHandler _handler;
    private readonly IApartmentRepository _apartmentRepository;
    private readonly IBookingRepository _bookingRepository;
    private readonly IDateTimeProvider _dateTimeProvider;

    private static readonly Guid ApartmentId = Guid.NewGuid();
    private static readonly DateTime UtcNow = DateTime.UtcNow;

    public ReserveBookingCommandHandlerTests()
    {
        _apartmentRepository = Substitute.For<IApartmentRepository>();
        _bookingRepository = Substitute.For<IBookingRepository>();
        _dateTimeProvider = Substitute.For<IDateTimeProvider>();
        _dateTimeProvider.UtcNow.Returns(UtcNow);

        _handler = new ReserveBookingCommandHandler(
            _apartmentRepository,
            _bookingRepository,
            _dateTimeProvider);
    }
}
```

I'm using [NSubstitute](https://nsubstitute.github.io/) to create mocks of our dependencies.
Each test starts with fresh mocks, preventing test interference.
The static fields provide consistent values across all tests.

Notice how I mock `IDateTimeProvider`.
This is crucial for testing time-dependent code.
Never use `DateTime.UtcNow` directly in your production code - it makes testing much harder.

## Testing the Not Found Scenario

Our first test verifies the behavior when an apartment doesn't exist:

```csharp {10,11}
[Fact]
public async Task Handle_WhenApartmentDoesNotExist_ShouldReturnNotFoundError()
{
    // Arrange
    var command = new ReserveBookingCommand(
        ApartmentId,
        new DateOnly(2024, 1, 1),
        new DateOnly(2024, 1, 5));

    _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())
        .Returns((Apartment?)null);

    // Act
    var result = await _handler.Handle(command, default);

    // Assert
    result.IsFailure.Should().BeTrue();
    result.Error.Should().Be(ApartmentErrors.NotFound);
}
```

This test follows the **Arrange-Act-Assert** pattern:

1. Arrange: Set up the command and mock the repository to return `null`
2. Act: Call the handler
3. Assert: Verify we get the correct error

I use [FluentAssertions](https://fluentassertions.com/) because it provides clear, readable assertions and better error messages than the standard Assert class.

## Handling Booking Conflicts

The overlap test ensures we can't double-book apartments:

```csharp {10-14}
[Fact]
public async Task Handle_WhenBookingOverlaps_ShouldReturnOverlapError()
{
    // Arrange
    var command = new ReserveBookingCommand(
        ApartmentId,
        new DateOnly(2024, 1, 1),
        new DateOnly(2024, 1, 5));

    var apartment = new Apartment { Id = ApartmentId };
    _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())
        .Returns(apartment);
    _bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())
        .Returns(true);

    // Act
    var result = await _handler.Handle(command, default);

    // Assert
    result.IsFailure.Should().BeTrue();
    result.Error.Should().Be(BookingErrors.Overlap);
}
```

Here, we verify the overlap check works correctly.
Notice how we:

1. Mock the apartment repository to return a valid apartment
2. Mock the booking repository to indicate an overlap
3. Verify we get the overlap error

## Testing Successful Bookings

The happy path test ensures everything works when all conditions are met:

```csharp {21-24}
[Fact]
public async Task Handle_WhenValidRequest_ShouldCreateBooking()
{
    // Arrange
    var command = new ReserveBookingCommand(
        ApartmentId,
        new DateOnly(2024, 1, 1),
        new DateOnly(2024, 1, 5));

    var apartment = new Apartment { Id = ApartmentId };
    _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())
        .Returns(apartment);
    _bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())
        .Returns(false);

    // Act
    var result = await _handler.Handle(command, default);

    // Assert
    result.IsSuccess.Should().BeTrue();
    await _bookingRepository.Received(1)
        .Add(Arg.Is<Booking>(b =>
            b.Id == result.Value &&
            b.ApartmentId == ApartmentId));
}
```

This test is more complex because we need to:

1. Set up multiple mocks
2. Verify the success result
3. Check that the booking was added with correct properties

NSubstitute's `Received()` method lets us verify the `Add` method was called **exactly once** with the right booking.

## Verifying Exception Handling

Testing exception scenarios is crucial for robust code:

```csharp {14,20}
[Fact]
public async Task Handle_WhenRepositoryThrowsOverlapException_ShouldPropagateException()
{
    // Arrange
    var command = new ReserveBookingCommand(
        ApartmentId,
        new DateOnly(2024, 1, 1),
        new DateOnly(2024, 1, 5));

    var apartment = new Apartment { Id = ApartmentId };
    _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())
        .Returns(apartment);
    _bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())
        .Throws<BookingOverlapException>();

    // Act
    var act = () => _handler.Handle(command, default);

    // Assert
    await act.Should().ThrowAsync<BookingOverlapException>();
}
```

This test ensures exceptions propagate correctly. We:

1. Set up the scenario
2. Make the repository throw an exception
3. Verify the exception bubbles up

FluentAssertions makes testing async exceptions clean and readable.

## Understanding Test Coverage Limitations

When we look back at our booking overlap test, there's an important distinction to make.
Our unit test verifies that our command handler behaves correctly when the booking repository reports an overlap.
However, it doesn't verify that the overlap detection logic itself works correctly.

Consider what we're actually testing:

```csharp
_bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())
    .Returns(true);
```

We're simply telling our mock repository to return `true`.
This gives us confidence that our command handler correctly handles the overlap scenario,
but it does not tell us whether our actual overlap detection logic works correctly.

This is where integration tests become essential.
An integration test for this scenario would:

- Insert real bookings into a test database
- Attempt to create overlapping bookings
- Verify that the overlap detection works with real data

The combination of unit and integration tests provides complete coverage:

- Unit tests verify the business logic flow
- Integration tests verify the actual overlap detection logic

This example highlights why we need different types of tests.
Unit tests are excellent for verifying behavior and logic flows,
but they can't verify the correctness of complex business rules that depend on real data interactions.

## Summary

Unit testing Clean Architecture use cases requires careful thought about dependencies and behavior.
Here are the key points:

- Mock all external dependencies
- Test both success and failure scenarios
- Verify exception handling logic
- Use descriptive test names
- Follow the Arrange-Act-Assert pattern

Good tests act as documentation.
They show how the code should behave and catch issues before they reach production.
Invest time in writing good tests - your future self will thank you.

Want to dive deeper into testing Clean Architecture applications?
I cover this and much more in my [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture) course.
You'll learn how to write effective unit tests, integration tests, and end-to-end tests that give you real confidence in your system.

Writing quality tests is a skill that improves with practice and understanding.
Take the time to write them well.

That's all for today.

See you next week.

---


Previous issues of The .NET Weekly