
<Sponsorships>

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


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

</Sponsorships>

Not every AI feature needs a dedicated vector database.

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

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

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

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

Let's dive in.

## What Is Vector Search?

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

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

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

When would you use this?

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

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

## Provisioning Infrastructure With .NET Aspire

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

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

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

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

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

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

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

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

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

## Configuring the API Project

The API project needs a few packages:

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

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

Register the services in `Program.cs`:

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

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

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

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

## Initializing the Database

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

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

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

    conn.ReloadTypes();

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

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

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

A few things to note:

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

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

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

## Generating and Storing Embeddings

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

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

    int count = 0;

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

        var embedding = await embeddingGenerator.GenerateAsync(content);

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

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

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

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

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

## Similarity Search With Cosine Distance

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

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

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

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

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

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

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

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

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

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

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

pgvector supports three distance operators:

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

Cosine distance is the most common choice for text embeddings.

## Summary

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

Here's what we covered:

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

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

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

Thanks for reading.

And stay awesome!

---



<Sponsorships>

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

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

</Sponsorships>

I ran into this one the hard way.

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

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

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

## Why SignalR Breaks When You Scale Out

With a single instance, everything just works.

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

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

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

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

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

## The Backplane Pattern

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

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

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

When Server 1 wants to notify Client 3:

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

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

## Setting It Up

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

### Install the NuGet Package

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

### Register the Backplane

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

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

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

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

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

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

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

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

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

## The Sticky Sessions Requirement

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

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

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

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

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

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

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

## What Happens When Redis Goes Down?

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

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

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

## Redis Backplane vs. Azure SignalR Service

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

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

## Summary

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

Just remember two things:

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

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

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

Hope this was useful. See you next week.

---



<Sponsorships>

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

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

</Sponsorships>

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

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

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

Let's go through each approach.

## The Scenario

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

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

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

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

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

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

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

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

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

await transaction.CommitAsync();
```

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

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

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

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

await using var db = new AppDbContext(options);

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

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

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

await db.SaveChangesAsync();
```

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

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

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

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

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

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

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

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

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

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

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

await transaction.CommitAsync();
```

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

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

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

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

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

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

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

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

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

await transaction.CommitAsync();
```

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

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

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

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

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

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

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

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

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

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

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

await transaction.CommitAsync();
```

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

## Approach 6: Dapper with UNNEST (PostgreSQL)

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

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

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

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

await transaction.CommitAsync();
```

This is my preferred approach when working with PostgreSQL:

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

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

## Approach 7: Temp Table + Binary COPY

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

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

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

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

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

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

await transaction.CommitAsync();
```

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

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

## Benchmark Results

Here are the numbers across all three batch sizes:

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

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

## Summary

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

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

A few things worth keeping in mind:

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

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

That's all for today.

See you next week.

---



<Sponsorships>

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

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

</Sponsorships>

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

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

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

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

## ArchUnitNET and the Test Setup

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

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

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

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

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

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

## 1. Layer Dependency Tests

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

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

So why bother with these tests?

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

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

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

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

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

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

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

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

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

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

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

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

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

Six tests, one for each illegal dependency direction.

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

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

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

## 2. Naming Convention Tests

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

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

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

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

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

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

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

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

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

## 3. Colocation Tests

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

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

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

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

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

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

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

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

                Type genericDef = iface.GetGenericTypeDefinition();

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

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

        return pairs;
    }
}
```

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

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

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

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

## 4. Visibility Tests

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

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

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

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

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

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

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

## 5. Dependency Guard Tests

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

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

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

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

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

Add whatever libraries make sense for your project.

## Summary

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

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

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

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

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

Thanks for reading.

And stay awesome!

---


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



<Sponsorships>

As AI moves into production, legacy identity becomes a bottleneck. Anonymous execution and static credentials don't scale.
Join Teleport's [**free Feb 19 webinar**](https://fandf.co/3MnTC71) to learn how to move faster with AI,
without compromising security or reliability.

