
<Sponsorships>

[**AWS Summit Washington DC: the Future of Cloud Innovation**](https://fnf.dev/4kGXJqr)\
Join AWS innovators at AWS Summit, June 10-11 in Washington DC, for deep dives on everything cloud from architecture to infrastructure.
340+ sessions with hands-on workshops, labs, interactive builder sessions led by AWS experts, “chalk talk” whiteboard sessions, and skillset-building training.
Learn from cutting-edge cloud technologists solving real-world challenges across industries.
[**FREE registration — claim your spot today!**](https://fnf.dev/4kGXJqr)

[**Design .NET Apps Visually with ABP Studio**](https://abp.io/studio?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_may17)\
Say goodbye to boilerplate and repetitive setup.
ABP Studio is your visual development tool for building modern, modular .NET applications—faster than ever.
Generate full-layered solutions, manage modules, entities, and UI from an intuitive interface — all fully aligned with the ABP.IO
No more context switching or manual coding for scaffolding. Just build, customize, and ship.
➡️ [**Download & Try ABP Studio today**](https://abp.io/studio?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_may17)

</Sponsorships>

MediatR is going commercial.

[Jimmy Bogard recently announced](https://www.jimmybogard.com/automapper-and-mediatr-going-commercial/)
that MediatR will adopt a commercial license model for companies above a certain size.

For many teams, this is a trigger to re-evaluate their usage and possibly look for alternatives.

And it's not a bad time to do so.
MediatR became almost synonymous with CQRS in .NET, despite the fact that [**CQRS and MediatR are not the same thing**](stop-conflating-cqrs-and-mediatr).
Most projects use it as a thin dispatching layer for commands and queries — a use case that can be covered with a few straightforward abstractions.

By removing MediatR, you gain:

- Full control over your CQRS infrastructure
- Predictable, explicit handler dispatching
- Simpler debugging and onboarding
- Cleaner DI setup and better testability

In this article, I'll walk you through building a minimal CQRS setup with just a few interfaces and support for decorators.
No hidden DI magic.
Just clean, predictable code.

We'll cover:

- Defining `ICommand`, `IQuery`, and handler contracts
- Adding support for decorators (logging, validation, etc.)
- Registering everything with DI
- A full working example in a real-world scenario

Let's get started.

## Commands, Queries, and Handlers

Let's start by defining the basic contracts for commands and queries.

```csharp
// ICommand.cs
public interface ICommand;
public interface ICommand<TResponse>;

// IQuery.cs
public interface IQuery<TResponse>;
```

These interfaces exist purely as markers.
They allow us to structure application logic around intention — write operations go through `ICommand`, read operations through `IQuery`.

The handler interfaces follow the same model:

```csharp
// ICommandHandler.cs
public interface ICommandHandler<in TCommand>
    where TCommand : ICommand
{
    Task<Result> Handle(TCommand command, CancellationToken cancellationToken);
}

public interface ICommandHandler<in TCommand, TResponse>
    where TCommand : ICommand<TResponse>
{
    Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken);
}
```

```csharp
// IQueryHandler.cs
public interface IQueryHandler<in TQuery, TResponse>
    where TQuery : IQuery<TResponse>
{
    Task<Result<TResponse>> Handle(TQuery query, CancellationToken cancellationToken);
}
```

These are nearly identical to MediatR's `IRequest` and `IRequestHandler` APIs, making migration trivial if you're moving off of MediatR.

You'll notice we're using a `Result` wrapper for all return types.
This is optional, but it promotes explicit success/failure handling and encourages consistency across the application boundary.
You can learn more about it in my [**previous article**](functional-error-handling-in-dotnet-with-the-result-pattern).

These interfaces form a lightweight CQRS infrastructure, focused purely on intent and separation of concerns.
No mediator, no runtime indirection — just clear contracts for handling reads and writes.

## Practical Example: Command Handler

To see these abstractions in action, let's implement a command that marks a todo item as completed.

```csharp
// CompleteTodoCommand.cs
public sealed record CompleteTodoCommand(Guid TodoItemId) : ICommand;

// CompleteTodoCommandHandler.cs
internal sealed class CompleteTodoCommandHandler(
    IApplicationDbContext context,
    IDateTimeProvider dateTimeProvider,
    IUserContext userContext)
    : ICommandHandler<CompleteTodoCommand>
{
    public async Task<Result> Handle(CompleteTodoCommand command, CancellationToken cancellationToken)
    {
        TodoItem? todoItem = await context.TodoItems
            .SingleOrDefaultAsync(
                t => t.Id == command.TodoItemId && t.UserId == userContext.UserId,
                cancellationToken);

        if (todoItem is null)
        {
            return Result.Failure(TodoItemErrors.NotFound(command.TodoItemId));
        }

        if (todoItem.IsCompleted)
        {
            return Result.Failure(TodoItemErrors.AlreadyCompleted(command.TodoItemId));
        }

        todoItem.IsCompleted = true;
        todoItem.CompletedAt = dateTimeProvider.UtcNow;

        todoItem.Raise(new TodoItemCompletedDomainEvent(todoItem.Id));

        await context.SaveChangesAsync(cancellationToken);

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

A few important things to note:

- The command is an immutable value object (just data, no behavior).
- The handler encapsulates all business logic: validation, state change, raising domain events, and persistence.
- There's no mediator, no `ISender`, no hidden dispatching. The handler is invoked directly via our custom abstractions.

This makes intent explicit, avoids magic, and keeps the dependencies minimal.

We'll look at how to add decorators next, so we can introduce things like logging, validation, or transactions without modifying the handler itself.

## Decorators

To support cross-cutting concerns like logging, validation, and transactions, we apply the **decorator pattern** around our handlers.
Technically, this is closer to the **proxy pattern**, since we're injecting behavior before/after delegating to the real handler.
But in the context of cross-cutting concerns, most people refer to this as a decorator — which is fine for our purposes.

Let's look at two examples: one for logging, one for validation.

```csharp
using Serilog.Context;

internal sealed class LoggingCommandHandler<TCommand, TResponse>(
    ICommandHandler<TCommand, TResponse> innerHandler,
    ILogger<CommandHandler<TCommand, TResponse>> logger)
    : ICommandHandler<TCommand, TResponse>
    where TCommand : ICommand<TResponse>
{
    public async Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken)
    {
        string commandName = typeof(TCommand).Name;

        logger.LogInformation("Processing command {Command}", commandName);

        Result<TResponse> result = await innerHandler.Handle(command, cancellationToken);

        if (result.IsSuccess)
        {
            logger.LogInformation("Completed command {Command}", commandName);
        }
        else
        {
            using (LogContext.PushProperty("Error", result.Error, true))
            {
                logger.LogError("Completed command {Command} with error", commandName);
            }
        }

        return result;
    }
}
```

This class wraps any `ICommandHandler<TCommand, TResponse>`, injecting the decorated handler as `innerHandler`.
It adds structured logging around the command execution without touching the core business logic.

Now a [**validation example with FluentValidation**](cqrs-validation-with-mediatr-pipeline-and-fluentvalidation):

```csharp
using FluentValidation;
using FluentValidation.Results;

internal sealed class ValidationCommandHandler<TCommand, TResponse>(
    ICommandHandler<TCommand, TResponse> innerHandler,
    IEnumerable<IValidator<TCommand>> validators)
    : ICommandHandler<TCommand, TResponse>
    where TCommand : ICommand<TResponse>
{
    public async Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken)
    {
        // Validate the command using all registered validators
        ValidationFailure[] validationFailures = await ValidateAsync(command, validators);

        if (validationFailures.Length == 0)
        {
            return await innerHandler.Handle(command, cancellationToken);
        }

        // If validation fails, return a failure result with the errors
        return Result.Failure<TResponse>(CreateValidationError(validationFailures));
    }

    private static async Task<ValidationFailure[]> ValidateAsync<TCommand>(
        TCommand command,
        IEnumerable<IValidator<TCommand>> validators)
    {
        if (!validators.Any())
        {
            return [];
        }

        var context = new ValidationContext<TCommand>(command);

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

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

        return validationFailures;
    }

    private static ValidationError CreateValidationError(ValidationFailure[] validationFailures) =>
        new(validationFailures.Select(f => Error.Problem(f.ErrorCode, f.ErrorMessage)).ToArray());
}
```

Each decorator handles a single concern and can be layered transparently around the core handler.

**Important:** Since we're working with generic interfaces (`ICommandHandler<,>`, `IQueryHandler<,>`),
each decorator must explicitly target the same generic contract.
That means you'll need separate decorator classes for each handler abstraction you're using (e.g. command with result, command without result, query with result).

In the next section, we'll wire this up using [Scrutor](https://github.com/khellang/Scrutor).
It's a simple assembly scanning library that helps us register and decorate handlers cleanly.
Yes, it uses reflection, but only during startup — and it's fully transparent and predictable.

## DI Setup

With our handlers and decorators in place, we can register everything using Scrutor.

```csharp
services.Scan(scan => scan.FromAssembliesOf(typeof(DependencyInjection))
    .AddClasses(classes => classes.AssignableTo(typeof(IQueryHandler<,>)), publicOnly: false)
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(classes => classes.AssignableTo(typeof(ICommandHandler<>)), publicOnly: false)
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(classes => classes.AssignableTo(typeof(ICommandHandler<,>)), publicOnly: false)
        .AsImplementedInterfaces()
        .WithScopedLifetime());
```

This scans the application assembly and registers all command and query handlers (including internal types) as their respective interfaces.

Next, we apply decorators for validation and logging:

```csharp
services.Decorate(typeof(ICommandHandler<,>), typeof(ValidationDecorator.CommandHandler<,>));
services.Decorate(typeof(ICommandHandler<>), typeof(ValidationDecorator.CommandBaseHandler<>));

services.Decorate(typeof(IQueryHandler<,>), typeof(LoggingDecorator.QueryHandler<,>));
services.Decorate(typeof(ICommandHandler<,>), typeof(LoggingDecorator.CommandHandler<,>));
services.Decorate(typeof(ICommandHandler<>), typeof(LoggingDecorator.CommandBaseHandler<>));
```

Each `Decorate` call wraps the previous registration.
**Order matters**, but it might not be intuitive at first glance.

The last decorator applied will be the outermost one at runtime.
So in this example:

- The **base handler** is first decorated by **validation**
- That composite is then decorated again by **logging**

Which means the **logging decorator runs first**, followed by **validation**, and then the core handler.

This order allows logging to capture the full command lifecycle, including any early exits from validation failures.

With this setup, you now have a fully functional and extensible CQRS pipeline:

- Custom handler interfaces
- Clean decorator chain
- Assembly-scanned DI setup

## Usage from Minimal API

Once everything is wired up, using a command handler from a Minimal API endpoint is straightforward:

```csharp
internal sealed class Complete : IEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app)
    {
        app.MapPut("todos/{id:guid}/complete", async (
            Guid id,
            ICommandHandler<CompleteTodoCommand> handler,
            CancellationToken cancellationToken) =>
        {
            var command = new CompleteTodoCommand(id);

            Result result = await handler.Handle(command, cancellationToken);

            return result.Match(Results.NoContent, CustomResults.Problem);
        })
        .WithTags(Tags.Todos)
        .RequireAuthorization();
    }
}
```

We're injecting the appropriate `ICommandHandler<CompleteTodoCommand>` directly into the endpoint.
No need for `ISender`, no mediator layer, no runtime lookup.

This keeps the endpoint clean and focused on its primary responsibility: handling HTTP requests.

Everything is resolved explicitly by the container.
This makes the code easier to test, reason about, and trace while maintaining all the benefits of CQRS and separation of concerns.

## Conclusion

CQRS doesn't require a complex framework.

With a few small interfaces, some decorator classes, and a clean DI setup, you can build a simple and flexible pipeline for handling commands and queries.
It's easy to understand, easy to test, and easy to extend.

If you want to see this pattern applied in a complete solution,
my [**free Clean Architecture template**](/templates/clean-architecture) includes everything covered in this article (fully wired up).

Use it as a reference or as a starting point for your next project.

---



<Sponsorships>

[**Aiven for OpenSearch®**](https://fnf.dev/3SpnQpp) is the fully managed, open source alternative to Elasticsearch - built for
high-performance, distributed search and analytics.
Spin up production-ready clusters in under 10 minutes, deploy to the cloud of your choice,
and offload the rest to Aiven so you can focus on building, not managing infrastructure.
[**Sign up for free and get additional $100 credits here!**](https://fnf.dev/3EW72Dy)

Code reviews are time-consuming.
[**CodeRabbit**](https://fnf.dev/3F2eDR1) is your AI co-pilot—instantly generating review comments, one-click fixes, and custom AST-grep rules.
It can even plan refactors and merge via chat.
Trusted on 10M+ PRs across 1M repos and 70K+ OSS projects.
[**Try Code Rabbit today and cut .NET code review time and bugs in half**](https://fnf.dev/3F2eDR1).

</Sponsorships>

If you've ever worked with a legacy C# codebase, you know the pain of an anemic domain model.
You have probably opened an `OrderService` (_all similarities to production code are merely a coincidence_) and thought _"this file does everything."_
Pricing logic, discount rules, stock checks, database writes — **all jam-packed into one class**.
It works — until it doesn't.
New features turn into **regression roulette**, and test coverage plummets because the domain is buried under infrastructure.

This is the classic symptom of an anemic domain model, where entities are nothing but data holders, and all logic lives elsewhere.
It makes the system harder to reason about, and every change becomes a guessing game.
But what if we could push behavior back into the domain, one rule at a time?

In this article, we'll:

1. **Inspect** a typical anemic implementation.
2. **Identify** hidden business rules that make it brittle.
3. **Refactor** toward a behavior-rich aggregate one refactor at a time.
4. **Highlight** the concrete payoffs so you can justify the change to teammates.

Everything fits in a 6-minute read, but the pattern scales to any legacy system.

## Starting Point: God-like Service Class

Below is an (unfortunately common) `OrderService`.
Besides calculating totals it also:

- applies a **5 % VIP discount**,
- throws if any product is **out of stock**, and
- rejects orders that would **exceed the customer's credit limit**.

```csharp
// OrderService.cs
public void PlaceOrder(Guid customerId, IEnumerable<OrderItemDto> items)
{
    var customer = _db.Customers.Find(customerId);
    if (customer is null)
    {
        throw new ArgumentException("Customer not found");
    }

    var order = new Order { CustomerId = customerId };

    foreach (var dto in items)
    {
        var inventory = _inventoryService.GetStock(dto.ProductId);
        if (inventory < dto.Quantity)
        {
            throw new InvalidOperationException("Item out of stock");
        }

        var price = _pricingService.GetPrice(dto.ProductId);
        var lineTotal = price * dto.Quantity;
        if (customer.IsVip)
        {
            lineTotal *= 0.95m; // 5% discount for VIPs
        }

        order.Items.Add(new OrderItem
        {
            ProductId = dto.ProductId,
            Quantity = dto.Quantity,
            UnitPrice = price,
            LineTotal = lineTotal
        });
    }

    order.Total = order.Items.Sum(i => i.LineTotal);

    if (customer.CreditUsed + order.Total > customer.CreditLimit)
    {
        throw new InvalidOperationException("Credit limit exceeded");
    }

    _db.Orders.Add(order);
    _db.SaveChanges();
}
```

### What's Wrong Here?

- **Scattered rules:** Discount application, stock validation, and credit-limit checks are buried inside the service.
- **Tight coupling:** `OrderService` must know about pricing, inventory, and EF Core just to place an order.
- **Painful testing:** Each unit test needs fakes for DB access, pricing, inventory, and VIP vs. non-VIP flows.

<div className='blockquote'>

**Goal:** Embed these rules **inside the domain** so the application layer only deals with orchestration.

</div>

## Guiding Principles Before We Touch Code

1. **Protect invariants close to the data.**
   Stock, discounts, and credit checks belong where the data lives — inside the `Order` aggregate.
2. **Expose intent, hide mechanics.**
   The application layer should read like a story: _"place order"_, not _"calculate totals, check credit, write to DB"_.
3. **Refactor in slices.**
   Each move is safe and compilable; no big-bang rewrites.
4. **Balance purity with pragmatism.**
   Move rules only when the payoff (clarity, safety, testability) beats the extra lines of code.

## Step-by-Step Refactor

The goal here isn't to chase purity or academic DDD.
It's to incrementally improve cohesion and make room for the domain to express itself.

At every step, we ask: Is this behavior something the domain should own?
If yes, we pull it inward.

### Embed Creation & Validation Logic

The first move is to make the aggregate responsible for building itself.
A static `Create` method gives us a single entry point where all invariants can fail fast.

While pushing stock validation into `Order` improves testability,
it does couple the order flow with inventory availability.
In some domains, you'd instead model this as a domain event and validate asynchronously.

```csharp
// Order.cs (Factory Method)
public static Order Create(
    Customer customer,
    IEnumerable<(Guid productId, int quantity)> lines,
    IPricingService pricingService,
    IInventoryService inventoryService)
{
    var order = new Order(customer.Id);

    foreach (var (productId, quantity) in lines)
    {
        if (inventoryService.GetStock(productId) < quantity)
        {
            throw new InvalidOperationException("Item out of stock");
        }

        var unitPrice = pricingService.GetPrice(productId);
        order.AddItem(productId, quantity, unitPrice, customer.IsVip);
    }

    order.EnsureCreditWithinLimit(customer);

    return order;
}
```

**Why?**
Creation now **fails fast** if any invariant is broken.
The service no longer micromanages stock or discounts.

Notice how we're now following the "Tell, Don't Ask" principle.
Rather than the service checking conditions and then manipulating the Order,
we're telling the Order to create itself with the necessary validations built in.
This is a fundamental shift toward **encapsulation**.

**💡 On Injecting Services into Domain Methods**

Passing services like `IPricingService` or `IInventoryService` into a domain method such as `Order.Create` might seem unconventional at first glance.
But it's a deliberate design choice: it keeps the orchestration inside the domain model, where the business logic naturally belongs,
instead of bloating the application service with procedural workflows.

This approach maintains the entity's autonomy while still aligning with dependency injection principles — dependencies are passed explicitly, not resolved from within.
It's a powerful technique, but one that should be used selectively — only when the operation clearly fits within the domain's responsibility
and benefits from direct access to external services.

### Guard the Aggregate's Internal State

```csharp
// Order.cs (excerpt)
private readonly List<OrderItem> _items = new();
public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly(); // C# 12 -> [.._items]

private void AddItem(Guid productId, int quantity, decimal unitPrice, bool isVip)
{
    if (quantity <= 0)
    {
        throw new ArgumentException("Quantity must be positive");
    }

    var finalPrice = isVip ? unitPrice * 0.95m : unitPrice;
    _items.Add(new OrderItem(productId, quantity, finalPrice));

    RecalculateTotal();
}

private void EnsureCreditWithinLimit(Customer customer)
{
    if (customer.CreditUsed + Total > customer.CreditLimit)
    {
        throw new InvalidOperationException("Credit limit exceeded");
    }
}
```

**Why bother?**

- **Encapsulation**: Consumers can't mutate `_items` directly, ensuring invariants hold.
- **Self-protection**: The domain model protects its own consistency rather than relying on service-level checks.
- **True OOP**: Objects now combine data and behavior, as object-oriented programming intended.
- **Simpler services**: Application services can focus on coordination rather than business rules.

### Shrink the Application Layer to Pure Orchestration

```csharp
public void PlaceOrder(Guid customerId, IEnumerable<OrderLineDto> lines)
{
    var customer = _db.Customers.Find(customerId);
    if (customer is null)
    {
        throw new ArgumentException("Customer not found");
    }
    var input = lines.Select(l => (l.ProductId, l.Quantity));

    var order = Order.Create(customer, input, _pricingService, _inventoryService);

    _db.Orders.Add(order);
    _db.SaveChanges();
}
```

The `PlaceOrder` method drops from **44 lines** to **14**, with **zero business logic**.

## What We Gained

**Before the refactor**

- Service owned pricing, stock, discount, and credit checks.
- Unit tests required heavy EF Core and service fakes.
- Adding a new rule meant touching multiple files.

**After the refactor**

- Aggregate owns all business rules; service only orchestrates.
- Pure domain tests — no database container required.
- Most changes are isolated to the `Order` aggregate.

## Wrapping Up

The real value in refactoring anemic models isn't technical — it's strategic.

By moving business logic closer to the data, you:

- Reduce the blast radius of changes
- Make business rules explicit and testable
- Open the door for tactical patterns like validation, events, and invariants

But you don't need a big rewrite.
Start with one rule.
Refactor it.
Then the next.

That's how legacy systems evolve into maintainable architectures.

If you enjoyed this breakdown and want a hands-on, real-world guide to untangling messy services,
check out my course [**Domain-Driven Design Refactoring**](/ddd-refactoring).
It's packed with before-and-after examples like this one.

---



<Sponsorships>

[**POST/CON 25**](https://fnf.dev/3EROWlV): Build Smarter APIs for an AI-Driven World\
Join 2,000+ engineers at POST/CON 25, June 3 & 4 in LA, for deep dives on building scalable APIs,
automating with Flows, and deploying AI-native systems. 30+ sessions, hands-on workshops, and zero
fluff. Learn from Postman engineers and peers solving real-world problems.
[**Register with code PMN50CAM1 for 50% off**](https://fnf.dev/3EROWlV)

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

</Sponsorships>

[Event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture) (EDA) can make applications more flexible and reliable.
Instead of one part of the system calling another directly, we let events flow through a message broker.
In this quick guide, I'll show you how to set up a simple event-driven system in .NET using [RabbitMQ](https://www.rabbitmq.com/).

We'll build a small example with a producer that sends events and a consumer that receives them.
For testing, I'll run RabbitMQ in a Docker container (with the Management UI enabled so we can see what's happening).
We'll use the official [RabbitMQ.Client](https://www.nuget.org/packages/rabbitmq.client/) NuGet package in a .NET console app.

<div className='blockquote'>

Note: If you don't have RabbitMQ installed, you can run it quickly with Docker. For example:

```bash
docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4-management
```

This starts a RabbitMQ broker on localhost (AMQP port `5672`) and a management website at `http://localhost:15672`.

</div>

## RabbitMQ Basics

Before coding, let's cover the basic components in RabbitMQ:

- **Producer**: an application that sends messages (events) to RabbitMQ.
- **Consumer**: an application that receives messages from a queue.
- **Queue**: a mailbox inside RabbitMQ that stores messages.
  Consumers read from queues.
  Many producers can send to the same queue.
- **Exchange**: a routing mechanism that receives messages from producers and directs them to queues.
  Producers actually send to an exchange instead of directly to a queue.
  This decouples producers from specific queues - the exchange can decide where messages go, based on rules.

In RabbitMQ, you can have multiple producers and multiple consumers.
Producers never send directly to a queue by name; instead, they send to an exchange.
The exchange decides which queues (if any) should get each message based on routing rules.

For now, we'll use a simple setup where the exchange will deliver all messages to one queue.

## Producer - Sending Events

Let's start with the producer.
In our .NET console app, we'll use RabbitMQ.Client to connect to the RabbitMQ broker and send a message.

For instance, an `OrderPlaced` event could trigger downstream services - inventory, email notifications, etc. -
without the ordering system needing to call them directly.

```csharp
var factory = new ConnectionFactory() { HostName = "localhost" };
using var connection = await factory.CreateConnectionAsync();
using var channel = await connection.CreateChannelAsync();

// Ensure the queue exists (create it if not already there)
await channel.QueueDeclareAsync(
    queue: "orders",
    durable: true, // save to disk so the queue isn’t lost on broker restart
    exclusive: false, // can be used by other connections
    autoDelete: false, // don’t delete when the last consumer disconnects
    arguments: null);

// Create a message
var orderPlaced = new OrderPlaced
{
     OrderId = Guid.NewGuid(),
     Total = 99.99,
     CreatedAt = DateTime.UtcNow
};
var message = JsonSerializer.Serialize(orderPlaced);
var body = Encoding.UTF8.GetBytes(message);

// Publish the message
await channel.BasicPublishAsync(
    exchange: string.Empty, // default exchange
    routingKey: "orders",
    mandatory: true, // fail if the message can’t be routed
    basicProperties: new BasicProperties { Persistent = true }, // message will be saved to disk
    body: body);

Console.WriteLine($"Sent: {message}");
```

This code connects to RabbitMQ on `localhost`, declares a queue named `orders` (creates it if it doesn't exist already),
and publishes an `OrderPlaced` message to that queue.
We use an empty string for the exchange parameter, which tells RabbitMQ to use the default exchange.
The default exchange routes the message directly to the `orders` queue.

What's happening here:

- We declare a **durable queue**, so it survives RabbitMQ restarts
- We mark the message as **persistent**, which tells RabbitMQ to write it to disk
- We serialize an object into JSON and send it as a UTF-8 encoded byte array

Now let's look at the consumer side.

## Consumer - Receiving Events

Next, let's set up a consumer to receive messages from the queue.
The consumer will also connect to RabbitMQ and subscribe to the same queue.

To test this out, start the consumer application first (it will wait for messages), then run the producer application to send an event.

```csharp
var factory = new ConnectionFactory() { HostName = "localhost" };
using var connection = await factory.CreateConnectionAsync();
using var channel = await connection.CreateChannelAsync();

// Declare (or check) the queue to consume from
await channel.QueueDeclareAsync(
    queue: "orders",
    durable: true, // must match the producer's queue settings
    exclusive: false, // can be used by other connections
    autoDelete: false, // don’t delete when the last consumer disconnects
    arguments: null);

// Define a consumer and start listening
var consumer = new AsyncEventingBasicConsumer(channel);
consumer.ReceivedAsync += async (sender, eventArgs) =>
{
    byte[] body = eventArgs.Body.ToArray();
    string message = Encoding.UTF8.GetString(body);
    var orderPlaced = JsonSerializer.Deserialize<OrderPlaced>(message);

    Console.WriteLine($"Received: OrderPlaced - {orderPlaced.OrderId}");

    // Acknowledge the message
    await ((AsyncEventingBasicConsumer)sender)
        .Channel.BasicAckAsync(eventArgs.DeliveryTag, multiple: false);
};
await channel.BasicConsumeAsync("orders", autoAck: false, consumer);

Console.WriteLine("Waiting for messages...");
```

The consumer code declares the same `orders` queue and sets up an event handler for incoming messages.
We call `BasicConsumeAsync` to start listening on the queue.
RabbitMQ will push any new messages to our consumer's event handler.
Whenever a message arrives, the `consumer.ReceivedAsync` event fires, and we print out the message.

What's important here:

- `autoAck: false` ensures we only acknowledge messages we actually process
- If processing fails, we could use `BasicNack` to requeue or route to a dead-letter queue
- Deserializing into a strongly typed object makes it easy to reason about the event

So far we've had one consumer. But what if we run multiple consumers on the same queue?

## Competing Consumers - Scaling Out

What if you have multiple consumers for the same queue?
RabbitMQ allows **competing consumers** on a queue.

If two or more consumers listen on the same queue, each message from that queue will be delivered to **only one** of them:

- RabbitMQ will distribute messages among the consumers (roughly in round-robin order)
- This is great for scaling: you can run multiple instances of a worker to process messages in parallel

In other words, consumers _compete_ for messages on that queue.
This pattern helps spread the workload, but note that each individual message is still processed by a single consumer.

## Fanout Exchange: Broadcast to Multiple Consumers

Competing consumers share the work by dividing messages, but sometimes you want every service to get the event.
That's where a **fanout exchange** comes in.

In RabbitMQ, a fanout exchange is used for broadcasting events to multiple consumers.
Instead of all consumers sharing one queue, each consumer has its own queue.
When the producer sends a message to a fanout exchange, the exchange copies and routes the message to all bound queues.
This way, every consumer receives a copy via its own queue.

To set this up in code, we declare a fanout exchange and bind queues to it.

**Producer**:

```csharp
// Producer setup for fanout
await channel.ExchangeDeclareAsync(
    exchange: "orders",
    durable: true, // durable exchange
    autoDelete: false, // don’t delete when the last consumer disconnects
    type: ExchangeType.Fanout);

// Publish a message to the fanout exchange (routingKey is ignored for fanout)
var orderPlaced = new OrderPlaced
{
     OrderId = Guid.NewGuid(),
     Total = 99.99,
     CreatedAt = DateTime.UtcNow
};
var message = JsonSerializer.Serialize(orderPlaced);
var body = Encoding.UTF8.GetBytes(message);

await channel.BasicPublishAsync(
    exchange: "orders",
    routingKey: string.Empty,
    mandatory: true,
    basicProperties: new BasicProperties { Persistent = true },
    body: body);
```

**Consumer**:

```csharp
// Consumer setup for fanout
await channel.ExchangeDeclareAsync(
    exchange: "orders",
    durable: true,
    autoDelete: false,
    type: ExchangeType.Fanout);

// Create a queue for this consumer and bind it
await channel.QueueDeclareAsync(
    queue: "orders-consumer-1",
    durable: true,
    exclusive: false,
    autoDelete: false,
    arguments: null);

await channel.QueueBindAsync("orders-consumer-1", "orders", routingKey: string.Empty);

// Then consume messages from queueName as usual...
```

In the producer, we call `ExchangeDeclareAsync` to make sure an `orders` exchange exists (of type fanout).
We then `BasicPublishAsync` to that exchange.
For a fanout exchange, the `routingKey` can be an empty string because it's ignored (fanout sends to all queues regardless of any routing key).
On the consumer side, we declare the same exchange and then create a new `orders-consumer-1` queue.
We bind that queue to the `orders` exchange.
Now any message sent to the exchange will be delivered to this queue, and we can consume it.

If you run multiple consumer programs (each with its own queue bound to `orders` exchange),
each one will get every message (unlike the competing consumers scenario).
You can also peek into RabbitMQ's Management UI to see the exchange and queues in action.

<div className="centered">
  <Image
    src="blogs/mnw_140/rabbitmq_ui.png"
    width={818 * 0.75}
    height={889 * 0.75}
    alt="RabbitMQ Management UI"
  />
</div>

## Next Steps

You can expand this basic setup with more advanced RabbitMQ features.
For example, you might use a **direct exchange** or **topic exchange** to route events to specific services,
set up acknowledgment and retry policies for robustness,
or implement **dead-letter queues** for error handling.
The core idea throughout is the same: decouple senders and receivers with a message broker, making your system more flexible and resilient.

If you want to explore event-driven architecture further, including patterns like the ones we touched on (and beyond),
check out my [**Modular Monolith Architecture**](/modular-monolith-architecture) course.
It covers these concepts in depth with practical examples, so you can apply EDA in real-world projects.

Good luck out there, and see you next week.

---


Latest On YouTube

Let's connect

The .NET Weekly

Latest On YouTube

Let's connect