
<Sponsorships>

A live directory for your infrastructure that replaces hardcoded ownership logic in your alert rules -
that's Catalog by [**incident.io**](https://fandf.co/4cIIfB2).
Add a service, update Catalog, and your entire response system reconfigures itself.
[**Read the blog to learn more**](https://fandf.co/4cIIfB2).

[**Teleport**](https://fandf.co/3PhCocK) replaces static credentials with short-lived certificates bound to cryptographic identity.
One identity layer and workflow across servers, Kubernetes, databases, cloud, and MCP.
No vaults, no standing privileges, no secrets rotation.
[**See how it works →**](https://fandf.co/3PhCocK)

</Sponsorships>

I've written before about implementing [**API versioning**](api-versioning-in-aspnetcore) in ASP.NET Core.

But the more important question isn't _how_ to version an API.
It's _when_.

Every API team eventually reaches for the same escape hatch:

> Just create `v2`.

It sounds responsible.
Except now you maintain two APIs, two sets of docs, two behaviors, and a migration project clients will postpone for as long as possible.

I also touched on this briefly in [**my REST API design mistakes article**](the-5-most-common-rest-api-design-mistakes-and-how-to-avoid-them), but I want to make the point more directly today:

**Versioning is a compatibility tool. It is not a design strategy.**

Most API changes do not require a new version.
They require better change management.

And that distinction matters.

If you treat every contract change as a versioning problem, you end up cloning APIs.
If you treat it as a change management problem, you start asking better questions:

- Can I add instead of replace?
- Can old and new behavior coexist for a while?
- Can I introduce a new operation instead of mutating an old one?
- Can I deprecate this safely with telemetry and a migration path?

That mindset leads to APIs that age much better.

## What Actually Breaks Clients?

Breaking changes usually aren't about the URL alone.

Clients break when you:

- Remove or rename fields
- Change the meaning of existing data
- Tighten request validation
- Change pagination or error formats
- Assume enum-like values are closed forever

This breaks a client just as surely as deleting an endpoint:

```json
// Before
{ "total": 100 }

// After
{ "total": { "amount": 100, "currency": "USD" } }
```

You didn't change the path.
You didn't rename the endpoint.
You still broke clients.

So instead of asking, "Should this be v2?", ask, "Can the old and new contract safely coexist?"

I'll use a simple `orders` API as the running example for the rest of the article.

## The Compatibility Rules

When I want an API to age well, I keep four rules in mind:

- Keep existing fields and behavior in place
- Don't turn optional request data into required data
- Don't change what an existing operation does
- Make anything new additive and optional by default

These map directly onto the four rules from Z. Nemec's [API Change Management](https://medium.com/good-api/api-change-management-2fe5bba32e9b) article: don't take anything away, don't change processing rules, don't make optional things required, and anything you add must be optional.

If you follow those rules, many "versioning problems" turn back into ordinary contract evolution.

## 1. Add, Don't Replace

The safest change is usually an additive one.

Let's say your original `GET /orders/{id}` response looked like this:

```json
{
  "id": "ord_123",
  "status": "paid",
  "total": 100
}
```

Instead of replacing `total`, add a new field:

```json
{
  "id": "ord_123",
  "status": "paid",
  "total": 100,
  "totalMoney": {
    "amount": 100,
    "currency": "USD"
  }
}
```

Existing clients keep using `total`.
New clients can migrate to `totalMoney`.
You mark the old field as deprecated and remove it only after a real migration window.

The same idea applies beyond fields.
If you need richer semantics, don't mutate a field into a different shape.
Add a new field, a new link, or a new operation that carries the new meaning explicitly.

Sometimes an ugly contract is the price of compatibility.

## 2. Make Clients Tolerant Readers

A well-behaved client should not explode because the server added a field it doesn't understand.

If the response evolves from this:

```json
{
  "id": "ord_123",
  "status": "paid"
}
```

to this:

```json
{
  "id": "ord_123",
  "status": "paid",
  "estimatedDeliveryDate": "2026-05-29"
}
```

older clients should ignore the extra property and keep working.

In .NET, `System.Text.Json` helps because unknown properties are ignored by default.
The real risk is usually overly strict generated SDKs or contract tests that assert exact JSON equality.

This is one of the most common self-inflicted problems I see.
Teams say they want backward compatibility, then generate client models that reject any unexpected field in the response.

That is not a compatibility strategy.
That is a trap.

Your server should be free to add optional data.
Your clients should be resilient enough to ignore what they don't understand.

## 3. Don't Change What an Existing Operation Does

Fields and shapes get most of the attention in compatibility discussions, but the most dangerous breaking changes hide in **behavior**.

The URL is the same.
The request body is the same.
The response shape is the same.
What the operation _does_ on the server is different.

Take `DELETE /orders/{id}`.

When the API shipped, that endpoint was a soft delete.
The order moved into an `archived` state, stayed in the database, still showed up in audit reports, and could be restored by support.

The contract that clients built on wasn't just the HTTP verb and the path.
It was the full behavior:

- The order is recoverable
- Related invoices and shipments are untouched
- Audit history is preserved
- The same call is safe to retry

Months later, the team decides soft-delete is messy.
The "fix" turns `DELETE /orders/{id}` into a hard delete:

- The order row is gone
- Related invoices cascade or get orphaned
- Audit history loses references
- Retrying after a network blip can wipe the wrong record

No client noticed at code-review time.
The SDK call still compiles.
The response is still `204 No Content`.
A support tool that used to call `DELETE` and then "undo" it now silently destroys data.

This is exactly the kind of change Z. Nemec's rules call out:
**you must not change the processing rules of an existing operation.**
Once clients have integrated, the behavior _is_ the contract, even if it was never written down anywhere.

The same pattern shows up in subtler ways:

- `POST /orders` used to be idempotent on a client-supplied key, then quietly stops being
- `POST /orders/{id}/cancel` used to refund automatically, then stops issuing refunds because "refunds should be a separate call"
- `PUT /orders/{id}` used to be a full replace, then becomes a partial merge
- A webhook used to fire once per order, now fires per line item

Each of these keeps the URL, the verb, and the JSON shape stable.
Each one breaks every existing integration in a way that won't show up in a schema diff.

The safe move is the same as before: **add, don't mutate.**

If you want a hard delete, expose it as a new operation and leave the old one alone:

```http
DELETE /orders/{id}            # still soft-delete, unchanged
DELETE /orders/{id}?purge=true # new, opt-in hard delete
```

Or introduce a new resource entirely (`DELETE /orders/{id}/purge`) so the destructive behavior has its own name and its own permissions.

The rule is simple: **once an operation ships, its behavior is part of the contract.**
You can add new operations next to it.
You can deprecate it.
You cannot quietly change what it does.

## 4. Be Very Careful With Validation

This one is underrated.

There are two flavors of the same mistake:

- Taking an existing optional field and making it required
- Adding a brand-new field and making it required from day one

Both break older clients in exactly the same way.
The endpoint path doesn't move, but requests that used to succeed now get rejected.

Here's a simple example using `POST /orders`.

Yesterday this request was valid:

```json
{
  "customerId": "cus_123",
  "currency": "USD"
}
```

Today the API requires a country for tax calculation:

```json
{
  "customerId": "cus_123",
  "currency": "USD",
  "country": "US"
}
```

Whether `country` was previously optional or didn't exist at all, the result is the same: every existing integration starts failing at runtime.

A safer path is to accept missing values for older clients, infer defaults where possible, or introduce a new operation for the stricter workflow.

For example:

- Accept missing `country` during a transition window
- Infer it from an existing billing profile if you can
- Add a new `POST /checkout-sessions` flow that requires the richer request model

Response changes usually get careful design review.
Request validation changes deserve the same scrutiny.
And the underlying rule is the one that catches both flavors: **anything you add to the contract has to be optional, and anything that was optional has to stay optional.**

## A New Operation Is Often Cheaper Than a New Version

Sometimes the use case really did change enough that piling more flags and optional parameters onto an existing endpoint becomes confusing.

This is what a bad evolution path looks like:

```http
POST /orders?validateOnly=true&includeTaxEstimate=true&reserveInventory=true
```

At that point you don't have one clean operation.
You have multiple workflows hiding behind one endpoint.

That's when I prefer a new operation or resource over a whole API version.

```http
POST /orders
POST /orders/quote
POST /checkout-sessions
```

This keeps the old contract stable while giving the new behavior a clean home.

`POST /orders` stays the simple "place an order" endpoint.
`POST /orders/quote` becomes the "tell me what this would cost" operation.
`POST /checkout-sessions` can support a richer, more guided flow without contaminating the original contract.

That is usually much cheaper than creating `/v2/orders` and dragging the rest of your API along with it.

## Deprecate Like You Mean It

This is the missing half of API change management.

Most deprecations are fake.
They exist in docs, but nothing operational happens.

A real deprecation process should include four things:

1. Mark the old field or endpoint as deprecated in your OpenAPI description.
2. Signal the deprecation at runtime.
3. Give consumers a migration path.
4. Measure actual usage before removing anything.

If you're on HTTP, runtime signaling can be as simple as response headers like these:

```http
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migrations/orders-total>; rel="deprecation"
```

Now the deprecation is visible in the docs, visible in live traffic, and connected to an actual migration guide.

And this is where telemetry matters.
If you don't know which clients still use the deprecated field or endpoint, you are not managing change.
You are guessing.

Track usage by client ID, API key, tenant, or application name.
Then wait until usage is effectively gone before removing anything.

## When Versioning Is Actually The Right Call

I am not anti-versioning.

Version when the old and new semantics cannot coexist safely.
Version when the resource model changed fundamentally.
Version when compatibility rules would force you into a contract nobody can reason about.

In those cases, version deliberately.

And deliberate versioning means choosing the smallest break you can justify.

Sometimes that's a new endpoint shape.
Sometimes it's a representation variant.
Sometimes, especially for public APIs, it's straightforward URL versioning because it is explicit and easy to communicate.

The key is not which mechanism you pick.
The key is that you reached for it because coexistence failed, not because it was the first idea on the table.

And if you do version, pair it with an actual deprecation process:

- Mark old fields or endpoints as deprecated
- Communicate a removal date
- Give clients migration examples
- Monitor usage before removing anything

The real work is not creating `v2`.
The real work is getting consumers off `v1`.

## Takeaway

The best API version is often the one you never have to create.

If you want a simple decision rule, use this:

1. Can I add instead of replace?
2. Can old and new contracts coexist during a migration window?
3. Can I introduce a new operation instead of mutating an old one?
4. Can I deprecate the old shape with docs, headers, and telemetry?

If the answer is yes, you probably don't need a new version.

If the answer is no, and the old and new worlds genuinely cannot live side by side, version deliberately.

That's the real point.

Design contracts to evolve.
Treat clients as long-lived integrations, not just today's code.
And reserve versioning for the cases where compatibility truly runs out.

If you want to go deeper on designing and evolving HTTP APIs, check out [**Pragmatic REST APIs**](/pragmatic-rest-apis).
It's where I cover the patterns, trade-offs, and implementation details I use when building APIs that need to survive real clients and real change.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

Are you using VS Code or Cursor for C#?
AI writes your C# code - [**ReSharper**](https://www.jetbrains.com/resharper/?product=vsc&utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper-vsc) makes sure it's actually correct.
[**Give it a try**](https://www.jetbrains.com/resharper/?product=vsc&utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper-vsc)!

[**Aiven's developer tier for Apache Kafka**](https://fandf.co/4cVcIdL) lets you ditch the local setup
and provision a managed cluster with an integrated Schema Registry and REST Proxy in under two minutes.
For $29/month, you get 100 partitions and 20 topics on the same stack used for enterprise-grade workloads,
providing a production-ready playground for prototyping your event-driven services.
[**Start building**](https://fandf.co/4cVcIdL).

</Sponsorships>

A lot of the "DDD-ish" .NET code I review scatters business rules across handlers, validators,
and controllers, and barely puts any on the domain model itself.

Each copy of the same rule drifts a little over time, and whether a given object is _valid_ starts to depend on which path the caller took to reach it.

You can absolutely build a working system this way.
I've shipped plenty of procedural code with enough `if`-checks to keep things in line.
But there's a cleaner way to think about it, and it starts with a single idea.

## What Is an Invariant?

An **invariant** is a rule about an object that must hold true for as long as the object exists.

Not just when you save it, or when a validator happens to run.
The rule has to hold every time you touch the object, no matter how it got into memory.

A few examples:

- A `Course` always has a non-empty title.
- An `Order` total always equals the sum of its line items.
- A `Subscription` is in exactly one state: `Trial`, `Active`, `PastDue`, or `Canceled`.
- A published course has at least one lesson.

None of these mention validation, persistence, or HTTP.
They're statements about the _domain_, and they should be true regardless of how the object got loaded.

## Where Procedural Code Goes Wrong

Take a simple `Course` written the way most CRUD-ish .NET apps still write it:

```csharp
public class Course
{
    public string Title { get; set; }
    public CourseStatus Status { get; set; }
    public DateTime? PublishedOn { get; set; }
    public decimal Price { get; set; }
}
```

There's no constructor and every property has a public setter, so the class is willing to accept any combination of values.

To keep the data correct, the rules end up scattered across the application:

- `CreateCourseValidator` checks the title isn't empty.
- `PublishCourseHandler` sets `Status` and `PublishedOn`, and remembers to check the course isn't already published.
- `ChangePriceHandler` checks the course isn't archived.
- A new endpoint shows up, someone copies an existing handler, and the archive check quietly goes missing.

Every rule lives in a place that just happens to be on the path the request took.
Nothing on the `Course` itself prevents it from drifting into an invalid state.

That's the real cost of an [**anemic model**](refactoring-from-an-anemic-domain-model-to-a-rich-domain-model).
It isn't that there's no behavior on the class.
It's that the class makes no promises, so every caller has to enforce the rules itself.

## Always-Valid: The Model as the Source of Truth

The shift I want to make is simple: the model never accepts an invalid state.

If you're holding a `Course` reference, you can trust it.
You don't need an `if (course.Title is null)` somewhere down the call stack, you don't need a parallel validator double-checking, and you don't need to hope the handler remembered the right guard.

Three moves get you there.

### 1. Block construction of invalid objects

A `Course` without a title shouldn't exist, so the easiest fix is to make it impossible to construct.

```csharp
public class Course
{
    private Course(CourseId id, string title, Money price)
    {
        Id = id;
        Title = title;
        Price = price;
        Status = CourseStatus.Draft;
    }

    public static Result<Course> Create(string title, Money price)
    {
        if (string.IsNullOrWhiteSpace(title))
        {
            return CourseErrors.TitleRequired;
        }

        return new Course(CourseId.New(), title, price);
    }
}
```

A private constructor with a static factory gives you a single, well-known place where a `Course` can come into existence, and that's where the validation runs.
From that point on, any code holding a `Course` reference can assume it has a valid title.

[**Value objects**](value-objects-in-dotnet-ddd-fundamentals) like `Money` apply the same idea at a smaller scope, so a `Money` can't be negative or be missing its currency by the time you're using it.

### 2. Encapsulate state transitions

Once construction is locked down, the next leak is state changes.
The class should control how it changes, instead of leaving that up to whoever has a reference to it.
No setters, and every change goes through a method that knows the rules.

```csharp
public Result Publish(IDateTimeProvider clock)
{
    if (Status != CourseStatus.Draft)
    {
        return CourseErrors.AlreadyPublished;
    }

    if (_lessons.Count == 0)
    {
        return CourseErrors.CannotPublishWithoutLessons;
    }

    Status = CourseStatus.Published;
    PublishedOn = clock.UtcNow;
    return Result.Success();
}
```

The handler doesn't need to know whether the course was already published, and it doesn't need to remember to check for empty lessons.
It calls `Publish` and propagates whatever result comes back.
The rule lives next to the state it protects, in one place.

### 3. Encapsulate the aggregate

Some rules span multiple entities inside the same boundary.
The aggregate root is the right place to enforce those, because it's the transactional boundary.

Take this rule: a published course must have at least one lesson, and lessons can't be removed once it's published.

The wrong way is to expose `Lessons` as a mutable collection and rely on the application service to remember the rule everywhere it's used.
The right way is to keep the collection private and force every change through the root:

```csharp
public sealed class Course
{
    private readonly List<Lesson> _lessons = [];
    public IReadOnlyCollection<Lesson> Lessons => _lessons.AsReadOnly();

    public Result RemoveLesson(LessonId id)
    {
        if (Status == CourseStatus.Published)
        {
            return CourseErrors.CannotModifyPublishedLessons;
        }

        var lesson = _lessons.FirstOrDefault(l => l.Id == id);
        if (lesson is null)
        {
            return CourseErrors.LessonNotFound;
        }

        _lessons.Remove(lesson);
        return Result.Success();
    }
}
```

When a rule needs to span _two_ aggregates instead of one, that's a different problem, and I'd reach for a [**domain event**](how-to-use-domain-events-to-build-loosely-coupled-systems) rather than letting one aggregate reach into another.

## What You Actually Get

You can write the same system procedurally, and it can work well.
The thing you give up is **trust**.

In a procedural system, every caller shares responsibility for not breaking the rules.
In an always-valid model, that responsibility lives on the domain model.
The difference compounds over time:

- Validators don't drift, because there's nothing to duplicate.
- Code reviews focus on behavior instead of "did we forget a check?".
- New endpoints can't accidentally bypass a rule that lives on the entity.
- Tests stop covering scenarios that aren't even expressible.

The model goes from being a passive data carrier to being the smallest, sharpest place where the business rules live.

Fundamentally, this is about **encapsulation**.
The model encapsulates the rules that govern its state, and the rest of the system interacts with it through a well-defined interface.
That leads to cleaner code, fewer bugs, and a more maintainable system overall.

## Summary

An invariant is a rule that must always hold true while the object exists, and the cleanest place to enforce it is on the object itself.

- **Construction invariants** belong in a private constructor behind a factory.
- **State transition invariants** belong in methods that own the state they change.
- **Aggregate-wide invariants** belong on the root, with child entities accessed only through it.

The tradeoff is that you give up the freedom to write procedural code that could be easier to understand in the short term,
but you get a model that you can trust to always be valid.

If you want to go deeper into modeling aggregates, value objects, and rich behavior across a real system,
I think you will enjoy [**Pragmatic Domain-Driven Design**](/pragmatic-domain-driven-design).

See you next week.

---



<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!

---


Previous issues of The .NET Weekly