
<Sponsorships>

Developers must start adopting AI in their daily workflow to be competitive,
which is why Dometrain just launched a [**Deep Dive into Boosting Developer Productivity with AI**](https://dometrain.com/course/deep-dive-boosting-developer-productivity-with-ai/?ref=milan-jovanovic&promo=newsletter-20250412&coupon_code=BIRTHDAY2).
From Claude Sonnet to GPT4o and from ChatGPT to any IDE, this new Dometrain course will ensure your productivity and competitiveness in the market.
Use code BIRTHDAY2 at checkout for 40% off.
[**Get it at 40% off**](https://dometrain.com/course/deep-dive-boosting-developer-productivity-with-ai/?ref=milan-jovanovic&promo=newsletter-20250412&coupon_code=BIRTHDAY2)!

[**Hey .NET devs, can your AI Agent do this**](https://fnf.dev/4hzFtNz)?

- Add new features spanning multiple files
- Queue up tests for you in the terminal
- Open Linear tickets, start a pull request
- Start a new branch in GitHub from recent commits

Augment Code's new AI Agent can. [**Try it in VS Code now**](https://fnf.dev/4hzFtNz)!

</Sponsorships>

**Vector search** is changing how we find information.
Unlike old search methods that look for exact words, vector search finds content based on meaning.
This makes search results more helpful and human-like.

When you search for "quick healthy breakfast ideas," vector search can find articles about "nutritious morning meals" even if they don't use your exact words.
This happens because vector search understands what you mean, not just what you type.

In this week's newsletter, we'll break down how vector search works and why it's important.

## Understanding Vector Embeddings

At the heart of vector search are **vector embeddings**.
These are lists of numbers that represent data.
But how do we get from words or images to numbers?

Here's how it works:

1. We feed text, images, or other data into a [**large language model (LLM)**](working-with-llms-in-dotnet-using-microsoft-extensions-ai)
2. The LLM turns each piece of data into a list of numbers (a vector)
3. These numbers capture the meaning of the data
4. Similar things get similar number patterns

<div className="centered">
  <Image
    src="blogs/mnw_137/vector_space.png"
    width={1719 * 0.3}
    height={1937 * 0.3}
    alt="Vector space visualization."
  />
</div>

Think of each number in the vector as describing one aspect of the data.
With hundreds or thousands of these numbers, vectors can capture complex meanings and relationships.

For example, in vector form, the words "lion" and "bobcat" would have similar number patterns because they refer to similar animals.
Meanwhile, "cat" would have a different pattern, though still somewhat similar since it's also a feline.

## How Vector Search Works

When you search using vector search:

1. Your search question gets turned into a vector
2. The system compares this vector to all the vectors in its database
3. It finds the vectors that are most similar to your search vector
4. It returns the data connected to those similar vectors

To find similar vectors, the system measures how close they are to each other.
Think of each vector as a point in space - the closer two points are, the more similar their meanings.

<Image
  src="blogs/mnw_137/vector_search.png"
  width={2487}
  height={786}
  alt="Vector search visualization."
/>

### Vector Databases

To make vector search work well with lots of data, we need special storage systems called **vector databases**.
These databases are built to store and quickly search through millions or billions of vectors.

Vector databases do more than just store vectors - they organize them in smart ways that make searching faster.
They use special methods called "Approximate Nearest Neighbor" (ANN) algorithms that can find similar vectors without checking every single one in the database.

<figure className="figure-center">
  <div className="bordered">
    <Image
      src="blogs/mnw_137/vector_databases_landscape.png"
      width={1400}
      height={832}
      alt="Vector databases landscape."
    />
  </div>
  <figcaption>
    Source: [What are Vector Databases? A Beginner's
    Guide](https://www.infracloud.io/blogs/vector-databases-beginners-guide/)
  </figcaption>
</figure>

These databases also store the original content along with its vector, so when you get search results,
you see the actual text, images, or other data you were looking for.
Popular vector databases include Weaviate, Pinecone, and Qdrant.
But you can also turn PostgreSQL into a vector database using the pgvector extension.

The combination of vector embeddings and vector databases makes search extremely fast, even with millions of items to search through.
This speed makes vector search practical for real-world applications where users expect instant results.

## Key Differences from Traditional Search

Traditional keyword search works like this:

- You type "red shoes"
- The system finds pages with the words "red" and "shoes"
- Results that mention these words more often rank higher

This approach has problems:

- It misses related terms ("scarlet footwear")
- It doesn't understand context
- It can't handle questions well

An improvement to keyword search is [**full-text search**](how-i-implemented-full-text-search-on-my-website), which looks at the whole text of documents.
However, this still has some shortcomings that vector search solves.

Vector search fixes these issues by focusing on meaning rather than exact words.
It can:

- Find content with related concepts
- Understand the context of your search
- Return helpful results even for complex questions

This is why vector search powers many modern AI applications.
It helps chatbots find relevant information and makes recommendation systems more accurate.

## Summary

Vector search represents a major step forward in how computers understand and retrieve information.
By converting data into number patterns that capture meaning, vector search can find connections that keyword search would miss.

This technology is behind many of the smart search features we now take for granted -
from finding similar products in online stores to helping AI assistants answer our questions.
As AI continues to advance, vector search will play an increasingly important role in helping us navigate the growing sea of digital information.

While not perfect, vector search bridges the gap between how computers store data and how humans think about meaning -
making our digital tools more helpful and intuitive to use.

In a future newsletter, we'll dive into the practical side of vector search.
You'll learn how to implement your own vector search system using popular tools and libraries, with step-by-step code examples and best practices.

That's all for today.

See you next week.

---



<Sponsorships>

Stack traces > “it just broke” — [**Sentry for .NET**](https://sentry.io/for/dot-net/?utm_source=dotnetweekly&utm_medium=paid-community&utm_campaign=errors-fy26q1-evergreen&utm_content=newsletter-itbroke-trysentry)
gets it.
NullReferenceException: object not set to an instance of anything remotely helpful.
Sentry captures the full error, request, and user context so you can stop debugging production like it's a murder mystery.
👉 [**Start fixing with Sentry — free trial, no guessing**](https://sentry.io/for/dot-net/?utm_source=dotnetweekly&utm_medium=paid-community&utm_campaign=errors-fy26q1-evergreen&utm_content=newsletter-itbroke-trysentry).

Sure, you can roll your own auth - if you hate free time.
If you're done doing auth on your own, don't sacrifice your control.
[**FusionAuth**](https://fnf.dev/4jDQajN) is downloadable, and can be developed and tested locally.
A single-tenant architecture provides better scale and security than a purely multi-tenant SaaS model,
even if you deploy via the cloud.
[**Try it for free**](https://fnf.dev/4jDQajN), and check out our transparent pricing!

</Sponsorships>

Big changes are happening in the .NET ecosystem.
Three powerhouse libraries - MediatR, AutoMapper, and MassTransit - are moving to commercial licenses.
Not so long ago, Fluent Assertions also announced its plans to move to a commercial license.

As someone who's built countless systems with these tools over the past decade, I have thoughts.
And some strong opinions.

## The Libraries We Love (And Sometimes Hate)

If you're a .NET developer, you likely use at least one of these:

[**AutoMapper**](https://github.com/AutoMapper/AutoMapper) (794.7M downloads) transforms objects from one type to another.
It removes mountains of tedious mapping code that nobody enjoys writing.
One line replaces twenty.
**I personally despise AutoMapper and mapping libraries in general**, but I can't deny their popularity.

[**MediatR**](https://github.com/jbogard/MediatR) (286.6M downloads) implements the [**mediator pattern**](cqrs-pattern-with-mediatr).
It decouples requests from the objects handling them, promoting separation of concerns.
There's also the pipeline behavior feature, which allows you to add cross-cutting concerns.
I'm a huge fan and use it regularly in my projects.

[**MassTransit**](https://github.com/MassTransit/MassTransit) (130.0M downloads) makes distributed messaging simple.
It wraps message brokers like [**RabbitMQ and Azure Service Bus**](using-masstransit-with-rabbitmq-and-azure-service-bus) with an elegant API.
Building event-driven systems becomes approachable.
This is another tool I love and often recommend.

These libraries aren't just popular - they're transformative.
They've shaped how we build .NET applications.

## The Maintainer's Reality

Both announcements tell a similar story.

<figure className="figure-center">
  <div className="bordered">
    <Image
      src="blogs/mnw_136/mediatr_automapepr_announcement.png"
      width={1183}
      height={801}
      alt="AutoMapper and MediatR Going Commercial."
    />
  </div>
  <figcaption>
    Source: [AutoMapper and MediatR Going
    Commercial](https://www.jimmybogard.com/automapper-and-mediatr-going-commercial/)
  </figcaption>
</figure>

Jimmy Bogard (AutoMapper, MediatR) writes:

> You can see exactly where my contributions cratered and flat-lined. And that's just commits—issues, PRs, discussions, all my time dried up.

His OSS work was previously sponsored by his former employer.
When he went independent, that support vanished.
His focus shifted to his consulting business.

<figure className="figure-center">
  <div className="bordered">
    <Image
      src="blogs/mnw_136/masstransit_announcement.png"
      width={1093}
      height={594}
      alt="Announcing MassTransit v9."
    />
  </div>
  <figcaption>
    Source: [Announcing MassTransit
    v9](https://masstransit.io/introduction/v9-announcement)
  </figcaption>
</figure>

Similarly, MassTransit has grown from "a single assembly that supported MSMQ" in 2007 to over thirty NuGet packages.
Its success created demands that are impossible to meet through volunteer work alone:

- Full-time development resources
- Enterprise-grade support
- Long-term sustainability

Both maintainers face the same dilemma: how do you support widely used libraries when nobody pays you to do it?

## The Commercial Transition

Here's what's happening:

**AutoMapper and MediatR**: Jimmy hasn't shared specific timing or pricing yet.
He states, "Short term, nothing will change."

**MassTransit**: Moving from v8 (open source) to v9 (commercial) with this timeline:

- Q3 2025: v9 prerelease for early adopters
- Q1 2026: v9 official release under commercial license
- Through 2026: v8 security patches continue

MassTransit's pricing targets:

- Small/medium businesses: $400/month or $4000/year
- Large enterprises: $1200/month or $12000/year
- Support for ISVs and consultants who build client applications

None of this is set in stone.
The pricing aspect should be final by the time the commercial version is released.

## Why I Respect This Decision

Both maintainers waited over a decade before making this move.
They've contributed immense value to our community for free.

Their announcements show careful consideration.
They're not abandoning users:

- Existing versions remain open source
- Security patches will continue
- Commercial licenses support sustainable development

I honestly hope none of the above changes in the future.
The work they do is valuable.

Writing these libraries from scratch would cost your team far more than their license fees.

## Your Options Now (With My Take)

If your project uses these libraries, you have choices:

1. **Purchase the commercial license**  
   This supports continued development and gets you new features and official support.

2. **Stay on the current open source version**  
   MassTransit v8 and current MediatR/AutoMapper will remain available.
   Security patches will continue through 2026 for MassTransit.
   For MassTransit specifically, I'd consider staying on v8 for the long term if possible.

3. **Switch to alternatives**  
   For AutoMapper: consider [Mapster](https://github.com/MapsterMapper/Mapster) or **manual mapping** (my recommendation).

   For MediatR: explore [FastEndpoints](https://github.com/FastEndpoints/FastEndpoints) or [**build a simple mediator yourself**](stop-conflating-cqrs-and-mediatr).

   For MassTransit: look at raw client libraries like [RabbitMQ.Client](https://www.nuget.org/packages/rabbitmq.client/) and
   [Azure.Messaging.ServiceBus](https://www.nuget.org/packages/Azure.Messaging.ServiceBus),
   and another option to consider is [**Rebus**](implementing-the-saga-pattern-with-rebus-and-rabbitmq).

4. **Write equivalent functionality yourself**  
   MediatR isn't too complex to build on your own.
   I recommend giving it a try as an excellent coding exercise - it's probably the simplest way to move away from MediatR.

   For AutoMapper, many teams have deep integrations with business logic in custom mappers.
   This makes extracting and replacing it difficult.
   Expect significant tech debt if you don't address this.

   MassTransit, on the other hand, does so many things (and does them well) that migrating away would be challenging.
   [**Saga support**](implementing-the-saga-pattern-with-masstransit) or the [**request-response messaging**](request-response-messaging-pattern-with-masstransit)
   features are hard to replicate.
   The only real alternative is diving into raw client libraries for your chosen message transport.

Each option involves tradeoffs. The right choice depends on your project needs and budget.

## A Shift to Fundamentals

These changes have made me reflect on something important: we should never lose sight of fundamentals.

We've been pampered and spoiled by these awesome libraries.
It's easy to lose sight of the actual problems they're solving and how they work under the hood.
People know how to use MediatR, but they don't understand the mechanisms behind it.

The same goes for MassTransit.
It abstracts away so many complexities of working with message brokers that it's possible to use it without knowing how RabbitMQ or Azure Service Bus actually works.

Remember this: using a library that abstracts something away doesn't excuse you from understanding the patterns and tools you're using.
The **fundamentals are still there** and always have been.
This might be the perfect opportunity to deepen your knowledge of what's happening beneath these abstractions.

## A Reality Check

Open source isn't free. Someone pays - either with time or money.

I'm honestly tired of seeing developers complain about these changes.
Who are they to demand software for free?
The entitlement is astounding.
These maintainers have provided immense value for over a decade without asking for anything in return.

We've enjoyed years of exceptional tooling without directly funding it.
Now we face a reckoning.

As businesses reap massive productivity gains from these libraries, it's reasonable to ask: shouldn't some of that value flow back to the creators?

I hope these projects thrive under their new models.
They've earned support after years of thankless work.

Both my [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture) and
[**Modular Monolith Architecture**](/modular-monolith-architecture) courses currently use MediatR and MassTransit extensively.
I plan to keep them on MediatR v12 and MassTransit v8 in the short term.
However, I'll also be updating them to show migration paths away from these libraries.

What's your take?
Will you stick with the open versions, pay for licenses, or explore alternatives?

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**Augment Code's AI assistant is a power tool for pro software engineers**](https://fnf.dev/4ipAdxn).
- Built to handle huge, gnarly, production-grade codebases
- Fully compatible with Vim, VSCode, JetBrains, etc
- Knows your dependencies and your team's coding standards

Skip the AI toys and build real stuff with Augment Code.
[**Try 30 days free**](https://fnf.dev/4ipAdxn).

[**Get every Dometrain Course at 40% off**](https://dometrain.com/dometrain-pro/?ref=milan-jovanovic&promo=newsletter-20250329&coupon_code=MILAN04)!
It's Dometrain's 2nd birthday, and they are celebrating by offering 40% off everything!
That's 81 courses, 11 bundles, and 3 workshops enjoyed by 56.000 students, all available at 40% off. 
Use code MILAN04 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-20250329&coupon_code=MILAN04)!

</Sponsorships>

Unless you've been living under a rock, you know that [.NET Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview)
is changing (for the better) how we build distributed applications in .NET.
A simple way to think about Aspire: it makes all the difficult things in software development easy.

.NET Aspire is a cloud-native application stack that simplifies the development and deployment of distributed applications.
One of the key challenges when building multi-service applications is building reliable [**communication between services**](modular-monolith-communication-patterns).

In this week's newsletter, I want to focus on one aspect of .NET Aspire - [**service discovery**](service-discovery-in-microservices-with-net-and-consul).
Service discovery lets our services figure out how to locate other services they want to integrate with.
.NET Aspire tackles this challenge with a simple, configuration-based approach that reduces complexity and boilerplate code.

## Understanding Service Discovery

[**Service discovery**](https://learn.microsoft.com/en-us/dotnet/core/extensions/service-discovery)
is the process by which services in a distributed application locate and communicate with each other.
As applications scale and evolve, keeping track of service endpoints becomes increasingly challenging.
Services might run on different ports during development or be deployed to different environments in production,
making hard-coded service URLs impractical.

Traditional approaches to service discovery often introduce complexity:

- Manual configuration of service endpoints that must be updated as environments change
- Complex intermediary systems that require additional maintenance
- Custom code to handle service resolution and connection management

While many service discovery implementations rely on centralized registries,
.NET Aspire takes a different approach by leveraging application configuration to connect services.
This design choice simplifies the development experience while maintaining flexibility for various deployment scenarios.
Aspire automatically takes care of wiring up the correct service URLs and injecting them into your application settings.

<Image
  src="blogs/mnw_135/aspire_service_discovery.png"
  width={2597}
  height={1616}
  alt="Diagram explaining how the .NET Aspire service discovery mechanism works."
/>

## Practical Example of Service Discovery

To understand how .NET Aspire handles service discovery, let's look at a practical example of an application with multiple services:

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

// Add services to the app
var apiService = builder.AddProject<Projects.WeatherApi>("weather-api");
var webFrontend = builder.AddProject<Projects.WebFrontend>("web-frontend")
    .WithReference(apiService);
    
builder.Build().Run();
```

In this App Host definition, we're creating two services: a weather API and a web frontend.
The `.WithReference()` method establishes a connection between these services, which enables service discovery.
This simple declaration tells [**.NET Aspire**](dotnet-aspire-a-game-changer-for-cloud-native-development)
that the web frontend depends on the weather API and needs to communicate with it.
Note that the `web-frontend` has to be a server-side application (like [Blazor Server](https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models))
for Aspire to be able to inject the service URL.

With this configuration in place, the web frontend can now reach the API using the service name `weather-api`
without additional service discovery code:

```csharp {7}
// Configures the default Aspire services, including service discovery
builder.AddServiceDefaults();

// In Program.cs of the web-frontend project
builder.Services.AddHttpClient("weather-api", (_, client) => {
    // The service name "weather-api" automatically resolves to the correct address
    client.BaseAddress = new Uri("http://weather-api");
});
```

This works because .NET Aspire manages the mapping between service names and their actual endpoints.
When the application runs, service discovery ensures that requests to `http://weather-api` are routed to the appropriate destination.

## Service Discovery Under the Hood

The previous example contains a bit of "magic" that might not be immediately clear.
The `AddServiceDefaults()` method configures the default services for the application, including service discovery.

If we were to configure everything manually, it would look something like this:

```csharp {1,6}
builder.Services.AddServiceDiscovery();

builder.Services.AddHttpClient("weather-api", (_, client) => {
    client.BaseAddress = new Uri("http://weather-api");
})
.AddServiceDiscovery();
```

The first `AddServiceDiscovery()` method registers the necessary services to enable service discovery in the application.
The second `AddServiceDiscovery()` method on the HTTP client configures it to use service discovery for resolving the base address.
This means that when the HTTP client makes requests to `http://weather-api`,
it will automatically resolve the correct endpoint based on the service discovery configuration.

We can also configure service discovery globally for all HTTP clients in the application:

```csharp
builder.Services.ConfigureHttpClientDefaults(static http =>
{
    // Turn on service discovery by default
    http.AddServiceDiscovery();
});
```

This configuration ensures that all HTTP clients in the application will use service discovery by default,
eliminating the need to configure it for each client individually.

What Aspire does at runtime for all of this to work is inject a set of configuration values.
The configuration value names are derived from the service names we defined in the App Host, plus the respective scheme (http or https).
Here's an example of what the `weather-api` configuration might look like:

```json
{
  "Services": {
    "weather-api": {
      "http": [
        "localhost:8080"
      ]
    }
  }
}
```

We can also configure service discovery to work with HTTPS by adding the `https` scheme to the service name:

```csharp
// Specify the https scheme explicitly in the service name
builder.Services.AddHttpClient("weather-api", (_, client) => {
    client.BaseAddress = new Uri("https://weather-api");
});

// Alternatively, we can use the https+http scheme and let Aspire handle the conversion
builder.Services.AddHttpClient("weather-api-2", (_, client) => {
    client.BaseAddress = new Uri("https+http://weather-api");
});
```

A significant advantage of Aspire's service discovery is its consistent behavior across environments:

- During development, services might run on localhost with different ports
- In testing environments, services could be containerized
- In production, services might be deployed to Kubernetes or other platforms

Your code remains unchanged across these scenarios because the service name abstraction shields you from the underlying networking details.

Note that you don't have to use .NET Aspire to benefit from [service discovery](https://learn.microsoft.com/en-us/dotnet/core/extensions/service-discovery).
It's available as a standalone library (`Microsoft.Extensions.ServiceDiscovery`) and you can use it in any .NET application.

## Service Discovery with YARP as a Proxy

A powerful application of .NET Aspire's service discovery capabilities is in API gateway scenarios using
[**YARP**](implementing-an-api-gateway-for-microservices-with-yarp) (Yet Another Reverse Proxy).
Let's explore how to implement this pattern:

```csharp
// In the App Host
var apiService = builder.AddProject<Projects.WeatherApi>("weather-api");
var userService = builder.AddProject<Projects.UserApi>("user-api");
var proxyService = builder.AddProject<Projects.ApiGateway>("api-gateway")
    .WithReference(apiService)
    .WithReference(userService);
```

We'll need to add the YARP NuGet package to the API gateway project:

```powershell
Install-Package Yarp.ReverseProxy # Adds the YARP package
Install-Package Microsoft.Extensions.ServiceDiscovery.Yarp # Adds the YARP service discovery package
```

In the gateway project, we can configure YARP to use service discovery:

```csharp {5,11}
// In Program.cs of the api-gateway project
var builder = WebApplication.CreateBuilder(args);

// Cofigures the service discovery services
builder.Services.AddServiceDiscovery();

// Add YARP services
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))
    // Configures a destination resolver that can use service discovery
    .AddServiceDiscoveryDestinationResolver();

var app = builder.Build();

// Configure the HTTP request pipeline
app.MapReverseProxy();

app.Run();
```

The YARP configuration in `appsettings.json` leverages the service names for endpoint resolution:

```json
{
  "ReverseProxy": {
    "Routes": {
      "weather-route": {
        "ClusterId": "weather-cluster",
        "Match": {
          "Path": "/weather/{**catch-all}"
        },
        "Transforms": [
          { "PathRemovePrefix": "/weather" }
        ]
      },
      "user-route": {
        "ClusterId": "user-cluster",
        "Match": {
          "Path": "/users/{**catch-all}"
        },
        "Transforms": [
          { "PathRemovePrefix": "/users" }
        ]
      }
    },
    "Clusters": {
      "weather-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://weather-api"
          }
        }
      },
      "user-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://user-api"
          }
        }
      }
    }
  }
}
```

This configuration creates an API gateway that:

- Routes requests with path `/weather/*` to the weather API service
- Routes requests with path `/users/*` to the user API service
- Uses service names (`weather-api` and `user-api`) that service discovery resolves at runtime

The beauty of this approach is that the gateway doesn't need to know the actual endpoints of the backend services.
It simply uses the service names, and .NET Aspire handles providing the configuration at runtime.
This makes the gateway configuration more portable and easier to maintain as the application evolves.

## Conclusion

.NET Aspire transforms service discovery from a complex infrastructure challenge into a straightforward configuration concern.
By using a configuration-based approach rather than a centralized registry,
it simplifies the development experience while maintaining the flexibility needed for various deployment scenarios.

The key advantages of Aspire's service discovery include:

- Declarative service relationships in the App Host
- Simple service name resolution that works across environments
- Seamless integration with the .NET ecosystem and dependency injection
- Powerful applications in patterns like API gateways with YARP

As the .NET Aspire stack continues to evolve, its approach to service discovery represents
one of the ways it's making cloud-native development more accessible to .NET developers.
By reducing the complexity of service-to-service communication,
Aspire enables teams to focus on building features rather than wrestling with infrastructure concerns.

If you want to explore more robust service discovery solutions for large-scale distributed systems,
check out my previous article on [**implementing service discovery with Consul**](service-discovery-in-microservices-with-net-and-consul).
It provides a complementary approach for scenarios that might require a more traditional service registry.

For those who found the YARP integration particularly interesting, my [**Modular Monolith Architecture**](/modular-monolith-architecture)
course dives deeper into building scalable applications with YARP as an API gateway.
You'll learn how to leverage these patterns to create maintainable,
evolvable systems regardless of whether you're using microservices or a monolith.

That's all for today.

See you next Saturday.

---



<Sponsorships>

Using [**MassTransit with RabbitMQ** or **Azure Service Bus**](https://go.particular.net/mt_error_management-mj-2)?
Messages exhausting retry policies and ending up in error queues is inevitable.
If you're manually "shoveling" them from Management UIs or have custom scripts to send them back to be reprocessed, there is a better way.
[**Try the MassTransit Error Management platform today**](https://go.particular.net/mt_error_management-mj-2)!

[**Webinar: Design System PoC Live Demo**](https://www.telerik.com/webinars/kendo-react-ui/how-bitovi-builds-a-design-system-poc-in-under-an-hour-with-react?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_webinar_KendoReact_Bitovi)\
Would you accept the challenge of creating a design system PoC in front of a live audience in under an hour?
We did!
[**Join us on March 26th to watch the simulation**](https://www.telerik.com/webinars/kendo-react-ui/how-bitovi-builds-a-design-system-poc-in-under-an-hour-with-react?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_webinar_KendoReact_Bitovi).

</Sponsorships>

If you've worked with the [**Options Pattern**](how-to-use-the-options-pattern-in-asp-net-core-7) in ASP.NET Core,
you're likely familiar with the built-in validation using [Data Annotations](https://learn.microsoft.com/en-us/aspnet/core/mvc/models/validation?view=aspnetcore-9.0#validation-attributes).
While functional, Data Annotations can be limiting for complex validation scenarios.

The **Options Pattern** lets you use classes to obtain strongly typed configuration objects at runtime.

The problem? You can't be certain that the configuration is valid until you try to use it.

So why not validate it at application startup?

In this article, we'll explore how to integrate the more powerful [FluentValidation](https://docs.fluentvalidation.net/en/latest/)
library with ASP.NET Core's [Options Pattern](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/options),
to build a robust validation solution that executes at application startup.

## Why FluentValidation Over Data Annotations?

Data Annotations work well for simple validations, but FluentValidation offers several advantages:

- More expressive and flexible validation rules
- Better support for complex conditional validations
- Cleaner separation of concerns (validation logic separate from model)
- Easier testing of validation rules
- Better support for custom validation logic
- Allows for injecting dependencies into validators

## Understanding the Options Pattern Lifecycle

Before diving deep into validation, it's important to understand the lifecycle of options in ASP.NET Core:

- Options are registered with the DI container
- Configuration values are bound to options classes
- Validation occurs (if configured)
- Options are resolved when requested via `IOptions<T>`, `IOptionsSnapshot<T>`, or `IOptionsMonitor<T>`

The `ValidateOnStart()` method forces validation to occur during application startup rather than when options are first resolved.

## Common Configuration Failures Without Validation

Without validation, configuration issues can manifest in several ways:

- **Silent failures**: An incorrectly configured option may result in default values being used without warning
- **Runtime exceptions**: Configuration issues may only surface when the application tries to use invalid values
- **Cascading failures**: One misconfigured component can cause failures in dependent systems

By validating at startup, you create a fast feedback loop that prevents these issues.

## Setting Up the Foundation

First, let's add the FluentValidation package to our project:

```powershell
Install-Package FluentValidation # base package
Install-Package FluentValidation.DependencyInjectionExtensions # for DI integration
```

For our example, we'll use a `GitHubSettings` class that requires validation:

```csharp
public class GitHubSettings
{
    public const string ConfigurationSection = "GitHubSettings";

    public string BaseUrl { get;init; }
    public string AccessToken { get; init; }
    public string RepositoryName { get; init; }
}
```

## Creating a FluentValidation Validator

Next, we'll create a validator for our settings class:

```csharp
public class GitHubSettingsValidator : AbstractValidator<GitHubSettings>
{
    public GitHubSettingsValidator()
    {
        RuleFor(x => x.BaseUrl).NotEmpty();

        RuleFor(x => x.BaseUrl)
            .Must(baseUrl => Uri.TryCreate(BaseUrl, UriKind.Absolute, out _))
            .When(x => !string.IsNullOrWhiteSpace(x.baseUrl))
            .WithMessage($"{nameof(GitHubSettings.BaseUrl)} must be a valid URL");

        RuleFor(x => x.AccessToken)
            .NotEmpty();

        RuleFor(x => x.RepositoryName)
            .NotEmpty();
    }
}
```

## Building the FluentValidation Integration

To integrate FluentValidation with the Options Pattern, we need to create a custom `IValidateOptions<T>` implementation:

```csharp
using FluentValidation;
using Microsoft.Extensions.Options;

public class FluentValidateOptions<TOptions>
    : IValidateOptions<TOptions>
    where TOptions : class
{
    private readonly IServiceProvider _serviceProvider;
    private readonly string? _name;

    public FluentValidateOptions(IServiceProvider serviceProvider, string? name)
    {
        _serviceProvider = serviceProvider;
        _name = name;
    }

    public ValidateOptionsResult Validate(string? name, TOptions options)
    {
        if (_name is not null && _name != name)
        {
            return ValidateOptionsResult.Skip;
        }

        ArgumentNullException.ThrowIfNull(options);

        using var scope = _serviceProvider.CreateScope();

        var validator = scope.ServiceProvider.GetRequiredService<IValidator<TOptions>>();

        var result = validator.Validate(options);
        if (result.IsValid)
        {
            return ValidateOptionsResult.Success;
        }

        var type = options.GetType().Name;
        var errors = new List<string>();

        foreach (var failure in result.Errors)
        {
            errors.Add($"Validation failed for {type}.{failure.PropertyName} " +
                       $"with the error: {failure.ErrorMessage}");
        }

        return ValidateOptionsResult.Fail(errors);
    }
}
```

A few important notes about this implementation:

1. We create a scoped service provider to properly resolve the validator (since validators are typically registered as scoped services)
2. We handle named options through the `_name` property
3. We build informative error messages that include the property name and error message

## How the FluentValidation Integration Works

When adding our custom FluentValidation integration, it's helpful to understand how it connects to ASP.NET Core's options system:

1. The `IValidateOptions<T>` interface is the hook that ASP.NET Core provides for options validation
2. Our `FluentValidateOptions<T>` class implements this interface to bridge to FluentValidation
3. When `ValidateOnStart()` is called, ASP.NET Core resolves all `IValidateOptions<T>` implementations and runs them
4. If validation fails, an `OptionsValidationException` is thrown, preventing the application from starting

## Creating Extension Methods for Easy Integration

Now, let's create a few extension methods to make our validation easier to use:

```csharp
public static class OptionsBuilderExtensions
{
    public static OptionsBuilder<TOptions> ValidateFluentValidation<TOptions>(
        this OptionsBuilder<TOptions> builder)
        where TOptions : class
    {
        builder.Services.AddSingleton<IValidateOptions<TOptions>>(
            serviceProvider => new FluentValidateOptions<TOptions>(
                serviceProvider,
                builder.Name));

        return builder;
    }
}
```

This extension method allows us to call `.ValidateFluentValidation()` when configuring options, similar to the built-in `.ValidateDataAnnotations()` method.

For even more convenience, we can create another extension method to simplify the entire configuration process:

```csharp
public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddOptionsWithFluentValidation<TOptions>(
        this IServiceCollection services,
        string configurationSection)
        where TOptions : class
    {
        services.AddOptions<TOptions>()
            .BindConfiguration(configurationSection)
            .ValidateFluentValidation() // Configure FluentValidation validation
            .ValidateOnStart(); // Validate options on application start

        return services;
    }
}
```

## Registering and Using the Validation

There are a few ways to use our FluentValidation integration:

### Option 1: Standard Registration with Manual Validator Registration

```csharp
// Register the validator
builder.Services.AddScoped<IValidator<GitHubSettings>, GitHubSettingsValidator>();

// Configure options with validation
builder.Services.AddOptions<GitHubSettings>()
    .BindConfiguration(GitHubSettings.ConfigurationSection)
    .ValidateFluentValidation() // Configure FluentValidation validation
    .ValidateOnStart();
```

### Option 2: Using the Convenience Extension Method

```csharp
// Register the validator
builder.Services.AddScoped<IValidator<GitHubSettings>, GitHubSettingsValidator>();

// Use the convenience extension
builder.Services.AddOptionsWithFluentValidation<GitHubSettings>(GitHubSettings.ConfigurationSection);
```

### Option 3: Automatic Validator Registration

If you have many validators and want to register them all at once, you can use FluentValidation's assembly scanning:

```csharp
// Register all validators from assembly
builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);

// Use the convenience extension
builder.Services.AddOptionsWithFluentValidation<GitHubSettings>(GitHubSettings.ConfigurationSection);
```

## What Happens at Runtime?

With `.ValidateOnStart()`, the application will throw an exception during startup if any validation rules fail.
For example, if your `appsettings.json` is missing the required `AccessToken`, you'll see something like:

```
Microsoft.Extensions.Options.OptionsValidationException:
    Validation failed for GitHubSettings.AccessToken with the error: 'Access Token' must not be empty.
```

This prevents your application from even starting with invalid configuration, ensuring issues are caught as early as possible.

## Working with Different Configuration Sources

ASP.NET Core's configuration system supports multiple sources.
When using the Options Pattern with FluentValidation, remember that validation works regardless of the source:

- Environment variables
- Azure Key Vault
- User secrets
- JSON files
- In-memory configuration

This is particularly useful for containerized applications where configuration comes from environment variables or mounted secrets.

## Testing Your Validators

One benefit of using FluentValidation is that validators are easy to test:

```csharp
// Uses helper methods from FluentValidation.TestHelper
[Fact]
public void GitHubSettings_WithMissingAccessToken_ShouldHaveValidationError()
{
    // Arrange
    var validator = new GitHubSettingsValidator();
    var settings = new GitHubSettings { RepositoryName = "test-repo" };

    // Act
    TestValidationResult<GitHubSettings>? result = await validator.TestValidate(settings);

    // Assert
    result.ShouldNotHaveAnyValidationErrors();
}
```

## Summary

By combining FluentValidation with the Options Pattern and `ValidateOnStart()`,
we create a powerful [**validation system**](cqrs-validation-with-mediatr-pipeline-and-fluentvalidation) that ensures our application has correct configuration at startup.

This approach:

1. Provides more expressive validation rules than Data Annotations
2. Separates validation logic from configuration models
3. Catches configuration errors at application startup
4. Supports complex validation scenarios
5. Is easily testable

This pattern is particularly valuable in [**microservice architectures**](monolith-to-microservices-how-a-modular-monolith-helps) or containerized applications
where configuration errors should be detected immediately rather than at runtime.

Remember to register your validators appropriately and use `.ValidateOnStart()` to ensure validation happens during application startup.

That's all for today.

See you next Saturday.

---



<Sponsorships>

[**Code Faster With Amazon Q**]().
Amazon Q Developer is your AI-powered coding companion that helps developers build, operate,
and transform software with intelligent assistance at every step of the development lifecycle.
Accelerate your workflow with line-by-line code suggestions and quality improvements in your favorite IDE.
Get expert AWS guidance on architecture, troubleshooting, and resource optimization.
Transform existing applications and automate upgrades without starting from scratch.
[**Learn more in the AWS Developer Center**](https://fnf.dev/40HtNBT).

[**GitLab Duo Self-Hosted: The enterprise AI solution designed for data-sensitive environments**](https://fnf.dev/428kxIQ).
**Maintain Data Residency**: Run leading AI models (Anthropic, Mistral, OpenAI) within your own infrastructure, ensuring complete data control.
**Compliance Ready**: Ideal for regulated industries, GitLab Duo Self-Hosted helps meet stringent data privacy requirements.
**Boost Developer Productivity**: Integrate powerful AI assistance directly into your development workflow, without compromising security.
[**Learn how GitLab Duo Self-Hosted can empower your team**](https://fnf.dev/428kxIQ).

</Sponsorships>

I remember the days of deploying .NET applications by hand: publishing locally, copying files to servers, running scripts,
and crossing my fingers that nothing would break.
It was stressful, time-consuming, and honestly, a bit scary.

But those days are over.

After implementing [CI/CD](https://en.wikipedia.org/wiki/CI/CD) pipelines for dozens of projects,
I've seen firsthand how automation transforms the deployment process from a dreaded chore into a reliable, even boring, part of development.

And boring deployments are good deployments.

In this article, I'll walk you through setting up a robust CI/CD pipeline for .NET 9 applications using
[GitHub Actions](https://github.com/features/actions) and [Azure App Service](https://azure.microsoft.com/en-us/products/app-service).
I'll cover:

- What CI/CD is and why it matters for .NET developers
- A complete workflow that builds, tests, and deploys your application
- How to extend your pipeline with database migrations, code coverage, and more
- Practical tips I've learned from real-world deployments

Whether you're tired of manual deployments or looking to improve your existing automation,
this guide will help you build a robust CI/CD pipeline that you can easily extend to fit your needs.

## What is CI/CD and Why Should You Care?

CI/CD stands for **Continuous Integration** and **Continuous Delivery/Deployment**.

In simple terms:

- **Continuous Integration (CI)** means frequently merging code changes and running automated tests to catch issues early
- **Continuous Delivery (CD)** means getting those changes to production-ready environments quickly and safely
- **Continuous Deployment (CD)** is an extension of Continuous Delivery where every change that passes automated tests is deployed to production automatically

The main benefits I've seen:

1. **Faster feedback**: Find bugs within minutes instead of days
2. **More stable releases**: Small, incremental changes are easier to fix
3. **Time savings**: Let automation handle repetitive tasks while you focus on writing code
4. **Consistent deployment**: No more "it works on my machine" problems

## My GitHub Actions Workflow for .NET 9

Here's the workflow I use to deploy a simple time service API to Azure App Service:

```yaml
# Name of the workflow as it appears in GitHub Actions UI
name: Time Service CI

# Define when this workflow will run
on:
  workflow_dispatch: # Allow manual triggering from GitHub UI
  push:
    branches:
      - main # Run automatically when code is pushed to main branch

# Environment variables used throughout the workflow
env:
  AZURE_WEBAPP_NAME: time-service
  AZURE_WEBAPP_PACKAGE_PATH: './Time.Api/publish'
  DOTNET_VERSION: '9.x'
  SOLUTION_PATH: 'Time.Api.sln'
  API_PROJECT_PATH: 'Time.Api'
  PUBLISH_DIR: './publish'

# Define the separate jobs that make up this workflow
jobs:
  # First job: build and test the application
  build-and-test:
    name: Build and Test
    runs-on: ubuntu-latest # Use Ubuntu runner for this job

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}

      - name: Restore
        run: dotnet restore ${{ env.SOLUTION_PATH }}

      - name: Build
      run: dotnet build ${{ env.SOLUTION_PATH }}
        --configuration Release
        --no-restore

    - name: Test
      run: dotnet test ${{ env.SOLUTION_PATH }}
        --configuration Release
        --no-restore
        --no-build
        --verbosity normal


    - name: Publish
      run: dotnet publish ${{ env.API_PROJECT_PATH }}
        --configuration Release
        --no-restore
        --no-build
        --property:PublishDir=${{ env.PUBLISH_DIR }}

    # Store the published output as an artifact for later jobs
    - name: Publish Artifacts
      uses: actions/upload-artifact@v4
      with:
        name: webapp  # Name of the artifact
        path: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}

  # Second job: deploy the application to Azure
  deploy:
    name: Deploy to Azure
    runs-on: ubuntu-latest
    needs: [build-and-test] # This job depends on the build-and-test job

    steps:
      # Retrieve the artifacts from the build job
      - name: Download artifact from build job
        uses: actions/download-artifact@v4
        with:
          name: webapp
          path: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}

      # Deploy to Azure App Service using publish profile credentials
      - name: Deploy
        uses: azure/webapps-deploy@v2
        with:
          app-name: ${{ env.AZURE_WEBAPP_NAME }}
          # Authentication credentials stored as a secret
          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
          package: '${{ env.AZURE_WEBAPP_PACKAGE_PATH }}'
```

This workflow does two main things: it builds and tests the code and then deploys it to Azure.

The first job checks out our repository, sets up .NET 9, and runs through a standard build process:
restore packages, build the solution, run tests, and publish the application.
The detailed comments in the YAML explain each step.
Once everything passes, it packages the application as an artifact for the next job.

The second job takes that artifact and deploys it to Azure App Service using a publish profile.
I store the publish profile as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) for security.
The `needs: [build-and-test]` line ensures deployment only happens if all tests pass, which protects our production environment from broken code.

<figure className="figure-center">
  <div className="bordered">
    <Image
      src="blogs/mnw_133/ci_cd_pipeline.png"
      width={1906}
      height={831}
      alt="An example of what a workflow run looks like from the GitHub UI."
    />
  </div>
  <figcaption>
    Here's an example of what a workflow run looks like from the GitHub UI.
  </figcaption>
</figure>

## Extending Your CI/CD Pipeline

While the basic workflow gets your application deployed, most real-world projects need more sophisticated pipelines.
As your project grows, so should your CI/CD process.
Extensions to your pipeline could help catch issues earlier, ensure quality standards, and provide better visibility into your development process.

Here are some valuable additions to consider:

### 1. Running Database Migrations

Database schema changes can be tricky to coordinate with code deployments.
There are several approaches to handling this:

**Using EF Core Migration Bundles**:

```yaml
- name: Create migration bundle
  run: dotnet ef migrations bundle --project ${{ env.DATA_PROJECT }} --output ${{ env.MIGRATIONS_BUNDLE }}

- name: Apply migrations
  run: ${{ env.MIGRATIONS_BUNDLE }}
```

[**Migration bundles**](efcore-migrations-a-detailed-guide) (introduced in EF Core 6.0) package your migrations into a standalone executable,
making them easier to run in deployment pipelines.

**Adding Manual Review for Migrations**:

```yaml
deploy-database:
  name: Deploy Database Changes
  environment: production
  runs-on: ubuntu-latest
  needs: [build-and-test]
```

This approach adds an environment with protection rules, requiring a DBA to review and approve migration scripts before they run.
This is safer for production databases with valuable data.

**Pros**:

- No manual migration steps
- Schema and code changes deploy together
- Database changes are versioned with code

**Cons**:

- Failed migrations can be hard to roll back
- Might need extra handling for production data
- Requires secure database credentials in CI

To minimize risks, I test migrations in a staging environment first and always back up production databases before deployment.

### 2. Code Coverage Reports

I like knowing how much of my code is covered by tests.
Here's an example of how to generate and publish code coverage reports to [Codecov](https://about.codecov.io/):

```yaml
- name: Generate coverage report
  run: dotnet test ${{ env.SOLUTION_PATH }} /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura

- name: Publish coverage report
  uses: codecov/codecov-action@v5
  with:
    files: ./**/coverage.cobertura.xml
    fail_ci_if_error: true
    token: ${{ secrets.CODECOV_TOKEN }}
```

Adding minimum coverage requirements prevents drops in test coverage and encourages the team to maintain quality standards.
You can also configure it to fail builds when coverage falls below a threshold.

### 3. Multi-Environment Deployment

For larger projects, deploying to multiple environments with approval gates provides better control:

```yaml
deploy-staging:
  name: Deploy to Staging
  environment: staging
  runs-on: ubuntu-latest
  needs: [build-and-test]
  steps:
    # Deployment steps...

deploy-production:
  name: Deploy to Production
  environment: production
  runs-on: ubuntu-latest
  needs: [deploy-staging]
  steps:
    # Deployment steps...
```

Adding protection rules to your production environment creates checkpoints where team members can verify changes before they reach users.

Here's an example of some GitHub Environment protection rules:

- **Required reviewers**: Specify team members who must approve deployments
- **Wait timers**: Add a delay before deployments to give time for review
- **Deployment branches**: Restrict which branches can deploy to production

These guardrails are especially important for critical environments where downtime can be costly.

## Final Thoughts

A good CI/CD pipeline evolves with your project.
Start simple, focus on automating the most painful manual tasks first, then gradually add more features as needed.

The initial setup takes time, but the long-term benefits are huge.
My team now deploys multiple times per day instead of once every few weeks, with fewer bugs reaching production.

If you want to learn more about building robust APIs that complement your CI/CD process, check out my [**Pragmatic REST APIs**](/pragmatic-rest-apis) course.
It covers designing, implementing, and deploying production-ready APIs with best practices that work perfectly with the deployment pipeline we've discussed here.

What's your CI/CD setup like?
I'd love to hear how you've customized your workflows for .NET applications.

That's all for today.

See you next week.

---



<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(createHabitDto);

        Habit habit = createHabitDto.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.

---


Previous issues of The .NET Weekly