
<Sponsorships>

AI-assisted development often falters when agents operate in a vacuum,
blind to the unspoken rules and architectural nuances unique to a specific codebase.
By grounding AI agents in repo-aware dynamic context, [**Sonar's Context Augmentation**](https://fandf.co/480ZOcJ)
reduces iterative rework with first-pass precision, ensuring every AI-generated line
respects the architectural and security standards of your project.
[**Check it out**](https://fandf.co/480ZOcJ).

[**exe.dev**](https://fandf.co/4cMnV0c) reimagines cloud dev with instant persistent VMs
\- SSH in, build anything, deploy without touching infrastructure.
[**Learn more here**](https://fandf.co/4cMnV0c).

</Sponsorships>

I'll be honest. For years, my projects didn't look like the **test pyramid**.

A wide base of unit tests, a narrow middle of integration tests, a tiny sliver of end-to-end tests at the top.
I'd nod along in conference talks, then go back to my own code and do something different.

A thin layer of unit tests for the things worth unit-testing.
A thick slab of integration tests against real PostgreSQL, real RabbitMQ, real HTTP.
A handful of end-to-end tests for the flows that would get me fired if they broke.

And I shipped with more confidence that way, not less.
Here's why, and here's the shape I actually use.

## Where the Pyramid Comes From

The pyramid was popularized by Mike Cohn in 2009, when integration tests meant a shared database server, flaky CI, and 20-minute builds.
Unit tests with mocks were the pragmatic compromise.

<Image
  src="blogs/mnw_191/test_pyramid.png"
  width={2519}
  height={1153}
  alt="The classic test pyramid, with a wide base of unit tests, a narrow middle of integration tests, and a tiny sliver of end-to-end tests at the top."
/>

That world is gone.
With [**Testcontainers**](testcontainers-integration-testing-using-docker-in-dotnet), I can spin up PostgreSQL, Redis, and RabbitMQ in a fresh container per test class in a few seconds.
The [**Aspire test host**](https://learn.microsoft.com/en-us/dotnet/aspire/testing/overview) takes this further by wiring up your entire application graph.
The argument that real dependencies are too expensive mostly doesn't apply anymore.

But the advice didn't update.

## The Bug That Convinced Me

A few years ago I had a service with **94% unit test coverage**. All green.

A user reported that deleting an account didn't actually delete their data.
The bug was three lines long:

```csharp
public async Task Handle(DeleteAccountCommand command, CancellationToken ct)
{
    var account = await _repository.GetByIdAsync(command.AccountId, ct);
    account.MarkAsDeleted();
    // Missing: await _unitOfWork.SaveChangesAsync(ct);
}
```

The honest diagnosis is that the test for this case was never written.
You can absolutely verify `SaveChangesAsync` was called with a mock.
But in a codebase where that test is _one of hundreds_ of handler tests, each with its own mock setup and its own verification list, it's the kind of assertion people forget.
I forgot.

A single integration test against a real database would have caught it without anyone having to remember.
That's the point: the fewer invariants your test style forces you to remember, the fewer bugs slip through.

That was the last week I took the test pyramid seriously.

## What Unit Tests Are Actually Good At

I still write unit tests. Just not many.

They earn their keep when the logic is non-trivial, pure (no I/O, no time, no randomness), and hard to exercise end-to-end.
That's a specific set of code: [**value objects**](value-objects-in-dotnet-ddd-fundamentals) and [**rich domain models**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model), pricing and tax calculations, parsers, mappers, serializers.

Notice what's **not** on that list: application services, handlers, controllers, repositories, infrastructure.
Those live at the seams, and the seams are where real bugs live.

## What I Actually Write Instead

Here's the shape I've settled on for a typical .NET service or [**modular monolith**](what-is-a-modular-monolith).

### Layer 1: A thin base of unit tests

Maybe 15-25% of the test count. All domain logic.
No mocks of collaborators. If a unit test needs a mock, I usually pull the test up to the integration layer instead.

```csharp
[Fact]
public void Confirm_WhenPending_TransitionsToConfirmed()
{
    var order = Order.Create(CustomerId.New(), Money.Usd(100));

    order.Confirm();

    order.Status.Should().Be(OrderStatus.Confirmed);
    order.DomainEvents.Should().ContainSingle(e => e is OrderConfirmedEvent);
}
```

No container or mocks.
Microseconds per test.
This is what unit tests are for.

### Layer 2: A thick middle of integration tests

The majority. Maybe 60-70% of the suite.
Every [**command and query handler**](cqrs-pattern-with-mediatr), every HTTP endpoint, every message consumer gets a test that runs against **real infrastructure** inside Testcontainers.
In a [**modular monolith**](testing-modular-monoliths-system-integration-testing), this is where you verify that modules talk to each other correctly across their public APIs.

```csharp
public class DeleteAccountTests(IntegrationTestWebAppFactory factory)
    : BaseIntegrationTest(factory)
{
    [Fact]
    public async Task DeleteAccount_WhenAccountExists_MarksAccountAsDeleted()
    {
        var account = await CreateAccountAsync();

        var response = await HttpClient.DeleteAsync($"/accounts/{account.Id}");

        response.StatusCode.Should().Be(HttpStatusCode.NoContent);

        var stored = await DbContext.Accounts
            .IgnoreQueryFilters()
            .SingleAsync(a => a.Id == account.Id);

        stored.IsDeleted.Should().BeTrue();
    }
}
```

That test exercises the HTTP layer, routing, model binding, authorization, the handler, the unit of work, EF Core, and PostgreSQL.
It proves the thing you actually care about: **when I call this endpoint, the row changes.**
And it does it without anyone having to remember to assert `SaveChangesAsync` was called.

### Layer 3: A small cap of end-to-end tests

Under 10%. Only the flows where a silent failure would be a commercial or compliance problem.
Signup, payment, refund, password reset, [**two-factor enrollment**](how-to-implement-two-factor-authentication-in-aspnetcore).
They're slow and occasionally flaky, but they catch the one failure mode everything else misses: _the system as a whole still works_.

### Layer 0: Architecture and contract tests

Often forgotten, but they're part of the suite.
[**Architecture tests**](5-architecture-tests-you-should-add-to-your-dotnet-projects) enforce layering and module boundaries.
Contract tests verify that message schemas and API shapes don't drift.
They run in milliseconds and catch the "six months from now, someone will break this without realizing" kind of bug.

The shape that comes out of this is closer to Kent C. Dodds' **testing trophy** than a pyramid.
The fat middle is deliberate. That's where my confidence comes from.

## The Usual Objections

**"Integration tests are slow."**
My typical integration suite runs in 2-4 minutes in CI with Testcontainers reuse and test-class parallelization.
Slower than unit tests, yes. Faster than finding the bug in production.

**"Mocks are fine if you're disciplined."**
Maybe. But every large codebase I've audited that leaned heavily on mocks had the same pathology: tests that pass after a refactor even though the refactor broke production.
That's not discipline failing. That's the tool being pointed in the wrong direction.

## Summary

The test pyramid was good advice for 2009 infrastructure and poor advice for 2026 infrastructure.
Testcontainers and Aspire changed the economics, and the fastest feedback loop that still tells you the truth is now an integration test against real dependencies.
Unit tests still belong on pure domain logic. Everything at the seams belongs in the integration layer.

If you want to see how I wire this into a real system, with the [**integration test harness**](testing-modular-monoliths-system-integration-testing), module boundaries, and the full [**Clean Architecture**](/pragmatic-clean-architecture) setup, check out [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture).
It's the same approach I use on my own projects.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**AI Infrastructure**](https://fandf.co/4mAyU1q) That Lets Developers Build, Deploy, and Scale Without Friction.
Runpod removes cloud complexity so you can focus on shipping AI.
[**Start building with Runpod**](https://fandf.co/4mAyU1q).

JetBrains is conducting a survey to [**better understand how .NET dev tools impact developer productivity**](https://surveys.jetbrains.com/s3/NET-Tools-DX-Survey-NL18?utm_source=newsletter_newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=survey),
and your perspective could really help the company make its tooling even better.
[**Take the survey**](https://surveys.jetbrains.com/s3/NET-Tools-DX-Survey-NL18?utm_source=newsletter_newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=survey)
and get a chance to win a small prize.

</Sponsorships>

I'll be honest. I resisted primary constructors for a while.

When C# 12 extended them from `record` types to regular classes and structs, my first reaction was skepticism.
An implicit mutable capture instead of explicit `readonly` fields?
That felt like trading safety for convenience.

But after using them across several projects, I changed my mind.
The boilerplate they eliminate in DI service classes is significant, and the pitfall I was worried about is manageable once you know about it.

Here's what convinced me to switch, and the one thing you need to watch out for.

## What Changed My Mind

Here's what my service classes used to look like:

```csharp
public class OrderService
{
    private readonly IOrderRepository _orderRepository;
    private readonly ILogger<OrderService> _logger;

    public OrderService(
        IOrderRepository orderRepository,
        ILogger<OrderService> logger)
    {
        _orderRepository = orderRepository;
        _logger = logger;
    }

    public async Task<Order?> GetOrderAsync(Guid id)
    {
        _logger.LogInformation("Fetching order {OrderId}", id);

        return await _orderRepository.GetByIdAsync(id);
    }
}
```

And here's what they look like now:

```csharp
public class OrderService(
    IOrderRepository orderRepository,
    ILogger<OrderService> logger)
{
    public async Task<Order?> GetOrderAsync(Guid id)
    {
        logger.LogInformation("Fetching order {OrderId}", id);

        return await orderRepository.GetByIdAsync(id);
    }
}
```

The field declarations, the constructor body, the assignments. All gone.
The parameters are captured and available throughout the class body.

This is the most common use case for primary constructors: [**dependency injection**](improving-aspnetcore-dependency-injection-with-scrutor) in service classes.
You declare what you need, and use it directly.

## Where I Use Them Most: DI Service Classes

The place where primary constructors sold me is ASP.NET Core service classes.
This is where I spend most of my time, and the boilerplate savings add up fast.

Here's a more realistic example from a checkout flow:

```csharp
public class CheckoutService(
    IPaymentProcessor paymentProcessor,
    IOrderRepository orderRepository,
    ILogger<CheckoutService> logger,
    IOptions<CheckoutOptions> options)
{
    public async Task<CheckoutResult> ProcessAsync(
        Cart cart,
        CancellationToken ct = default)
    {
        var settings = options.Value;

        if (cart.Total < settings.MinimumOrderAmount)
        {
            logger.LogWarning("Order below minimum: {Total}", cart.Total);
            return CheckoutResult.BelowMinimum;
        }

        var order = Order.Create(cart);

        await paymentProcessor.ChargeAsync(order, ct);
        await orderRepository.SaveAsync(order, ct);

        logger.LogInformation("Checkout complete for order {OrderId}", order.Id);

        return CheckoutResult.Success;
    }
}
```

Four dependencies, zero boilerplate.
The class reads top-to-bottom without any noise.

This pattern works well because service classes typically don't need to validate or transform their dependencies.
The DI container provides them, and you use them.
Primary constructors are a perfect fit for this.

## Entity Construction (With a Caveat)

I also started using primary constructors for [**domain entities**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model) and [**value objects**](value-objects-in-dotnet-ddd-fundamentals) where you want to enforce required parameters at construction time:

```csharp
public class Order(Guid customerId, Money total)
{
    public Guid Id { get; } = Guid.NewGuid();
    public Guid CustomerId { get; } = customerId;
    public Money Total { get; } = total;
    public OrderStatus Status { get; private set; } = OrderStatus.Pending;
    public DateTime CreatedAt { get; } = DateTime.UtcNow;

    public void Confirm()
    {
        if (Status != OrderStatus.Pending)
        {
            throw new InvalidOperationException(
                $"Cannot confirm order in {Status} status.");
        }

        Status = OrderStatus.Confirmed;
    }
}
```

There's no way to create an `Order` without a `customerId` and `total`.
The primary constructor makes this constraint visible at the type declaration level.

Notice the key difference from the service class pattern: here, I'm assigning primary constructor parameters to **properties with initializers** (`= customerId`).
This is important, and it leads to the biggest pitfall.

## The Pitfall That Almost Stopped Me

This was the reason I held off for so long.

**Primary constructor parameters are not `readonly` fields.**

When you use a primary constructor parameter directly in the class body (like we did in the service class), the compiler captures it as a **mutable variable**.
There's no `readonly` backing field generated behind the scenes.

This means you can accidentally reassign a parameter:

```csharp
public class OrderService(
    IOrderRepository orderRepository,
    ILogger<OrderService> logger)
{
    public async Task<Order?> GetOrderAsync(Guid id)
    {
        logger.LogInformation("Fetching order {OrderId}", id);

        return await orderRepository.GetByIdAsync(id);
    }

    public void SomeOtherMethod()
    {
        // This compiles. No warning. No error.
        orderRepository = null!;
        logger = null!;
    }
}
```

This compiles without any warning.

With a traditional constructor and `private readonly` fields, the compiler would stop you immediately.
With primary constructors, it stays silent.

**If you need immutability guarantees**, explicitly assign the parameter to a `readonly` field:

```csharp
public class OrderService(
    IOrderRepository orderRepository,
    ILogger<OrderService> logger)
{
    private readonly IOrderRepository _orderRepository = orderRepository;
    private readonly ILogger<OrderService> _logger = logger;

    public async Task<Order?> GetOrderAsync(Guid id)
    {
        _logger.LogInformation("Fetching order {OrderId}", id);

        return await _orderRepository.GetByIdAsync(id);
    }
}
```

But now you've lost most of the benefit of primary constructors.
You're back to field declarations and assignments, just with a different syntax.

In practice, I've never actually hit this bug in a DI service class.
You're unlikely to accidentally reassign `logger` in the middle of a method.
But it **can** bite you in entity classes or value types where immutability actually matters.
That's the one place where I still stay cautious.

## Where I Still Use Traditional Constructors

I haven't switched everything over.
Here are the cases where I stick with the traditional approach:

**Complex validation logic.** If you need to validate parameters before assigning them, you need a constructor body:

```csharp
public class EmailAddress
{
    private readonly string _value;

    public EmailAddress(string value)
    {
        if (string.IsNullOrWhiteSpace(value) || !value.Contains('@'))
        {
            throw new ArgumentException(
                "Invalid email address.", nameof(value));
        }

        _value = value;
    }
}
```

Primary constructors don't give you a place to put validation logic before the class body runs.

**Multiple constructor overloads.** Primary constructors support one constructor signature.
If you need overloads, you'll have to chain secondary constructors with `this(...)`, which gets messy fast.

**Too many parameters.** Once you hit 5+ dependencies, the primary constructor line becomes hard to read.
At that point, your class probably has too many responsibilities, and [**refactoring**](5-awesome-csharp-refactoring-tips) it is a better solution than formatting tricks.

## Summary

Here's what I've settled on after using primary constructors across several projects:

- I use **primary constructors** for all my **DI service classes**. The boilerplate savings are worth it.
- They're useful for **entity construction** when you want to enforce required parameters at the type level.
- Primary constructor parameters are **captured as mutable variables**, not `readonly` fields. This is the one thing you need to know.
- I'm not afraid of the mutable capture pitfall in service classes, because it's unlikely to cause real bugs in that context.
- I stick with **traditional constructors** for validation-heavy types, multiple overloads, or classes with too many dependencies

The switch was worth it.
My service classes are shorter, easier to scan, and the pitfall is manageable with the right tooling.

That's all for today.
See you next week.

---



<Sponsorships>

AI workloads are unpredictable, which makes cloud commitments feel like a gamble.
[**Archera**](https://fandf.co/3PTpW3b) insures your commitments against underutilization,
so you can push coverage higher without the risk of getting stuck.
If usage drops, Archera covers the downside. Commitment Release Guarantee included.
[**Save with Archera**](https://fandf.co/3PTpW3b).

If you care about clean and maintainable .NET code, [**Pragmatic .NET Code Rules**](https://thecodeman.net/pragmatic-dotnet-code-rules)
is worth a look.
It's in presale and almost ready, with a focus on real-world practices.
[**Learn more**](https://thecodeman.net/pragmatic-dotnet-code-rules).

</Sponsorships>

Long-running business processes don't fit neatly into a single request.

Think about user onboarding: you register the user, send a verification email, wait for them to verify, and then send a welcome email.
Each step depends on the previous one.
If the user never verifies, you need a way to handle that.

The [**Saga pattern**](implementing-the-saga-pattern-with-masstransit) breaks this into a sequence of steps, each with its own message and handler.
If a step fails or times out, the saga runs [compensation logic](https://en.wikipedia.org/wiki/Compensating_transaction) instead of leaving the system in a broken state.

I've covered sagas with [**MassTransit**](implementing-the-saga-pattern-with-masstransit) and [**Rebus**](implementing-the-saga-pattern-with-rebus-and-rabbitmq) before.
Both work well, but their [state machine](https://en.wikipedia.org/wiki/Finite-state_machine) DSLs come with a fair amount of ceremony.
Since [MassTransit moved to a commercial license](mediatr-and-masstransit-going-commercial-what-this-means-for-you), more teams have been exploring Wolverine as an alternative.

[**Wolverine**](https://wolverinefx.net/) takes a [different approach](https://wolverinefx.net/guide/durability/sagas) - you write a class that extends `Saga`, define `Handle` methods for each message type, and [cascade new messages](https://wolverinefx.net/guide/handlers/cascading) from return values.
Wolverine handles routing, persistence, and correlation automatically.

## Configuring Wolverine

We need [**RabbitMQ**](event-driven-architecture-in-dotnet-with-rabbitmq) for message transport and [PostgreSQL](https://www.postgresql.org/) for durable saga state and messaging.

```csharp
var connectionString = builder.Configuration.GetConnectionString("user-mgmt");

builder.Host.UseWolverine(options =>
{
    options.UseRabbitMqUsingNamedConnection("rmq")
        .AutoProvision()
        .UseConventionalRouting();

    options.Policies.DisableConventionalLocalRouting();

    options.PersistMessagesWithPostgresql(connectionString!);
});
```

- `AutoProvision` creates RabbitMQ exchanges and queues automatically
- `UseConventionalRouting` routes messages to queues based on message type names
- `DisableConventionalLocalRouting` forces all messages through RabbitMQ instead of in-process handling
- [`PersistMessagesWithPostgresql`](https://wolverinefx.net/guide/durability/postgresql) stores saga state and messages in PostgreSQL. Wolverine uses [**lightweight saga storage**](https://wolverinefx.net/guide/durability/sagas#lightweight-saga-storage) to create a table per saga type, and the [**durable messaging**](https://wolverinefx.net/guide/durability/) infrastructure ensures nothing is lost if the process crashes

Wolverine gives you **three ways to persist saga state**.
[**Lightweight storage**](https://wolverinefx.net/guide/durability/sagas#lightweight-saga-storage) (what we're using) serializes saga state as JSON in a per-saga table with zero ORM config.
[**Marten**](https://wolverinefx.net/guide/durability/marten/sagas) stores sagas as [Marten](https://martendb.io/) documents with [optimistic concurrency](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) and strong-typed IDs.
[**EF Core**](https://wolverinefx.net/guide/durability/efcore/sagas) maps sagas into a flat, queryable table and lets you commit saga state with other data in a single transaction.
If you just need saga state management, lightweight storage is the simplest path.

Required packages:

```xml
<PackageReference Include="WolverineFx" Version="5.16.2" />
<PackageReference Include="WolverineFx.Postgresql" Version="5.16.2" />
<PackageReference Include="WolverineFx.RabbitMQ" Version="5.16.2" />
```

## The Saga Messages

Before building the saga, let's define all the messages it will work with:

```csharp
public record SendVerificationEmail(Guid UserId, string Email);
public record VerificationEmailSent(Guid Id);

public record VerifyUserEmail(Guid Id);

public record SendWelcomeEmail(Guid UserId, string Email, string FirstName);
public record WelcomeEmailSent(Guid Id);

public record OnboardingTimedOut(Guid Id) : TimeoutMessage(5.Minutes());
```

`OnboardingTimedOut` extends Wolverine's [`TimeoutMessage`](https://wolverinefx.net/guide/durability/sagas#timeout-messages), which automatically schedules a delayed delivery.
When the saga starts, Wolverine will deliver this message after 5 minutes.
If the user hasn't verified by then, the saga compensates.

## The Saga State Diagram

Here's how the saga transitions between states:

<div className="centered">
  <Image
    src="blogs/mnw_189/saga_pattern_state_diagram.png"
    width={966 * 0.5}
    height={1160 * 0.5}
    alt="Saga pattern state diagram showing message flow from broker to consumer to database and processor."
  />
</div>

## Building the Saga

Here's the complete saga class:

```csharp
public class UserOnboardingSaga : Saga
{
    public Guid Id { get; set; }
    public string Email { get; set; } = string.Empty;
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
    public bool IsVerificationEmailSent { get; set; }
    public bool IsEmailVerified { get; set; }
    public bool IsWelcomeEmailSent { get; set; }
    public DateTime StartedAt { get; set; }

    // Step 1: Start the saga when UserRegistered is published
    public static (
        UserOnboardingSaga,
        SendVerificationEmail,
        OnboardingTimedOut) Start(
            UserRegistered @event,
            ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation(
            "Starting onboarding for user {UserId}", @event.Id);

        var saga = new UserOnboardingSaga
        {
            Id = @event.Id,
            Email = @event.Email,
            FirstName = @event.FirstName,
            LastName = @event.LastName,
        };

        return (
            saga,
            new SendVerificationEmail(saga.Id, saga.Email),
            new OnboardingTimedOut(saga.Id));
    }

    // Step 2: Verification email was sent
    public void Handle(
        VerificationEmailSent @event,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation(
            "Verification email sent for user {UserId}", Id);

        IsVerificationEmailSent = true;
    }

    // Step 3: User verified their email
    public SendWelcomeEmail Handle(
        VerifyUserEmail command,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation("Email verified for user {UserId}", Id);

        IsEmailVerified = true;

        return new SendWelcomeEmail(Id, Email, FirstName);
    }

    // Step 4: Welcome email sent - onboarding complete
    public void Handle(
        WelcomeEmailSent @event,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation("Onboarding complete for user {UserId}", Id);

        IsWelcomeEmailSent = true;

        MarkCompleted();
    }

    // Compensation: timeout handler
    public void Handle(
        OnboardingTimedOut timeout,
        ILogger<UserOnboardingSaga> logger)
    {
        if (IsEmailVerified)
        {
            logger.LogInformation(
                "Timeout ignored - email already verified for user {UserId}",
                Id);
            return;
        }

        logger.LogWarning(
            "Onboarding timed out for user {UserId} - email not verified",
            Id);

        MarkCompleted();
    }

    // NotFound: messages arriving for completed/deleted sagas
    public static void NotFound(
        VerifyUserEmail command,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogWarning(
            "Verify email received but saga {Id} no longer exists",
            command.Id);
    }

    public static void NotFound(
        OnboardingTimedOut timeout,
        ILogger<UserOnboardingSaga> logger)
    {
        logger.LogInformation(
            "Timeout received for already-completed saga {Id}",
            timeout.Id);
    }
}
```

A few things worth calling out.

**Starting the saga.** `Start` is a static factory that returns a tuple: the saga instance, a `SendVerificationEmail` command, and a [scheduled](https://wolverinefx.net/guide/messaging/message-bus#scheduling-message-delivery-or-execution) `OnboardingTimedOut` message. Wolverine persists the saga and delivers the messages for you.

**Handling messages.** Wolverine [**correlates messages**](https://wolverinefx.net/guide/durability/sagas#saga-message-identity) to the correct saga instance by looking for a `[SagaIdentity]` attribute, then `{SagaTypeName}Id`, then `Id`. Return `void` to update state silently, or return a message to cascade a new command.

> **Warning:** Do not call `IMessageBus.InvokeAsync()` within a saga handler to execute a command on that same saga. You'll be acting on stale or missing data. Use cascading messages (return values) for subsequent work.

**Completing the saga.** `MarkCompleted()` tells Wolverine to delete the saga state from PostgreSQL.

**Concurrency.** Wolverine applies [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) to saga state by default. If two messages for the same saga arrive at the same time, one succeeds and the other retries automatically.

**Timeout and compensation.** `OnboardingTimedOut` fires 5 minutes after the saga started. If the user verified, we ignore it. Otherwise, we compensate and end the saga. This is the key advantage over fire-and-forget workflows.

**NotFound handlers.** Static [`NotFound` methods](https://wolverinefx.net/guide/durability/sagas#when-sagas-are-not-found) handle messages for sagas that no longer exist. You **must** have one for any message type that could arrive after the saga is deleted. The timeout `NotFound` handler matters most: in the happy path, the saga completes before the timeout fires.

## The Sequence Flow

Here's the happy path where the user verifies before the timeout:

<Image
  src="blogs/mnw_189/saga_pattern_sequence_diagram.png"
  width={2243}
  height={1930}
  alt="Saga pattern sequence diagram showing message flow from broker to consumer to database and processor."
/>

If the user never verifies, the `VerifyUserEmail` message never arrives.
After 5 minutes, `OnboardingTimedOut` fires and the saga compensates.

## Summary

Wolverine's `Saga` base class gives you a convention-driven way to implement long-running workflows:

- **`Start` methods** create and initialize the saga from a triggering event
- **`Handle` methods** process messages and cascade new commands via return values
- **`TimeoutMessage`** schedules delayed compensation without external schedulers
- **`MarkCompleted()`** cleans up the saga state when the workflow is done
- **`NotFound` handlers** gracefully handle messages for sagas that no longer exist

The Saga pattern shines when you have multi-step processes with potential failures.
Instead of hoping everything goes right, you design for the cases where it doesn't.

What I really like about Wolverine's approach is how little code you need.
You skip the state machine DSL and explicit correlation config entirely.

If you want to go deeper on orchestrating distributed workflows and building real-world sagas,
check out [**Modular Monolith Architecture**](/modular-monolith-architecture).

Hope this was useful. See you next week.

---



<Sponsorships>

The new ReSharper extension brings 20 years of C# expertise to VS Code and Cursor.
[**Try it today**](https://www.jetbrains.com/resharper/?product=vsc?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper)
and [**start shipping production-ready code with confidence**](https://www.jetbrains.com/resharper/?product=vsc?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper)!

[**Add Working AI UI Without Starting From Scratch**](https://www.telerik.com/ai-components?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=ai_components_awareness)\
Speed up the development of AI apps and start building AI UI.
Implement smart featured components into your apps and projects right away by
starting a free trial for the component library of your choice.
[**Try now**](https://www.telerik.com/ai-components?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=ai_components_awareness)!

</Sponsorships>

The [**Outbox pattern**](implementing-the-outbox-pattern) gets a lot of attention, and rightly so.
But what about the consumer side?

Your publisher reliably sends a message.
The broker delivers it.
Your consumer processes it.
Then something goes wrong. A timeout, a crash, a network blip.
The broker **redelivers the same message**.
Your consumer runs the same logic twice.
This is a problem.

The **Inbox pattern** is the counterpart to the Outbox.
The Outbox ensures reliable _publishing_. The Inbox ensures reliable _consumption_.
Each incoming message is processed **exactly once**, even when the broker retries.

Here's how to implement it.

## Why You Need an Inbox

Most message brokers provide **at-least-once delivery**.
The broker guarantees every message will be delivered,
but it **doesn't** guarantee each message arrives only once.

Here's a common failure path:

1. The broker delivers a message to your consumer
2. Your consumer processes it successfully
3. Before the ACK reaches the broker, the connection drops
4. The broker assumes the message was lost and redelivers it
5. Your consumer processes the same message **twice**

You could make each handler [**idempotent**](the-idempotent-consumer-pattern-in-dotnet-and-why-you-need-it).
That works, but it means every consumer needs to check a deduplication table before doing any work.
The Inbox centralizes this into a single mechanism at the infrastructure level.
I will talk more about the trade-offs between the Inbox and the Idempotent Consumer at the end.

The idea:

1. A message arrives from the broker
2. Instead of processing it immediately, **write it to an inbox table**
3. If the message already exists (duplicate), the write is silently ignored
4. A [**background process**](running-background-tasks-in-asp-net-core) reads unprocessed messages and handles them

This decouples reception from processing.
The consumer becomes a thin persistence layer that can't produce duplicates.

<Image
  src="blogs/mnw_188/inbox_pattern_sequence_diagram.png"
  width={2633}
  height={2176}
  alt="Inbox pattern sequence diagram showing message flow from broker to consumer to database and processor."
/>

## Inbox Database Schema

The `inbox_messages` table stores every incoming message:

```sql
CREATE TABLE IF NOT EXISTS inbox_messages (
    id UUID PRIMARY KEY,
    type VARCHAR(255) NOT NULL,
    content JSONB NOT NULL,
    received_on_utc TIMESTAMP WITH TIME ZONE NOT NULL,
    processed_on_utc TIMESTAMP WITH TIME ZONE NULL,
    error TEXT NULL
);

CREATE INDEX IF NOT EXISTS idx_inbox_messages_unprocessed
ON public.inbox_messages (received_on_utc, processed_on_utc)
INCLUDE (id, type, content)
WHERE processed_on_utc IS NULL;
```

The structure mirrors the [**Outbox pattern's**](implementing-the-outbox-pattern) `outbox_messages` table.
The `id` enables idempotent inserts via `ON CONFLICT DO NOTHING`.
The filtered index keeps the index small since processed messages drop out automatically.

Messages between services use a shared `IntegrationEvent` base record:

```csharp
public abstract record IntegrationEvent(Guid MessageId);

public sealed record OrderCreatedIntegrationEvent(Guid OrderId)
    : IntegrationEvent(Guid.CreateVersion7());
```

## Inbox Consumer

The consumer is a [**MassTransit**](using-masstransit-with-rabbitmq-and-azure-service-bus) `IConsumer<T>`.
Instead of processing the message, it **writes it to the inbox table** and returns.
That's it.

We can make this generic so it works for any integration event:

```csharp
internal sealed class InboxConsumer<T>(NpgsqlDataSource dataSource)
    : IConsumer<T> where T : IntegrationEvent
{
    public async Task Consume(ConsumeContext<T> context)
    {
        await using var connection = await dataSource.OpenConnectionAsync(
            context.CancellationToken);

        const string sql =
            @"""
            INSERT INTO public.inbox_messages (id, type, content, received_on_utc)
            VALUES (@Id, @Type, @Content::jsonb, @ReceivedOnUtc)
            ON CONFLICT (id) DO NOTHING;
            """;

        await connection.ExecuteAsync(sql, new
        {
            Id = context.Message.MessageId,
            Type = typeof(T).FullName,
            Content = JsonSerializer.Serialize(context.Message),
            ReceivedOnUtc = DateTime.UtcNow
        });
    }
}
```

`ON CONFLICT (id) DO NOTHING` is doing the heavy lifting.
If the broker delivers the same message twice, the second insert is silently ignored.
Crash after insert but before ACK? The next delivery is safely deduplicated.

## Inbox Processor

The processor runs in a [**background service**](running-background-tasks-in-asp-net-core)
or a [**scheduled job**](scheduling-background-jobs-with-quartz-net),
fetching unprocessed messages in batches and dispatching them for handling.

```csharp
internal sealed class InboxProcessor(
    NpgsqlDataSource dataSource,
    IEventDispatcher eventDispatcher,
    ILogger<InboxProcessor> logger)
{
    private const int BatchSize = 1000;

    public async Task<int> Execute(CancellationToken cancellationToken = default)
    {
        await using var connection =
            await dataSource.OpenConnectionAsync(cancellationToken);
        await using var transaction =
            await connection.BeginTransactionAsync(cancellationToken);

        var messages = (await connection.QueryAsync<InboxMessage>(
            @"""
            SELECT id AS Id, type AS Type, content AS Content
            FROM inbox_messages
            WHERE processed_on_utc IS NULL
            ORDER BY received_on_utc
            LIMIT @BatchSize
            FOR UPDATE SKIP LOCKED
            """,
            new { BatchSize },
            transaction: transaction)).AsList();

        var processedAt = DateTime.UtcNow;
        var results = new List<(Guid Id, DateTime ProcessedAt, string? Error)>(
            messages.Count);

        foreach (var message in messages)
        {
            try
            {
                var messageType = Type.GetType(message.Type)!;
                var deserialized = JsonSerializer.Deserialize(
                    message.Content, messageType)!;

                await eventDispatcher.DispatchAsync(deserialized, cancellationToken);

                results.Add((message.Id, processedAt, null));
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Failed to process inbox message {Id}", message.Id);
                results.Add((message.Id, processedAt, ex.ToString()));
            }
        }

        if (results.Count > 0)
        {
            await connection.ExecuteAsync(
                @"""
                UPDATE inbox_messages
                SET processed_on_utc = v.processed_on_utc,
                    error = v.error
                FROM UNNEST(@Ids, @ProcessedAts, @Errors)
                    AS v(id, processed_on_utc, error)
                WHERE inbox_messages.id = v.id
                """,
                new
                {
                    Ids = results.Select(r => r.Id).ToArray(),
                    ProcessedAts = results.Select(r => r.ProcessedAt).ToArray(),
                    Errors = results.Select(r => r.Error).ToArray()
                },
                transaction: transaction);
        }

        await transaction.CommitAsync(cancellationToken);

        return messages.Count;
    }
}
```

- **`FOR UPDATE SKIP LOCKED`** lets multiple processor instances run concurrently
  without contention. I covered this in [**scaling the Outbox pattern**](scaling-the-outbox-pattern).
- **Batch update with `UNNEST`** writes all results in a single round-trip
  using the same [**bulk update approach**](optimizing-bulk-database-updates-in-dotnet).
- **Error capture**: failed messages get marked with the exception so they don't block the queue.

If the process crashes mid-batch, the transaction rolls back
and messages get picked up on the next run.

## Things to Watch Out For

**Table growth.**
The inbox table grows indefinitely.
Delete processed messages after a retention period,
or partition by time range and drop old partitions.
You can also archive them to another table if you need to keep a history.

**Poison messages.**
If a message consistently fails, it gets marked with an error each time.
Consider a max retry count. After N failures, dead-letter it and alert.

**Ordering.**
`ORDER BY received_on_utc` gives you rough arrival-time ordering.
But with `SKIP LOCKED` and multiple processors, strict ordering is **not** guaranteed.
If you need [**per-aggregate ordering**](solving-message-ordering-from-first-principles),
you'll need additional coordination.

**Monitoring.**
Track the lag between `received_on_utc` and `processed_on_utc`.
If this gap grows, increase the batch size, decrease the polling interval,
or scale out more processor instances.

## Inbox vs. Idempotent Consumer

Both the Inbox and the [**Idempotent Consumer**](idempotent-consumer-handling-duplicate-messages) prevent duplicate processing.
The difference is _when_ processing happens and _who controls_ retries.

The [**Idempotent Consumer**](the-idempotent-consumer-pattern-in-dotnet-and-why-you-need-it) processes messages inline.
It checks a deduplication table, does the work, and records the dedup entry in the same transaction.
If processing fails, the transaction rolls back, no dedup record is written,
and the **broker** redelivers the message on its own schedule.
You don't control retry timing or backoff.

The Inbox separates reception from processing.
The consumer writes the message and ACKs immediately. The broker is done.
If the processor fails, it records the error and moves on.
Retries are your responsibility: reset `processed_on_utc` to `NULL` for messages under a retry threshold,
or run a separate loop that picks up failed messages after a delay.

Use the **Idempotent Consumer** when your side effects are transactional
and broker-managed retries are good enough.
Use the **Inbox** when you need batching, custom retry policies,
or horizontal scaling via `FOR UPDATE SKIP LOCKED`.

## Summary

The Inbox pattern is the consumer-side counterpart to the [**Outbox pattern**](implementing-the-outbox-pattern).

- **`ON CONFLICT DO NOTHING`** makes consumer inserts idempotent
- **Separation of reception and processing** gives you independent retry control
- **`FOR UPDATE SKIP LOCKED`** enables horizontal scaling of the processor
- **Batch updates with `UNNEST`** minimize database round-trips

If you want to see how I build [**event-driven systems**](event-driven-architecture-in-dotnet-with-rabbitmq) with these patterns,
check out [**Modular Monolith Architecture**](/modular-monolith-architecture).

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**Azure Copilot Migration Agent is Here, from Microsoft Azure**](https://fandf.co/4b8ukDv)\
The new Microsoft Azure Copilot Migration Agent turns complex migration data into clear answers.
Through natural language prompts, you can evaluate readiness, risk, ROI,
and automate landing zone requirements to make confident decisions.
It streamlines planning and analysis, so migrations are better scoped, better justified,
and far less error-prone.
[**Download the playbook to get started**](https://fandf.co/4b8ukDv).


[**Report: 84% of teams use AI. Only 21% have efficient workflows**](https://www.telerik.com/ai-design-development-workflows-report-2025?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_design_development_report_2026).
AI is speeding teams up—but not always making them better.
This report reveals what's working, what's breaking,
and how teams are scaling AI across design and development—plus what to focus on next in 2026.
[**Explore the report here**](https://www.telerik.com/ai-design-development-workflows-report-2025?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_design_development_report_2026).

</Sponsorships>

Not every AI feature needs a dedicated vector database.

Dedicated vector databases like [Pinecone](https://www.pinecone.io/), [Qdrant](https://qdrant.tech/), and [Weaviate](https://weaviate.io/) get all the attention.
But if your data already lives in PostgreSQL, you don't need another moving part.

[pgvector](https://github.com/pgvector/pgvector) is a PostgreSQL extension that adds vector storage and similarity search directly to your existing database.
You enable the extension, create a vector column, and start querying.

In this week's issue, I'll walk you through:

- What [**vector search**](what-is-vector-search-a-concise-guide) is and when you need it
- Provisioning pgvector with .NET Aspire and Ollama
- Generating embeddings with [**MEAI**](working-with-llms-in-dotnet-using-microsoft-extensions-ai) and storing with Dapper
- Querying by semantic similarity using cosine distance

Let's dive in.

## What Is Vector Search?

Traditional database queries work with exact matches.
You search for `"authentication"` and get rows containing that exact word.
But what about rows that mention `"login"`, `"sign-in"`, or `"identity verification"`?
Those are semantically similar, but a `LIKE` query won't find them.

[**Vector search**](what-is-vector-search-a-concise-guide) solves this by comparing **meaning** instead of text.

You convert text into an array of numbers (called an **embedding**) using a machine learning model.
Semantically similar text produces similar arrays.
Then, instead of matching keywords, you find the vectors that are **closest** to your query vector.

When would you use this?

- **Semantic search** - Find results by meaning, not just keywords
- **RAG (Retrieval-Augmented Generation)** - Feed relevant context to an LLM
- **Recommendations** - "Users who liked X also liked Y"
- **Deduplication** - Find near-duplicate content

The key insight is that you don't need a specialized database for this.
If you're already on PostgreSQL, pgvector gives you all of this as an extension.

## Provisioning Infrastructure With .NET Aspire

We'll use [**.NET Aspire**](dotnet-aspire-a-game-changer-for-cloud-native-development)
to provision a pgvector-enabled PostgreSQL container and an [**Ollama**](how-to-extract-structured-data-from-images-using-ollama-in-dotnet)
instance with the [qwen3-embedding](https://ollama.com/library/qwen3-embedding) embedding model.

```csharp {8,13}
var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddOllama("ollama")
    .WithLifetime(ContainerLifetime.Persistent)
    .WithDataVolume()
    .WithGPUSupport();

var embeddingModel = ollama.AddModel("qwen3-embedding:0.6b");

var postgres = builder.AddPostgres("postgres", port: 6432)
    .WithLifetime(ContainerLifetime.Persistent)
    .WithDataVolume()
    .WithImage("pgvector/pgvector", "pg17")
    .AddDatabase("articles");

builder.AddProject<Projects.PgVector_Articles>("pgvector-articles")
    .WithReference(embeddingModel)
    .WithReference(postgres)
    .WaitFor(embeddingModel)
    .WaitFor(postgres);

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

The `pgvector/pgvector:pg17` image is PostgreSQL 17 with the pgvector extension pre-installed.
`WithLifetime(ContainerLifetime.Persistent)` keeps the containers running across app restarts so you don't lose data during development.
`WaitFor` ensures the database and model are ready before the API starts.

If you're not using Aspire, you can run the same `pgvector/pgvector:pg17` image via `docker compose` and point to it with a regular connection string.

## Configuring the API Project

The API project needs a few packages:

```bash
dotnet add package Aspire.Npgsql
dotnet add package Pgvector.Dapper
dotnet add package CommunityToolkit.Aspire.OllamaSharp
```

`Pgvector.Dapper` provides the Dapper type handler for the `Vector` type.
Other than [Pgvector.Dapper](https://github.com/pgvector/pgvector-dotnet/tree/master/src/Pgvector.Dapper), there are also libraries for [Npgsql](https://github.com/pgvector/pgvector-dotnet/tree/master/src/Pgvector) and [EF Core](https://github.com/pgvector/pgvector-dotnet/tree/master/src/Pgvector.EntityFrameworkCore) if you prefer those instead.

Register the services in `Program.cs`:

```csharp
builder.AddOllamaApiClient("ollama-qwen3-embedding")
    .AddEmbeddingGenerator();

builder.AddNpgsqlDataSource("articles", configureDataSourceBuilder: b =>
{
    b.UseVector();
});

SqlMapper.AddTypeHandler(new VectorTypeHandler());
```

`AddEmbeddingGenerator()` registers an `IEmbeddingGenerator<string, Embedding<float>>` using the [`Microsoft.Extensions.AI`](working-with-llms-in-dotnet-using-microsoft-extensions-ai) abstraction.
`UseVector()` enables pgvector type mapping on the Npgsql data source.
The `VectorTypeHandler` lets Dapper serialize and deserialize `Vector` parameters.

## Initializing the Database

Before storing vectors, we need to enable the pgvector extension and create a table.

```csharp
app.MapPost("/init", async (NpgsqlDataSource dataSource) =>
{
    await using var conn = await dataSource.OpenConnectionAsync();

    await using var enableExt = new NpgsqlCommand(
        "CREATE EXTENSION IF NOT EXISTS vector", conn);
    await enableExt.ExecuteNonQueryAsync();

    conn.ReloadTypes();

    await conn.ExecuteAsync(
        """
        CREATE TABLE IF NOT EXISTS articles (
            id SERIAL PRIMARY KEY,
            url TEXT NOT NULL,
            title TEXT NOT NULL,
            embedding vector(1024) NOT NULL
        )
        """);

    await conn.ExecuteAsync(
        """
        CREATE INDEX IF NOT EXISTS articles_embedding_idx
        ON articles USING hnsw (embedding vector_cosine_ops)
        """);

    return Results.Ok("Database initialized.");
});
```

A few things to note:

- `CREATE EXTENSION IF NOT EXISTS vector` enables pgvector in the database
- `embedding vector(1024)` defines a vector column with 1024 dimensions, matching the Ollama embedding model's output (`qwen3-embedding:0.6b`)
- `conn.ReloadTypes()` refreshes Npgsql's type cache so it recognizes the new `vector` type
- The **HNSW index** with `vector_cosine_ops` enables fast approximate nearest-neighbor search using cosine distance.

 [HNSW](https://en.wikipedia.org/wiki/Hierarchical_navigable_small_world) (Hierarchical Navigable Small World) is a graph-based algorithm that builds a multi-layer structure for efficient similarity lookups.

Without the index, pgvector does a sequential scan over every row.
That's fine for hundreds of rows, but HNSW keeps queries fast as the dataset grows.

## Generating and Storing Embeddings

Now we generate embeddings for our content and store them alongside the data.

```csharp
app.MapPost("/embeddings/generate", async (
    BlogService blogService,
    IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator,
    NpgsqlDataSource dataSource,
    ILogger<Program> logger) =>
{
    await using var conn = await dataSource.OpenConnectionAsync();
    conn.ReloadTypes();

    int count = 0;

    foreach (var articleUrl in File.ReadAllLines("sitemap_urls.txt"))
    {
        var (title, content) = await blogService.GetTitleAndContentAsync(articleUrl);

        var embedding = await embeddingGenerator.GenerateAsync(content);

        await conn.ExecuteAsync(
            "INSERT INTO articles (url, title, embedding) VALUES (@url, @title, @embedding)",
            new
            {
                url = articleUrl,
                title,
                embedding = new Vector(embedding.Vector.ToArray())
            });

        count++;
        logger.LogInformation("Processed ({Count}): {Url}", count, articleUrl);
    }

    return Results.Ok(new { processed = count });
});
```

`embeddingGenerator.GenerateAsync(content)` sends the text to the Ollama model and returns a vector.
We wrap it in a `Pgvector.Vector` and Dapper handles the rest.

The `IEmbeddingGenerator` is provider-agnostic.
If you want to swap Ollama for OpenAI or Azure OpenAI later, only the registration in `Program.cs` changes.
Your endpoint code stays the same.

## Similarity Search With Cosine Distance

This is where it gets interesting.
To search, we embed the query text and find the closest vectors in the database.

```csharp
app.MapGet("/search", async (
    string query,
    IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator,
    NpgsqlDataSource dataSource,
    int limit = 5) =>
{
    var searchEmbedding = await embeddingGenerator.GenerateAsync(query);

    await using var con = await dataSource.OpenConnectionAsync();
    con.ReloadTypes();

    var embedding = new Vector(searchEmbedding.Vector.ToArray());

    var results = await con.QueryAsync<SearchResult>(
        @"""
        SELECT title, url, embedding <=> @embedding as distance
        FROM articles
        ORDER BY embedding <=> @embedding
        LIMIT @limit
        """,
        new { embedding, limit });

    return Results.Ok(new { query, results });
});

record SearchResult(string Title, string Url, double Distance);
```

The `<=>` operator is pgvector's **cosine distance** function, where lower values mean more similar.
We order by distance ascending and take the top N matches.

The critical part: the query text must be embedded with the **same model** that produced the stored embeddings.
Different models produce vectors in different embedding spaces, and comparing them would be meaningless.

There are also shared embedding spaces models that can embed text and images into compatible vectors, but that's a more advanced topic.
One example is the [Voyage 4 model family](https://blog.voyageai.com/2026/01/15/voyage-4/).

A query like `"how to secure an API"` will surface articles about authentication, JWT validation, and authorization, even if they don't contain those exact words.

pgvector supports three distance operators:

- `<->` - L2 (Euclidean) distance, uses `vector_l2_ops`
- `<=>` - Cosine distance, uses `vector_cosine_ops`
- `<#>` - Inner product (negative), uses `vector_ip_ops`

Cosine distance is the most common choice for text embeddings.

## Summary

You don't need a dedicated vector database to add semantic search to your application.
If you're already running PostgreSQL, pgvector gives you vector storage and similarity search without adding new infrastructure.

Here's what we covered:

- **pgvector** is a PostgreSQL extension - enable it and you get a native `vector` column type
- **.NET Aspire** provisions pgvector-enabled PostgreSQL and Ollama with minimal configuration
- **Embeddings** turn text into vectors using models like `qwen3-embedding` via `IEmbeddingGenerator`
- **Similarity search** uses the cosine distance operator (`<=>`) to find the closest matches
- **HNSW indexes** make vector queries fast at scale

Your vectors live right next to your relational data, so you can join, filter, and paginate just like any other query without syncing between databases or managing extra infrastructure.

If you want to explore more advanced scenarios like [**building semantic search with S3 Vectors and Semantic Kernel**](building-semantic-search-with-amazon-s3-vectors-and-semantic-kernel), I've covered that in a previous article.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

Get design and reference implementation for secure deployment of AI agents on infrastructure.
[**Teleport's Agentic Identity Framework**](https://fandf.co/4lgKsWT) provides standards-based,
opinionated designs so teams can ship confidently.
[**Check it out**](https://fandf.co/4lgKsWT).

Don't gamble with AI Agents.
[**Coder Workspace**](https://fandf.co/4kTUexX) provides a secure, self-hosted environment, so you can leverage AI safely, collaborate effectively, and stay in control.
[**Learn more**](https://fandf.co/4kTUexX).

</Sponsorships>

I ran into this one the hard way.

I built a [**real-time notification feature with SignalR**](adding-real-time-functionality-to-dotnet-applications-with-signalr), tested it locally, everything worked great.
Then I scaled to two instances behind a load balancer, and notifications started disappearing for some users.

The code was fine.
The problem was that **SignalR connections are bound to the server process that accepted them**.
Each instance only knows about its own connections.
So when an API request lands on Server 1 but the user is connected to Server 2, the notification just... doesn't get delivered.

This is the SignalR scale-out problem, and it bites almost everyone who goes from one instance to more.

## Why SignalR Breaks When You Scale Out

With a single instance, everything just works.

<Image
  src="blogs/mnw_186/signalr_single_server.png"
  width={1690}
  height={899}
  alt="SignalR single server deployment showing all clients connected to the same server."
/>

The server holds the full map of who's connected, so sending a message to a user, a group, or all clients works because that map is complete.

But scale out to two or more instances, and that map fractures.

<Image
  src="blogs/mnw_186/signalr_multi_server.png"
  width={1590}
  height={1230}
  alt="SignalR multi-server deployment showing clients connected to different servers."
/>

Server 1 has no idea Client 3 or Client 4 even exist.
So when an order status change happens on Server 1 and needs to reach Client 3, Server 1 checks its connection map, finds nothing, and the message is quietly dropped.

## The Backplane Pattern

The fix is a **backplane** - a shared messaging layer that sits between all your server instances.

Every server publishes outgoing messages to a central channel, and every server subscribes to that same channel.
When a message comes in, each server checks if any of its local connections should receive it.

<Image
  src="blogs/mnw_186/signalr_backplane.png"
  width={2754}
  height={1230}
  alt="SignalR backplane deployment showing clients connected to different servers."
/>

When Server 1 wants to notify Client 3:

1. Server 1 publishes the message to the backplane
2. All servers receive the message
3. Server 2 recognizes Client 3 as one of its connections and delivers the notification

From your code's perspective, it looks like every server can see every connection.
Redis works really well for this because its [**Pub/Sub**](simple-messaging-in-dotnet-with-redis-pubsub) delivers messages to all subscribers in near real-time.
And if you're already using Redis for [**distributed caching**](caching-in-aspnetcore-improving-application-performance), you don't even need to spin up anything new.

## Setting It Up

Let me walk through how I set this up in an order notification system.
Clients connect to a SignalR hub, authenticate via JWT, and get real-time status updates when an order changes.

### Install the NuGet Package

```bash
dotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis
```

### Register the Backplane

Chain `.AddStackExchangeRedis()` onto your `AddSignalR()` call:

```csharp
builder.Services.AddSignalR()
    .AddStackExchangeRedis(builder.Configuration.GetConnectionString("cache")!);
```

If you're running with [**.NET Aspire**](dotnet-aspire-a-game-changer-for-cloud-native-development),
you will have the Redis connection string registered via environment variables, so you can just pull it from configuration.
Reference the same named connection:

```csharp
builder.AddRedisDistributedCache("cache");

builder.Services.AddSignalR()
    .AddStackExchangeRedis(builder.Configuration.GetConnectionString("cache")!);
```

If you have multiple SignalR apps sharing the same Redis instance, you'll want to add a channel prefix.
Otherwise, messages from one app will reach subscribers in every app on that Redis server.

```csharp
builder.Services.AddSignalR()
    .AddStackExchangeRedis(connectionString, options =>
    {
        options.Configuration.ChannelPrefix = RedisChannel.Literal("OrderNotifications");
    });
```

The nice thing is that your `IHubContext<>` call site doesn't change at all.
`Clients.User(...)` works the same whether you have one instance or ten - the backplane handles routing behind the scenes.

When I tested this with two replicas in [**.NET Aspire**](dotnet-aspire-a-game-changer-for-cloud-native-development), I tagged each notification with the sending instance's ID.
A client on Replica 1 received a notification stamped with Replica 2's ID, which confirmed the message was crossing instances through Redis.

## The Sticky Sessions Requirement

This is something you should know before you set up the backplane: **you still need sticky sessions**.

The Redis backplane solves message _routing_, but it does **not** remove the need for sticky sessions.

SignalR's connection negotiation is a two-step process:

1. The client sends a `POST` to `/hub/negotiate` to obtain a connection token
2. The client uses that token to establish the WebSocket connection

Both requests must land on the **same server**.
If your load balancer routes the negotiation to Server 1 but the WebSocket upgrade to Server 2, the connection fails.

<Image
  src="blogs/mnw_186/sticky_sessions.png"
  width={2553}
  height={1758}
  alt="SignalR connection negotiation showing the need for sticky sessions."
/>

**Make sure sticky sessions are enabled in your load balancer.**
Most load balancers support this via IP hash or cookie affinity - check the docs for whichever you're using.

## What Happens When Redis Goes Down?

One thing worth knowing: **SignalR does not buffer messages when Redis is unavailable**.

If Redis stops responding, any messages sent during the outage are simply lost.
SignalR may throw exceptions, but your existing WebSocket connections stay open - clients don't get disconnected.
Once Redis comes back, SignalR reconnects automatically.

For most real-time scenarios like order updates or live dashboards, this is fine.
The next state change triggers a fresh notification anyway, or the user can just reload.
If you're dealing with something more critical (financial data, operational alerts), you'll want a reconciliation strategy on reconnect or a durable queue running alongside.

## Redis Backplane vs. Azure SignalR Service

If you're on Azure, the managed [Azure SignalR Service](https://learn.microsoft.com/en-us/azure/azure-signalr/signalr-overview) is worth considering.
It proxies all client connections through the service, so sticky sessions aren't required and your servers only hold a small number of constant connections to the service.

The Redis backplane is the better fit when you're self-hosted, latency-sensitive, or already running Redis.
For everything else, Azure SignalR Service is the cleaner option.

## Summary

Honestly, the Redis backplane is almost _too_ simple to set up.
One method call on `AddSignalR()` and your app goes from silently dropping messages to routing them across every instance.
You don't need to make changes to your hub code, client code, or application logic.

Just remember two things:

- **You still need sticky sessions**
- **Messages aren't buffered** if Redis goes down temporarily

Get those two right and SignalR scales out just as smoothly as the rest of your stack.

If you want to go deeper on building real-time features and APIs in .NET,
check out my [**Pragmatic REST APIs**](/pragmatic-rest-apis) course.

Hope this was useful. See you next week.

---



<Sponsorships>

[**NServiceBus**](https://particular.net/pricing/small-business-program?utm_source=newsletter2&utm_medium=email&utm_campaign=spb_promotion2) -
The gold standard for async .NET microservices on Azure, AWS, and On-Prem.
**Free** for orgs under $1M, and with extended discounts, under $25/month for 10 microservices.
Sign up for the [**Small Business Program**](https://particular.net/pricing/small-business-program?utm_source=newsletter2&utm_medium=email&utm_campaign=spb_promotion2)
today!

[**If you build .NET APIs every day**](https://fandf.co/47shjCm), you know the pain of not having a clear view
of what's running in production, who owns what, or what's failing in CI.
The new [**Postman API Catalog**](https://fandf.co/47shjCm) fixes that.
One searchable view of every API and service your team owns, with endpoint health,
CI/CD pass rates, spec linting, and ownership all in one place.

</Sponsorships>

Every outbox processor, job queue, and batch pipeline hits the same problem at some point:
mark a set of rows as done in bulk.

I went through this recently while optimizing an outbox processor.
I measured seven different approaches against 1,000, 10,000, and 25,000 rows in PostgreSQL.
At 10,000 rows the slowest approach took 2,414ms and the fastest took 41ms.
The bottleneck was almost never the SQL.
It was how many times the code was talking to the database.

The scenario: mark a batch of orders as processed by setting a status and a **unique** `processed_at` timestamp per row.
That uniqueness constraint is what makes it tricky.
You can't use a simple `UPDATE ... WHERE id IN (...)` with a single value because every row gets a different timestamp.

Let's go through each approach.

## The Scenario

A table of orders, each needing two updates: a `status` change to `"Processed"` and a unique `processed_at` timestamp.

```sql
CREATE TABLE orders (
    id            UUID         NOT NULL PRIMARY KEY,
    customer_name TEXT         NOT NULL,
    status        TEXT         NOT NULL DEFAULT 'Pending',
    processed_at  TIMESTAMPTZ
);
```

The update payload is a simple record pairing each order with its timestamp:

```csharp
record OrderUpdate(Guid Id, DateTime ProcessedAt);
```

With 10,000 of these, here's how each approach plays out.

## Approach 1: Naive Dapper, One UPDATE Per Row

The first thing you'd try: loop through the list and fire one `UPDATE` per row.

```csharp
await using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();
await using var transaction = await connection.BeginTransactionAsync();

foreach (var update in updates)
{
    await connection.ExecuteAsync(
        """
        UPDATE orders
        SET processed_at = @ProcessedAt,
            status       = 'Processed'
        WHERE id = @Id
        """,
        new { update.Id, update.ProcessedAt },
        transaction: transaction);
}

await transaction.CommitAsync();
```

10,000 rows means 10,000 round-trips to the database.
Each `ExecuteAsync` call sends the SQL, waits for PostgreSQL to respond, then moves on to the next one.
At 10,000 rows this took **2,414ms** in my benchmark. At 25,000 rows it was over 6 seconds.
Over a real network it would be worse.
The database is not slow. The constant back-and-forth is.

## Approach 2: EF Core SaveChanges, Batched Round-Trips

EF Core batches the generated SQL statements to cut down on round-trips.
With `MaxBatchSize` set high enough, you can push all 10,000 updates in far fewer network calls.
The default batch size is 42, in case you were wondering.
You can read more about this in the [EF Core efficient updating docs](https://learn.microsoft.com/en-us/ef/core/performance/efficient-updating).

```csharp
var options = new DbContextOptionsBuilder<AppDbContext>()
    .UseNpgsql(connectionString, o => o.MinBatchSize(5000).MaxBatchSize(10000))
    .Options;

await using var db = new AppDbContext(options);

var ids = updates.Select(u => u.Id).ToHashSet();
var orders = await db.Orders
    .Where(o => ids.Contains(o.Id))
    .ToListAsync();

var updateMap = updates.ToDictionary(u => u.Id);

foreach (var order in orders)
{
    order.Status = "Processed";
    order.ProcessedAt = updateMap[order.Id].ProcessedAt;
}

await db.SaveChangesAsync();
```

It's a meaningful improvement over the loop.
At 10,000 rows it came in at **1,030ms**, roughly half the time of Approach 1.
But there's hidden cost in two places: the upfront `SELECT` to load all 10,000 entities into the change tracker,
and the fact that EF Core still generates 10,000 individual `UPDATE` statements.
They're packed into fewer round-trips, but the SQL is all still there.

## Approach 3: Dapper with a VALUES Table, One Statement, One Round-Trip

Instead of sending N separate statements, you can send a single `UPDATE` that supplies all the new values inline
using a derived `VALUES` table:

```sql
UPDATE orders
SET processed_at = v.processed_at,
    status       = 'Processed'
FROM (VALUES
    (@Id0, @ProcessedAt0),
    (@Id1, @ProcessedAt1),
    ...
) AS v(id, processed_at)
WHERE orders.id = v.id::uuid
```

Here's the C# code to build and execute that:

```csharp
await using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();
await using var transaction = await connection.BeginTransactionAsync();

const string updateTemplate =
    @"""
    UPDATE orders
    SET processed_at = v.processed_at,
        status       = 'Processed'
    FROM (VALUES
        {0}
    ) AS v(id, processed_at)
    WHERE orders.id = v.id::uuid
    """;

var paramNames = string.Join(
    ",\n    ",
    updates.Select((_, i) => $"(@Id{i}, @ProcessedAt{i})"));

var sql = string.Format(updateTemplate, paramNames);

var parameters = new DynamicParameters();
for (int i = 0; i < updates.Count; i++)
{
    parameters.Add($"Id{i}", updates[i].Id.ToString());
    parameters.Add($"ProcessedAt{i}", updates[i].ProcessedAt);
}

await connection.ExecuteAsync(sql, parameters, transaction: transaction);

await transaction.CommitAsync();
```

PostgreSQL receives one statement, builds one execution plan, and updates all rows in a single pass.
One round-trip total.
This dropped from 2,414ms down to **89ms** at 10,000 rows.

There is a trade-off: the SQL string grows with the batch size.
At 10,000 rows you end up with 10,000 parameter pairs in the query text.
PostgreSQL allows a **maximum of 65,535 parameters**, so you have headroom,
but it is something to be aware of at very large batch sizes.
Approaches 6 and 7 avoid this entirely.

## Approach 4: EF Core ExecuteSqlRaw, Same SQL Inside EF Core

The SQL here is exactly the same as Approach 3.
The reason to use this instead is if you're already working inside an EF Core `DbContext` and want your bulk update to share the same transaction as other EF Core operations.

```csharp
await using var db = new AppDbContext(options);
await using var transaction = await db.Database.BeginTransactionAsync();

var paramEntries = new List<NpgsqlParameter>();
var valueClauses = new List<string>();

for (int i = 0; i < updates.Count; i++)
{
    valueClauses.Add($"(@Id{i}::uuid, @ProcessedAt{i})");
    paramEntries.Add(new NpgsqlParameter($"Id{i}", updates[i].Id.ToString()));
    paramEntries.Add(new NpgsqlParameter($"ProcessedAt{i}", updates[i].ProcessedAt));
}

var sql = string.Format(updateTemplate, string.Join(",\n    ", valueClauses));

await db.Database.ExecuteSqlRawAsync(sql, paramEntries);

await transaction.CommitAsync();
```

The performance is the same as Approach 3 since it's the same SQL hitting the database.
In my benchmark it came in at **166ms** at 10,000 rows, a bit slower than Approach 3's 89ms.
The small gap is likely overhead from the EF Core transaction wrapper rather than the SQL itself.
What you get is the ability to mix change-tracked operations with raw SQL inside the same EF Core transaction.
Dapper and EF Core are not mutually exclusive.

One thing to watch out for: `ExecuteSqlRawAsync` doesn't accept Dapper's `DynamicParameters`.
You have to use [`NpgsqlParameter`](https://www.npgsql.org/doc/api/Npgsql.NpgsqlParameter.html) objects directly.
If you want a full overview of EF Core's raw SQL options,
I covered them in [**this article**](ef-core-raw-sql-queries).

## Approach 5: Dapper CTE (WITH ... AS VALUES)

This is a variation on Approach 3 that wraps the same `VALUES` data in a named CTE instead of an inline derived table:

```sql
WITH updates(id, processed_at) AS (
    VALUES
        (@Id0::uuid, @ProcessedAt0),
        (@Id1::uuid, @ProcessedAt1),
        ...
)
UPDATE orders
SET processed_at = updates.processed_at,
    status       = 'Processed'
FROM updates
WHERE orders.id = updates.id
```

And here's the C# code to execute it:

```csharp
await using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();
await using var transaction = await connection.BeginTransactionAsync();

var valueClauses = string.Join(
    ",\n        ",
    updates.Select((_, i) => $"(@Id{i}::uuid, @ProcessedAt{i})"));

var sql =
    @$"""
    WITH updates(id, processed_at) AS (
        VALUES
            {valueClauses}
    )
    UPDATE orders
    SET processed_at = updates.processed_at,
        status       = 'Processed'
    FROM updates
    WHERE orders.id = updates.id
    """;

var parameters = new DynamicParameters();
for (int i = 0; i < updates.Count; i++)
{
    parameters.Add($"Id{i}", updates[i].Id.ToString());
    parameters.Add($"ProcessedAt{i}", updates[i].ProcessedAt);
}

await connection.ExecuteAsync(sql, parameters, transaction: transaction);

await transaction.CommitAsync();
```

Still a single statement and a single round-trip.
PostgreSQL materializes the CTE once and joins against it for the update.
In the benchmark it came in at **103ms** at 10,000 rows, slightly behind the plain `VALUES` approach at 89ms.
The performance difference is small enough that this is really a style choice.
Some teams prefer the CTE form when the update logic is more involved and they want to name the data source explicitly.

## Approach 6: Dapper with UNNEST (PostgreSQL)

If you're on PostgreSQL, there's a cleaner option: [`UNNEST`](https://www.postgresql.org/docs/current/functions-array.html).
Instead of building `@Id0` through `@Id9999` dynamically, you pass two arrays as parameters and let PostgreSQL expand them:

```csharp
await using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();
await using var transaction = await connection.BeginTransactionAsync();

var ids = updates.Select(u => u.Id).ToArray();
var processedAts = updates.Select(u => u.ProcessedAt).ToArray();

await connection.ExecuteAsync(
    @"""
    UPDATE orders
    SET processed_at = v.processed_at,
        status       = 'Processed'
    FROM UNNEST(@Ids, @ProcessedAts) AS v(id, processed_at)
    WHERE orders.id = v.id
    """,
    new { Ids = ids, ProcessedAts = processedAts },
    transaction: transaction);

await transaction.CommitAsync();
```

This is my preferred approach when working with PostgreSQL:

- **No dynamic SQL.** The query text is always the same. No `string.Format`, no growing parameter lists.
- **Two parameters total.** `@Ids` and `@ProcessedAts`.
  Npgsql maps `Guid[]` and `DateTime[]` directly to PostgreSQL array types.
- **Stable query plans.** The SQL never changes,
  so PostgreSQL can cache and reuse the execution plan regardless of how many rows you're updating.
- **Scales cleanly.** The query text stays constant for any batch size.
  Only the array data grows, and it's sent as compact binary.

The catch: `UNNEST` is PostgreSQL-specific.
If you're targeting multiple databases, stick with the `VALUES` approach from Approach 3, 4, or 5.
Or you can research the equivalent array expansion functions in your other database of choice.

## Approach 7: Temp Table + Binary COPY

All the previous approaches pass data as SQL parameters.
At extreme batch sizes that starts to become a constraint, both from the 65,535 parameter limit and from the overhead of building large parameter lists.

A completely different path: skip parameters altogether.
Create a temporary staging table, bulk-load the data using [Npgsql's binary COPY](https://www.npgsql.org/doc/copy.html), then run a single `UPDATE ... FROM`.

```csharp
await using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();
await using var transaction = await connection.BeginTransactionAsync();

await connection.ExecuteAsync(
    @"""
    CREATE TEMP TABLE temp_updates (
        id           UUID        NOT NULL,
        processed_at TIMESTAMPTZ NOT NULL
    ) ON COMMIT DROP
    """,
    transaction: transaction);

await using (var writer = await connection.BeginBinaryImportAsync(
    "COPY temp_updates (id, processed_at) FROM STDIN (FORMAT BINARY)"))
{
    foreach (var u in updates)
    {
        await writer.StartRowAsync();
        await writer.WriteAsync(u.Id, NpgsqlTypes.NpgsqlDbType.Uuid);
        await writer.WriteAsync(u.ProcessedAt, NpgsqlTypes.NpgsqlDbType.TimestampTz);
    }
    await writer.CompleteAsync();
}

await connection.ExecuteAsync(
    @"""
    UPDATE orders
    SET processed_at = t.processed_at,
        status       = 'Processed'
    FROM temp_updates t
    WHERE orders.id = t.id
    """,
    transaction: transaction);

await transaction.CommitAsync();
```

Binary COPY is Npgsql's most efficient data loading path.
It bypasses the SQL parameter system and streams rows directly in PostgreSQL's binary wire format.
The `ON COMMIT DROP` means the temp table is cleaned up automatically when the transaction ends.

The trade-off is complexity: you create a table, stream data into it, then fire the update.
It is technically two operations (COPY + UPDATE), but both are efficient.
At 10,000 rows it came in at **41ms**, matching UNNEST.
At larger batch sizes (say, 100k+ rows), binary COPY would likely pull ahead further since the data payload grows but the query text stays constant and there are no parameter limits to worry about.

## Benchmark Results

Here are the numbers across all three batch sizes:

```
| Approach                                   | 1,000 rows | 10,000 rows | 25,000 rows |
| ------------------------------------------ | ---------- | ----------- | ----------- |
| Approach 1: Naive Dapper                   | 317ms      | 2,414ms     | 6,283ms     |
| Approach 2: EF Core SaveChanges            | 575ms      | 1,030ms     | 1,767ms     |
| Approach 3: Dapper + VALUES table          | 19ms       | 89ms        | 233ms       |
| Approach 4: EF Core ExecuteSqlRaw + VALUES | 58ms       | 166ms       | 282ms       |
| Approach 5: Dapper + CTE                   | 13ms       | 103ms       | 251ms       |
| Approach 6: Dapper + UNNEST                | 12ms       | 41ms        | 92ms        |
| Approach 7: Temp table + binary COPY       | 11ms       | 41ms        | 93ms        |
```

A few things stand out.
EF Core `SaveChanges` is actually faster than naive Dapper at 10,000+ rows because its batching cuts down round-trips significantly.
But both are far behind the single-statement approaches.
The biggest jump in the table is from Approach 2 to Approach 3.
Approach 5 (CTE) is essentially the same performance as Approach 3 (VALUES), confirming it is a style choice rather than a performance one.
Approaches 6 and 7 are the fastest at every scale, and the gap over CTE and VALUES widens as batch size grows.

## Summary

The takeaway from this exercise is simple: round-trips are expensive and individual SQL statements add up fast.

Reducing 10,000 database calls to 1 is where all the gains come from.
Everything else is secondary.

A few things worth keeping in mind:

- **EF Core `SaveChanges` is not a bulk update tool.**
  It reduces round-trips through batching, but it still generates N individual `UPDATE` statements
  and requires a `SELECT` to load the change tracker.
  For bulk mutations, raw SQL is a better fit.
  The same logic applies to inserts - I covered that in
  [**Fast SQL Bulk Inserts with C# and EF Core**](fast-sql-bulk-inserts-with-csharp-and-ef-core).
- **For PostgreSQL, `UNNEST` and binary COPY are the best options at scale.**
  Both use a fixed query text that doesn't grow with batch size and have no parameter count limits.
  `VALUES` and CTE are solid choices for smaller batches or when you need to stay closer to portable SQL.
- **Dapper and EF Core work well together.**
  You don't have to choose one or the other.
  Query with EF Core, bulk-update with raw SQL, share the same transaction.

If you want to go deeper on SQL performance more broadly,
I recently wrote about [**a common myth around filter and join ordering in SQL queries**](debunking-the-filter-early-join-later-sql-performance-myth)
that trips up a lot of developers.

That's all for today.

See you next week.

---



<Sponsorships>

Build AI applications with [**Redis as a vector database using RedisVL**](https://fandf.co/4kKFUaR) (Redis Vector Library):
Dedicated Python and [**Java**](https://fandf.co/4aLNlvi) client libraries that provide high-level abstractions
for vector similarity search and semantic caching, enabling AI-powered applications
on top of Redis' real-time performance, scalability, and reliability.
[**Click here to view the docs**](https://fandf.co/4kKFUaR).

AI-assisted coding can quickly accelerate tech debt and lead to costly rewrites.
Sonar just launched [**SonarQube Architecture Management**](https://fandf.co/4b3b0pS),
which helps teams detect architectural violations early and resolve them directly in the developer workflow.
[**Learn how it prevents architectural drift**](https://fandf.co/4b3b0pS), enforces codebase standards,
and reduces the risk of expensive structural rewrites.

</Sponsorships>

Every project starts with good intentions.
You agree on layer boundaries, naming conventions, dependency direction.
The diagram goes on Confluence.

Six months later, someone moves a domain service into the `Infrastructure` project because it needs database access.
Or a handler gets named `ProcessPaymentService` because the dev didn't know the convention.
Or a class that should be `internal` is `public` because that's the default.
Nobody catches it in code review.

[**Architecture tests**](shift-left-with-architecture-testing-in-dotnet) stop this from happening.
They turn your architectural rules into automated tests that run in CI.
If someone violates a rule, the build fails.

Here are 5 types of architecture tests I add to every .NET project.

## ArchUnitNET and the Test Setup

[ArchUnitNET](https://github.com/TNG/ArchUnitNET) is the .NET port of the Java [ArchUnit](https://www.archunit.org/) library.
It lets you write [**architecture rules**](enforcing-software-architecture-with-architecture-tests)
using a fluent API and run them as regular xUnit tests.

```bash
# there are other test frameworks supported, but I use xUnit
dotnet add package TngTech.ArchUnitNET.xUnit
```

You need a base class that loads all the assemblies you want to test.
Each layer gets an "anchor type" to grab a reference to the assembly at compile time:

```csharp
public abstract class BaseTest
{
    protected static readonly Assembly DomainAssembly = typeof(User).Assembly;
    protected static readonly Assembly ApplicationAssembly = typeof(ICommand).Assembly;
    protected static readonly Assembly InfrastructureAssembly = typeof(ApplicationDbContext).Assembly;
    protected static readonly Assembly PresentationAssembly = typeof(Program).Assembly;

    protected static readonly Architecture Architecture = new ArchLoader()
        .LoadAssemblies(
            DomainAssembly,
            ApplicationAssembly,
            InfrastructureAssembly,
            PresentationAssembly)
        .Build();
}
```

The `ArchLoader` scans these assemblies and builds an in-memory model of all types and their dependencies.
Every test class inherits from `BaseTest`.

## 1. Layer Dependency Tests

The most important rule in [**Clean Architecture**](/pragmatic-clean-architecture) is the **dependency rule**.
Inner layers must not reference outer layers.
All dependencies point inward.

In most Clean Architecture setups, the project references already prevent the obvious violations.
You can't add a reference from `Application` to `Infrastructure`
because `Infrastructure` already references `Application`, and the compiler won't allow circular dependencies.

So why bother with these tests?

Because project references aren't the only way dependencies leak in.
A NuGet package used in Infrastructure might expose types that bleed into Application through transitive references.
Someone could reorganize the solution and change the project reference graph.
Or you might move to a [**modular monolith**](what-is-a-modular-monolith)
where multiple layers share an assembly, and the compiler can't help you at all.

These tests are a safety net.
And they double as living documentation of the intended architecture.

```csharp
using static ArchUnitNET.Fluent.ArchRuleDefinition;

public class LayerTests : BaseTest
{
    private static readonly IObjectProvider<IType> DomainLayer =
        Types().That().ResideInAssembly(DomainAssembly).As("Domain layer");

    private static readonly IObjectProvider<IType> ApplicationLayer =
        Types().That().ResideInAssembly(ApplicationAssembly).As("Application layer");

    private static readonly IObjectProvider<IType> InfrastructureLayer =
        Types().That().ResideInAssembly(InfrastructureAssembly).As("Infrastructure Layer");

    private static readonly IObjectProvider<IType> PresentationLayer =
        Types().That().ResideInAssembly(PresentationAssembly).As("Presentation Layer");

    [Fact]
    public void DomainLayer_ShouldNotDependOn_ApplicationLayer()
    {
        Types().That().Are(DomainLayer).Should()
            .NotDependOnAny(ApplicationLayer)
            .Check(Architecture);
    }

    [Fact]
    public void DomainLayer_ShouldNotDependOn_InfrastructureLayer()
    {
        Types().That().Are(DomainLayer).Should()
            .NotDependOnAny(InfrastructureLayer)
            .Check(Architecture);
    }

    [Fact]
    public void DomainLayer_ShouldNotDependOn_PresentationLayer()
    {
        Types().That().Are(DomainLayer).Should()
            .NotDependOnAny(PresentationLayer)
            .Check(Architecture);
    }

    [Fact]
    public void ApplicationLayer_ShouldNotDependOn_InfrastructureLayer()
    {
        Types().That().Are(ApplicationLayer).Should()
            .NotDependOnAny(InfrastructureLayer)
            .Check(Architecture);
    }

    [Fact]
    public void ApplicationLayer_ShouldNotDependOn_PresentationLayer()
    {
        Types().That().Are(ApplicationLayer).Should()
            .NotDependOnAny(PresentationLayer)
            .Check(Architecture);
    }

    [Fact]
    public void InfrastructureLayer_ShouldNotDependOn_PresentationLayer()
    {
        Types().That().Are(InfrastructureLayer).Should()
            .NotDependOnAny(PresentationLayer)
            .Check(Architecture);
    }
}
```

Six tests, one for each illegal dependency direction.

The fluent API reads like English:
"Types that are in the Domain layer should not depend on any types in the Application layer".
When a violation happens, the test tells you exactly which type depends on which.

This is the first architecture test I add to any project.
If you only add one type from this list, make it this one.

You can also extend this further.
For example, I sometimes add tests that specific namespaces within a layer can't reference each other
(like `Application.Orders` shouldn't depend on `Application.Users`).
This can be great for enforcing a [**vertical slice architecture**](vertical-slice-architecture)
where each feature is self-contained, or inside a [**modular monolith**](/modular-monolith-architecture)
where modules shouldn't depend on each other.

## 2. Naming Convention Tests

This one might seem minor, but it adds up fast.

When you have 50 command handlers and 3 of them are named `CreateOrderService` or `ProcessPaymentUseCase`,
searching the codebase becomes unreliable. You search for `CommandHandler` and miss three handlers.

ArchUnitNET lets you enforce naming rules by selecting classes based on the interfaces they implement:

```csharp
using static ArchUnitNET.Fluent.ArchRuleDefinition;

public class NamingConventionTests : BaseTest
{
    [Fact]
    public void CommandHandlers_ShouldHave_NameEndingWith_CommandHandler()
    {
        Classes().That()
            .ImplementInterface(typeof(ICommandHandler<>))
            .Or()
            .ImplementInterface(typeof(ICommandHandler<,>))
            .And().DoNotResideInNamespace("Application.Abstractions.Behaviors")
            .Should().HaveNameEndingWith("CommandHandler")
            .Check(Architecture);
    }

    [Fact]
    public void QueryHandlers_ShouldHave_NameEndingWith_QueryHandler()
    {
        Classes().That()
            .ImplementInterface(typeof(IQueryHandler<,>))
            .And().DoNotResideInNamespace("Application.Abstractions.Behaviors")
            .Should().HaveNameEndingWith("QueryHandler")
            .Check(Architecture);
    }

    [Fact]
    public void Validators_ShouldHave_NameEndingWith_Validator()
    {
        Classes().That()
            .HaveNameEndingWith("Validator")
            .Should().ResideInAssembly(ApplicationAssembly)
            .Check(Architecture);
    }
}
```

One gotcha here: decorators like `ValidationBehavior` implement handler interfaces too.
They're decorators in the pipeline, not domain-specific handlers.
The `DoNotResideInNamespace("Application.Abstractions.Behaviors")` filter excludes them.
I learned this the hard way when every behavior started failing the naming check.

The validator test works in the opposite direction.
It says "classes ending with `Validator` should live in the Application assembly".
I've seen validators accidentally placed in the Infrastructure project.
This catches that.

## 3. Colocation Tests

This is the test I wish I had earlier in my career.

When you use [**CQRS**](cqrs-pattern-the-way-it-should-have-been-from-the-start),
you end up with pairs: a command (or query) and its handler.
I keep them in the same namespace so everything for a use case lives together.
`Application.TodoItems.Create` would contain both `CreateTodoItemCommand` and `CreateTodoItemCommandHandler`.

But nothing stops someone from putting the handler in a completely different namespace:

```csharp
public class ColocationTests : BaseTest
{
    [Theory]
    [MemberData(nameof(GetHandlerAndCommandPairs))]
    public void Handlers_ShouldResideInSameNamespace_AsTheirCommandOrQuery(
        Type handlerType,
        Type commandOrQueryType)
    {
        handlerType.Namespace.ShouldBe(
            commandOrQueryType.Namespace,
            $"{handlerType.Name} should be in the same namespace as {commandOrQueryType.Name}");
    }

    public static TheoryData<Type, Type> GetHandlerAndCommandPairs()
    {
        Type[] handlerInterfaces =
        [
            typeof(ICommandHandler<>),
            typeof(ICommandHandler<,>),
            typeof(IQueryHandler<,>)
        ];

        var pairs = new TheoryData<Type, Type>();

        IEnumerable<Type> handlers = ApplicationAssembly
            .GetTypes()
            .Where(t => t is { IsClass: true, IsAbstract: false, IsGenericTypeDefinition: false })
            .Where(t => t.DeclaringType is null);

        foreach (Type handler in handlers)
        {
            foreach (Type iface in handler.GetInterfaces())
            {
                if (!iface.IsGenericType)
                {
                    continue;
                }

                Type genericDef = iface.GetGenericTypeDefinition();

                if (!handlerInterfaces.Contains(genericDef))
                {
                    continue;
                }

                Type commandOrQueryType = iface.GetGenericArguments()[0];
                pairs.Add(handler, commandOrQueryType);
            }
        }

        return pairs;
    }
}
```

This test doesn't use ArchUnitNET.
It uses **raw reflection** combined with xUnit's `[Theory]` and `[MemberData]`.
ArchUnitNET can't express a rule like
"this class should be in the same namespace as the generic type argument of its interface".
So we drop down to reflection.

The `GetHandlerAndCommandPairs` method scans the Application assembly,
finds all classes implementing a handler interface,
extracts the command/query type from the generic argument,
and returns pairs for the test to assert on.

This enforces a [**vertical slice**](vertical-slice-architecture-structuring-vertical-slices) style of organizing code.
When a new developer joins the team, they can find everything for a use case in one folder.

You can expand this to cover request and response types, validators, or anything else that should be colocated.

## 4. Visibility Tests

Command and query handlers are implementation details.
They get resolved through DI, not referenced directly.

But most developers make them `public` by default.
It's just muscle memory.
The problem is that a `public` handler can be referenced directly from another layer,
bypassing the abstractions you set up.

```csharp
using static ArchUnitNET.Fluent.ArchRuleDefinition;

public class VisibilityTests : BaseTest
{
    [Fact]
    public void CommandHandlers_ShouldBeInternal()
    {
        Classes().That()
            .ImplementInterface(typeof(ICommandHandler<>))
            .Or()
            .ImplementInterface(typeof(ICommandHandler<,>))
            .Should().BeInternal()
            .Check(Architecture);
    }

    [Fact]
    public void QueryHandlers_ShouldBeInternal()
    {
        Classes().That()
            .ImplementInterface(typeof(IQueryHandler<,>))
            .Should().BeInternal()
            .Check(Architecture);
    }
}
```

If you're worried about DI not finding `internal` classes, don't be.
Assembly scanning discovers them just fine.

You could extend this to other types too.
I've thought about enforcing that EF Core configurations are `internal` as well,
since there's no reason for `OrderConfiguration` to be visible outside of Infrastructure.

## 5. Dependency Guard Tests

Layer tests guard against references to your own assemblies.
But infrastructure libraries can leak in through transitive NuGet references.

Your Domain layer shouldn't know about Entity Framework. Your Application layer shouldn't know about Npgsql.
The compiler won't stop this if the package is transitively available.

```csharp
using static ArchUnitNET.Fluent.ArchRuleDefinition;

public class DependencyGuardTests : BaseTest
{
    [Fact]
    public void DomainLayer_ShouldNotDependOn_EntityFramework()
    {
        Types().That().ResideInAssembly(DomainAssembly).Should()
            .NotDependOnAnyTypesThat()
            .ResideInNamespace("Microsoft.EntityFrameworkCore")
            .Check(Architecture);
    }

    [Fact]
    public void ApplicationLayer_ShouldNotDependOn_EntityFramework()
    {
        Types().That().ResideInAssembly(ApplicationAssembly).Should()
            .NotDependOnAnyTypesThat()
            .ResideInNamespace("Microsoft.EntityFrameworkCore")
            .Check(Architecture);
    }
}
```

Add whatever libraries make sense for your project.

## Summary

Architectural rules that only exist in documentation will be violated.
It's not a question of _if_, it's _when_.

All of these tests run in milliseconds and don't require any infrastructure to run.
They sit right next to your unit tests and run on every build.

Architecture tests are a safety net that catches violations before they reach production.

Start with layer dependency tests.
They take five minutes to set up and catch the most damaging violations.
Then add the rest as your codebase grows.

If you want to see how I structure Clean Architecture projects with these guardrails,
check out [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture).

Thanks for reading.

And stay awesome!

---



<Sponsorships>

EU compliance shouldn't mean slower inference.
[**Infercom**](https://fandf.co/4kwsmzT) runs OpenAI-compatible APIs on dedicated SambaNova RDU infrastructure in Europe.
Deploy models like DeepSeek and Llama, or build agents with frameworks like OpenClaw.
European jurisdiction, CLOUD Act protection, zero prompt retention.
[**Start Building For Free**](https://fandf.co/4kwsmzT).

Treat your credit card like a programmable dev environment.
[**Klutch**](https://fandf.co/4tFOLyL) gives you full API access to script your own spending rules, view real-time transaction behavior,
and deploy unlimited virtual cards directly from your stack.
[**Start coding your card with Klutch**](https://fandf.co/4tFOLyL).

</Sponsorships>

Most teams get the macro architecture right.
They build a [**modular monolith**](what-is-a-modular-monolith) with clear module boundaries, [**public APIs**](internal-vs-public-apis-in-modular-monoliths), and proper [**data isolation**](modular-monolith-data-isolation).

But then they stop thinking about architecture.
Every module gets the same internal structure, usually some form of layered architecture.

The thing is, [**Clean Architecture**](/pragmatic-clean-architecture) and [**Vertical Slice Architecture**](vertical-slice-architecture) aren't as far apart as people think.
Both focus on use cases and maximizing cohesion.
Clean Architecture just adds a rule for the direction of dependencies, which often leads to more abstractions and ceremony.
My [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture) approach takes a middle ground, and it's quite similar to VSA in nature.

The real question isn't which one is "better".
It's where each one shines inside your modular monolith.
And the beautiful part is: you can mix and match.

## Two Levels of Architecture

There are two architectural decisions you need to make when building a modular monolith:

1. **Macro architecture** - How do you decompose the system into modules?
   This covers module boundaries, [**communication patterns**](modular-monolith-communication-patterns),
   [**data isolation**](modular-monolith-data-isolation), public API design, and how modules are deployed.
2. **Micro architecture** - How do you organize code _inside_ each module?
   This covers folder structure, the direction of dependencies, how you implement use cases,
   where validation lives, and how you access the database.

Most articles about modular monoliths focus entirely on the macro level.
And for good reason.
Getting **module boundaries** wrong is **expensive to fix**.

<Image
  src="blogs/mnw_182/modular_monolith.png"
  width={2934}
  height={1554}
  alt="Modular monolith."
/>

But the micro level is equally important.
It determines how easy it is to add features, navigate code, and onboard new developers within a module.
It's the architecture your team interacts with every day.

The key insight is this:

> The macro architecture constrains how modules interact.
> The micro architecture is a local decision each module can make independently.

Your `Ticketing` module doesn't have to follow the same internal structure as your `Notifications` module.
The modular boundary gives you this freedom.

### Vertical Slices Are Not Modules

I've seen people conflate vertical slices with modules.
On the macro level, a module can look like a "vertical slice" of the business domain.
But that analogy breaks down at the application level.

A module is a bounded context.
It owns its data, exposes a public API, and encapsulates a business capability.
A vertical slice is a feature implementation pattern.
It groups the request, handler, validation, and data access for a single use case.

Modules and vertical slices operate at different levels.
Modules define the boundaries of the system.
Vertical slices organize the code within those boundaries.

<Image
  src="blogs/mnw_182/vertical_slices.png"
  width={2159}
  height={1276}
  alt="Vertical slices."
/>

## Vertical Slices Inside a Module

[**Vertical Slice Architecture**](vertical-slice-architecture-structuring-vertical-slices)
organizes code by feature instead of by technical layer.
Each feature is a self-contained unit: request, handler, validation, data access, all in one place.

Inside a modular monolith module, this is a natural fit.
The module boundary already enforces separation from the rest of the system.
You don't need layers to protect you.
The module's [**public API**](internal-vs-public-apis-in-modular-monoliths) does that.

Here's what a `Ticketing` module looks like with vertical slices using one file per feature:

```
📁 Modules/
|__ 📁 Ticketing
    |__ 📁 Features
        |__ 📁 AddItemToCart
            |__ #️⃣ AddItemToCart.cs
        |__ 📁 SubmitOrder
            |__ #️⃣ SubmitOrder.cs
        |__ 📁 GetOrder
            |__ #️⃣ GetOrder.cs
        |__ 📁 CancelOrder
            |__ #️⃣ CancelOrder.cs
        |__ 📁 RefundPayment
            |__ #️⃣ RefundPayment.cs
    |__ 📁 Data
        |__ #️⃣ TicketingDbContext.cs
    |__ 📁 Entities
        |__ #️⃣ Order.cs
        |__ #️⃣ Ticket.cs
    |__ #️⃣ ITicketingModule.cs
    |__ #️⃣ TicketingModule.cs
```

You can also use separate files per component if you prefer more granularity:

```
📁 Modules/
|__ 📁 Ticketing
    |__ 📁 Features
        |__ 📁 SubmitOrder
            |__ #️⃣ SubmitOrderRequest.cs
            |__ #️⃣ SubmitOrderResponse.cs
            |__ #️⃣ SubmitOrderHandler.cs
            |__ #️⃣ SubmitOrderValidator.cs
            |__ #️⃣ SubmitOrderEndpoint.cs
        |__ 📁 GetOrder
            |__ #️⃣ GetOrderRequest.cs
            |__ #️⃣ GetOrderResponse.cs
            |__ #️⃣ GetOrderHandler.cs
            |__ #️⃣ GetOrderEndpoint.cs
    |__ 📁 Data
    |__ 📁 Entities
    |__ #️⃣ ITicketingModule.cs
    |__ #️⃣ TicketingModule.cs
```

Both approaches keep everything for a feature in one folder.
Compare this to having `Application`, `Domain`, and `Infrastructure`
folders with dozens of files scattered across layers.
The vertical slice version is flat, scannable, and easy to navigate.

Here's a concrete example using a static class to group the feature components:

```csharp
public static class SubmitOrder
{
    public record Request(string CartId);
    public record Response(string OrderId, decimal Total);

    public class Validator : AbstractValidator<Request>
    {
        public Validator()
        {
            RuleFor(x => x.CartId).NotEmpty();
        }
    }

    public class Endpoint : IEndpoint
    {
        public void MapEndpoint(IEndpointRouteBuilder app)
        {
            app.MapPost("orders", Handler).WithTags("Ticketing");
        }

        public static async Task<IResult> Handler(
            Request request,
            IValidator<Request> validator,
            TicketingDbContext context)
        {
            var result = validator.Validate(request);
            if (!result.IsValid)
            {
                return Results.BadRequest(result.Errors);
            }

            var cart = await context.Carts
                .Include(c => c.Items)
                .FirstOrDefaultAsync(c => c.Id == request.CartId);

            if (cart is null)
            {
                return Results.NotFound();
            }

            var order = Order.Create(cart);

            context.Orders.Add(order);
            await context.SaveChangesAsync();

            return Results.Ok(
                new Response(order.Id, order.Total));
        }
    }
}
```

Adding a new feature means adding a new folder.
You're not touching shared code across layers.
You're not worrying about side effects.

## Choosing the Internal Architecture

A common misconception is that VSA is only for simple modules and Clean Architecture is for complex ones.
That's not how it works.

Vertical slices work great with rich domain models.
You can have domain entities, value objects, and domain events inside a vertical slice.
The slice organizes the entry point and orchestration. The domain model handles the business rules.
As the slice grows in complexity, you [**push logic into the domain**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model)
just like you would in Clean Architecture.

Similarly, [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture) works well for simpler modules too.
The structure is lightweight when the domain is simple.

So the decision isn't about complexity.
It's about what your team is comfortable with and what gives you the most clarity.

Here are a few things I consider:

- **Team familiarity.** If your team already thinks in layers and dependency direction,
  Clean Architecture will feel natural. If they prefer organizing around features, VSA reduces friction.
- **Shared domain logic.** When many use cases share the same domain entities,
  having a dedicated `Domain` layer can make that sharing explicit.
  With VSA, you'd extract shared logic into a separate folder, which also works.
- **Independence of features.** When features are mostly independent and rarely share behavior,
  vertical slices keep things simple. Each feature is self-contained, and the mental model is straightforward.

The modular boundary protects the rest of the system regardless of what you choose inside the module.
So pick what makes your team most productive and be willing to change as the module evolves.

## Takeaway

[**Modular Monolith**](what-is-a-modular-monolith) answers the macro question:
how to decompose the system into modules with clear boundaries.
[**Vertical Slice Architecture**](vertical-slice-architecture) answers the micro question:
how to organize code by feature inside those modules.

They operate at different levels.
Modular Monolith gives you high cohesion within each module and helps you manage coupling between modules.
Vertical Slice Architecture gives you high cohesion within each feature inside a module.

You don't have to pick one internal architecture for the entire system.
Each module can choose what works best for its context.
Some modules will use [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture).
Others will use vertical slices.
A well-defined module boundary makes this safe.

If you want to see how I build modular monoliths with this approach,
check out [**Modular Monolith Architecture**](/modular-monolith-architecture).

See you next week.

---


Previous issues of The .NET Weekly