NEW: Use [**Augment Code's Context Engine**](https://fandf.co/3MI2WTh) with your favorite models!
[**Connect via MCP**](https://fandf.co/4rfBsTX) to see how you can get faster, higher-quality results using fewer tokens.

</Sponsorships>

I wanted to see how well a **vision model** (LLM) could parse grocery receipts into structured data.

And I don't just mean describe what it sees.
I want to be able to actually extract line items, quantities, and prices into clean JSON.
Running entirely on my machine with [**Ollama**](https://ollama.com/) and a **llama3.2-vision** model.

It started as a quick experiment. I ended up spending a whole evening on it.

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

- Setting up Ollama with a vision model in .NET
- Sending images to the model and getting structured output
- Iterating on the system prompt to improve accuracy
- Deserializing LLM responses into strongly typed C# objects
- Testing whether the results are actually consistent

Let's dive in.

## Setting Up Ollama With Microsoft.Extensions.AI

[Ollama](https://ollama.com/) lets you run large language models locally.
You pull a model the same way you'd pull a Docker image, and it runs on your hardware.

```bash
ollama pull llama3.2-vision:latest

# Then run the model locally
ollama run llama3.2-vision:latest
```

On the .NET side, [**Microsoft.Extensions.AI**](https://learn.microsoft.com/en-us/dotnet/ai/ai-extensions)
provides a unified `IChatClient` interface for talking to any LLM provider.
Combined with [OllamaSharp](https://github.com/awaescher/OllamaSharp), the setup is minimal:

```csharp {3-6}
var builder = Host.CreateApplicationBuilder();

builder.Services.AddChatClient(
    new OllamaApiClient(
        new Uri("http://localhost:11434"),
        "llama3.2-vision:latest"));

var app = builder.Build();

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

That gives us an `IChatClient` backed by a local vision model.
You don't have to manage any API keys or cloud dependencies.

The nice thing about `IChatClient` is that it's **provider-agnostic**.
If you want to swap Ollama for OpenAI or Azure later, your application code doesn't change.

## Sending an Image to the Model

The simplest thing to try: send a receipt image and ask what's in it.

```csharp
var message = new ChatMessage(
    ChatRole.User, "What's in this image?");

message.Contents.Add(
    new DataContent(
        File.ReadAllBytes("receipts/receipt_1.png"),
        "image/png"));

var response = await chatClient.GetResponseAsync([message]);

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

You read the image bytes, wrap them in a `DataContent` with the appropriate MIME type, and attach it to a `ChatMessage`.

Here's the receipt I used for testing.

<div className="centered">
  <Image
    src="blogs/mnw_181/receipt_1.png"
    width={430}
    height={363}
    alt="A grocery receipt with line items, quantities, and prices."
  />
</div>

And here's the raw text response from the model:

```text
This image appears to be a receipt or invoice in a foreign language, likely Russian or another
Slavic language. The document is in black and white and features a large QR code at the bottom.
The text is in a blocky, old-style font and includes several columns of numbers and words.
The top of the page has a header with some information in a foreign language, followed by a
series of columns with various details such as date, time, and product information. The document
also includes some calculations and a total at the bottom. The overall design and layout suggest
that this is a receipt or invoice from a store or restaurant, but the specific details and
language make it difficult to understand without further context or translation.
```

The model correctly identified it as a receipt and listed the items on it.
That's impressive for a first try with zero fine-tuning.
But it's not very useful if we want to extract structured data.

The good thing is we can refine our prompt and ask for a more specific output format.

## Asking for JSON Output

A text description isn't very useful programmatically. So I asked for structured JSON instead:

```csharp
var message = new ChatMessage(ChatRole.User,
    @"""
    Extract all line items from this receipt.
    Respond in JSON format with this structure:
    {
        "items": [
            {
                "name": "item name",
                "quantity": 1.500,
                "unitPrice": 0.00,
                "totalPrice": 0.00
            }
        ],
        "subtotal": 0.00
    }
    """);
message.Contents.Add(
    new DataContent(
        File.ReadAllBytes("receipts/receipt_1.png"),
        "image/png"));

var response = await chatClient.GetResponseAsync([message]);

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

Here's the new response from the model:

```text
Here is the receipt in JSON format with all line items extracted:

{
    "items": [
        {
            "name": "limun /kg (A)",
            "quantity": 280.00,
            "unitPrice": 1.105,
            "totalPrice": 309.40
        },
        {
            "name": "salata /kom (A)",
            "quantity": 70.00,
            "unitPrice": 3.00,
            "totalPrice": 210.00
        },
        {
            "name": "susam 100g trpeza /kom (A)",
            "quantity": 90.00,
            "unitPrice": 1.00,
            "totalPrice": 90.00
        }
    ],
    "subtotal": 609.40
}
```

This worked surprisingly well on the first try.
The model returned a JSON blob with item names, quantities, and prices.
Some quantities were slightly off but the structure was correct.

For zero fine-tuning, I was impressed.

## Iterating on the System Prompt

Here's what I found: when the model misreads a digit or rounds a number, you don't fix a bug in C#.
You refine the system prompt.

What is a system prompt?
It's the initial instruction you give the model to set the context for the conversation.
Notice the `ChatRole.System` in the code below.
Conversely, we use `ChatRole.User` for the message where we ask the question.

After a few rounds of this, my system prompt ended up reading like a specification document:

```csharp
var systemMessage = new ChatMessage(ChatRole.System,
    @"""
    You are a receipt parsing assistant. Extract all line items from the receipt image.
    For each line item, extract the name, quantity, unit price, and total price.
    Quantity can be a decimal number (e.g. weight in kg like 0.550 or 1.105).
    Extract the subtotal which is the final total amount shown on the receipt.
    IMPORTANT: Read every digit exactly as printed on the receipt.
    Pay very close attention to each decimal digit - do NOT round or approximate.
    For example, if the receipt shows 1.105, report exactly 1.105, not 1.1 or 1.2.
    Verify that quantity * unitPrice = totalPrice for each line item.
    Don't invent items that aren't on the receipt.

    DECIMAL FORMAT: Receipts may use different number formats depending on locale.
    - Some use period as decimal separator: 7,499.00
    - Some use comma as decimal separator: 7.499,00
    First, detect which format the receipt uses by examining the numbers on it.
    Then, always output numbers in the JSON using a period as the decimal separator.
    For example: 7499.00, not 7.499,00 or 7,499.00.
    """);
```

Every instruction in that prompt exists because the model got something wrong.

"Read every digit exactly as printed": it was rounding `1.105` to `1.1`.

"Don't invent items": it hallucinated a line item that wasn't on the receipt.

The entire decimal format section: my receipts use commas as decimal separators (European locale),
and the model kept confusing thousands separators with decimal points.

Each prompt iteration is like a debugging session with words instead of code.
It's not the most fun part, but it's necessary to get accurate results.

And to think we used to write code to tell computers what to do.
Now we write prompts to tell models how to think.
I digress...

## Strongly Typed Responses

This is where [`Microsoft.Extensions.AI`](working-with-llms-in-dotnet-using-microsoft-extensions-ai) gets interesting.

Instead of parsing raw JSON strings yourself, you can call `GetResponseAsync<T>` and get back a **strongly typed** object:

```csharp {1, 5}
var response = await chatClient.GetResponseAsync<Receipt>(
    [systemMessage, message],
    new ChatOptions { Temperature = 0 });

if (response.Result is { } receipt)
{
    Console.WriteLine(
        $"\nExtracted {receipt.Items.Count} line items:");

    foreach (var item in receipt.Items)
    {
        Console.WriteLine(
            $"  {item.Name} - " +
            $"Qty: {item.Quantity} x {item.UnitPrice:C}" +
            $" = {item.TotalPrice:C}");
    }

    Console.WriteLine($"  Subtotal: {receipt.Subtotal:C}");
}
```

The `Receipt` and `LineItem` classes are plain C# objects:

```csharp
public class Receipt
{
    public List<LineItem> Items { get; set; } = [];
    public decimal Subtotal { get; set; }
}

public class LineItem
{
    public string Name { get; set; } = string.Empty;
    public decimal Quantity { get; set; }
    public decimal UnitPrice { get; set; }
    public decimal TotalPrice { get; set; }
}
```

The library generates the JSON schema, sends it to the model, and deserializes the response.
You get back a `Receipt` object directly.

I also set `Temperature = 0` to make the output as deterministic as possible.
For data extraction, you want accuracy.
This isn't foolproof, but it helps.

Here's the object we get back from the model in Visual Studio:

<Image
  src="blogs/mnw_181/chat_client_typed_response_in_vs.png"
  width={986}
  height={528}
  alt="Visual Studio screenshot showing the Receipt object with line items and subtotal extracted from the model response."
/>

## Testing Consistency

One thing I wanted to verify: if I send the same receipt with the same prompt five times, do I get the same result?

```csharp
const int runs = 5;
Console.WriteLine($"\n--- Consistency test ({runs} runs) ---");

var results = new List<Receipt>();
for (int i = 0; i < runs; i++)
{
    Console.WriteLine($"\nRun {i + 1}...");
    var testResponse = await chatClient.GetResponseAsync<Receipt>(
        [systemMessage, message],
        new ChatOptions { Temperature = 0 });

    if (testResponse.Result is { } r)
    {
        results.Add(r);
        Console.WriteLine(
            $"  Items: {r.Items.Count}, " +
            $"Subtotal: {r.Subtotal:C}");

        foreach (var item in r.Items)
        {
            Console.WriteLine(
                $"    {item.Name} - " +
                $"Qty: {item.Quantity} x {item.UnitPrice:C}" +
                $" = {item.TotalPrice:C}");
        }
    }
}
```

Then I compare every run against the baseline:

```csharp
var baseline = results[0];
for (int i = 1; i < results.Count; i++)
{
    bool match = baseline.Subtotal == results[i].Subtotal
        && baseline.Items.Count == results[i].Items.Count
        && baseline.Items.Zip(results[i].Items).All(pair =>
            pair.First.Name == pair.Second.Name
            && pair.First.Quantity == pair.Second.Quantity
            && pair.First.UnitPrice == pair.Second.UnitPrice
            && pair.First.TotalPrice == pair.Second.TotalPrice);

    Console.WriteLine(
        $"  Run 1 vs Run {i + 1}: " +
        $"{(match ? "MATCH" : "DIFFERENT")}");
}
```

Temperature 0 helps, but vision models aren't perfectly deterministic.
Most runs matched. Some didn't.
The differences were usually small - a misread digit, a slightly different item name.

This is worth keeping in mind when working with LLMs.
They're probabilistic systems.
Even with temperature 0, the same input can produce slightly different output.
If you need guaranteed accuracy, you'll want validation layers on top of this.

## Where I Want to Take This

The receipt scanner is a starting point.
Once you have structured data from receipt images, you can build on top of it.

I've been thinking about extending this into a **personal finance tracker**.
Scan receipts, store the data, and use the same LLM to categorize purchases.
Groceries, household, electronics - let the model figure it out.

From there, you could generate **weekly and monthly spending summaries**.
How much did I spend on groceries this month?
How does that compare to last month?

You could also do **multi-receipt aggregation** for business trips.
Scan a stack of receipts and generate an expense report.

Or **price tracking** over time - detect when items at your usual store go up in price.

We could defintiely build [**semantic search**](building-semantic-search-with-amazon-s3-vectors-and-semantic-kernel)
on top of this too.
Search through your past receipts for specific items or price ranges.
This works by embedding the structured data and using [**vector search**](what-is-vector-search-a-concise-guide)
to find relevant entries.

The vision model handles the hard part: turning unstructured images into structured data.
Everything after that is regular application development.

I might build some of this out. We'll see.

## Summary

Running a vision model locally with Ollama is straightforward to set up.
`Microsoft.Extensions.AI` and `OllamaSharp` make the .NET integration clean.
You get a provider-agnostic `IChatClient` with support for strongly typed responses.
You could also run this with [**Aspire and GitHub models**](building-generative-ai-applications-with-github-models-and-dotnet-aspire)
if you want to keep everything in the Microsoft ecosystem.

The system prompt is where most of the work happens.
Every line in mine was the result of the model getting something wrong and me adding a corrective instruction.

If you want to try this yourself:

1. Install [Ollama](https://ollama.com/)
2. Pull the vision model: `ollama pull llama3.2-vision:latest`
3. Create a .NET console app and add the `OllamaSharp` and `Microsoft.Extensions.AI` NuGet packages
4. Point it at a receipt and see what comes back

Hope this was useful. See you next week.

---



<Sponsorships>

[**NServiceBus**](https://particular.net/pricing/small-business-program?utm_source=newsletter1&utm_medium=email&utm_campaign=spb_promotion) -
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=newsletter1&utm_medium=email&utm_campaign=spb_promotion)
today!

[**OutSystems**](https://fandf.co/45RwwfE) is hosting a [**$1,000 Groundhog Day AI Challenge**](https://fandf.co/45RwwfE)
that tests real development skills. Your challenge?
Progress from UI-level puzzle solving to using AI inside the IDE,
and race to save Phil the Groundhog faster than anyone else.

</Sponsorships>

**Authentication** is one of those things that's easy to get wrong and **expensive to fix later**.
Rolling your own auth system means dealing with password hashing, token management, session handling,
and a never-ending stream of security patches.

I was never a fan of this...

What if you could outsource all of that to a battle-tested **identity provider**?

[Keycloak](https://www.keycloak.org/) is an open-source identity and access management solution.
It handles user authentication, authorization, and identity brokering (social logins, enterprise SSO) out of the box.
You get a polished admin console, built-in support for **OAuth 2.0** and **OpenID Connect**, and it runs anywhere Docker does.

We'll spin up Keycloak as a container, create a realm with a public client,
and wire up Swagger UI to authenticate using the [OAuth 2.0](https://oauth.net/2/) **Authorization Code flow**.
Then we'll add [JWT](https://www.rfc-editor.org/rfc/rfc7519.html) validation to our .NET backend and
trace the entire authentication flow using the [**Aspire Dashboard**](standalone-aspire-dashboard-setup-for-distributed-dotnet-applications).

## Running Keycloak as a Container

The fastest way to spin up **Keycloak** is with [Docker](<https://en.wikipedia.org/wiki/Docker_(software)>).
We'll run it in development mode, which disables HTTPS and uses an embedded H2 database.
This is perfect for local development but **not suitable for production** (more on that later).

Here's a minimal `docker-compose.yml`:

```yaml
services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.5.2
    container_name: keycloak
    environment:
      - KC_BOOTSTRAP_ADMIN_USERNAME=admin
      - KC_BOOTSTRAP_ADMIN_PASSWORD=admin
    ports:
      - '8080:8080'
    command: start-dev
```

Start it with:

```bash
docker compose up -d
```

Once Keycloak is running, navigate to `http://localhost:8080` and log in with `admin` / `admin`.

<Image
  src="blogs/mnw_180/keycloak_admin_login.png"
  width={1919}
  height={1079}
  alt="The Keycloak admin login screen with username and password fields."
/>

You should see the Keycloak admin console.

<Image
  src="blogs/mnw_180/keycloak_admin_console.png"
  width={1919}
  height={1079}
  alt="The Keycloak admin console showing the master realm dashboard."
/>

## Setting Up a Realm and Client

Keycloak organizes everything into **realms**.
A realm is a space where you manage users, roles, and applications.
The `master` realm is reserved for Keycloak administration, so we'll create a new one for our application.

### Creating a Realm

1. Click the **Manage Realms** button in the top-left corner
2. Click **Create realm**
3. Enter a name (e.g., `keycloak-demo`) and click **Create**

<Image
  src="blogs/mnw_180/keycloak_create_realm_dialog.png"
  width={1117}
  height={809}
  alt="The Keycloak create realm dialog with 'demo' entered as the realm name."
/>

### Creating a Public Client

Now we need to register our application.
In OAuth 2.0 terms, this is a **client**.
Since Swagger UI runs in the browser, we'll create a **public client** (no client secret).

1. Go to **Clients** → **Create client**
2. Set **Client ID** to `demo-api`
3. Leave **Client type** as `OpenID Connect`
4. Click **Next**

<Image
  src="blogs/mnw_180/keycloak_create_client_step1.png"
  width={1919}
  height={1079}
  alt="The first step of creating a client in Keycloak, showing the Client ID field."
/>

5. Enable **Client authentication**: Off (public client)
6. Check **Standard flow** (Authorization Code)
7. Choose **PKCE Method**: S256 (SHA-256)
8. Click **Next**

<Image
  src="blogs/mnw_180/keycloak_create_client_step2.png"
  width={1919}
  height={1079}
  alt="The second step of creating a client showing authentication settings."
/>

9. Configure the redirect URIs:
   - **Valid redirect URIs**: `https://localhost:5001/*` (your API's Swagger URL)
   - **Web origins**: `https://localhost:5001`
10. Click **Save**

<Image
  src="blogs/mnw_180/keycloak_create_client_step3.png"
  width={1919}
  height={1079}
  alt="The third step showing redirect URI configuration."
/>

### Creating a Test User

We need a user to authenticate with.

1. Go to **Users** → **Add user**
2. Fill in the details (username, email, etc.)
3. Leave **Email Verified** checked to avoid email confirmation
4. Click **Create**
5. Go to the **Credentials** tab
6. Click **Set password** and create a password (disable "Temporary")

<Image
  src="blogs/mnw_180/keycloak_create_user.png"
  width={1919}
  height={1079}
  alt="The Keycloak user creation form."
/>

You're now ready to authenticate users against Keycloak!

## The Authorization Code Flow

Before we dive into code, let's understand what happens when a user authenticates.
The [**Authorization Code flow**](https://www.rfc-editor.org/rfc/rfc6749#section-4.1) is the recommended OAuth 2.0 flow for browser-based applications.

There's an important security enhancement called **PKCE** ([Proof Key for Code Exchange](https://www.rfc-editor.org/rfc/rfc7636))
that prevents authorization code interception attacks.
It works by having the client generate a random secret (the code verifier) and deriving a hash (the code challenge) sent in the initial authorization request.
When exchanging the authorization code for tokens, the client must present the original code verifier.

Here's the sequence:

<Image
  src="blogs/mnw_180/authorization_code_flow.png"
  width={2725}
  height={2208}
  alt="A sequence diagram showing the OAuth 2.0 Authorization Code flow between Browser, API, and Keycloak."
/>

1. **User clicks "Authorize"** in Swagger UI
2. **Browser redirects** to Keycloak's authorization endpoint
3. **User logs in** at Keycloak
4. **Keycloak redirects back** with an authorization code
5. **Swagger UI exchanges** the code for tokens (access token, refresh token, ID token)
6. **Swagger UI attaches** the access token to API requests
7. **API validates** the token signature and claims

The beauty of this flow is that credentials never touch your application.
The user authenticates directly with Keycloak, and your API only sees signed tokens.

## Configuring Swagger UI with OAuth 2.0

Now let's set up our .NET API to use Swagger UI as our OAuth 2.0 test client.

First, install the required packages:

```bash
dotnet add package Swashbuckle.AspNetCore
```

Configure Swagger in your `Program.cs`:

```csharp
var keycloakAuthority = builder.Configuration["Keycloak:Authority"]!;
var keycloakClientId = builder.Configuration["Keycloak:ClientId"]!;

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Demo API",
        Version = "v1"
    });

    // Define the OAuth 2.0 security scheme
    options.AddSecurityDefinition(nameof(SecuritySchemeType.OAuth2), new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.OAuth2,
        Flows = new OpenApiOAuthFlows
        {
            AuthorizationCode = new OpenApiOAuthFlow
            {
                AuthorizationUrl = new Uri($"{keycloakAuthority}/protocol/openid-connect/auth"),
                TokenUrl = new Uri($"{keycloakAuthority}/protocol/openid-connect/token"),
                Scopes = new Dictionary<string, string>
                {
                    { "openid", "OpenID Connect scope" },
                    { "profile", "User profile" }
                }
            }
        }
    });

    // Apply security to all operations
    options.AddSecurityRequirement(doc => new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecuritySchemeReference(nameof(SecuritySchemeType.OAuth2), doc),
            []
        }
    });
});
```

And configure the Swagger UI middleware:

```csharp
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.OAuthClientId(keycloakClientId); // Default Client ID
        options.OAuthUsePkce(); // Proof Key for Code Exchange (security enhancement)
    });
}
```

Your `appsettings.Development.json`:

```json
{
  "Keycloak": {
    "Authority": "http://localhost:8080/realms/keycloak-demo",
    "ClientId": "demo-api",
    "Audience": "account",
    "Issuer": "http://localhost:8080/realms/keycloak-demo",
    // Here we use the Docker service name for Keycloak
    "MetadataAddress": "http://keycloak:8080/realms/keycloak-demo/.well-known/openid-configuration"
  }
}
```

Now when you open Swagger UI, you'll see an **Authorize** button.
Clicking it opens the OAuth flow, redirecting you to Keycloak to log in.

<Image
  src="blogs/mnw_180/swagger_authorize_form.png"
  width={1919}
  height={1079}
  alt="Swagger UI showing the Authorize form for OAuth 2.0."
/>

## Adding JWT Validation

At this point, Swagger UI can obtain tokens, but our API isn't validating them yet.
Let's add JWT Bearer authentication.

Install the authentication package:

```bash
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
```

Configure authentication in `Program.cs`:

```csharp
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.MetadataAddress = builder.Configuration["Keycloak:MetadataAddress"]!;
        options.Audience = builder.Configuration["Keycloak:Audience"];

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidIssuer = builder.Configuration["Keycloak:Issuer"]
        };

        // Required for HTTP in development (Keycloak uses HTTP by default in dev mode)
        options.RequireHttpsMetadata = !builder.Environment.IsDevelopment();
    });

builder.Services.AddAuthorization();
```

The default `TokenValidationParameters` will validate the token signature, expiration, issuer, and audience.

Add the middleware:

```csharp
app.UseAuthentication();
app.UseAuthorization();
```

Create a protected endpoint:

```csharp
app.MapGet("users/me", (ClaimsPrincipal user) =>
{
    return Results.Ok(new
    {
        UserId = user.FindFirstValue(ClaimTypes.NameIdentifier),
        Email = user.FindFirstValue(ClaimTypes.Email),
        Name = user.FindFirstValue("preferred_username"),
        Claims = user.Claims.Select(c => new { c.Type, c.Value })
    });
})
.RequireAuthorization();
```

## How JWT Validation Works

When a request hits your protected endpoint, here's what happens under the hood:

<Image
  src="blogs/mnw_180/jwt_validation_flow.png"
  width={2030}
  height={2108}
  alt="A sequence diagram showing how JWT validation works in ASP.NET Core."
/>

1. **Middleware extracts** the `Authorization: Bearer <token>` header
2. **JWT Handler fetches** Keycloak's public keys from the JWKS endpoint (cached)
3. **Signature validation** proves the token wasn't tampered with
4. **Claims are extracted** and the `ClaimsPrincipal` is populated
5. **Authorization middleware** checks if the user meets the endpoint requirements
6. **Endpoint executes** with access to `HttpContext.User`

The key insight here is that your API **never contacts Keycloak** to validate individual tokens.
It fetches the signing keys once and validates tokens locally.
This is what makes JWT-based authentication so fast.

## Observing the Flow with Aspire Dashboard

If you're using [**Aspire**](https://aspire.dev), you can observe the entire authentication flow in the distributed traces.

Here's what a successful authentication looks like:

<Image
  src="blogs/mnw_180/aspire_auth_trace.png"
  width={1919}
  height={1079}
  alt="Aspire Dashboard showing a distributed trace of the authentication flow."
/>

You can see:

1. The initial request to `users/me` (with the Bearer token)
2. The outbound call to Keycloak's `.well-known/openid-configuration` endpoint
3. The outbound call to Keycloak's JWKS endpoint (fetching signing keys)
4. The response back to the client

On subsequent requests, you won't see the JWKS call because the keys are cached.

This is why JWT validation adds virtually no latency after the initial key fetch.

## Production Considerations

What we've built is great for development.
For production, you'll want to address a few things:

**1. HTTPS Everywhere**

Keycloak should run behind HTTPS.
Set `KC_HOSTNAME` and configure TLS certificates.

**2. Persistent Storage**

Replace the embedded H2 database with PostgreSQL or MySQL:

```yaml
environment:
  - KC_DB=postgres
  - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
  - KC_DB_USERNAME=keycloak
  - KC_DB_PASSWORD=secret
```

**3. Require HTTPS Metadata**

Remove `options.RequireHttpsMetadata = false` in production.

## Summary

In about 10 minutes, we've set up:

- A [**containerized**](containerize-your-dotnet-applications-without-a-dockerfile) Keycloak instance
- A realm with a public OAuth 2.0 client
- Swagger UI acting as an OAuth client with Authorization Code + PKCE
- JWT validation in ASP.NET Core
- Observability with [**OpenTelemetry**](introduction-to-distributed-tracing-with-opentelemetry-in-dotnet) into the authentication flow

What I really like about Keycloak is how easy it is to extend.
Want Google login? Configure it in Keycloak.
Need enterprise SSO? Add a SAML provider.
Your API code stays exactly the same because it just validates tokens.

If you want to see how I integrate Keycloak in a real-world system with role-based access control,
check out [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture) and
[**Modular Monolith Architecture**](/modular-monolith-architecture).

See you next week.

---


<Sponsorships>

Developers report that [**over 40% of committed code is now AI-assisted**](https://fandf.co/4qexwBR), yet they still spend about 25% of their week on toil.
Sonar's new developer survey shows AI didn't eliminate work; it shifted it into reviewing, fixing, and verifying code that looks correct but isn't.
[**Download the report**](https://fandf.co/4qexwBR) to understand why your workload feels the same, just harder to reason about.
(No form fill required.)

[**Webinar: How to Build Faster with AI Agents**](https://www.telerik.com/webinars/devcraft/ai-for-developers-how-to-achieve-a-50-percent-productivity-boost?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_ai_productivity_webinar_bitovi)
Learn how full-stack developers boost productivity by 50% with AI agents that automate layout,
styling, and component generation through RAG and LLM pipelines.
See how orchestration and spec-driven workflows keep you in control of quality and consistency.
[**Check it out**](https://www.telerik.com/webinars/devcraft/ai-for-developers-how-to-achieve-a-50-percent-productivity-boost?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_ai_productivity_webinar_bitovi)

</Sponsorships>

Containers have become the standard for deploying modern applications.
But if you've ever written a [Dockerfile](https://docs.docker.com/reference/dockerfile/), you know it can be tedious.
You need to understand multi-stage builds, pick the right base images, configure the right ports, and remember to copy files in the correct order.

What if I told you that **you don't need a Dockerfile at all**?

Since .NET 7, the SDK has built-in support for publishing your application directly to a container image.
You can do this with a single `dotnet publish` command.

In this week's newsletter, we'll explore:

- Why Dockerfile-less publishing matters
- How to enable container publishing in your project
- Customizing the container image
- Publishing to container registries
- **How I'm using this to deploy to a VPS**

## The Traditional Approach: Writing a Dockerfile

Before we look at the SDK approach, let's see what we're replacing.

A typical multi-stage Dockerfile for a .NET application looks like this:

```bash
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["src/MyApi/MyApi.csproj", "src/MyApi/"]
RUN dotnet restore "src/MyApi/MyApi.csproj"

COPY . .
WORKDIR "/src/src/MyApi"
RUN dotnet build "MyApi.csproj" -c $BUILD_CONFIGURATION  -o /app/build

FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish "MyApi.csproj" -c $BUILD_CONFIGURATION -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyApi.dll"]
```

This works, but there's a learning curve and maintenance overhead:

- **Maintenance burden**: You need to update base image tags manually
- **Layer caching**: Getting the COPY order wrong kills your build cache
- **Duplication**: Every project needs a similar Dockerfile
- **Context switching**: You're writing Docker DSL, not .NET code

The .NET SDK approach eliminates all of this.

## Enabling Container Publishing

If you're running on .NET 10, you don't need to do anything special to enable container publishing.
This will work for ASP.NET Core apps, worker services, and console apps.

You can publish directly to a container image:

```bash
dotnet publish --os linux --arch x64 /t:PublishContainer
```

That's it. The .NET SDK will:

1. Build your application
2. Select the appropriate base image
3. Create a container image with your published output
4. Load it into your local OCI-compliant daemon

The most popular option is Docker, but it also works with Podman.

<Image
  src="blogs/mnw_179/dotnet_publish_container.png"
  width={1891}
  height={457}
  alt="An image showing the output of the dotnet publish command creating a container image."
/>

## Customizing the Container Image

The SDK provides sensible defaults, but you'll often want to customize the image.
For a more comprehensive list of options, see the [official docs](https://learn.microsoft.com/en-us/dotnet/core/containers/publish-configuration).

I'll cover the most common customizations here.

### Setting the Image Name and Tag

The `ContainerRepository` property sets the image name (repository).
The `ContainerImageTags` property sets one or more tags (separated by semicolons).
If you want a single tag, you can use `ContainerImageTag` instead.

```xml
<PropertyGroup>
  <ContainerRepository>ghcr.io/USERNAME/REPOSITORY</ContainerRepository>
  <ContainerImageTags>1.0.0;latest</ContainerImageTags>
</PropertyGroup>
```

From .NET 8 and onwards, when a tag isn't provided the default is `latest`.

### Choosing a Different Base Image

By default, the SDK uses the following base images:

- `mcr.microsoft.com/dotnet/runtime-deps` for self-contained apps
- `mcr.microsoft.com/dotnet/aspnet` image for ASP.NET Core apps
- `mcr.microsoft.com/dotnet/runtime` for other cases

You can switch to a smaller or different image:

```xml
<PropertyGroup>
  
  <ContainerBaseImage>mcr.microsoft.com/dotnet/aspnet:10.0-alpine</ContainerBaseImage>
</PropertyGroup>
```

You could also do this by setting `ContainerFamily` to `alpine`, and letting the rest be inferred.

Here's the size difference between the default and Alpine images for an ASP.NET Core app:

<Image
  src="blogs/mnw_179/container_image_size.png"
  width={1623}
  height={409}
  alt="An image showing the size difference between the default and Alpine base images for ASP.NET Core applications."
/>

```text
| Base Image                                  | Size (MB) |
| ------------------------------------------- | --------- |
| mcr.microsoft.com/dotnet/aspnet:10.0        | 231.73    |
| mcr.microsoft.com/dotnet/aspnet:10.0-alpine | 122.65    |
```

You can see a significant size reduction by switching to `alpine`.

### Configuring Ports

For web applications, the default exposed ports are `8080` and `8081` for HTTP and HTTPS.
These are inferred from ASP.NET Core environment variables (`ASPNETCORE_URLS`, `ASPNETCORE_HTTP_PORT`, `ASPNETCORE_HTTPS_PORT`).
The `Type` attribute can be `tcp` or `udp`.

```xml
<ItemGroup>
  <ContainerPort Include="8080" Type="tcp" />
  <ContainerPort Include="8081" Type="tcp" />
</ItemGroup>
```

## Publishing to a Container Registry

Publishing locally is useful for development, but you'll want to push to a registry for deployment.
You can specify the target registry during publishing.

Here's an example publishing to GitHub Container Registry:

```bash
dotnet publish --os linux --arch x64  /t:PublishContainer /p:ContainerRegistry=ghcr.io
```

**Authentication**: The SDK uses your local Docker credentials.
Make sure you've logged in with `docker login` before publishing to a remote registry.

However, **I don't use the above approach**.
I prefer using docker CLI for the publishing step, as it gives me more control over authentication and tagging.

## CI/CD Integration

Here's what I'm doing in my [**GitHub Actions workflow**](how-to-build-ci-cd-pipeline-with-github-actions-and-dotnet) to build and push my .NET app container.
I left out the boring bits of seting up the .NET environment and checking out code.

This will build the container image, tag it, and push it to [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry):

```yaml
- name: Publish
  run: dotnet publish "${{ env.WORKING_DIRECTORY }}" --configuration ${{ env.CONFIGURATION }} --os linux -t:PublishContainer
# Tag the build for later steps
- name: Log in to ghcr.io
  run: echo "${{ env.DOCKER_PASSWORD }}" | docker login ghcr.io -u "${{ env.DOCKER_USERNAME }}" --password-stdin
- name: Tag Docker image
  run:
    docker tag ${{ env.IMAGE_NAME }}:${{ github.sha }} ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:${{ github.sha }} |
    docker tag ${{ env.IMAGE_NAME }}:latest ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:latest
- name: Push Docker image
  run:
    docker push ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:${{ github.sha }} |
    docker push ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:latest
```

Once my images are up in the registry, I can deploy them to my VPS.

I'm using [Dokploy](https://dokploy.com/) (a simple but powerful deployment tool for Docker apps) to pull the latest image and restart my service.

```yaml
deploy:
  runs-on: ubuntu-latest
  needs: build-and-publish
  steps:
    - name: Trigger deployment
      run: |
        curl -X POST ${{ env.DEPLOYMENT_TRIGGER_URL }} \
          -H 'accept: application/json' \
          -H 'Content-Type: application/json' \
          -H 'x-api-key: ${{ env.DEPLOYMENT_TRIGGER_API_KEY }}' \
          -d '{
            "applicationId": "${{ env.DEPLOYMENT_TRIGGER_APP_ID }}"
          }'
```

This kicks off a deployment on my VPS, pulling the latest image and restarting the container.

<Image
  src="blogs/mnw_179/dokploy_deployment.png"
  width={1206}
  height={833}
  alt="An image showing the output of the dokploy deployment command restarting the container."
/>

By the way, I'm running my VPS on [Hetzner Cloud](https://www.hetzner.com/cloud) - highly recommended if you're looking for affordable and reliable VPS hosting.

## When You Still Need a Dockerfile

The SDK container support is powerful, but it doesn't cover every scenario.

You'll still need a Dockerfile when:

- **Installing system dependencies**: If your app needs native libraries (like `libgdiplus` for image processing)
- **Complex multi-stage builds**: When you need to run custom build steps
- **Non-.NET components**: If your container needs additional services or tools

For most web APIs and background services, the SDK approach is sufficient.

## Summary

The .NET SDK's built-in container support removes the friction of containerization.

You get:

- **No Dockerfile to maintain** - one less file to worry about
- **Automatic base image selection** - always uses the right image for your framework version
- **MSBuild integration** - configure everything in your `.csproj`
- **CI/CD friendly** - works anywhere `dotnet` runs

The days of copy-pasting Dockerfiles between projects are over.

Just enable the feature, customize what you need, and publish.

Thanks for reading.

And stay awesome!

---


<Sponsorships>

[**Push updates live faster with RunPod**](https://fandf.co/4aVMokD)\
Spin up compute and storage in seconds with RunPod.
Deploy serverless inference that scales automatically, with no manual tuning or capacity planning.
Push updates live, iterate fast, and monitor everything in one place with logs, and metrics built in.
RunPod is infrastructure for AI startups and technical teams who want to stay in flow, move fast,
and spend less time on cloud plumbing and more time shipping real products.
[**Explore Runpod**](https://fandf.co/4aVMokD)

[**Data Engineering Design Patterns - Book Giveaway from Buf**](https://fandf.co/49GvtA9)\
Buf Schema Registry brings type safety to data pipelines with Protobuf.
Manage schemas centrally, validate changes, and generate Python code automatically.
Plus: Buf is giving away an O'Reilly Media book, Data Engineering Design Patterns with proven solutions to
idempotency, error handling, observability challenges and more.
[**Get your copy now**](https://fandf.co/49GvtA9).

</Sponsorships>

Security requirements evolve.
What was considered "secure enough" five years ago might not pass a security audit today.

You need to upgrade to a modern algorithm like [Argon2](https://en.wikipedia.org/wiki/Argon2) or [Bcrypt](https://en.wikipedia.org/wiki/Bcrypt).
But here is the problem: hashing is a **one-way operation**.
You cannot reverse-engineer the existing hashes to "upgrade" them.

If you simply swap your `IPasswordHasher` implementation, you break the application.
Every single existing user who tries to log in will fail authentication because your new hasher doesn't understand the old format.

In this article, I want to demo a **zero-downtime migration** concept in practice.

Real systems have more constraints (and you should not build auth from scratch).
But this is a clean example of a **pattern** you can reuse for [**database migrations**](efcore-migrations-a-detailed-guide):

- Move from old format to new format
- Keep existing behavior working
- Gradually migrate data
- Delete legacy only when you are done

Let's dive in.

## The Naive Approach and Why It Fails

Let's imagine you have a simple authentication system.
You want to replace your legacy `PBKDF2` hasher with a standard `Argon2` implementation.

You might think, "I'll just register the new implementation in the dependency injection container."

```csharp
// Switching from LegacyHasher to ModernHasher
builder.Services.AddSingleton<IPasswordHasher, ModernHasher>();
```

Here is the failure scenario:

1. **New Users:** They register and log in perfectly.
   Their passwords are hashed with Argon2 from day one.
2. **Existing Users:** A user enters their correct password.
   The system fetches the _old_ [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) hash from the database.
3. **The Crash:** The `ModernHasher` tries to verify the PBKDF2 hash.
   It fails immediately, returning `401 Unauthorized`.

You have inadvertently locked out your entire user base.
We need a way to support _both_ algorithms simultaneously without making the login code a mess.

## The Solution: Migration on Login

The strategy is simple: we don't migrate the database in a batch job.
We migrate users lazily when they prove their identity.

The flow looks like this:

1. **Attempt 1:** Try to verify the password using the **New** algorithm.
2. **Attempt 2 (Fallback):** If that fails, check if the **Legacy** algorithm can verify it.
3. **The Migration:** If the _Legacy_ verification succeeds:
   - Log the user in (Success).
   - **Immediately re-hash** their password using the **New** algorithm.
   - Update the database record.

Future logins for this user will now succeed via the standard flow.

<Image
  src="blogs/mnw_178/migration_on_login_flow.png"
  width={959}
  height={1189}
  alt="A sequence diagram showing the migration on login flow, with attempts to verify using new and legacy hashers."
/>

## Implementation with .NET Keyed Services

In .NET 8, Microsoft introduced **Keyed Services**, which are perfect for this scenario.
They allow us to register multiple implementations of the same interface and retrieve them by name.

### 1. Registering the Services

We register both hashers in our `Program.cs`, assigning them unique keys:

```csharp
// Register the implementations with specific keys
builder.Services.AddKeyedSingleton<IPasswordHasher, Pbdkf2PasswordHasher>("legacy");
builder.Services.AddKeyedSingleton<IPasswordHasher, Argon2PasswordHasher>("modern");

// (Optional) Register the modern one as the default for other services
builder.Services.AddSingleton<IPasswordHasher, Argon2PasswordHasher>();
```

### 2. The Login Command Handler

Now we implement the migration logic.
We inject both hashers using the `[FromKeyedServices]` attribute.

```csharp
public class LoginCommandHandler(
    IUserRepository userRepository,
    [FromKeyedServices("modern")] IPasswordHasher newHasher,
    [FromKeyedServices("legacy")] IPasswordHasher legacyHasher)
{
    public async Task<AuthenticationResult> Handle(LoginCommand command)
    {
        var user = await userRepository.GetByEmailAsync(command.Email);
        if (user is null)
        {
            return AuthenticationResult.Fail();
        }

        // 1. Try the new algorithm first (Happy Path)
        if (newHasher.Verify(user.PasswordHash, command.Password))
        {
            return AuthenticationResult.Success(user);
        }

        // 2. Fallback: Check if it's a legacy hash
        if (legacyHasher.Verify(user.PasswordHash, command.Password))
        {
            // 3. MIGRATION STEP: Re-hash and save
            var newHash = newHasher.Hash(command.Password);

            user.UpdatePasswordHash(newHash);
            await userRepository.SaveChangesAsync();

            return AuthenticationResult.Success(user);
        }

        return AuthenticationResult.Fail();
    }
}

```

This code ensures that active users are automatically upgraded.
After a few months, the vast majority of your user base will be on the new algorithm.

## Real-World Improvements

While the implementation above works, here are two improvements to make it production-ready.

### 1. Algorithm Prefixes

Relying on "trial and error" verification works, but it's cleaner to know exactly which algorithm was used to create a hash.

Standard algorithms often include a prefix (e.g., Bcrypt starts with `$2a$` or `$2b$`).
You can use this to route the request efficiently:

```csharp
public bool IsLegacyHash(string hash)
{
    // This assumes we're storing a prefix for PBKDF2 hashes. Something to consider.
    return hash.StartsWith("pbkdf2$");
}
```

Another benefit this unlocks is being able to query the database for users still on the legacy format.

### 2. Feature Flags

Performing a database write during a login request adds latency.
If you have high traffic, you might want to control this roll-out.

By wrapping the migration logic behind a [**Feature Flag**](feature-flags-in-dotnet-and-how-i-use-them-for-ab-testing), you can disable the "write" step if your database comes under load,
while still allowing users to log in via the read-only fallback.

```csharp
if (await featureManager.IsEnabledAsync(FeatureFlags.MigratePasswords) &&
    legacyHasher.Verify(user.PasswordHash, command.Password))
{
    // Perform migration...
}
```

## Finishing the Migration

After you run this for a while (usually a few months), most active accounts will be upgraded.
You can then run a cleanup script to identify any remaining legacy hashes and force those users to reset their passwords on the next login attempt.

At that point, you can remove:

- The legacy hasher registration
- The legacy verification code path
- The feature flag

And the migration is complete.

## Summary

A "simple" hashing upgrade is really a **data migration**.
This article is about the migration pattern.
Not about reinventing auth.

The **zero-downtime pattern** looks like this:

1. New format for new writes
2. Support both formats for reads
3. Migrate old data gradually (migrate-on-login is a great trick)
4. Put it behind a feature flag
5. Delete legacy when you are done

By allowing the old and new formats to coexist for a period of time, you achieve a seamless transition.
Once your monitoring shows that 99% of active users have migrated,
you can identify the users on the legacy format and force a password reset on their next attempt.

If you want to see a practical demo of this, [**check out this video I made**](https://youtu.be/7YUV4O9eMjQ).

Hope this was helpful!

---


Previous issues of The .NET Weekly