And most of what runs on a server was never built to play it. The database. The admin panel. The metrics dashboard. The internal API only your other services call.

None of that is meant for the public. Yet the standard tutorial hands each one a public port anyway, and with it a second job: certificates, login pages, IP allowlists, and bots probing around the clock.

There's a better default: keep those services private, reachable only by you and by each other, and expose nothing. This issue shows you how, using Tailscale.

What Tailscale Actually Is

A VPN (virtual private network) is an encrypted tunnel between machines over the public internet. Traffic inside it stays private, even across networks you don't control.

Tailscale uses that idea to connect your own machines (PCs, servers, phones) into a single private network only your devices can see, called a tailnet. It runs on WireGuard, a modern, heavily audited encryption protocol, and manages all the keys and addresses for you.

The shape is what sets it apart from an old-school VPN. A traditional VPN is hub and spoke: every device dials one central server, and all traffic funnels through it. Tailscale builds a mesh, where every device connects directly to every other device over its own encrypted tunnel.

No server sits in the traffic path. Your app-to-database traffic takes the shortest route between the boxes, and there's nothing to babysit.

How do devices find each other with no server in the middle? Tailscale splits the job: a coordination server keeps a directory of your devices and their keys (a phone book), while your actual data flows directly between devices, encrypted end to end.

The key property: devices only ever dial outward, to the coordination server and to each other. Nothing has to connect inward, which is what lets us close every firewall port next.

Connecting Two VPSs With Zero Open Ports

Installing Tailscale is two commands per machine (plus the app on your PC):

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Open the login URL it prints, approve the device, and it joins your tailnet with a stable private IP (in the 100.x.y.z range) and a name that never change, on any network.

Here's the setup we'll build:

• vps-app (100.64.0.2) runs a .NET API in Docker.
• vps-data (100.64.0.3) runs Postgres and Grafana in Docker.
• The API queries Postgres across the boxes, you reach everything from your PC, and the internet sees none of it.

Close the firewall. Because Tailscale only dials outward, your cloud firewall needs no inbound rules to reach these boxes. Confirm SSH works over the tailnet, then delete the public port-22 rule so SSH stops existing as far as the internet is concerned.

Bind services to the tailnet IP. This is the step that makes "zero open ports" true. Publishing a Docker port the usual way (-p 5432:5432) binds it to 0.0.0.0, every interface. Publish private services on the tailnet IP only instead. On vps-data:

services:
  postgres:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - '100.64.0.3:5432:5432'   # tailnet IP, not 0.0.0.0
    volumes:
      - pgdata:/var/lib/postgresql/data

  grafana:
    image: grafana/grafana:12.1.0
    restart: unless-stopped
    ports:
      - '100.64.0.3:3000:3000'
    volumes:
      - grafana:/var/lib/grafana

volumes:
  pgdata:
  grafana:

Now Postgres has no public endpoint at any layer, yet every device on your tailnet reaches it.

Wire the app to the other box with an ordinary connection string pointed at the data box's stable tailnet IP:

services:
  api:
    image: ghcr.io/milanjovanovic/api:latest
    restart: unless-stopped
    ports:
      - '100.64.0.2:8080:8080'
    environment:
      ConnectionStrings__AppDb: 'Host=100.64.0.3;Port=5432;Database=app;Username=app;Password=${POSTGRES_PASSWORD}'

Then from your PC, on any network:

curl http://vps-app:8080/health
psql -h vps-data -p 5432 -U app app

Look back at everything this setup let you skip. WireGuard encrypts every byte, so TLS certificates never entered the picture. Grafana went up without a reverse proxy or a login page, and you reached each service by its tailnet name instead of a DNS record. The services run, but the internet can't see them.

The Payoff

Once your machines share one private network, every internal service (databases, queues, dashboards, admin panels, service-to-service APIs) stops being a public endpoint you have to defend. It becomes a private address you simply connect to.

This is the exact pattern I run for Katabench, the coding platform I'm building. One reverse proxy on 80 and 443 is public, because users load the app through it. Everything else (the deployment panel, Postgres, the message queue, Grafana, all the telemetry) lives on the tailnet with no public hostname at all.

The mental model that makes it stick: a public hostname is something a service has to earn, and only when an outside party genuinely must reach it. Everything else stays private by default.

Fifteen minutes of setup, zero open ports, and your infrastructure disappears from the public internet without losing an ounce of convenience.

Thanks for reading.

And stay awesome!

NATS almost never comes up. That's a shame: it's quietly become one of my favorite tools for this.

NATS is a messaging system written in Go that runs as a single binary with no external dependencies. JetStream, its durable layer, turns it into a real queue with at-least-once delivery. And the .NET client is a pleasure to work with.

Core NATS vs JetStream

NATS has two layers, and the difference matters.

Core NATS is fire-and-forget pub/sub. You publish to a subject, and whoever is subscribed at that moment gets it. If no one is listening, the message is gone, which suits live notifications but not a work queue.

JetStream is the persistence layer on top. It captures messages published to a subject into a stream on disk, so a consumer can read them later, even after a restart. That persistence is what turns a subject into a durable queue.

Why It's Worth a Look

A few things stood out coming from the usual brokers:

• Tiny. The official server image is about 18 MB, a single Go binary with no ZooKeeper or Erlang to babysit.
• Fast. Core NATS pushes millions of small messages per second on a single node. JetStream adds disk persistence, so it's slower, but still comfortably in the hundreds of thousands per second.
• Cheap to run. A server idles in tens of megabytes of RAM, so it runs right next to your app.
• Flexible per stream. Each stream sets its own storage and retention, so one server can host a cache and a strict work queue side by side.

Set It Up

You need the server and two NuGet packages.

Run the server with JetStream enabled. -js turns it on, and -sd points it at a directory so streams survive a restart:

# docker-compose.yml
nats:
  image: nats:2.14-alpine
  command: ['-js', '-sd', '/data']
  ports: ['4222:4222']
  volumes:
    - nats-data:/data
  restart: unless-stopped

Add the client and its dependency-injection integration:

dotnet add package NATS.Net
dotnet add package NATS.Extensions.Microsoft.DependencyInjection

Then wire it into Program.cs. AddNatsClient registers one multiplexed, self-reconnecting connection, and the next line exposes a JetStream context to inject anywhere:

// Program.cs
builder.Services.AddNatsClient(nats =>
    nats.ConfigureOptions(opts => opts with { Url = "nats://localhost:4222" }));

builder.Services.AddSingleton(sp =>
    sp.GetRequiredService<INatsConnection>().CreateJetStreamContext());

Publish a Job

With the JetStream context in DI, a Minimal API endpoint publishes in one call. Job is a plain record, and NATS.Net serializes it to JSON for you, so you work with typed messages, no extra setup. EnsureSuccess throws if the stream didn't store the message:

app.MapPost("/jobs", async (CreateJob request, INatsJSContext js, CancellationToken ct) =>
{
    var job = new Job(Guid.NewGuid(), request.Payload);

    PubAckResponse ack = await js.PublishAsync("jobs.work", job, cancellationToken: ct);
    ack.EnsureSuccess();

    return Results.Accepted($"/jobs/{job.Id}");
});

Process Jobs in a Worker

A BackgroundService is the natural home for the consumer. It creates the stream and durable consumer on startup, then pulls messages in a loop. Every running instance shares the workers consumer, so they compete for jobs and each runs once:

public class JobWorker(INatsJSContext js) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        await js.CreateStreamAsync(new StreamConfig("JOBS", ["jobs.work"])
        {
            Retention = StreamConfigRetention.Workqueue, // a queue: acked messages are removed
            Storage   = StreamConfigStorage.File         // durable: survives a restart
        }, ct);

        var consumer = await js.CreateOrUpdateConsumerAsync("JOBS", new ConsumerConfig("workers")
        {
            AckPolicy  = ConsumerConfigAckPolicy.Explicit,
            AckWait    = TimeSpan.FromSeconds(30), // must exceed your worst-case processing time
            MaxDeliver = 5                         // drop a poison message after 5 tries
        }, ct);

        await foreach (var msg in consumer.ConsumeAsync<Job>(cancellationToken: ct))
        {
            await ProcessAsync(msg.Data, ct);          // the side effect
            await msg.AckAsync(cancellationToken: ct); // then ack
        }
    }
}

Register it with builder.Services.AddHostedService<JobWorker>(). The worker is a singleton, so resolve scoped dependencies like DbContext through IServiceScopeFactory.

Two stream settings shape how the queue behaves.

Storage is File (on disk, survives restarts) or Memory (faster, but gone on restart).

Retention controls when a message leaves the stream:

• Limits (the default) keeps every message until it hits an age, size, or count limit. The stream is a replayable log, and reading a message doesn't remove it.
• Workqueue drops a message the moment a consumer acks it, so the stream itself is the queue. Messages are delivered in publish order, oldest first (FIFO).
• Interest keeps a message only while a consumer still needs it, then drops it once every interested consumer acks.

For a job queue: Workqueue on File, as in the worker above.

Acknowledge After the Side Effect

Look closely at the worker loop: it processes first, then acks. That order is the rule that makes JetStream reliable, and most quickstarts skip it.

Acknowledge the message after the side effect, never before.

JetStream gives you at-least-once delivery. If a worker runs a job and crashes before acking, JetStream redelivers it. But ack before the work is finished, and a crash leaves the job marked done with nothing to show for it.

The flip side is that a job can run more than once, so your handler has to be idempotent. The usual fix is to track the messages you've already handled and skip duplicates, in the same transaction as the side effect. I covered the full pattern in The Idempotent Consumer Pattern in .NET. At-least-once delivery only holds up when the handler reading the stream is idempotent.

Summary

NATS JetStream gives you a durable, at-least-once work queue from a single 18 MB binary, and it slots into an ASP.NET Core app cleanly: publish from an endpoint, process in a BackgroundService, ack after the work is done.

I went in skeptical, half-expecting to miss RabbitMQ. It won me over: easy to operate, no surprises, and it clusters with Raft-based replication when a bigger load calls for it. It's now the first thing I reach for when I need a queue and don't want to think much about the broker.

If you haven't tried it, spin up the container and publish a message. That's all there is to getting started.

Thanks for reading.

And stay awesome!

The system let dealers and customers build an order together on a showroom floor. So giving that order-building collaboration its own module, separate from the product catalog, was an easy decision to defend. They were two distinct domains, and separating them into modules is textbook.

It took about a year, and a piece of business context none of us had at the start, for that decision to quietly stop being reversible.

The Setup

This was the 40-year-old system I wrote about rewriting. The backend is a manufacturing ERP, with the dealer ordering tool layered on top.

Two areas felt obviously distinct. The Catalog module owned products, configurations, options, and pricing. The Collaboration module owned the back-and-forth of building an order: drafts, comments, approvals, revisions. It looked like a clean separation: different responsibilities, different parts of the team.

Splitting them was the deliberate call, not a reflex, and every choice that followed held up on its own.

The Slow Snowball

The trouble started as ordinary feature work.

A collaboration screen needed product options, so it read from the catalog. Then it needed live pricing too. Then a requirement landed: an order had to reflect catalog changes immediately. None of them looked like an architecture decision.

But every one of them added a thread between Collaboration and Catalog. The two modules I had carefully separated were weaving themselves back together, one feature at a time. The boundary was still there in the folder structure. It had stopped being there in any way that mattered.

The Assumption That Aged Badly

The deeper problem was the communication style, and it's the decision I'd still defend hardest. Across the whole rewrite, modules communicated asynchronously, through events. It kept modules decoupled during a high-stakes migration and let us replace the legacy system one piece at a time. Catalog publishes an event, Collaboration reacts when it gets to it, and the two stay independent.

That held up right until the business needed an order to be correct now. A dealer changes a configuration, and the price has to be right the instant they hit save. Eventual consistency had been the right assumption for every requirement we knew about. The requirement that broke it didn't exist yet when we drew the boundary.

You can't bolt immediate consistency onto an asynchronous boundary. So we did what everyone does: synchronous calls, shared transactions, and workarounds to paper over the gap. Fix by fix, the system was telling us that, given the consistency the business now needed, these two belonged in one module.

The Signals That Didn't Look Like Signals

In hindsight, the signals were all there. At the time, not one of them looked like a signal.

• Collaboration constantly read Catalog's data. I took it for ordinary cross-module traffic, when it was really the boundary telling me the two belonged together.
• Nearly every new Collaboration feature reached into Catalog. That feels like healthy growth, right up until you notice it's merge pressure.
• We kept adding event handlers just to keep the two in sync. It passed for good event-driven design, and it was actually the coupling I wanted to avoid, wearing a disguise.
• Then came the first "this has to be correct immediately" hotfix. Easy to wave off as a one-off, except it was the eventual-consistency assumption starting to crack.

Any one of these is invisible. Together, over a year, they're the whole story.

What I'd Tell My Past Self

A module boundary is a guess, so treat it like one. You're guessing - so keep testing the guess instead of filing it away as settled.

Start with fewer, coarser modules. You can always split a module once the seam is obvious. When you're unsure, keep things together and let a module earn its independence. It's the same instinct as waiting for the third repetition before you extract an abstraction.

Let consistency draw your boundaries. Eventual consistency across a boundary is a bet that they never will. Make that bet on purpose, not by default.

Watch the cheap decisions, not the expensive ones. We pour deliberation into decisions that are easy to reverse and wave through the ones that quietly aren't. A module boundary feels cheap, because on the day you draw it, it is. The cost shows up later, compounding, which is exactly why nobody's watching when it does.

The Part That's Uncomfortable

None of this means modular monoliths are a trap, or that async messaging is a mistake. I'd build it as a modular monolith again tomorrow. Every call was sound for the context we had, and that context was incomplete in a way nobody could see yet.

The lesson is smaller and harder to sit with: the boundaries you draw earliest are the ones most likely to be invalidated by what you learn later, and the least likely to be revisited once they are. The door wasn't one-way when I walked through it. It became one-way behind me, one reasonable feature at a time.

Summary

• A module boundary is a guess made when you know the least, so treat it as provisional, not settled.
• Prefer fewer, coarser modules. Splitting one later is cheap - merging two back together is the expensive, risky direction.
• Let consistency draw your boundaries. If two things have to be correct at the same instant, they belong on the same side of the line.

If you want a structured way to design module boundaries, and the judgment for when to keep modules together or split them apart, that's exactly what I teach in Modular Monolith Architecture.

Thanks for reading.

And stay awesome!

An order gets placed, inventory gets checked, a payment gets charged, stock gets reserved, and the customer gets notified. Each step can fail, time out, or need a retry. And the whole thing has to survive a process restart without losing its place or charging someone twice.

We usually solve this with a pile of queues, a state table, and a lot of defensive code to track where each process is. It works, but the business logic ends up scattered across handlers and database rows, and nobody can read the flow top to bottom anymore.

Dapr (a graduated CNCF project) has a building block for exactly this: Workflow. You write the process as ordinary C# code, and Dapr makes it durable. If the host crashes halfway through, the workflow picks up right where it left off.

In this article, we'll build a small Dapr Workflow, run it with .NET Aspire, and inspect its state with the Diagrid Dev Dashboard. If you'd rather learn this hands-on, there's also a free Dapr University track built around this exact stack.

Let's dive in.

What Dapr Workflow Actually Is

You define a workflow that orchestrates a process, and activities that do the actual work (call a database, hit an API, send an email). This is orchestration rather than choreography: one place drives the process instead of services reacting to each other's events.

The definitions live in your app; the workflow engine that executes them runs in the Dapr sidecar:

The key idea is durable execution. Dapr records every step to a state store, so the workflow can be replayed from history at any time. A crash, a deployment, or a scale-out event doesn't lose progress, and a workflow can run for seconds or for months.

One rule follows from this: workflow code must be deterministic. No DateTime.Now, no random values, no I/O - anything non-deterministic goes into an activity. Even logging is affected: use context.CreateReplaySafeLogger<T>() inside a workflow, or every replay will repeat your log lines.

Under the hood, this all runs on Dapr actors, which is why the state store must support actors. More on that in a moment.

Building the Workflow

The quickest starting point is the Aspire CLI's starter template:

aspire new aspire-starter -n OrderProcessing

It generates the app host, an API service, and a ServiceDefaults project that wires up OpenTelemetry and health checks (that's where the AddServiceDefaults call comes from later). If you're on Claude Code, the Dapr Skills plugin can scaffold the entire workflow project from a prompt and review it for determinism mistakes. Everything we build here is also in a working sample on my GitHub, so you can clone it and follow along.

The API service needs the Dapr.Workflow package:

<PackageReference Include="Dapr.Workflow" Version="1.18.1" />

A workflow derives from Workflow<TInput, TOutput> and reads top to bottom like a normal method, even though every step is durably persisted:

using Dapr.Workflow;

namespace OrderApi.Workflows;

internal sealed class OrderProcessingWorkflow : Workflow<OrderPayload, OrderResult>
{
    public override async Task<OrderResult> RunAsync(
        WorkflowContext context,
        OrderPayload order)
    {
        // 1. Check inventory
        var inventory = await context.CallActivityAsync<InventoryResult>(
            nameof(CheckInventoryActivity),
            order);

        if (!inventory.InStock)
        {
            return new OrderResult(order.OrderId, "Rejected: out of stock");
        }

        // 2. Charge the customer
        await context.CallActivityAsync(
            nameof(ProcessPaymentActivity),
            new PaymentRequest(order.OrderId, order.TotalAmount));

        // 3. Reserve the stock
        await context.CallActivityAsync(
            nameof(UpdateInventoryActivity),
            order);

        // 4. Notify the customer
        await context.CallActivityAsync(
            nameof(NotifyCustomerActivity),
            order.CustomerId);

        return new OrderResult(order.OrderId, "Completed");
    }
}

CallActivityAsync doesn't invoke the activity directly. It schedules the work with the workflow engine, which records the result once the activity completes. If the process dies after the payment step, Dapr replays the workflow, feeds it the recorded results for completed steps, and resumes at the inventory update. The customer never gets charged twice.

This is the task chaining pattern. Dapr Workflow also supports fan-out/fan-in, external events, timers, and child workflows - all in plain C# (fan-out is just Select plus Task.WhenAll). If you want to build the richer patterns hands-on, the free Build Dapr Workflows in .NET with Aspire track has you fan out to parallel activities and aggregate the results.

One production caveat: the recorded history is tied to the shape of your code, so changing a workflow while instances are in flight breaks their replay. That's solved with workflow versioning; we're staying on version one here.

An activity is where the real work happens, and the only place you're allowed to be non-deterministic. It derives from WorkflowActivity<TInput, TOutput> and supports constructor injection:

using Dapr.Workflow;

namespace OrderApi.Activities;

internal sealed class CheckInventoryActivity(IInventoryService inventory)
    : WorkflowActivity<OrderPayload, InventoryResult>
{
    public override async Task<InventoryResult> RunAsync(
        WorkflowActivityContext context,
        OrderPayload order)
    {
        bool inStock = await inventory.HasStockAsync(order.ProductId, order.Quantity);

        return new InventoryResult(inStock);
    }
}

The other activities follow the same shape: charge the card, decrement stock, send the confirmation email. Each one is isolated, so Dapr can retry a failed activity without re-running the whole workflow. And since every input and output gets serialized to the state store, simple JSON-friendly records are the right tool for these types.

Starting Workflows Over HTTP

Register the workflow and its activities in the API service's Program.cs:

builder.Services.AddDaprWorkflow(options =>
{
    options.RegisterWorkflow<OrderProcessingWorkflow>();

    options.RegisterActivity<CheckInventoryActivity>();
    options.RegisterActivity<ProcessPaymentActivity>();
    options.RegisterActivity<UpdateInventoryActivity>();
    options.RegisterActivity<NotifyCustomerActivity>();
});

This also registers a DaprWorkflowClient we can use to start and query workflow instances:

app.MapPost("/orders", async (
    OrderPayload order,
    DaprWorkflowClient workflowClient) =>
{
    string instanceId = await workflowClient.ScheduleNewWorkflowAsync(
        name: nameof(OrderProcessingWorkflow),
        instanceId: order.OrderId,
        input: order);

    return Results.Accepted($"/orders/{instanceId}", new { instanceId });
});

app.MapGet("/orders/{instanceId}", async (
    string instanceId,
    DaprWorkflowClient workflowClient) =>
{
    WorkflowState? state = await workflowClient.GetWorkflowStateAsync(instanceId);

    if (state is null || !state.Exists)
    {
        return Results.NotFound();
    }

    return Results.Ok(new
    {
        RuntimeStatus = state.RuntimeStatus.ToString(),
        Output = state.ReadOutputAs<OrderResult>()
    });
});

ScheduleNewWorkflowAsync returns immediately and the workflow runs in the background. It's the same idea as scaling long-running API requests: return 202 Accepted and let the client poll for status. Two SDK quirks worth knowing: GetWorkflowStateAsync returns null for an instance it has never seen, and RuntimeStatus is an enum that serializes as a bare number without the ToString().

Running Everything With Aspire

Here's where Aspire earns its keep. A Dapr Workflow needs a sidecar and a state store running alongside the app, and Aspire orchestrates all of it from one place.

The app host needs two packages. The Dapr integration lives in the Aspire Community Toolkit these days; the original Aspire.Hosting.Dapr package is deprecated.

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Dapr" Version="13.0.0" />
<PackageReference Include="Aspire.Hosting.Valkey" Version="13.4.3" />

Then the app host:

using CommunityToolkit.Aspire.Hosting.Dapr;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDapr();

// Pin the password. Aspire generates a random one on every run otherwise,
// and the Dapr component file below has to know it.
var statePassword = builder.AddParameter(
    "statestore-password", "state-store-123", secret: true);

// Valkey (a Redis fork) as the workflow state store
var statestore = builder
    .AddValkey("statestore", 16379, statePassword)
    .WithDataVolume();

builder.AddProject<Projects.OrderApi>("order-api")
    .WithDaprSidecar(new DaprSidecarOptions
    {
        ResourcesPaths = ["./Resources"]
    })
    .WaitFor(statestore);

builder.Build().Run();

WithDaprSidecar runs a Dapr sidecar next to order-api, and ResourcesPaths points it at the Dapr component files (relative paths resolve against the app host directory).

The one component the workflow needs is a state store - a statestore.yaml in the app host's Resources folder:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: workflowstore
spec:
  type: state.redis
  version: v1
  metadata:
    - name: redisHost
      value: 'localhost:16379'
    - name: redisPassword
      value: 'state-store-123'
    - name: actorStateStore
      value: 'true'

That actorStateStore: "true" line is the one people forget. Dapr Workflow runs on top of actors, so without it, workflows won't run. Notice the application never sees any of this: swapping Valkey for Postgres means editing this YAML file, not your C# code.

Install the Dapr CLI and run dapr init once (that's where the sidecar binary comes from), then start everything with a single command:

aspire run

Aspire spins up Valkey, the Dapr sidecar, and the API, with logs, traces, and health in one dashboard. Grab the API's port from there and post an order:

curl -X POST http://localhost:5555/orders \
  -H "Content-Type: application/json" \
  -d '{"orderId":"order-001","customerId":"cust-42","productId":"pro-plan","quantity":2,"totalAmount":49.99}'

Poll the status endpoint and you'll see the workflow march through its activities (if the first request returns a 500, give the sidecar a few more seconds to connect to the placement service):

curl http://localhost:5555/orders/order-001

{
  "runtimeStatus": "Completed",
  "output": {
    "orderId": "order-001",
    "status": "Completed"
  }
}

Each activity shows up as a span in the distributed trace:

Inspecting Workflow State Locally

The Aspire dashboard shows you the request flow, but not the workflow's internal state: which step it's on, what each activity returned, and the full execution history. For that, there's the Diagrid Dev Dashboard: a free, local-only tool that reads your workflow state store (Redis-compatible, Postgres, or SQLite) and visualizes every instance. It comes from Diagrid, the company founded by the creators of the Dapr OSS project, which also provides enterprise Dapr support.

Since the whole point of this setup is that one command starts everything, let's add it to the app host:

builder.AddContainer("diagrid-dashboard", "ghcr.io/diagridio/diagrid-dashboard:latest")
    .WithBindMount("./Resources", "/app/components")
    .WithEnvironment("COMPONENT_FILE", "/app/components/dashboard-store.yaml")
    .WithEnvironment("APP_ID", "diagrid-dashboard")
    .WithHttpEndpoint(targetPort: 8080)
    .WaitFor(statestore);

Why a second component file? Networking. The sidecar runs as a host process, so localhost:16379 works for it. The dashboard runs in a container, where localhost means the container itself, so its dashboard-store.yaml reaches the host through host.docker.internal (on Linux without Docker Desktop, use the bridge gateway IP instead):

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: dashboardstore
spec:
  type: state.redis
  version: v1
  metadata:
    - name: redisHost
      value: 'host.docker.internal:16379'
    - name: redisPassword
      value: 'state-store-123'
    - name: actorStateStore
      value: 'true'
scopes:
  - diagrid-dashboard

The scopes field keeps the API's sidecar from picking up this component, since both files sit in the same Resources folder.

Run aspire run again and open the dashboard's endpoint from the Aspire resources view. Every workflow instance is listed with its status, app ID, and duration:

Clicking an instance shows the exact input the workflow received and the output it produced:

Below that sits the full execution history - the ground truth of what your workflow actually did. Expand a TaskScheduled event to see an activity's input, or a TaskCompleted event to see its input and output:

Being able to see the workflow's actual state, not just guess at it from logs, is what makes local workflow development feel sane. There's also a Diagrid.Aspire.Hosting.Dashboard package that wraps this container setup into a single AddDiagridDashboard call.

Summary

Dapr Workflow gives you durable execution for long-running processes without dragging a heavy orchestration engine into your code:

• The process is plain C# code that reads top to bottom.
• Dapr makes it fault-tolerant, replaying from the state store so a crash never loses progress.
• The orchestration stays deterministic; the side effects live in activities.
• Aspire runs the sidecar, the state store, and the dashboard with one command.
• The Diagrid Dev Dashboard shows you exactly what each instance is doing.

You can grab the complete source code for this article on my GitHub, including Aspire integration tests for the workflow.

If you want to go deeper, the free Build Dapr Workflows in .NET with Aspire track on Dapr University is the natural next step. You'll build a fan-out/fan-in workflow on this exact stack in a hosted sandbox, with nothing to install. The Dapr Workflow track covers the remaining patterns in standalone examples.

Thanks for reading.

And stay awesome!

Don't Repeat Yourself. See two pieces of code that look the same, extract a method, delete the duplicate. I did this for years and wrote some of the worst code I've ever had to maintain:

• A shared helper that grew a new boolean parameter every sprint.
• A base class nobody dared touch because six unrelated features inherited from it.
• A "common" module two independent parts of the system both depended on, so neither could change without the other.

Every one started as an innocent attempt to not repeat myself.

What DRY Actually Says

Here's the part most people skip. The original definition, from Andy Hunt and Dave Thomas in The Pragmatic Programmer, says nothing about code:

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

It's about knowledge. A single fact about your domain, like a tax rule or the format of an invoice number, should live in exactly one place. When that fact changes, you change it once instead of hunting for seven copies.

The Mistake: Deduplicating Code, Not Knowledge

Two pieces of code can look identical and represent completely different knowledge.

Say you validate two addresses. One is a customer's shipping address, the other is a warehouse address. Today the rules are identical:

public bool IsValid(Address address) =>
    !string.IsNullOrWhiteSpace(address.Street) &&
    !string.IsNullOrWhiteSpace(address.City) &&
    !string.IsNullOrWhiteSpace(address.PostalCode);

The DRY reflex says extract one validator and call it from both places. But these are different concepts that happen to share rules this week. The day the warehouse needs a loading-dock code, you're back in the shared method bolting on a flag to keep the other caller working:

public bool IsValid(Address address, bool requireDockCode = false) =>
    !string.IsNullOrWhiteSpace(address.Street) &&
    !string.IsNullOrWhiteSpace(address.City) &&
    !string.IsNullOrWhiteSpace(address.PostalCode) &&
    (!requireDockCode || !string.IsNullOrWhiteSpace(address.DockCode));

That boolean is the tell. The first time a shared method grows a flag so one caller behaves differently, you didn't have duplication. You had two things that looked alike and glued them together. Give it a year and the signature has three more flags, each one a place where the two concepts were never actually the same.

The Wrong Abstraction Costs More Than Duplication

Duplication is far cheaper than the wrong abstraction.

Copy-paste is visible and local. You can see both copies, and if they drift apart, that was always allowed. The wrong abstraction is invisible and global. Every caller depends on one shape and bends it to fit, the flags pile up, and you end up afraid to touch a method you no longer understand. I've spent more time deleting bad abstractions than I ever saved writing them.

This is the hidden coupling cost I wrote about in the abstractions piece, and DRY-by-reflex is one of the most common ways it sneaks in.

Where It Hurts Most: Across Boundaries

Inside one class, a bad helper is annoying. Across module boundaries, it's structural damage.

Picture a modular monolith with a Billing module and a Shipping module. Both have an Order. A well-meaning engineer notices the two classes share fields and pulls them into a shared type both modules reference:

// Shared.Orders, referenced by both Billing and Shipping
public class Order
{
    public Guid Id { get; set; }
    public string CustomerName { get; set; }
    public decimal Total { get; set; }
    // ...whatever either module happens to need
}

Now Billing and Shipping can't evolve independently. A change to billing's order forces a recompile, re-test, and redeploy of shipping. You took two bounded contexts that were supposed to be decoupled and welded them together to save a few properties.

Two modules each owning their own Order is the whole point of keeping data inside its boundaries. The shapes are allowed to be similar, modeling the same real-world thing from two points of view that drift over time. It's the same reason vertical slices tolerate a little repetition, so each slice can change on its own.

The Rule I Use: Wait for the Third Time

I don't deduplicate the second time I see something. I wait for the third, and I ask one question: if this rule changes, do both copies have to change together?

• Yes - it's real duplication, the same fact written in several places. Extract it, and that's DRY doing its job.
• No - the resemblance is a coincidence. Leave it alone, and coupling them will cost you later.

Let the code repeat until the right abstraction becomes obvious, because good abstractions are discovered from concrete cases, not guessed up front. Some people call this AHA, for "Avoid Hasty Abstractions."

A practical tell: extract when you can name the concept. A real domain name like Money, TaxRate, or InvoiceNumber is probably knowledge worth a value object. If the best name you can find is Helper, Utils, or ProcessData, you're abstracting shape, not knowledge.

When DRY Is Right

Applied correctly, DRY is invaluable. A business rule belongs in exactly one place. Watch what happens when "an order over $1,000 needs manager approval" gets copy-pasted across three services:

// OrderService
if (order.Total > 1000) { /* require approval */ }

// CheckoutService
if (order.Total > 1000m) { /* require approval */ }

// AdminController - someone bumped the limit here, and only here
if (order.Total > 5000) { /* require approval */ }

You will eventually update two of them and ship a bug. That drifted third copy is exactly how it happens. Push the rule into the domain model where it has one home:

public bool RequiresManagerApproval() => Total > 1000;

That's the single authoritative representation DRY is actually about.

Summary

• DRY is about knowledge, not code that looks alike.
• The wrong abstraction costs more than the duplication it replaced, and it's harder to undo.
• Wait for the third occurrence. Extract only when both copies encode the same fact and must change together.

The next time you're about to delete a duplicate, don't ask whether the code looks the same. Ask whether it means the same. That one question will save you more maintenance pain than DRY ever saved you typing.

If you want to see how I draw these boundaries in a real system, with independent modules and abstractions that earn their place, that's the heart of Pragmatic Clean Architecture.

Thanks for reading.

And stay awesome!

A parse that either gives you a number or an error. A lookup that returns a value or "not found". An operation that succeeds or fails. In C#, we've never had a clean way to model "this is an A or a B". So we faked it - with marker interfaces, abstract base classes, tuples, nullable returns, exceptions, or the excellent OneOf library.

C# 15 (shipping with .NET 11) finally adds union types to the language. I've wanted this for years, so let me give you a quick tour.

Let's dive in.

The Problem

Say a method can return a user or fail because they don't exist. Today you'd reach for something like this:

// Throw for the "failure" case - control flow via exceptions
public User GetUser(int id) =>
    _users.TryGetValue(id, out var user)
        ? user
        : throw new UserNotFoundException(id);

The signature says it returns a User, but that's a lie - it might throw instead. The caller has no way to know that without reading the body. The other usual workarounds (a bool TryGet with an out parameter, a custom Result class with nullable fields, or a OneOf<User, NotFound>) all add ceremony to express one simple idea.

What you actually want is a closed set of types. That's exactly what a union is.

Declaring a Union

The syntax is delightfully small. You list a name and the case types:

public union Result<T>(T, Exception);

That's it. A Result<T> is now either a T or an Exception - and nothing else. The types don't even need to be related, which is the whole point.

Here's a more concrete example with unrelated record types:

public record CreditCard(string Last4, string Brand);
public record PayPal(string Email);
public record BankTransfer(string Iban);

public union PaymentMethod(CreditCard, PayPal, BankTransfer);

Creating Values

There's an implicit conversion from each case type, so you just assign the value directly:

PaymentMethod method = new CreditCard("4242", "Visa");

Try to assign a type that isn't in the set, and it's a compile error. The set is closed.

Consuming a Union

This is where it shines. Pattern matching just works, and the compiler checks the inner value for you:

string Describe(PaymentMethod method) => method switch
{
    CreditCard card  => $"{card.Brand} ending {card.Last4}",
    PayPal paypal    => $"PayPal ({paypal.Email})",
    BankTransfer ach => $"Bank transfer to {ach.Iban}",
}; // No `_` or `default` needed

Notice there's no discard _ and no default arm. Because the union is closed, the compiler knows all three cases are covered. Forget one, and you get a warning at compile time:

warning CS8509: The switch expression does not handle all possible values
of its input type (it is not exhaustive). For example, the pattern 'BankTransfer'
is not covered.

That exhaustiveness check is the feature I'm most excited about. Add a new case to the union later, and the compiler points you at every switch you forgot to update.

Back to The Problem

Remember our lying GetUser method from earlier? Let's fix it with a union.

First, declare what the method can actually return - a User or a NotFound:

public record NotFound(int Id);

public union UserResult(User, NotFound);

Now the signature tells the truth, and there are no exceptions for control flow:

public UserResult GetUser(int id) =>
    _users.TryGetValue(id, out var user)
        ? user
        : new NotFound(id);

And the caller has to handle both outcomes - the compiler won't let them forget:

IResult response = GetUser(42) switch
{
    User user      => Results.Ok(user),
    NotFound found => Results.NotFound($"No user with id {found.Id}"),
};

That's the whole pitch. The return type tells you the truth: here are exactly the shapes you'll get back, and you can't ignore one by accident. No more reading the method body to discover what it might throw.

A Few Caveats

This is still a preview/experimental feature. A few things to keep in mind:

• It targets C# 15 / .NET 11, and the syntax may still change before release. Try it on .NET 11 Preview 4 or later.
• Under the hood, a union is compiled to a struct that boxes value-type cases and stores the contents as a single object?. There's a non-boxing path for performance-sensitive code, but the default is simple.
• This is a type union (an A or a B), not a full discriminated union with named cases yet. It covers the vast majority of what I reach for OneOf for today.

Summary

Union types close a gap that's been open in C# for a very long time.

• Declare a closed set of types with public union Name(A, B, C);.
• Assign case values directly - implicit conversions handle the rest.
• Pattern match with full compiler-checked exhaustiveness, no default arm required.
• Model results, options, and "one of these" returns without marker interfaces, base classes, or extra libraries.

It's a small syntax with a big payoff: your method signatures finally tell the truth about what they return, and the compiler keeps every switch honest.

I'll explore this feature more in the future, but I wanted to share this quick tour now that it's available in preview.

Thanks for reading.

And stay awesome!

You end up with two problems at once. Your users sit on a spinner for several minutes, and your API holds that request open the entire time - burning a thread, a connection, and a slot in your concurrency budget. A small traffic spike on that one endpoint could potentially take the rest of the API down with it.

I want to walk through the progression I use to fix this. It's the same path the diagram below traces, from "the request just blocks" to a fully decoupled, queue-backed worker pool - the shape I usually call an async API.

Depending on your requirements, you might stop at any point along the way - but I want to make sure you understand the full path and the trade-offs at each step.

Step 0: The Naive Version

A user sends a request. The application server does the work. The work takes five minutes. The connection stays open the whole time.

There is nothing wrong with this approach - it's just paying for correctness with availability. The user experience is bad, and the blast radius is large: every long request you accept is a request you can't accept somewhere else.

The first realization you need to internalize is that the response time and the work duration don't have to be the same thing.

Step 1: Accept the Work, Don't Do It

The first move is to stop doing the work inside the request.

I add a jobs table that represents the work I intend to do. The API endpoint now does three things:

1. Validate the request.
2. Insert a row into jobs with status Pending.
3. Return 202 Accepted with a job ID.

A background processor running inside the same API picks up Pending rows and works through them. The client either polls a GET /jobs/{id} endpoint or - better - I push updates via SignalR, Server-Sent Events, or email when the job is done.

This already buys you a lot. The endpoint returns in milliseconds, the user gets a job ID they can track, and a spike of incoming requests just becomes a spike of rows in a table. That table is cheap to write to.

But there's a ceiling here, and it's easy to hit.

Step 2: Decouple the Worker From the API

The background processor in Step 1 still lives inside your API process. It competes for the same CPU, memory, and connection pool as your real endpoints. If processing gets heavy or slow, your API starts feeling it - the very thing you were trying to avoid.

The fix is to pull the background processor out into its own deployable, and put a queue between the two.

The API now publishes a message to the queue (and optionally writes the job row for tracking). A pool of background workers consumes from the queue and does the actual work - the same shape I covered in event-driven architecture with RabbitMQ. This is the competing consumers pattern, and it gives you something the previous step couldn't: independent scaling.

Three things change once you cross this line:

• The queue absorbs spikes. Your API can keep accepting work at a constant rate while the workers drain at their own pace.
• You scale workers separately from the API. More throughput on background jobs doesn't mean more API instances.
• Failures become normal. A worker crash is just a message that goes back on the queue, not a 500 to your user.

You also get retryability, pause/resume, structured error handling, and a dead-letter queue for poison messages - effectively for free, because the queue infrastructure already provides them.

What This Costs You

I'd be lying if I said this was a free upgrade.

You're now running a queue, a worker fleet, and a notification path. That's more moving parts to deploy, monitor, and alert on. Your "is this done yet?" semantics are no longer obvious from the HTTP response - the client has to ask, or you have to tell them. And every job needs to be idempotent, because at-least-once delivery means your workers will see duplicates.

If you only have one slow endpoint and modest traffic, this is overkill. A simple "fire-and-forget with status polling" inside the same process is fine. Don't reach for a queue until the pain justifies it.

When I'd Use a Cloud Service Instead

You don't always need to assemble this from parts. A few alternatives I would consider:

• AWS SQS + Lambda or Azure Service Bus + Azure Functions when I want the worker pool to scale to zero and I don't want to manage hosts.
• Azure Durable Functions or AWS Step Functions when the work is a multi-step workflow with timers, retries, and human approvals. Orchestration is what they're good at.
• Temporal when the workflow is long-lived (hours, days) and I need first-class durable execution, versioning, and visibility across runs.

The trade-off is the usual one: less operational work, more vendor coupling, and a pricing model you need to model carefully when throughput grows.

Summary

The progression is simple, and it generalizes:

1. Don't do slow work inside the request. Accept it, persist it, return 202.
2. Don't run workers inside the API. Put a queue in between and scale the two sides independently.
3. Tell the user when it's done. Polling is fine, push is better.

This isn't a microservices argument. It's a separation between accepting work and doing work - two concerns that have very different scaling profiles and very different failure modes.

If you want the full implementation walkthrough, the video version is here.

Thanks for reading.

And stay awesome!

The customer was charged once, but our system thought the payment had failed. The payment provider had taken the money, the order had rolled back to a draft state, and the user had received a "Payment failed, please retry" email on top of it. A single user action left every subsystem with a different opinion about what actually happened.

A use case looks like a transaction because it sits behind a single method call. But the moment it touches more than one system, you are dealing with partial failure.

Here's how I think about it:

• The three categories every side effect falls into
• How to design use cases that fail loudly and recover safely
• When to reach for the Outbox pattern and when not to

Let's dive in.

The Code That Looks Fine

Here's a typical "place an order" use case. I've written this exact shape a hundred times, and so have you.

internal sealed class PlaceOrder(
    IOrderRepository orders,
    IPaymentService payments,
    IEmailService emails,
    IUnitOfWork unitOfWork)
{
    public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
    {
        var order = Order.Create(request.CustomerId, request.Items);
        orders.Insert(order);

        await payments.ChargeAsync(order.Id, order.Total, ct);

        await emails.SendOrderConfirmationAsync(order.Id, ct);

        await unitOfWork.SaveChangesAsync(ct);
        return Result.Success();
    }
}

There are three side effects in this method, sitting behind what looks like a single transactional boundary, with no coordination between them.

If SaveChangesAsync throws after ChargeAsync succeeded, you've taken the customer's money and lost the order. If SendOrderConfirmationAsync throws, the order saves and the charge goes through, but no email is sent. And if you naively retry, you double-charge.

The use case "works" until it doesn't, and when it doesn't, it tends to fail in a different way every time.

Three Categories of Side Effect

Before you write a single line of recovery code, classify every side effect into one of three buckets:

1. Transactional - lives inside your database transaction. Inserts, updates, domain events dispatched in-process.
2. External and reversible - an API call you can compensate for. Charge → refund. Reserve inventory → release.
3. External and irreversible - sent emails, posted webhooks, SMS messages. Once they're out, they're out.

The category determines the strategy. There is no single "handle errors properly" rule that covers all three.

Strategy 1: Pull Transactional Work to the End

The first move is mechanical. Anything transactional should commit last, after all external calls have either succeeded or been explicitly tolerated.

public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
{
    var order = Order.Create(request.CustomerId, request.Items);

    var charge = await payments.ChargeAsync(order.Id, order.Total, ct);
    if (charge.IsFailure) return charge;
    order.MarkPaid(charge.Value.TransactionId);

    orders.Insert(order);

    await unitOfWork.SaveChangesAsync(ct);
    return Result.Success();
}

You can't always do this - sometimes you need a database ID before calling the external service. That's fine. The point isn't ordering for its own sake. It's making sure that if you commit, you've already done the work the commit promises.

Strategy 2: Move Irreversible Side Effects Outside the Use Case

This is where the Outbox pattern earns its keep.

Instead of sending the email directly, raise an OrderPlaced domain event and let an outbox dispatcher pick it up after the transaction commits.

public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
{
    var order = Order.Create(request.CustomerId, request.Items);

    var charge = await payments.ChargeAsync(order.Id, order.Total, ct);
    if (charge.IsFailure) return charge;
    order.MarkPaid(charge.Value.TransactionId);

    orders.Insert(order);
    order.Raise(new OrderPlacedEvent(order.Id));
    await unitOfWork.SaveChangesAsync(ct);

    return Result.Success();
}

The email is no longer the use case's problem. If the transaction commits, the event commits with it inside the same write. If it doesn't, the event never escapes the database and no email is ever sent. A separate worker turns events into emails, with its own retries and its own idempotency guarantees.

Strategy 3: Make External Calls Idempotent or Compensable

The payment call is the dangerous one. If it succeeds and your transaction rolls back, you've taken money you can't account for.

What you do not do is silently swallow the failure:

try
{
    await payments.ChargeAsync(order.Id, order.Total, ct);
}
catch
{
    // shrug
}

The symptom disappears from your logs, the money stays gone, and the next time the user retries you charge them again.

There are two approaches I actually use, and they compose well together.

Approach A: Idempotency Keys

Most serious payment providers (Stripe, Adyen, Braintree) let you attach an idempotency key to a charge. A retry with the same key is a no-op on their side and returns the original result. The natural key here is the order ID:

var charge = await payments.ChargeAsync(
    new ChargeRequest
    {
        OrderId = order.Id,
        Amount = order.Total,
        IdempotencyKey = order.Id.ToString()
    },
    ct);

Now it's safe to retry the use case. If the previous attempt charged the customer and crashed before committing, the next attempt gets the same charge back from the provider instead of creating a new one, and the order finally gets persisted.

Approach B: Compensate via a Domain Event

Idempotency keys only help when you can replay with the same inputs. Sometimes you can't - the user gave up, the request was cancelled, or the failure is permanent.

In that case, the money is real and needs to come back. Make the failure itself a first-class event and refund out-of-band:

public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)
{
    var order = Order.Create(request.CustomerId, request.Items);

    var charge = await payments.ChargeAsync(order.Id, order.Total, ct);
    if (charge.IsFailure) return charge;
    order.MarkPaid(charge.Value.TransactionId);

    try
    {
        orders.Insert(order);
        order.Raise(new OrderPlacedEvent(order.Id));
        await unitOfWork.SaveChangesAsync(ct);
    }
    catch (Exception ex)
    {
        await outbox.PublishAsync(
            new PaymentFailedEvent(
                order.Id,
                charge.Value.TransactionId,
                order.Total,
                Reason: ex.Message),
            ct);
        throw;
    }

    return Result.Success();
}

A background consumer subscribes to PaymentFailedEvent and issues the refund, using the transaction ID as its own idempotency key. This turns a scary cross-process compensation into a normal, observable, retryable message handler.

In practice, I use Approach A for transient failures and Approach B for permanent ones. They aren't mutually exclusive.

When the Saga Pattern Wins Instead

The strategies above work when one use case coordinates a small number of side effects in a single service. Once the work spans multiple services and needs to survive process restarts, you're in saga territory.

The rule I use: if you can fit the recovery logic in your head, a well-designed use case is enough. If you can't, reach for a saga.

Summary

A use case is a unit of intent, not a unit of atomicity.

• Transactional work commits with the database, last.
• Irreversible work goes through the Outbox pattern, not the use case.
• External, reversible work uses idempotency keys first, compensating events second.
• Never swallow failures to make the use case "look successful".

Most of the production bugs I've debugged in event-driven systems come down to a use case that lied about whether it succeeded. Stop lying, and the system gets a lot easier to reason about.

If you want to see this kind of thinking applied across a full system, that's exactly what I build inside Modular Monolith Architecture.

Thanks for reading.

And stay awesome!

But the more important question isn't how to version an API. It's when.

Every API team eventually reaches for the same escape hatch:

Just create v2.

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

I also touched on this briefly in my REST API design mistakes article, but I want to make the point more directly today:

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

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

And that distinction matters.

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

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

That mindset leads to APIs that age much better.

What Actually Breaks Clients?

Breaking changes usually aren't about the URL alone.

Clients break when you:

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

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

// Before
{ "total": 100 }

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

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

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

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

The Compatibility Rules

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

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

These map directly onto the four rules from Z. Nemec's API Change Management article: don't take anything away, don't change processing rules, don't make optional things required, and anything you add must be optional.

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

1. Add, Don't Replace

The safest change is usually an additive one.

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

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

Instead of replacing total, add a new field:

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

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

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

Sometimes an ugly contract is the price of compatibility.

2. Make Clients Tolerant Readers

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

If the response evolves from this:

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

to this:

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

older clients should ignore the extra property and keep working.

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

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

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

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

3. Don't Change What an Existing Operation Does

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

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

Take DELETE /orders/{id}.

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

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

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

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

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

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

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

The same pattern shows up in subtler ways:

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

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

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

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

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

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

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

4. Be Very Careful With Validation

This one is underrated.

There are two flavors of the same mistake:

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

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

Here's a simple example using POST /orders.

Yesterday this request was valid:

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

Today the API requires a country for tax calculation:

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

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

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

For example:

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

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

A New Operation Is Often Cheaper Than a New Version

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

This is what a bad evolution path looks like:

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

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

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

POST /orders
POST /orders/quote
POST /checkout-sessions

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

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

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

Deprecate Like You Mean It

This is the missing half of API change management.

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

A real deprecation process should include four things:

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

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

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

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

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

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

When Versioning Is Actually The Right Call

I am not anti-versioning.

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

In those cases, version deliberately.

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

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

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

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

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

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

Takeaway

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

If you want a simple decision rule, use this:

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

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

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

That's the real point.

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

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

Thanks for reading.

And stay awesome!

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

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

What Is an Invariant?

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

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

A few examples:

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

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

Where Procedural Code Goes Wrong

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

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

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

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

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

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

That's the real cost of an anemic model. It isn't that there's no behavior on the class. It's that the class makes no promises, so every caller has to enforce the rules itself.

Always-Valid: The Model as the Source of Truth

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

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

Three moves get you there.

1. Block construction of invalid objects

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

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

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

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

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

Value objects like Money apply the same idea at a smaller scope, so a Money can't be negative or be missing its currency by the time you're using it.

2. Encapsulate state transitions

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

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

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

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

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

3. Encapsulate the aggregate

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

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

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

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

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

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

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

When a rule needs to span two aggregates instead of one, that's a different problem, and I'd reach for a domain event rather than letting one aggregate reach into another.

What You Actually Get

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

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

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

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

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

Summary

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

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

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

If you want to go deeper into modeling aggregates, value objects, and rich behavior across a real system, I think you will enjoy Pragmatic Domain-Driven Design.

See you next week.

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

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

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

Where the Pyramid Comes From

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

That world is gone. With Testcontainers, I can spin up PostgreSQL, Redis, and RabbitMQ in a fresh container per test class in a few seconds. The Aspire test host takes this further by wiring up your entire application graph. The argument that real dependencies are too expensive mostly doesn't apply anymore.

But the advice didn't update.

The Bug That Convinced Me

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

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

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

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

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

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

What Unit Tests Are Actually Good At

I still write unit tests. Just not many.

They earn their keep when the logic is non-trivial, pure (no I/O, no time, no randomness), and hard to exercise end-to-end. That's a specific set of code: value objects and rich domain models, pricing and tax calculations, parsers, mappers, serializers.

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

What I Actually Write Instead

Here's the shape I've settled on for a typical .NET service or modular monolith.

Layer 1: A thin base of unit tests

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

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

    order.Confirm();

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

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

Layer 2: A thick middle of integration tests

The majority. Maybe 60-70% of the suite. Every command and query handler, every HTTP endpoint, every message consumer gets a test that runs against real infrastructure inside Testcontainers. In a modular monolith, this is where you verify that modules talk to each other correctly across their public APIs.

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

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

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

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

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

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

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

Under 10%. Only the flows where a silent failure would be a commercial or compliance problem. Signup, payment, refund, password reset, two-factor enrollment. They're slow and occasionally flaky, but they catch the one failure mode everything else misses: the system as a whole still works.

Layer 0: Architecture and contract tests

Often forgotten, but they're part of the suite. Architecture tests enforce layering and module boundaries. Contract tests verify that message schemas and API shapes don't drift. They run in milliseconds and catch the "six months from now, someone will break this without realizing" kind of bug.

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

The Usual Objections

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

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

Summary

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

If you want to see how I wire this into a real system, with the integration test harness, module boundaries, and the full Clean Architecture setup, check out Pragmatic Clean Architecture. It's the same approach I use on my own projects.

Thanks for reading.

And stay awesome!

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

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

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

What Changed My Mind

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

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

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

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

        return await _orderRepository.GetByIdAsync(id);
    }
}

And here's what they look like now:

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

        return await orderRepository.GetByIdAsync(id);
    }
}

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

This is the most common use case for primary constructors: dependency injection in service classes. You declare what you need, and use it directly.

Where I Use Them Most: DI Service Classes

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

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

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

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

        var order = Order.Create(cart);

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

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

        return CheckoutResult.Success;
    }
}

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

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

Entity Construction (With a Caveat)

I also started using primary constructors for domain entities and value objects where you want to enforce required parameters at construction time:

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

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

        Status = OrderStatus.Confirmed;
    }
}

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

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

The Pitfall That Almost Stopped Me

This was the reason I held off for so long.

Primary constructor parameters are not readonly fields.

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

This means you can accidentally reassign a parameter:

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

        return await orderRepository.GetByIdAsync(id);
    }

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

This compiles without any warning.

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

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

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

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

        return await _orderRepository.GetByIdAsync(id);
    }
}

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

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

Where I Still Use Traditional Constructors

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

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

public class EmailAddress
{
    private readonly string _value;

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

        _value = value;
    }
}

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

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

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

Summary

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

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

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

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

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

The Saga pattern breaks this into a sequence of steps, each with its own message and handler. If a step fails or times out, the saga runs compensation logic instead of leaving the system in a broken state.

I've covered sagas with MassTransit and Rebus before. Both work well, but their state machine DSLs come with a fair amount of ceremony. Since MassTransit moved to a commercial license, more teams have been exploring Wolverine as an alternative.

Wolverine takes a different approach - you write a class that extends Saga, define Handle methods for each message type, and cascade new messages from return values. Wolverine handles routing, persistence, and correlation automatically.

Configuring Wolverine

We need RabbitMQ for message transport and PostgreSQL for durable saga state and messaging.

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

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

    options.Policies.DisableConventionalLocalRouting();

    options.PersistMessagesWithPostgresql(connectionString!);
});

• AutoProvision creates RabbitMQ exchanges and queues automatically
• UseConventionalRouting routes messages to queues based on message type names
• DisableConventionalLocalRouting forces all messages through RabbitMQ instead of in-process handling
• PersistMessagesWithPostgresql stores saga state and messages in PostgreSQL. Wolverine uses lightweight saga storage to create a table per saga type, and the durable messaging infrastructure ensures nothing is lost if the process crashes

Wolverine gives you three ways to persist saga state. Lightweight storage (what we're using) serializes saga state as JSON in a per-saga table with zero ORM config. Marten stores sagas as Marten documents with optimistic concurrency and strong-typed IDs. EF Core maps sagas into a flat, queryable table and lets you commit saga state with other data in a single transaction. If you just need saga state management, lightweight storage is the simplest path.

Required packages:

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

The Saga Messages

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

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

public record VerifyUserEmail(Guid Id);

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

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

OnboardingTimedOut extends Wolverine's TimeoutMessage, which automatically schedules a delayed delivery. When the saga starts, Wolverine will deliver this message after 5 minutes. If the user hasn't verified by then, the saga compensates.

The Saga State Diagram

Here's how the saga transitions between states:

Building the Saga

Here's the complete saga class:

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

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

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

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

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

        IsVerificationEmailSent = true;
    }

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

        IsEmailVerified = true;

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

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

        IsWelcomeEmailSent = true;

        MarkCompleted();
    }

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

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

        MarkCompleted();
    }

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

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

A few things worth calling out.

Starting the saga. Start is a static factory that returns a tuple: the saga instance, a SendVerificationEmail command, and a scheduled OnboardingTimedOut message. Wolverine persists the saga and delivers the messages for you.

Handling messages. Wolverine correlates messages to the correct saga instance by looking for a [SagaIdentity] attribute, then {SagaTypeName}Id, then Id. Return void to update state silently, or return a message to cascade a new command.

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

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

Concurrency. Wolverine applies optimistic concurrency control to saga state by default. If two messages for the same saga arrive at the same time, one succeeds and the other retries automatically.

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

NotFound handlers. Static NotFound methods handle messages for sagas that no longer exist. You must have one for any message type that could arrive after the saga is deleted. The timeout NotFound handler matters most: in the happy path, the saga completes before the timeout fires.

The Sequence Flow

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

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

Summary

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

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

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

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

If you want to go deeper on orchestrating distributed workflows and building real-world sagas, check out Modular Monolith Architecture.

Hope this was useful. See you next week.

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

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

Here's how to implement it.

Why You Need an Inbox

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

Here's a common failure path:

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

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

The idea:

1. A message arrives from the broker
2. Instead of processing it immediately, write it to an inbox table
3. If the message already exists (duplicate), the write is silently ignored
4. A background process reads unprocessed messages and handles them

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

Inbox Database Schema

The inbox_messages table stores every incoming message:

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

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

The structure mirrors the Outbox pattern's outbox_messages table. The id enables idempotent inserts via ON CONFLICT DO NOTHING. The filtered index keeps the index small since processed messages drop out automatically.

Messages between services use a shared IntegrationEvent base record:

public abstract record IntegrationEvent(Guid MessageId);

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

Inbox Consumer

The consumer is a MassTransit IConsumer<T>. Instead of processing the message, it writes it to the inbox table and returns. That's it.

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

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

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

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

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

Inbox Processor

The processor runs in a background service or a scheduled job, fetching unprocessed messages in batches and dispatching them for handling.

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

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

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

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

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

                await eventDispatcher.DispatchAsync(deserialized, cancellationToken);

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

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

        await transaction.CommitAsync(cancellationToken);

        return messages.Count;
    }
}

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

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

Things to Watch Out For

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

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

Ordering. ORDER BY received_on_utc gives you rough arrival-time ordering. But with SKIP LOCKED and multiple processors, strict ordering is not guaranteed. If you need per-aggregate ordering, you'll need additional coordination.

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

Inbox vs. Idempotent Consumer

Both the Inbox and the Idempotent Consumer prevent duplicate processing. The difference is when processing happens and who controls retries.

The Idempotent Consumer processes messages inline. It checks a deduplication table, does the work, and records the dedup entry in the same transaction. If processing fails, the transaction rolls back, no dedup record is written, and the broker redelivers the message on its own schedule. You don't control retry timing or backoff.

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

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

Summary

The Inbox pattern is the consumer-side counterpart to the Outbox pattern.

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

If you want to see how I build event-driven systems with these patterns, check out Modular Monolith Architecture.

Thanks for reading.

And stay awesome!

Dedicated vector databases like Pinecone, Qdrant, and Weaviate get all the attention. But if your data already lives in PostgreSQL, you don't need another moving part.

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 is and when you need it
• Provisioning pgvector with .NET Aspire and Ollama
• Generating embeddings with MEAI 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 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 to provision a pgvector-enabled PostgreSQL container and an Ollama instance with the qwen3-embedding embedding model.

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:

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, there are also libraries for Npgsql and EF Core if you prefer those instead.

Register the services in Program.cs:

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

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

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.

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.

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, I've covered that in a previous article.

Thanks for reading.

And stay awesome!

I built a real-time notification feature 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.

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.

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.

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 delivers messages to all subscribers in near real-time. And if you're already using Redis for distributed caching, 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

dotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis

Register the Backplane

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

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

If you're running with .NET Aspire, you will have the Redis connection string registered via environment variables, so you can just pull it from configuration. Reference the same named connection:

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.

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

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

Hope this was useful. See you next week.

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.

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:

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.

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.

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:

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:

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.

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 objects directly. If you want a full overview of EF Core's raw SQL options, I covered them in this article.

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:

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:

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. Instead of building @Id0 through @Id9999 dynamically, you pass two arrays as parameters and let PostgreSQL expand them:

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, then run a single UPDATE ... FROM.

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.
• 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 that trips up a lot of developers.

That's all for today.

See you next week.

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 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 is the .NET port of the Java ArchUnit library. It lets you write architecture rules using a fluent API and run them as regular xUnit tests.

# 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:

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

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 where each feature is self-contained, or inside a modular monolith 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:

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, 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:

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

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.

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.

Thanks for reading.

And stay awesome!

It was a wake-up call. Passwords alone are not enough. They get phished, leaked in breaches, or brute-forced. A second factor changes the equation entirely.

Two-Factor Authentication (2FA) adds an extra verification step beyond the password. Even if an attacker steals the password, they still can't get in without the second factor. It's one of the most effective security measures you can implement, and it's not that hard to build.

In this article, I'll walk you through implementing 2FA in .NET using Time-based One-Time Passwords (TOTP) with QR codes and authenticator apps like Google Authenticator.

We'll cover:

• How TOTP works under the hood
• Generating QR codes for authenticator app setup
• The correct setup flow to avoid putting users in a bad state
• Validating one-time codes
• Encrypting user secrets at rest

Let's dive in.

How TOTP Works

TOTP (Time-based One-Time Password) is the algorithm behind apps like Google Authenticator, Microsoft Authenticator, and Authy.

The idea is simple: a shared secret is established between the server and the user's authenticator app. Both sides use that secret combined with the current time to generate a 6-digit code that changes every 30 seconds.

Here's the flow:

1. The server generates a unique secret key for the user
2. The user scans a QR code containing that secret into their authenticator app
3. Both the server and the app now independently generate the same time-based codes
4. At login, the user enters the current code from their app, and the server verifies it

Because both sides compute the code independently, there's no network call to validate. The server just checks: "given this secret and the current time, does the code match?"

This makes TOTP fast, offline-capable, and resistant to replay attacks (each code is only valid for a short window).

Generating the Secret Key

Every user needs their own unique secret key. This key is the foundation of the entire 2FA system, so it must be cryptographically random.

We'll use the Otp.NET library for TOTP operations:

dotnet add package Otp.NET

Generate a secret key for a user:

using OtpNet;

byte[] secretKey = KeyGeneration.GenerateRandomKey(); // 20 bytes by default (SHA-1)
string base32Secret = Base32Encoding.ToString(secretKey);

KeyGeneration.GenerateRandomKey() produces a cryptographically secure random key. We encode it as Base32 because that's what the otpauth URI scheme expects.

This secret must be stored securely. It's the equivalent of a password. If an attacker gets the secret, they can generate valid codes. I'll cover encrypting it at rest later in this article.

Creating the QR Code

To set up 2FA, the user needs to scan a QR code with their authenticator app. The QR code encodes an otpauth:// URI that contains the secret key and metadata.

Install the QRCoder library:

dotnet add package QRCoder

Here's how to generate the QR code:

using QRCoder;

const string issuer = "MyApp";
const string user = "user@example.com";

string escapedIssuer = Uri.EscapeDataString(issuer);
string escapedUser = Uri.EscapeDataString(user);

string otpUri =
    $"otpauth://totp/{escapedIssuer}:{escapedUser}" +
    $"?secret={base32Secret}" +
    $"&issuer={escapedIssuer}" +
    $"&digits=6" +
    $"&period=30";

using var qrGenerator = new QRCodeGenerator();
using var qrCodeData = qrGenerator.CreateQrCode(otpUri, QRCodeGenerator.ECCLevel.Q);
using var qrCode = new PngByteQRCode(qrCodeData);
byte[] qrCodeImage = qrCode.GetGraphic(10);

Let's unpack the otpauth:// URI parameters:

• secret - The Base32-encoded shared secret
• issuer - Your application name (shown in the authenticator app)
• digits - Number of digits in the code (standard is 6)
• period - How often the code rotates in seconds (standard is 30)

The ECCLevel.Q gives us a good balance between error correction and QR code size. It means the QR code can still be scanned even if about 25% of it is damaged or obscured.

Here's what the generated QR code looks like:

And once the user scans it, the entry appears in their authenticator app:

You can also display the base32Secret string alongside the QR code. Some users prefer to type it in manually.

The Setup Flow

Getting the setup flow right is critical. If you enable 2FA the moment the user requests it, before they've even scanned the QR code, you've locked them out.

Here's the correct flow:

1. User requests 2FA setup - Generate a secret key and store it as pending (not yet active)
2. Show the QR code - The user scans it with their authenticator app
3. User enters the first code - This proves they successfully set up their authenticator app
4. Server validates the code - If it matches, activate 2FA for the user
5. Generate recovery codes - Give the user backup codes in case they lose their device

The key insight is step 3. Never enable 2FA until the user has confirmed they can generate valid codes. Otherwise, you'll end up with users who have 2FA "enabled" but no way to generate codes.

Here's what the API endpoints look like. All 2FA endpoints must be protected, the user has to be authenticated first. The best practice is to use .RequireAuthorization() on each endpoint:

app.MapPost("2fa/setup", async (HttpContext context, UserService userService) =>
{
    var userId = context.User.GetUserId();

    byte[] secretKey = KeyGeneration.GenerateRandomKey();
    string base32Secret = Base32Encoding.ToString(secretKey);

    // Store the pending secret (encrypted) - NOT yet active
    await userService.StorePendingTwoFactorSecret(userId, base32Secret);

    string otpUri =
        $"otpauth://totp/{Uri.EscapeDataString("MyApp")}:{Uri.EscapeDataString(userId)}" +
        $"?secret={base32Secret}" +
        $"&issuer={Uri.EscapeDataString("MyApp")}" +
        $"&digits=6&period=30";

    using var qrGenerator = new QRCodeGenerator();
    using var qrCodeData = qrGenerator.CreateQrCode(otpUri, QRCodeGenerator.ECCLevel.Q);
    using var qrCode = new PngByteQRCode(qrCodeData);
    byte[] qrCodeImage = qrCode.GetGraphic(10);

    return Results.File(qrCodeImage, "image/png");
})
.RequireAuthorization();

And the confirmation endpoint:

app.MapPost("2fa/confirm", async (
    ConfirmTwoFactorRequest request,
    HttpContext context,
    UserService userService) =>
{
    var userId = context.User.GetUserId();

    string? pendingSecret = await userService.GetPendingTwoFactorSecret(userId);
    if (pendingSecret is null)
    {
        return Results.BadRequest("No pending 2FA setup found.");
    }

    byte[] secretKey = Base32Encoding.ToBytes(pendingSecret);
    var totp = new Totp(secretKey);

    bool isValid = totp.VerifyTotp(
        request.Code,
        out _,
        VerificationWindow.RfcSpecifiedNetworkDelay);

    if (!isValid)
    {
        return Results.BadRequest("Invalid code. Please try again.");
    }

    // Code is valid - activate 2FA
    await userService.ActivateTwoFactor(userId, pendingSecret);

    // Generate recovery codes
    var recoveryCodes = await userService.GenerateRecoveryCodes(userId);

    return Results.Ok(new { recoveryCodes });
})
.RequireAuthorization();

internal record ConfirmTwoFactorRequest(string Code);

This two-step approach guarantees you never activate 2FA for a user who can't actually use it. If the user abandons the setup halfway through, the pending secret gets cleaned up and nothing breaks.

The Login Flow With 2FA

Here's a critical point that's easy to get wrong: don't issue a full access token until the user passes the 2FA check.

If a user has 2FA enabled and you issue a JWT after they enter their password, you've already given them full access. The 2FA step becomes meaningless.

The correct approach is a two-step login:

1. The user submits their username and password
2. If credentials are valid and 2FA is enabled, return a limited-scope token (or session) that only allows calling the 2fa/validate endpoint
3. The user submits their TOTP code
4. If the code is valid, issue the full access token

app.MapPost("auth/login", async (LoginRequest request, UserService userService) =>
{
    var user = await userService.ValidateCredentials(request.Email, request.Password);
    if (user is null)
    {
        return Results.Unauthorized();
    }

    if (user.TwoFactorEnabled)
    {
        // Issue a short-lived, limited token that only permits 2FA validation
        var limitedToken = TokenService.GenerateLimitedToken(user.Id, purpose: "2fa");

        return Results.Ok(new { requiresTwoFactor = true, token = limitedToken });
    }

    // No 2FA - issue full access token
    var accessToken = TokenService.GenerateAccessToken(user);

    return Results.Ok(new { accessToken });
});

The limited token should have a short expiration (2-3 minutes) and a claim or scope that restricts it to the 2fa/validate endpoint only. Your authorization policy on the validation endpoint can check for this specific claim.

This way, a stolen password alone never results in a full access token.

Validating TOTP Codes

Once 2FA is active, you need to validate codes during login. Here's the validation logic:

app.MapPost("2fa/validate", async (
    ValidateOtpRequest request,
    HttpContext context,
    UserService userService) =>
{
    var userId = context.User.GetUserId();

    string? secret = await userService.GetTwoFactorSecret(userId);
    if (secret is null)
    {
        return Results.BadRequest("2FA is not enabled.");
    }

    byte[] secretKey = Base32Encoding.ToBytes(secret);
    var totp = new Totp(secretKey);

    bool isValid = totp.VerifyTotp(
        request.Code,
        out long timeStepMatched,
        VerificationWindow.RfcSpecifiedNetworkDelay);

    return Results.Ok(new { isValid });
})
.RequireAuthorization();

internal record ValidateOtpRequest(string Code);

The VerificationWindow.RfcSpecifiedNetworkDelay parameter is important. It allows a small window of tolerance around the current time step. This accounts for clock drift between the server and the user's device.

Without a verification window, a code that was valid 2 seconds ago might be rejected because the server crossed into the next 30-second period. The RFC-specified window typically allows one time step before and after the current one.

Preventing Code Reuse

One subtle but important point: a TOTP code should only be accepted once.

If an attacker intercepts a valid code (e.g., through shoulder surfing), they shouldn't be able to reuse it. The timeStepMatched output parameter tells you which time step the code belongs to. You can store the last used time step and reject any code from the same or earlier step:

bool isValid = totp.VerifyTotp(
    request.Code,
    out long timeStepMatched,
    VerificationWindow.RfcSpecifiedNetworkDelay);

if (isValid)
{
    long? lastUsedTimeStep = await userService.GetLastUsedTimeStep(userId);

    if (lastUsedTimeStep.HasValue && timeStepMatched <= lastUsedTimeStep.Value)
    {
        return Results.BadRequest("Code already used.");
    }

    await userService.UpdateLastUsedTimeStep(userId, timeStepMatched);
}

This prevents replay attacks within the verification window.

Rate Limiting

The validation endpoint is a brute-force target. A 6-digit code has only 1,000,000 possible combinations. Without rate limiting, an attacker could try all of them in minutes.

At a minimum, you should:

• Limit attempts per user - Lock the account or add a delay after 3-5 failed attempts
• Use exponential backoff - Double the wait time after each failure
• Log failed attempts - Unusual patterns (many failures from one IP) are a red flag

ASP.NET Core has a built-in rate limiting middleware that makes this straightforward to add.

Encrypting Secrets at Rest

The TOTP secret key is the most sensitive piece of data in your 2FA system. If someone dumps your database, they shouldn't be able to generate valid codes for your users.

Never store TOTP secrets in plain text.

Encrypt them before writing to the database and decrypt only when you need to verify a code. I covered this in detail in my article on implementing AES encryption with C#.

Here's the general approach:

public class UserService
{
    private readonly IEncryptionService _encryptionService;

    public async Task StorePendingTwoFactorSecret(string userId, string secret)
    {
        string encryptedSecret = _encryptionService.Encrypt(secret);

        // Store encryptedSecret in the database
        await _dbContext.Users
            .Where(u => u.Id == userId)
            .ExecuteUpdateAsync(u => u
                .SetProperty(x => x.PendingTwoFactorSecret, encryptedSecret));
    }

    public async Task<string?> GetTwoFactorSecret(string userId)
    {
        var user = await _dbContext.Users.FindAsync(userId);
        if (user?.TwoFactorSecret is null) return null;

        return _encryptionService.Decrypt(user.TwoFactorSecret);
    }
}

The encryption key itself should live in a key management service like Azure Key Vault, AWS KMS, or HashiCorp Vault. Never store it in your appsettings.json or source code.

Recovery Codes

What happens when a user loses their phone?

Without a recovery mechanism, they're permanently locked out of their account. Recovery codes solve this. They're one-time-use codes generated when the user enables 2FA.

public async Task<List<string>> GenerateRecoveryCodes(string userId, int count = 8)
{
    var codes = new List<string>();

    for (int i = 0; i < count; i++)
    {
        // Generate a cryptographically random code
        var bytes = RandomNumberGenerator.GetBytes(5);
        var code = Convert.ToHexString(bytes).ToLower();
        codes.Add(code);
    }

    // Hash the codes before storing (same as passwords - one-way)
    var hashedCodes = codes
        .Select(c => BCrypt.Net.BCrypt.HashPassword(c))
        .ToList();

    await _dbContext.RecoveryCodes
        .Where(rc => rc.UserId == userId)
        .ExecuteDeleteAsync();

    _dbContext.RecoveryCodes.AddRange(
        hashedCodes.Select(h => new RecoveryCode
        {
            UserId = userId,
            CodeHash = h,
            IsUsed = false
        }));

    await _dbContext.SaveChangesAsync();

    // Return plain text codes to show the user ONCE
    return codes;
}

A few important details:

• Hash the recovery codes before storing them. They're single-use passwords. Use bcrypt (e.g. Bcrypt.Net) or similar.
• Show them only once. After the user dismisses the dialog, the plain text codes are gone.
• Mark codes as used. Each recovery code works exactly once.
• Generate enough codes. Eight to ten is standard. The user can regenerate them if they run low.

When validating a recovery code, check each stored hash until you find a match:

public async Task<bool> ValidateRecoveryCode(string userId, string code)
{
    var storedCodes = await _dbContext.RecoveryCodes
        .Where(rc => rc.UserId == userId && !rc.IsUsed)
        .ToListAsync();

    var matchingCode = storedCodes
        .FirstOrDefault(rc => BCrypt.Net.BCrypt.Verify(code, rc.CodeHash));

    if (matchingCode is null) return false;

    matchingCode.IsUsed = true;
    await _dbContext.SaveChangesAsync();

    return true;
}

Putting It All Together

Here's a minimal but complete setup showing the full 2FA flow. I'm using a route group with .RequireAuthorization() so every endpoint underneath is protected:

using OtpNet;
using QRCoder;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

var twoFactorGroup = app.MapGroup("2fa").RequireAuthorization();

twoFactorGroup.MapPost("setup", async (HttpContext context, UserService userService) =>
{
    var userId = context.User.GetUserId();

    byte[] secretKey = KeyGeneration.GenerateRandomKey();
    string base32Secret = Base32Encoding.ToString(secretKey);

    await userService.StorePendingTwoFactorSecret(userId, base32Secret);

    string otpUri =
        $"otpauth://totp/{Uri.EscapeDataString("MyApp")}:{Uri.EscapeDataString(userId)}" +
        $"?secret={base32Secret}" +
        $"&issuer={Uri.EscapeDataString("MyApp")}" +
        $"&digits=6&period=30";

    using var qrGenerator = new QRCodeGenerator();
    using var qrCodeData = qrGenerator.CreateQrCode(otpUri, QRCodeGenerator.ECCLevel.Q);
    using var qrCode = new PngByteQRCode(qrCodeData);
    byte[] qrCodeImage = qrCode.GetGraphic(10);

    return Results.File(qrCodeImage, "image/png");
});

twoFactorGroup.MapPost("confirm", async (
    ConfirmTwoFactorRequest request,
    HttpContext context,
    UserService userService) =>
{
    var userId = context.User.GetUserId();

    string? pendingSecret = await userService.GetPendingTwoFactorSecret(userId);
    if (pendingSecret is null)
    {
        return Results.BadRequest("No pending 2FA setup found.");
    }

    byte[] secretKey = Base32Encoding.ToBytes(pendingSecret);
    var totp = new Totp(secretKey);

    bool isValid = totp.VerifyTotp(
        request.Code,
        out _,
        VerificationWindow.RfcSpecifiedNetworkDelay);

    if (!isValid)
    {
        return Results.BadRequest("Invalid code. Please try again.");
    }

    await userService.ActivateTwoFactor(userId, pendingSecret);
    var recoveryCodes = await userService.GenerateRecoveryCodes(userId);

    return Results.Ok(new { recoveryCodes });
});

twoFactorGroup.MapPost("validate", async (
    ValidateOtpRequest request,
    HttpContext context,
    UserService userService) =>
{
    var userId = context.User.GetUserId();

    string? secret = await userService.GetTwoFactorSecret(userId);
    if (secret is null)
    {
        return Results.BadRequest("2FA is not enabled.");
    }

    byte[] secretKey = Base32Encoding.ToBytes(secret);
    var totp = new Totp(secretKey);

    bool isValid = totp.VerifyTotp(
        request.Code,
        out long timeStepMatched,
        VerificationWindow.RfcSpecifiedNetworkDelay);

    if (isValid)
    {
        long? lastUsedTimeStep = await userService.GetLastUsedTimeStep(userId);
        if (lastUsedTimeStep.HasValue && timeStepMatched <= lastUsedTimeStep.Value)
        {
            return Results.BadRequest("Code already used.");
        }

        await userService.UpdateLastUsedTimeStep(userId, timeStepMatched);
    }

    return Results.Ok(new { isValid });
});

app.Run();

internal record ConfirmTwoFactorRequest(string Code);
internal record ValidateOtpRequest(string Code);

If you don't need full control, Keycloak and ASP.NET Core Identity both support TOTP-based 2FA out of the box. But building it yourself is worth it when you need a custom flow or want to understand what's happening under the hood.

Summary

2FA is one of the highest-impact security features you can add to an application. TOTP with authenticator apps is a solid choice because it's offline-capable, widely supported, and doesn't depend on SMS (which is vulnerable to SIM swapping).

The important parts to get right:

• Use a proper setup flow. Generate the secret, show the QR code, and only activate 2FA after the user confirms their first code.
• Encrypt secrets at rest. The TOTP secret is as sensitive as a password. Encrypt it with AES and store keys in a key vault.
• Prevent code reuse. Track the last used time step to block replay attacks.
• Provide recovery codes. Users lose phones. Hash the codes before storing them, just like passwords.

If you're building APIs that handle sensitive operations, adding 2FA significantly raises the bar for attackers. It's not bulletproof, but it stops the vast majority of credential-based attacks.

If you're looking for a deep dive into building secure APIs with authentication and encryption, check out my Pragmatic REST APIs course.

Hope this was useful. See you next week.

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 and 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 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, 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.

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.

Vertical Slices Inside a Module

Vertical Slice Architecture 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 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:

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 just like you would in Clean Architecture.

Similarly, 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 answers the macro question: how to decompose the system into modules with clear boundaries. 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. 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.

See you next week.

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

ollama pull llama3.2-vision:latest

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

On the .NET side, Microsoft.Extensions.AI provides a unified IChatClient interface for talking to any LLM provider. Combined with OllamaSharp, the setup is minimal:

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.

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.

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

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:

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:

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:

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 gets interesting.

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

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:

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:

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?

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:

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

I was never a fan of this...

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

Keycloak 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 Authorization Code flow. Then we'll add JWT validation to our .NET backend and trace the entire authentication flow using the Aspire Dashboard.

Running Keycloak as a Container

The fastest way to spin up Keycloak is with Docker. 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:

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:

docker compose up -d

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

You should see the Keycloak admin console.

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

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

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

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

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

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 is the recommended OAuth 2.0 flow for browser-based applications.

There's an important security enhancement called PKCE (Proof Key for Code Exchange) 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:

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:

dotnet add package Swashbuckle.AspNetCore

Configure Swagger in your Program.cs:

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:

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:

{
  "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.

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:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Configure authentication in Program.cs:

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:

app.UseAuthentication();
app.UseAuthorization();

Create a protected endpoint:

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:

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, you can observe the entire authentication flow in the distributed traces.

Here's what a successful authentication looks like:

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:

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 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 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 and Modular Monolith Architecture.

See you next week.

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:

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:

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.

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.

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.

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

<PropertyGroup>
  <!-- Use the Alpine-based image for smaller size -->
  <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:

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

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

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

- 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 (a simple but powerful deployment tool for Docker apps) to pull the latest image and restart my service.

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.

By the way, I'm running my VPS on Hetzner 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!

You need to upgrade to a modern algorithm like Argon2 or 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:

• 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."

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

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:

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

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:

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, you can disable the "write" step if your database comes under load, while still allowing users to log in via the read-only fallback.

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.

Hope this was helpful!

In .NET 9, Microsoft introduced HybridCache to simplify caching. It's a fantastic library that combines the speed of in-memory caching (L1) with the durability of distributed caching (L2) like Redis. It also handles "cache stampede" protection out of the box.

However, there is a catch.

When you run multiple instances of your application, HybridCache doesn't automatically synchronize the local L1 cache across all nodes. If you update data on Node A, Node B will continue serving stale data from its in-memory cache until the entry expires.

While HybridCache is a massive step forward, the lack of a built-in backplane for invalidation is a known limitation. In fact, there is an active discussion on the dotnet/extensions GitHub repository tracking this exact feature request. Until that ships, we have to roll our own solution.

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

• The distributed caching dilemma
• Why HybridCache doesn't solve this alone
• Using Redis Pub/Sub as a backplane
• Implementing real-time cache invalidation

Let's dive in.

The Distributed Caching Dilemma

Let's imagine a typical production scenario. You have an API running on multiple servers (or pods) behind a load balancer.

To improve performance, you introduce caching. You want the speed of local memory, so you use HybridCache.

Here is the failure scenario:

1. User A updates their profile on Server 1.
2. Server 1 updates the database and clears its local cache.
3. User A (or User B) hits Server 2.
4. Server 2 still holds the old profile data in its local HybridCache.
5. The user sees outdated information, since the local cache hasn't been invalidated.

Why Not Just Shorten the Cache Duration?

A common "hack" to solve this is to simply reduce the L1 cache duration (TTL). For example, setting the local cache to expire every 10 seconds.

While this reduces the window of inconsistency, it doesn't solve the problem. It just masks it.

This approach introduces two new issues:

• Increased Latency: You are now forcing your application to reach out to the distributed L2 cache (Redis) or the database much more frequently.
• Lost Efficiency: The main benefit of L1 caching is avoiding network requests entirely. If you expire data too fast, you lose the performance gain for the majority of your traffic.

For things like user permissions, feature flags, or pricing, "mostly correct" is often not good enough. You need immediate consistency.

The Solution: Redis Pub/Sub Backplane

To solve this, we need a backplane. It's a communication channel that connects all our application nodes.

When a cache entry is removed or updated on one node, we publish a message to the backplane. All other nodes subscribe to this channel and, upon receiving the message, remove the corresponding key from their local cache.

Redis is already a popular choice for the L2 cache, so it makes perfect sense to use its Pub/Sub feature for this signaling mechanism.

It works like this:

1. Publisher: The node that modifies data publishes a cache-invalidation message with the cache key.
2. Subscriber: All nodes listen to this channel.
3. Action: When a message arrives, they call HybridCache.RemoveAsync(key).

Implementing the Solution

We will need the StackExchange.Redis library to handle the messaging.

Let's start by defining a simple service to handle the publishing. This service will be responsible for notifying the rest of the system that a key has changed.

public interface ICacheInvalidator
{
    Task InvalidateAsync(string key, CancellationToken cancellationToken = default);
}

public class RedisCacheInvalidator(
    IConnectionMultiplexer connectionMultiplexer,
    ILogger<RedisCacheInvalidator> logger)
    : ICacheInvalidator
{
    private const RedisChannel Channel = RedisChannel.Literal("cache-invalidation");

    public async Task InvalidateAsync(string key, CancellationToken cancellationToken = default)
    {
        var subscriber = connectionMultiplexer.GetSubscriber();

        await subscriber.PublishAsync(Channel, new RedisValue(key));

        logger.LogInformation("Published invalidation for key: {Key}", key);
    }
}

Now, whenever you update an entity in your Command Handler or Service, you just call ICacheInvalidator.InvalidateAsync.

public class UpdateUserProfileHandler(
    AppDbContext dbContext,
    ICacheInvalidator cacheInvalidator,
    ILogger<UpdateUserProfileHandler> logger)
{
    public async Task Handle(int userId, string newName, CancellationToken ct)
    {
        // 1. Update the database
        var user = await dbContext.Users.FindAsync([userId], ct);
        if (user is null)
        {
             return;
        }

        user.Name = newName;
        await dbContext.SaveChangesAsync(ct);

        // 2. Invalidate the cache (Distributed)
        var cacheKey = $"user:{userId}";
        await cacheInvalidator.InvalidateAsync(cacheKey, ct);

        logger.LogInformation("Updated user and invalidated cache for {UserId}", userId);
    }
}

The Background Listener

Next, we need a background service that runs on every node. It will subscribe to the Redis channel and evict keys from the local HybridCache.

A quick note on self-publishing: Because Redis Pub/Sub broadcasts to everyone subscribed, the node that published the invalidation will also receive the message. In this implementation, we simply remove the key again. It's redundant but harmless, and it keeps the code simple.

Note that we are injecting HybridCache directly into our background service. An alternative is using IMemoryCache, since that is the L1 cache inside HybridCache.

public class CacheInvalidationService(
    IConnectionMultiplexer connectionMultiplexer,
    HybridCache hybridCache,
    ILogger<CacheInvalidationService> logger)
    : BackgroundService
{
    private const RedisChannel Channel = RedisChannel.Literal("cache-invalidation");

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var subscriber = connectionMultiplexer.GetSubscriber();

        await subscriber.SubscribeAsync(Channel, (channel, value) =>
        {
            string key = value.ToString();

            logger.LogInformation("Invalidating local cache for: {Key}", key);

            // This removes the item from the local L1 cache
            var task = hybridCache.RemoveAsync(key, stoppingToken);

            if (!task.IsCompleted)
            {
                task.GetAwaiter().GetResult();
            }
        });
    }
}

Wiring It All Together

Finally, we need to register these services in our DI container.

builder.Services.AddSingleton<IConnectionMultiplexer>(sp =>
    ConnectionMultiplexer.Connect("<REDIS_CONNECTION_STRING>"));

// Register HybridCache (defaults generally work fine for L1)
builder.Services.AddHybridCache();

// Register our invalidation services
builder.Services.AddSingleton<ICacheInvalidator, RedisCacheInvalidator>();
builder.Services.AddHostedService<CacheInvalidationService>();

Now, when Node A calls InvalidateAsync("user:123"), Redis pushes that message to Node B, Node C, and so on. They all trigger hybridCache.RemoveAsync("user:123"), ensuring the next request fetches fresh data from the source (or the shared L2).

A Better Way: FusionCache

If building your own backplane feels like reinventing the wheel, you should look at FusionCache.

FusionCache is a mature, battle-tested library that has solved this exact problem for years. It has a built-in backplane feature that automatically handles the Pub/Sub messaging for you.

Even better, FusionCache recently added an implementation of the HybridCache abstract class. This means you can swap it in without changing much of your existing code.

// Using FusionCache's implementation of HybridCache
builder.Services.AddFusionCache()
    .WithBackplane(
        new RedisBackplane(new RedisBackplaneOptions { Configuration = "<REDIS_CONNECTION_STRING>" }))
    .AsHybridCache();

Summary

HybridCache is a powerful addition to the .NET ecosystem, effectively merging the benefits of IMemoryCache and IDistributedCache. However, for multi-node setups requiring high consistency, you still need a mechanism to synchronize the local caches.

Redis Pub/Sub offers a lightweight, effective solution to this problem.

By implementing a simple "bus" for invalidation messages, you get the best of both worlds: the extreme performance of local caching and the data consistency of a distributed system.

Good luck out there, and see you next week.

They need something simpler and more useful: events must be handled in order per aggregate.

Per OrderId, per InvoiceId, per CustomerId, or whatever your aggregate boundary is. You can make this as broad or as narrow as you need.

This starts as an eventing problem, but if you follow the requirements to their logical conclusion, you'll end up with a workflow. And that workflow has a name: a saga.

Domain Events Feel Like the Clean Solution

Domain events are attractive because they come from first principles:

• An aggregate changes state
• It emits events describing what happened
• Handlers react and do useful work

You also get a nice mental model:

State change → Event → Reaction

A typical example:

• OrderPlaced
• PaymentCaptured
• OrderShipped

But there's a catch.

Domain events are brittle when you try to use them for integration.

If you publish directly from your transaction, you're coupling business correctness to an unreliable side effect:

• The transaction succeeds but publishing fails
• Publishing succeeds but the transaction rolls back
• Consumers process duplicates
• Retries cause reordering

So we keep the model, but harden the delivery.

The Outbox Makes Publishing Reliable (but not ordered)

With an Outbox, we store outgoing events in the same transaction as the aggregate update.

Then a background publisher reads the Outbox and pushes events to a queue.

This fixes the reliability problem:

• If the transaction commits, the event is persisted
• If the publisher crashes, it can resume later
• We can retry safely

Now we've made event publishing reliable.

But we haven't made event handling ordered.

Competing consumers Are Great, Until Order Matters

The moment events hit a queue, we usually scale with the simplest lever: competing consumers.

Multiple instances consume from the same queue to increase throughput.

That works… until ordering matters.

Two events for the same OrderId can be processed at the same time:

• Consumer A receives PaymentCaptured
• Consumer B receives OrderPlaced
• Side effects run out of order

Even if the events were published in order, retries and redelivery can scramble processing order.

And now you have a subtle bug that only appears under load.

That's the key realization: queues scale work. They don't preserve your invariants.

What We Really Want is Per-Aggregate Ordering

You don't need one ordered line for everything.

You need many independent ordered lines, one per aggregate.

That usually holds true because:

• Aggregates already define consistency boundaries
• Events are naturally produced in order (v1, v2, v3…)
• The "correct" order is the aggregate's own timeline

If we could guarantee that only one handler processes events for a given aggregate at a time, most of the problem disappears.

The most direct solution is also the simplest: use a single consumer for the whole stream.

That enforces ordering, assuming events are published in order.

But it has an obvious drawback.

A Single Consumer Solves Ordering But Limits Scale

One consumer means:

• Throughput ceiling (one worker)
• Latency spikes under load
• Scaling becomes vertical, not horizontal

Even if your events are lightweight, you're artificially bottlenecking the system.

So we want:

• Per-aggregate ordering
• Horizontal scaling
• Reliability (Outbox still stays)

This is where teams often "invent" the next step.

Publish the Next Message From the Handler

If competing consumers break ordering, one natural idea is:

Don't let the queue decide what's next, we decide.

Instead of dumping all events into the queue and letting consumers race, we move to a chained approach:

1. Handle one message for an aggregate
2. When done, publish the next message to be handled

Now, the system processes a single message at a time per aggregate.

This is the key moment:

You've stopped building "event handlers".

You've started building a workflow.

And that workflow is… a saga.

Congratulations, You Built a Choreographed Saga

A choreographed saga is a workflow where:

• Each step reacts to an event
• Performs work
• Emits the next event to trigger the next step

There isn't a single central coordinator.

Instead, we have a chain of events: "when X happens, do Y, then publish Z".

This pattern naturally fits your new requirement:

• Per-aggregate ordering is preserved (the chain is sequential)
• You can scale across aggregates (many chains in flight)
• Each step is isolated and retryable

It also forces a useful discipline:

• "What's the next step?" becomes explicit
• Boundaries between steps become clearer
• You can observe the workflow as a sequence

But choreography has a limitation: control is distributed, so tracking progress and handling exceptions can get messy.

So we take the final step.

If You Want Control, Introduce a State Machine Saga

When the workflow becomes important, you often want:

• A single place that knows the current state
• Visibility into progress ("where are we stuck?")
• Explicit timeouts and retries
• Compensating actions when something fails

That's when you move from choreography to orchestration via a state machine saga:

• The saga holds the workflow state
• Events drive transitions
• The saga decides what message to publish next
• You gain control and observability

This doesn't replace the Outbox, by the way.

You still want reliable publishing.

You've just made the workflow explicit.

Broker Support Helps with Ordering, not Correctness

It's worth calling out that you don't always have to build this yourself.

Many popular message brokers provide technical primitives for ordered processing per key (your aggregate ID):

• Amazon SQS FIFO message groups (per key)
• Azure Service Bus sessions (per key)
• Kafka Partitions in a log (key → partition → ordered stream)
• RabbitMQ "single active consumer" style semantics (per queue)

These features can eliminate the most common failure mode of competing consumers: concurrent handling of messages for the same aggregate.

But even with perfect per-aggregate ordering, you still need patterns around it to keep the system correct:

• Outbox to publish reliably (ordering is useless if events are lost)
• Idempotent consumers / Inbox because retries and duplicates still happen
• Consistency boundaries (what's safe to do inside the transaction vs outside)
• Timeouts + compensation when the "ordered sequence" is actually a business workflow that can partially fail

So broker-level ordering is a great foundation. It reduces accidental complexity. It just doesn't remove the need to model long-running work explicitly when the business demands it.

Takeaway

If you follow the problem from first principles:

• Aggregates define the boundary where ordering matters
• The Outbox makes event publishing reliable
• Competing consumers break per-aggregate order
• A single consumer restores order but caps throughput
• Publishing "the next message" creates sequential progress per aggregate
• That sequential progress is a saga (choreographed first, state machine when you need control)

So you didn't reinvent something by accident.

You discovered that "ordered handling per aggregate at scale" is not a queue feature.

It's a workflow. And sagas are how we model workflows in distributed systems.

Once you see it that way, you stop fighting queues for ordering guarantees.

You design the workflow the business actually needs.

Hope this was helpful!

Looking back at my GitHub contribution graphs from the last few years, I see more than just green squares. I see a timeline of my own evolution.

I was chasing that dream many developers have: build a small product, ship it, get users, maybe turn it into a business. Most of those ideas didn't become a successful SaaS.

But that wasn't the point.

The point was that I was building constantly. Learning constantly. Shipping constantly.

And I loved it.

The Indie Hacker Dream

Back in 2020, my contribution graph shows the classic "burst" pattern. I was chasing the indiehacker dream. You know the one: build a SaaS, get to ramen profitability, escape the 9-to-5, tweet about your MRR milestones. I consumed every bootstrapper podcast, every "I made $10K/month" blog post, every ProductHunt launch breakdown.

I was working on a project called Expensely. I spent late nights pouring myself into this "genius" idea: a budgeting app.

Nothing revolutionary. The world didn't need another expense tracker. But I needed to build it.

Looking back now, it was far from genius. But at the time, I was convinced that this was the one.

In 2021, that momentum stayed steady for five months before life (or perhaps reality) intervened. Those green squares represent the fun periods. They represent the thrill of architecting an application, the satisfaction of a passing test suite, and the hope that you're building something that might change your life.

Expensely never became a business. Most side projects don't. But here's what I've come to understand: the outcome wasn't the point.

Even though those projects didn't become the next big SaaS, they were the forge where my skills were sharpened. You don't "waste" time building something that fails. You only waste time when you don't build at all. And I mean this both metaphorically and literally. Humans are meant to create. When we stop creating, we stagnate.

What Building Actually Gives You

When you build something from scratch - when you own every decision from the database schema to the button colors - you learn differently. There's no senior developer to ask. No established patterns to follow. Every problem is yours to solve.

You can use Railway-Oriented Programming if you want to, because who is going to stop you?

Jokes aside, functional programming is very useful. You should learn it.

Through my side projects, I wrestled with authentication, background jobs, payment integrations, deployment pipelines. I made mistakes and spent late nights fixing them. I built features nobody asked for and skipped features everyone needed.

There is one thing side projects can't teach you (unless you get users): dealing with the consequences of your decisions. When you build for yourself, the only person affected by your mistakes is you. When you build for users, every bug, every outage, every poor design choice has real consequences.

By mid 2021, the project had wound down. I was settling into a comfortable routine at my day job, working as a senior engineer at a big corporation. There was no time left for side projects.

The Unexpected Pivot

By 2022, something changed. My contribution graph exploded to over 1,600 commits. But the focus shifted. I wasn't building a product anymore. I was building something more meaningful. The repositories shifted to my tech blog and YouTube projects.

I had discovered content creation.

The urge to build hadn't disappeared. I found a new outlet. Instead of building products for users, I was building educational content for developers. Instead of SaaS metrics, I was tracking video views and newsletter subscribers. To me it was something new, something exciting.

I discovered that while I loved building software, I loved explaining it even more. I transitioned from an aspiring founder to a software engineering educator. At first it was just me writing and recording things I wish someone had explained to me earlier.

Then something interesting happened.

People started reading. Watching. Replying. Asking questions. More people showed up. And then even more.

Today, I get to help thousands of developers around the world improve their careers. It is, without a doubt, the most rewarding work I've ever done.

This is genuinely fulfilling work. When someone messages me saying my content helped them land a job or finally understand a concept they'd struggled with for years, that feeling is hard to describe. I'm doing something meaningful.

And yet.

The Lingering Itch

The urge to build something still remains.

It's not dissatisfaction. It's not that content creation isn't "real" building, it absolutely is. It's a different kind of building, certainly. But this feeling I have is something more fundamental. A part of my brain that wants to work on a fresh project. That wants to solve a problem nobody has asked me to solve. That wants to take an idea from nothing to something.

That's why I have a Hetzner server sitting idle right now. Never know when I might need it. Right? Also, I'm getting a great deal for €3.29/month. Can't argue with that.

I think this urge never fully goes away for people like us. We can channel it, redirect it, find new outlets for it. But it's always there, lingering. And maybe that's okay. Maybe that restlessness is what makes us who we are.

Why You Should Build Too

If you're reading this with your own idea rattling around in your head - some app concept, some tool you wish existed, some problem you think you could solve - I want to tell you something.

Build it.

Not because it will make you rich. Statistically, it won't. Not because it will become the next big thing. It probably won't be that either.

Build it because the person who finishes that project will not be the same person who started it. You will learn things no tutorial can teach. You will develop judgment that only comes from making real decisions with real consequences. You will have stories, opinions, and experiences that set you apart.

The outcome is almost beside the point. The transformation is the product.

Maybe you'll end up with a successful SaaS. Maybe you'll end up with a failed project and a mass of hard-won knowledge. Maybe, like me, you'll end up somewhere you never expected - doing work you couldn't have imagined when you wrote that first line of code.

You won't know until you build.

So open your terminal. Type git init. And start.

Let this be a year of building.

My first instinct is: "I'll just cache it".

In .NET, that usually means reaching for IMemoryCache or plugging in a distributed cache like Redis.

But have you ever stopped to wonder what's actually happening inside those libraries?
Why do we need all that complexity just to store a value in memory?

So I spent the afternoon trying to build a high-performance cache from scratch.

I don't recommend DIY-ing your own caching library for production use. But I learn best by doing something myself. Understanding these patterns (concurrency, race conditions, and locking) is what separates a "coder" from an engineer.

The Starting Point

I was working on a simple currency conversion handler. We're calling a third-party API to get exchange rates. The API returns the current exchange rate for a given currency code (like EUR, GBP, JPY) against USD.

This is the initial implementation:

public static class CurrencyConversion
{
    public static async Task<IResult> Handle(
		string currencyCode,
		decimal amount,
		CurrencyApiClient currencyClient)
	{
		// Validate currency code format (3 uppercase letters)
		if (string.IsNullOrWhiteSpace(currencyCode) ||
			currencyCode.Length != 3 ||
			!currencyCode.All(char.IsLetter))
		{
			return Results.BadRequest(
				new { error = "Currency code must be a 3-letter uppercase code (e.g., EUR, GBP)" });
		}

		// Validate amount (must be positive)
		if (amount < 0)
		{
			return Results.BadRequest(new { error = "Amount must be a positive number" });
		}

		var rate = await currencyClient.GetExchangeRateAsync(currencyCode);

		if (rate == null)
		{
			return Results.NotFound(
				new { error = $"Exchange rate for {currencyCode} not found or API error occurred" });
		}

		var convertedAmount = amount * rate.Value;

		return Results.Ok(new ExchangeRateResponse(
			Currency: currencyCode,
			BaseCurrency: "USD",
			Rate: rate.Value,
			Amount: amount,
			ConvertedAmount: convertedAmount
        ));
    }
}

This works fine in your local dev environment. But in production, if 100 people hit this at the same time, you're making 100 identical network calls. Your API provider will hate you (and you may even get rate limited), and your latency will spike.

Now let's build a cache to fix this without using any external libraries. Remember, we're doing this for learning purposes only.

Level 1: Adding a ConcurrentDictionary

Your first thought is probably to store the rates in a ConcurrentDictionary. It’s thread-safe, so it feels like the right tool.

private static readonly ConcurrentDictionary<string, decimal> Cache = new();

// In the Handler:
if (Cache.TryGetValue(currencyCode, out var cachedRate))
{
	return cachedRate;
}

var rate = await currencyClient.GetExchangeRateAsync(currencyCode);

Cache.TryAdd(currencyCode, rate.Value);

This definitely helps with performance under load. Multiple threads can read and write to the dictionary without crashing. But ConcurrentDictionary protects the dictionary structure, not your logic.

If 100 users request "EUR" at the exact same time, TryGetValue will return false for all of them. They will all proceed to call the API. This is a classic race condition. You've protected your memory, but you haven't protected the external API.

There's also another problem with this approach: the rates never expire.

Level 2: Adding Cache Expiration

Currency rates don't stay the same forever. We need a way to expire them. Since ConcurrentDictionary doesn't have a "Time to Live" (TTL), we have to wrap our data.

// Store both the rate and the time it was created
private record CacheEntry(decimal Rate, DateTime CreatedAt);

// Our cache now stores CacheEntry objects
private static readonly ConcurrentDictionary<string, CacheEntry> Cache = new();
private static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);

// Check: Is it there? And is it still "fresh"?
if (Cache.TryGetValue(currencyCode, out var entry) &&
    (DateTime.UtcNow - entry.CreatedAt) < CacheDuration)
{
	return entry.Rate;
}

Now we have expiration. But we've actually created a new problem: The Thundering Herd (a.k.a Cache Stampede).

Every 5 minutes, when the cache expires, all incoming traffic will see "stale" data and try to refresh it at once.

So we need to fix that next.

Level 3: Solving the "Cache Stampede"

To fix the stampede, we need to ensure that only one person can fetch the update while everyone else waits.

How do we do that in C#?

We use a SemaphoreSlim and a pattern called Double-Checked Locking. We check the cache once (the "fast path"), then we lock, and then we check again to see if someone else filled it while we were waiting for the lock.

// Basically a mutex but async-friendly
private static readonly SemaphoreSlim Lock = new(1, 1);

public static async Task<decimal> GetRateAsync(string code, CurrencyApiClient client)
{
	// Fast path: No locking needed
	if (Cache.TryGetValue(code, out var entry) && IsFresh(entry))
	{
		return entry.Rate;
	}

    var acquired = await Lock.WaitAsync(TimeSpan.FromSeconds(10)); // Avoid deadlocks
    if (!acquired)
    {
        throw new Exception("Could not acquire lock to fetch exchange rate.");
    }
	try
	{
		// Double-check: Did someone else finish the API call while we waited?
		if (Cache.TryGetValue(code, out entry) && IsFresh(entry))
		{
			return entry.Rate;
		}

		var rate = await client.GetExchangeRateAsync(code);
		var newEntry = new CacheEntry(rate.Value, DateTime.UtcNow);

		// Atomically update the cache
		// This is safe because we're inside the lock
		Cache.AddOrUpdate(code, newEntry, (_, _) => newEntry);
		return rate.Value;
	}
	finally
	{
		// Always release the lock
		Lock.Release();
	}
}

This is an improvement. But something still feels off.

Can you spot the problem with this code?

Our lock behaves like a global lock. This means that if one thread is fetching "EUR", all other threads (even those requesting "JPY") are blocked until the "EUR" fetch completes. This problem is called lock contention.

Let's fix that next.

Level 4: Scaling with Keyed Locking

The "pro" move here is Keyed Locking. We create a lock for every specific currency. Since the number of currencies is finite, this isn't too memory-intensive.

We need an additional ConcurrentDictionary to hold our semaphores, per currency code.

private static readonly ConcurrentDictionary<string, SemaphoreSlim> Locks = new();

// In the Handler:
var semaphore = Locks.GetOrAdd(currencyCode, _ => new SemaphoreSlim(1, 1));
if (!Cache.TryGetValue(currencyCode, out var cachedRate) &&
	DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)
{
    var acquired = await semaphore.WaitAsync(TimeSpan.FromSeconds(10));
    if (!acquired)
    {
        throw new Exception("Could not acquire lock to fetch exchange rate.");
    }
	try
	{
		// Fetch and update logic...
	}
	finally { semaphore.Release(); }
}

The only thing that changes is how we acquire the lock. Now, if one thread is fetching "EUR", other threads requesting "JPY" can proceed without waiting. This is the most scalable version of our cache.

But... It only works in memory. So it's not suitable for distributed systems or multiple server instances. There are also a few more edge cases to consider, but you can explore those as an exercise.

The Final Code

Here's the final version of our caching logic:

public static class CurrencyConversion
{
    private record CacheEntry(decimal Rate, DateTime CreatedAt);
    private static readonly ConcurrentDictionary<string, CacheEntry> Cache = new();
    private static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);

    private static readonly ConcurrentDictionary<string, SemaphoreSlim> Locks = new();

    public static async Task<IResult> Handle(
        string currencyCode,
        decimal amount,
        CurrencyApiClient currencyClient)
    {
        // Validate currency code format (3 uppercase letters)
        if (string.IsNullOrWhiteSpace(currencyCode) ||
            currencyCode.Length != 3 ||
            !currencyCode.All(char.IsLetter))
        {
            return Results.BadRequest(
                new { error = "Currency code must be a 3-letter uppercase code (e.g., EUR, GBP)" });
        }

        // Validate amount (must be positive)
        if (amount < 0)
        {
            return Results.BadRequest(new { error = "Amount must be a positive number" });
        }

        decimal? rate;
        var semaphore = Locks.GetOrAdd(currencyCode, _ => new SemaphoreSlim(1, 1));
        if (!Cache.TryGetValue(currencyCode, out var cachedRate) &&
            DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)
        {
            var acquired = await semaphore.WaitAsync(TimeSpan.FromSeconds(10));
            if (!acquired)
            {
                throw new Exception("Could not acquire lock to fetch exchange rate.");
            }

            try
            {
                // Double-check locking pattern: check again inside the lock
                if (!Cache.TryGetValue(currencyCode, out cachedRate) &&
                    DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)
                {
                    rate = await currencyClient.GetExchangeRateAsync(currencyCode);

                    if (rate == null)
                    {
                        return Results.NotFound(
                            new { error = $"Exchange rate for {currencyCode} not found or API error occurred" });
                    }

                    Cache.AddOrUpdate(currencyCode,
                        _ => new CacheEntry(rate.Value, DateTime.UtcNow),
                        (_, _) => new CacheEntry(rate.Value, DateTime.UtcNow));
                }
                else
                {
                    rate = cachedRate!.Rate;
                }
            }
            finally
            {
                semaphore.Release();
            }
        }
        else
        {
            rate = cachedRate!.Rate;
        }

        var convertedAmount = amount * rate.Value;

        return Results.Ok(new ExchangeRateResponse(
            Currency: currencyCode,
            BaseCurrency: "USD",
            Rate: rate.Value,
            Amount: amount,
            ConvertedAmount: convertedAmount
        ));
    }
}

The next step would be to extract the core caching logic into its own reusable class. That way, you can use it in other parts of your application.

Takeaway

Why go through all this trouble?

It's easy to look at a simple ConcurrentDictionary and think you're done. But as we've seen, the gap between "it works" and "it scales" is filled with edge cases that can bring a production system to its knees.

When you use a library, it handles these edge cases for you. But building it yourself teaches you about the "three pillars" of high-performance code:

1. Thread safety
2. Lock contention
3. Resource protection

Sometimes the most "boring" parts of our infrastructure, like a cache, are actually the most architecturally interesting.

There's also that 1% of the time when you need a custom solution that no library can provide. So it's worth knowing the fundamentals of how these things work.

Modern libraries like HybridCache or FusionCache handle this for you, but understanding these patterns ensures you know exactly why your application behaves the way it does under load.

And since this is the last issue of the year, I wish you a fantastic New Year! 🎉

With the release of ASP.NET Core 10, we finally have a native, high-level API for Server-Sent Events (SSE). It bridges the gap between basic HTTP polling and full-duplex WebSockets via SignalR.

Why SSE Instead of SignalR?

SignalR is a powerhouse that handles WebSockets, Long Polling, and SSE automatically, providing a full-duplex (two-way) communication channel. However, it comes with a footprint: a specific protocol (Hubs), a required client-side library, and a need for "sticky sessions" or a backplane (like Redis) for scaling.

SSE is different because:

• Unidirectional: It's designed specifically for streaming data from the server to the client.
• Native HTTP: It's just a standard HTTP request with a text/event-stream content type. No custom protocols.
• Automatic Reconnection: Browsers natively handle reconnections via the EventSource API.
• Lightweight: No heavy client libraries or complex handshake logic.

The Simplest Server-Sent Events Endpoint

The beauty of the .NET 10 SSE API is its simplicity. You can use the new Results.ServerSentEvents to return a stream of events from any IAsyncEnumerable<T>. Because IAsyncEnumerable represents a stream of data that can arrive over time, the server knows to keep the HTTP connection open rather than closing it after the first "chunk" of data.

Here's a minimal example of an SSE endpoint that streams order placements in real-time:

app.MapGet("orders/realtime", (
	ChannelReader<OrderPlacement> channelReader,
	CancellationToken cancellationToken) =>
{
	// 1. ReadAllAsync returns an IAsyncEnumerable
	// 2. Results.ServerSentEvents tells the browser: "Keep this connection open"
	// 3. New data is pushed to the client as soon as it enters the channel
	return Results.ServerSentEvents(
        channelReader.ReadAllAsync(cancellationToken),
        eventType: "orders");
});

When a client hits this endpoint:

1. The server sends a Content-Type: text/event-stream header.
2. The connection stays active and idle while waiting for data.
3. As soon as your application pushes an order into the Channel, the IAsyncEnumerable yields that item, and .NET immediately flushes it down the open HTTP pipe to the browser.

It's an incredibly efficient way to handle "push" notifications without the overhead of a stateful protocol.

I'm using a Channel here as a means to an end. In a real application, you might have a background service that listens to a message queue (like RabbitMQ or Azure Service Bus) or a database change feed, and pushes new events into the channel for connected clients to consume.

Handling Missed Events

The simple endpoint we just built is great, but it has one weakness: it's missing resilience.

One of the biggest challenges with real-time streams is connection drops. By the time the browser automatically reconnects, several events might have already been sent and lost. To solve this, SSE has a built-in mechanism: the Last-Event-ID header. When a browser reconnects, it sends this ID back to the server.

In .NET 10, we can use the SseItem<T> type to wrap our data with metadata like IDs and retry intervals.

By combining a simple in-memory OrderEventBuffer with the Last-Event-ID provided by the browser, we can "replay" missed messages upon reconnection:

app.MapGet("orders/realtime/with-replays", (
	ChannelReader<OrderPlacement> channelReader,
	OrderEventBuffer eventBuffer,
	[FromHeader(Name = "Last-Event-ID")] string? lastEventId,
	CancellationToken cancellationToken) =>
{
	async IAsyncEnumerable<SseItem<OrderPlacement>> StreamEvents()
	{
		// 1. Replay missed events from the buffer
		if (!string.IsNullOrWhiteSpace(lastEventId))
		{
			var missedEvents = eventBuffer.GetEventsAfter(lastEventId);
			foreach (var missedEvent in missedEvents)
			{
				yield return missedEvent;
			}
		}

		// 2. Stream new events as they arrive in the Channel
		await foreach (var order in channelReader.ReadAllAsync(cancellationToken))
		{
			var sseItem = eventBuffer.Add(order); // Buffer assigns a unique ID
			yield return sseItem;
		}
	}

	return TypedResults.ServerSentEvents(StreamEvents(), "orders");
});

Filtering Server-Sent Events by User

Server-Sent Events is built on top of standard HTTP. Because it is a standard GET request, your existing infrastructure "just works":

• Security: You can pass a standard JWT in the Authorization header.
• User Context: You can access HttpContext.User to extract a User ID and filter the stream. You only send a user the data that belongs to them.

Here's an example of an SSE endpoint that streams only the orders for the authenticated user:

app.MapGet("orders/realtime", (
	ChannelReader<OrderPlacement> channelReader,
	IUserContext userContext, // Injected context containing user metadata
	CancellationToken cancellationToken) =>
{
	// The UserId is extracted from the JWT access token by the IUserContext
	var currentUserId = userContext.UserId;

	async IAsyncEnumerable<OrderPlacement> GetUserOrders()
	{
		await foreach (var order in channelReader.ReadAllAsync(cancellationToken))
		{
			// We only yield data that belongs to the authenticated user
			if (order.CustomerId == currentUserId)
			{
				yield return order;
			}
		}
	}

	return Results.ServerSentEvents(GetUserOrders(), "orders");
})
.RequireAuthorization(); // Standard ASP.NET Core Authorization

Note that when you write a message to a Channel it's broadcast to all connected clients. This isn't ideal for per-user streams. You'll probably want to use something more robust for production.

Consuming Server-Sent Events in JavaScript

On the client side, you don't need to install a single npm package. The browser's native EventSource API handles the heavy lifting, including the "reconnect and send Last-Event-ID" logic we discussed above.

const eventSource = new EventSource('/orders/realtime/with-replays');

// Listen for the specific 'orders' event type we defined in C#
eventSource.addEventListener('orders', (event) => {
  const payload = JSON.parse(event.data);
  console.log(`New Order ${event.lastEventId}:`, payload.data);
});

// Do something when the connection opens
eventSource.onopen = () => {
  console.log('Connection opened');
};

// Handle generic messages (if any)
eventSource.onmessage = (event) => {
  console.log('Received message:', event);
};

// Handle errors and reconnections
eventSource.onerror = () => {
  if (eventSource.readyState === EventSource.CONNECTING) {
    console.log('Reconnecting...');
  }
};

Summary

SSE in .NET 10 is the perfect middle ground for simple, one-way updates like dashboards, notification bells, and progress bars. It's lightweight, HTTP-native, and easy to secure using your existing middleware.

However, SignalR remains the robust, battle-tested choice for complex bi-directional communication or massive scale requiring a backplane.

The goal isn't to replace SignalR, but to give you a simpler tool for simpler jobs. Choose the lightest tool that solves your problem.

That's all for today. Hope this was helpful.

Microsoft is (finally!) addressing that with .slnx: an XML-based, simpler solution format designed to be easier to read, edit, and merge.

Here is your practical guide to the future of .NET solutions.

The problem with .sln

Classic .sln files are verbose: GUID-heavy project entries + configuration blocks that explode as your solution grows. It's also a frequent source of merge conflicts.

To appreciate the new format, we must look at the old one.

Here's a typical .sln file from a moderately sized .NET solution:

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.7.34031.279
MinimumVisualStudioVersion = 10.0.40219.1
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{8FC526EA-218B-4615-8410-4E1850611F38}"
	ProjectSection(SolutionItems) = preProject
		.editorconfig = .editorconfig
		Directory.Build.props = Directory.Build.props
		Directory.Packages.props = Directory.Packages.props
	EndProjectSection
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{64A28C1B-09AF-426E-8721-D002BE554B48}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SharedKernel", "src\SharedKernel\SharedKernel.csproj", "{166778A2-518F-47F0-BBC7-DB49C76A963C}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Domain", "src\Domain\Domain.csproj", "{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Application", "src\Application\Application.csproj", "{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Infrastructure", "src\Infrastructure\Infrastructure.csproj", "{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Web.Api", "src\Web.Api\Web.Api.csproj", "{86506D03-3746-41E7-A645-97D3633981DB}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{1EB88D85-BE1E-46DE-99A2-2F02363060AF}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ArchitectureTests", "tests\ArchitectureTests\ArchitectureTests.csproj", "{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}"
EndProject
Project("{E53339B2-1760-4266-BCC7-CA923CBCF16C}") = "docker-compose", "docker-compose.dcproj", "{34BB3069-D5D0-4046-ACAD-A2025ED7678F}"
EndProject
Global
	GlobalSection(SolutionConfigurationPlatforms) = preSolution
		Debug|Any CPU = Debug|Any CPU
		Release|Any CPU = Release|Any CPU
	EndGlobalSection
	GlobalSection(ProjectConfigurationPlatforms) = postSolution
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{166778A2-518F-47F0-BBC7-DB49C76A963C}.Release|Any CPU.Build.0 = Release|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Release|Any CPU.Build.0 = Release|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Release|Any CPU.Build.0 = Release|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Release|Any CPU.Build.0 = Release|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{86506D03-3746-41E7-A645-97D3633981DB}.Release|Any CPU.Build.0 = Release|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Release|Any CPU.Build.0 = Release|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Release|Any CPU.Build.0 = Release|Any CPU
	EndGlobalSection
	GlobalSection(SolutionProperties) = preSolution
		HideSolutionNode = FALSE
	EndGlobalSection
	GlobalSection(NestedProjects) = preSolution
		{166778A2-518F-47F0-BBC7-DB49C76A963C} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{86506D03-3746-41E7-A645-97D3633981DB} = {64A28C1B-09AF-426E-8721-D002BE554B48}
		{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA} = {1EB88D85-BE1E-46DE-99A2-2F02363060AF}
	EndGlobalSection
	GlobalSection(ExtensibilityGlobals) = postSolution
		SolutionGuid = {B948A3CC-9872-4612-ABD2-BB3D49671542}
	EndGlobalSection
EndGlobal

Good luck trying to make sense of that during a merge conflict!

What .slnx looks like

A minimal .slnx is basically a list of projects in XML.

Here's the same solution as above, but in .slnx format. We even have solution items, folders, and a docker-compose project.

<Solution>
  <Folder Name="/Solution Items/">
    <File Path=".editorconfig" />
    <File Path="Directory.Build.props" />
    <File Path="Directory.Packages.props" />
  </Folder>
  <Folder Name="/src/">
    <Project Path="src/Application/Application.csproj" />
    <Project Path="src/Domain/Domain.csproj" />
    <Project Path="src/Infrastructure/Infrastructure.csproj" />
    <Project Path="src/SharedKernel/SharedKernel.csproj" />
    <Project Path="src/Web.Api/Web.Api.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/ArchitectureTests/ArchitectureTests.csproj" />
  </Folder>
  <Project Path="docker-compose.dcproj">
    <Build />
  </Project>
</Solution>

It looks remarkably similar to a .csproj file.

How to Migrate Today

The .slnx format is available in recent versions of Visual Studio 2022 (v17.13+) and the .NET 9 SDK. Here is how you can switch.

Option 1: The Command Line

If you have the .NET 9 SDK installed (specifically 9.0.200 or later), you can migrate instantly via the CLI.

1. Open your terminal in the solution folder.

2. Run the migration command:

   dotnet sln migrate
   

3. This creates a new .slnx file alongside your old .sln.

At this point I would recommend deleting the old .sln file to avoid confusion. There's no point in keeping both in the same repo.

Option 2: Visual Studio "Save As"

If you prefer the GUI, you can do this directly inside Visual Studio 2022 (or 2026).

1. Select the Solution in the Solution Explorer.

2. Go to File > Save Solution As....

   

3. Change the "Save as type" dropdown to Xml Solution File (*.slnx).

   

Why You Should Care

• Fewer Merge Conflicts: The #1 benefit. Because the file is simple XML without random GUIDs changing, git merges become trivial.
• Human Readable: You can open this in Notepad, understand it, and edit it without breaking your entire build.
• Consistency: It finally aligns the solution format with the project format (.csproj), which moved to simplified XML years ago.
• Performance: Smaller file sizes and simpler parsing mean slightly faster load times for massive solutions.

Is it Ready?

As of late 2025/early 2026, .slnx is technically a Preview feature.

Safe to use? Yes, the format is stable.

Tooling support? Visual Studio 2022, Visual Studio 2026 and Rider support it well. So does the .NET CLI. Some older CI/CD pipelines or 3rd party tools might not recognize the extension yet.

My recommendation: Try it on a side project or a branch first. If your CI pipeline passes, you are ready to modernize.

I'm using this format in all my new projects and have migrated several existing ones without issues.

You know the one: the "Executive Dashboard" or the "User Summary" screen. It's the endpoint that needs to fetch three or four completely unrelated sets of data to paint a complete picture for the user. It needs the last 50 orders, the current system health logs, the user's profile settings, and maybe a notification count.

So, you write the code the standard way:

var orders = await GetRecentOrdersAsync(userId);
var logs = await GetSystemLogsAsync();
var stats = await GetUserStatsAsync(userId);

return new DashboardDto(orders, logs, stats);

This works. It's clean. It's readable. But there is a problem.

If GetRecentOrdersAsync takes 300ms, GetSystemLogsAsync takes 400ms, and GetUserStatsAsync takes 300ms, your users are staring at a loading spinner for 1 full second (300 + 400 + 300).

In a distributed system, latency kills user experience. Since these data sets are unrelated, we should be able to run them in parallel. If we did, the total time would only be the duration of the slowest query (400ms). That is a 60% performance improvement just by changing how we execute the code.

But if you try the naive approach with Entity Framework Core, your application will crash.

The False Promise of Task.WhenAll

The most common mistake developers make when trying to optimize this is wrapping their existing repository calls in tasks and waiting for them all at once.

It looks something like this:

// ❌ DO NOT DO THIS
public async Task<DashboardData> GetDashboardData(int userId)
{
    // These methods all use the same injected _dbContext
    var ordersTask = _repository.GetOrdersAsync(userId);
    var logsTask = _repository.GetLogsAsync();
    var statsTask = _repository.GetStatsAsync(userId);

    await Task.WhenAll(ordersTask, logsTask, statsTask); // BOOM 💥

    return new DashboardData(ordersTask.Result, logsTask.Result, statsTask.Result);
}

If you run this, you will immediately hit this dreaded exception:

A second operation started on this context before a previous operation completed. This is usually caused by different threads using the same instance of DbContext, however instance members are not guaranteed to be thread safe.

Why does this happen?

The DbContext in EF Core is not thread-safe. It is a stateful object designed to manage a single unit of work. It maintains a "Change Tracker" to keep track of the entities you've loaded, and it wraps a single underlying database connection.

Database protocols (like the TCP stream for PostgreSQL or SQL Server) are generally synchronous at the connection level. You cannot push two different SQL queries down the same wire at the exact same millisecond. When you use Task.WhenAll, multiple threads try to grab that single connection simultaneously, and EF Core steps in to throw the exception to prevent data corruption.

So, we have a dilemma: We want the speed of parallelism, but the DbContext forces us into sequential execution.

The Solution

Since .NET 5, EF Core has provided a first-class solution for this exact scenario: IDbContextFactory<T>.

Instead of injecting a scoped instance of your context (which lives for the entire HTTP request), you inject a factory that allows you to create lightweight, independent instances of DbContext on demand.

Note: While using the factory is the cleanest approach for Dependency Injection, you can also manually instantiate the context (using var context = new AppDbContext(options)) if you have access to the DbContextOptions.

First, we need to register the factory in our Program.cs.

// This registers IDbContextFactory<AppDbContext> as a Singleton (by default)
// It also registers AppDbContext as Scoped for ease of use elsewhere
builder.Services.AddDbContextFactory<AppDbContext>(options =>
{
    options.UseNpgsql(builder.Configuration.GetConnectionString("db"));
});

Now, let's refactor our slow dashboard endpoint. Instead of injecting AppDbContext, we inject IDbContextFactory<AppDbContext>.

Inside our method, we spin up a dedicated task for each query. Inside each task, we create a brand new context, execute the query, and then immediately dispose of it.

using Microsoft.EntityFrameworkCore;

public class DashboardService(IDbContextFactory<AppDbContext> contextFactory)
{
    public async Task<DashboardDto> GetDashboardAsync(int userId)
    {
        // 1. Start the tasks (The queries start executing immediately upon invocation)
        var ordersTask = GetOrdersAsync(userId);
        var logsTask = GetSystemLogsAsync();
        var statsTask = GetUserStatsAsync(userId);

        // 2. Wait for all to complete
        await Task.WhenAll(ordersTask, logsTask, statsTask);

        // 3. Return results (using 'await Task.WhenAll' here unwraps the result cleanly)
        return new DashboardDto(
            await ordersTask,
            await logsTask,
            await statsTask
        );
    }

    private async Task<List<Order>> GetOrdersAsync(int userId)
    {
        // Create a fresh context for this specific operation
        await using var context = await contextFactory.CreateDbContextAsync();

        return await context.Orders
            .AsNoTracking()
            .Where(o => o.UserId == userId)
            .OrderByDescending(o => o.CreatedAt)
            .ThenByDescending(o => o.Amount)
            .Take(50)
            .ToListAsync();
    }

    private async Task<List<SystemLog>> GetSystemLogsAsync()
    {
        await using var context = await contextFactory.CreateDbContextAsync();

        return await context.SystemLogs
            .AsNoTracking()
            .OrderByDescending(l => l.Timestamp)
            .Take(50)
            .ToListAsync();
    }

    private async Task<UserStats?> GetUserStatsAsync(int userId)
    {
        await using var context = await contextFactory.CreateDbContextAsync();

        return await context.Users
            .Where(u => u.Id == userId)
            .Select(u => new UserStats { OrderCount = u.Orders.Count })
            .FirstOrDefaultAsync();
    }
}

Key Concepts

1. Isolation: Each task gets its own DbContext. This means they get their own database connection. There is no contention.
2. Disposal: Notice the await using. This is critical. As soon as the query is done, we want to dispose of that context and return the connection to the pool.

The Benchmark

To prove this works, I built a small .NET 10 app using Aspire and PostgreSQL.. Since I'm running this locally, the absolute times are very low. If I used a remote database, the times would be higher, but the speedup ratio would be similar.

Sequential Execution: ~36ms

The waterfall is painfully obvious here. Each operation waits for the previous one to finish.

Parallel Execution: ~13ms

By using the parallel approach, the timeline compresses. All three database spans start at the same time and complete together.

Trade-offs & Conclusion

IDbContextFactory bridges the gap between EF Core's unit-of-work design and the reality of modern, parallel requirements. It allows you to break out of the "one request, one thread" box without sacrificing safety.

However, use this pattern sparingly:

• Connection pool starvation: A single HTTP request now occupies 3 database connections simultaneously instead of 1. If you have high concurrency, you can easily exhaust your connection pool.
• Context overhead: If your queries are extremely fast (e.g., simple lookups by ID), the overhead of creating multiple contexts and tasks might make the parallel version slower than the sequential one.

Next time you are staring at a slow dashboard, don't reach for raw SQL immediately. Check your awaits. If they are lined up single-file, it might be time to introduce some parallelization.

But when you start implementing more complex features, the cracks begin to show.

You build a CreateOrder slice. Then UpdateOrder. Then GetOrder. Suddenly, you notice the repetition. The address validation logic is in three places. The pricing algorithm is needed by both Cart and Checkout.

You feel the urge to create a Common project or SharedServices folder. This is the most critical moment in your VSA adoption.

Choose wrong, and you'll reintroduce the coupling you were trying to escape. Choose right, and you maintain the independence that makes VSA worthwhile.

Here's how I approach shared code in Vertical Slice Architecture.

The Guardrails vs. The Open Road

To understand why this is hard, we need to look at what we left behind.

Clean Architecture provides strict guardrails. It tells you exactly where code lives: Entities go in Domain, interfaces go in Application, implementations go in Infrastructure. It's safe. It prevents mistakes, but it also prevents shortcuts when they're appropriate.

Vertical Slice Architecture removes the guardrails. It says, "Organize code by feature, not technical concern". This gives you speed and flexibility, but it shifts the burden of discipline onto you.

So what can you do about it?

The Trap: The "Common" Junk Drawer

The path of least resistance is to create a project (or folder) named Shared, Common, or Utils.

This is almost always a mistake.

Imagine a Common.Services project with an OrderCalculationService class. It has a method for cart totals (used by Cart), another for historical revenue (used by Reporting), and a helper for invoice formatting (used by Invoices). Three unrelated concerns. Three different change frequencies. One class coupling them all together.

A Common project inevitably becomes a junk drawer for anything you can't be bothered to name properly. It creates a tangled web of dependencies where unrelated features are coupled together because they happen to use the same helper method.

You've reintroduced the very coupling you tried to escape.

The Decision Framework

When I hit a potential sharing situation, I ask three questions:

1. Is this infrastructural or domain?

Infrastructure (database contexts, logging, HTTP clients) almost always gets shared. Domain concepts need more scrutiny.

2. How stable is this concept?

If it changes once a year, share it. If it changes with every feature request, keep it local.

3. Am I past the "Rule of Three"?

Duplicating the same code once is fine. However, creating three duplicates should raise an eyebrow. Don't abstract until you hit three.

We solve this by refactoring our code. Let's look at some examples.

The Three Tiers of Sharing

Instead of binary "Shared vs. Not Shared," think in three tiers.

Tier 1: Technical Infrastructure (Share Freely)

Pure plumbing that affects all slices equally: logging adapters, database connection factories, auth middleware, the Result pattern, validation pipelines.

Centralize this in a Shared.Kernel or Infrastructure project. Note that this can also be a folder within your solution. It rarely changes due to business requirements.

// ✅ Good Sharing: Technical Kernel
public readonly record struct Result
{
    public bool IsSuccess { get; }
    public string Error { get; }

    private Result(bool isSuccess, string error)
    {
        IsSuccess = isSuccess;
        Error = error;
    }

    public static Result Success() => new(true, string.Empty);
    public static Result Failure(string error) => new(false, error);
}

Tier 2: Domain Concepts (Share and Push Logic Down)

This is one of the best places to share logic. Instead of scattering business rules across slices, push them into entities and value objects.

Here's an example:

// ✅ Good Sharing: Entity with Business Logic
public class Order
{
    public Guid Id { get; private set; }
    public OrderStatus Status { get; private set; }
    public List<OrderLine> Lines { get; private set; }

    public bool CanBeCancelled() => Status == OrderStatus.Pending;

    public Result Cancel()
    {
        if (!CanBeCancelled())
        {
            return Result.Failure("Only pending orders can be cancelled.");
        }

        Status = OrderStatus.Cancelled;
        return Result.Success();
    }
}

Now CancelOrder, GetOrder, and UpdateOrder all use the same business rules. The logic lives in one place.

Tier 3: Feature-Specific Logic (Keep It Local)

Logic shared between related slices, like CreateOrder and UpdateOrder, doesn't need to go global. Create a Shared folder (there's an exception to every rule) within the feature:

📂 Features
└──📂 Orders
    ├──📂 CreateOrder
    ├──📂 UpdateOrder
    ├──📂 GetOrder
    └──📂 Shared
        ├──📄 OrderValidator.cs
        └──📄 OrderPricingService.cs

This also has a hiddene benefit. If you delete the Orders feature, the shared logic goes with it. No zombie code left behind.

Let's explore some advanced scenarios most people overlook.

Cross-Feature Sharing

What about sharing code between unrelated features in Vertical Slice Architecture?

The CreateOrder slice needs to check if a customer exists. GenerateInvoice needs to calculate tax. Orders and Customers both need to format notification messages.

This doesn't fit neatly into a feature's Shared folder. So where does it go?

First, ask: do you actually need to share?

Most cross-feature "sharing" is just data access in disguise.

If CreateOrder needs customer data, it queries the database directly. It doesn't call into the Customers feature. Each slice owns its data access. The Customer entity is shared (it lives in Domain), but there's no shared service between them.

When you genuinely need shared logic, ask what it is:

• Domain logic (business rules, calculations) → Domain/Services
• Infrastructure (external APIs, formatting) → Infrastructure/Services

// Domain/Services/TaxCalculator.cs
public class TaxCalculator
{
    public decimal CalculateTax(Address address, decimal subtotal)
    {
        var rate = GetTaxRate(address.State, address.Country);
        return subtotal * rate;
    }
}

Both CreateOrder and GenerateInvoice can use it without coupling to each other.

Before creating any cross-feature service, ask: could this logic live on a domain entity instead? Most "shared business logic" is actually data access, domain logic that belongs on an entity, or premature abstraction.

If you need to trigger a side effect in another feature, I recommend using messaging and events. Alternatively, the feature you want to call into can explore a facade (public API) for that operation.

When Duplication Is the Right Call

Sometimes "shared" code isn't actually shared. It just looks that way.

// Features/Orders/GetOrder
public record GetOrderResponse(Guid Id, decimal Total, string Status);

// Features/Orders/CreateOrder
public record CreateOrderResponse(Guid Id, decimal Total, string Status);

They're identical. The temptation to create a SharedOrderDto is overwhelming. Resist it.

Next week, GetOrder needs a tracking URL. But CreateOrder happens before shipping, so there's no URL yet. If you'd shared the DTO, you'd now have a nullable property that's confusingly empty half the time.

Duplication is cheaper than the wrong abstraction.

The Practical Structure

Here's what a mature Vertical Slice Architecture project looks like:

📂 src
└──📂 Features
│   ├──📂 Orders
│   │   ├──📂 CreateOrder
│   │   ├──📂 UpdateOrder
│   │   └──📂 Shared          # Order-specific sharing
│   ├──📂 Customers
│   │   ├──📂 GetCustomer
│   │   └──📂 Shared          # Customer-specific sharing
│   └──📂 Invoices
│       └──📂 GenerateInvoice
└──📂 Domain
│   ├──📂 Entities
│   ├──📂 ValueObjects
│   └──📂 Services            # Cross-feature domain logic
└──📂 Infrastructure
│   ├──📂 Persistence
│   └──📂 Services
└──📂 Shared
    └──📂 Behaviors

• Features — Self-contained slices. Each owns its request/response models.
• Features/[Name]/Shared — Local sharing between related slices.
• Domain — Entities, value objects, and domain services. Shared business logic lives here.
• Infrastructure — Technical concerns.
• Shared — Cross-cutting behaviors only.

The Rules

After building several systems this way, here's what I've landed on:

1. Features own their request/response models. No exceptions.

2. Push business logic into the domain. Entities and value objects are the best place to share business rules.

3. Keep feature-family sharing local. If only Order slices need it, keep it in Features/Orders/Shared (feel free to find a better name than Shared).

4. Infrastructure is shared by default. Database contexts, HTTP clients, logging. These are technical concerns.

5. Apply the Rule of Three. Don't extract until you have three real usages with identical, stable logic.

Takeaway

Vertical Slice Architecture asks: "What feature does this belong to?"

The shared code question is really asking: "What do I do when the answer is multiple features?"

Acknowledge that some concepts genuinely span features. Give them a home based on their nature (domain, infrastructure, or cross-cutting behavior). Resist the urge to share everything just because you could.

The goal isn't zero duplication. It's code that's easy to change when requirements change.

And requirements always change.

Thanks for reading.

And stay awesome!

It's Monday morning, you have a deadline, and you need to implement a user registration feature. It's simple enough: save the user, send a welcome email, and track the signup in your analytics dashboard.

You write this:

public class UserService(
        IUserRepository userRepository,
        IEmailService emailService,
        IAnalyticsService analyticsService)
{
    public async Task RegisterUser(string email, string password)
    {
        var user = new User(email, password);
        await userRepository.SaveAsync(user);

        // 1. Directly coupled to email service (external API)
        await emailService.SendWelcomeEmail(user.Email);

        // 2. Directly coupled to analytics (this could be an external API)
        await analyticsService.TrackUserRegistration(user.Id);

        // What if we need to add more features?
        // This method will keep growing...
    }
}

It looks clean. It's readable. It works on your machine.

But this method is a ticking time bomb.

It assumes the "Happy Path" is the only path. It assumes the network is reliable, the email provider is up, and the analytics API is fast. In production, none of these are guaranteed.

Thinking further, I'm sure you can imagine similar code in your own projects. It might not be this exact scenario, but the pattern is common: a single method that orchestrates multiple side effects in a linear fashion.

Let's break down why this code is dangerous and how we can refactor it into a robust, event-driven architecture.

The Hidden Dangers of the "God Method"

There are three major issues hiding in those ten lines of code.

1. Temporal Coupling (Latency)

When a user clicks "Register," they have to wait for:

1. The Database +
2. The SMTP Server +
3. The Analytics API

If your analytics provider is having a bad day and takes 3 seconds to respond, your user waits 3 seconds. You are punishing your user for the slowness of a background system they don't even care about.

2. The Partial Failure State

This is the most critical risk. Imagine this scenario:

1. SaveAsync(user) succeeds. The user is in the DB.
2. SendWelcomeEmail succeeds. The user gets an email.
3. TrackUserRegistration throws a 503 Service Unavailable.

What happens now? If you wrap this in a transaction and rollback, you have deleted the user from the DB... but you already sent them a welcome email. The user tries to log in, but they don't exist. Now what?

If you don't rollback, you have a user in your system that is missing from your analytics. You have data inconsistency.

3. Violation of Single Responsibility (SRP)

You might argue that because we are using interfaces (IEmailService), we are decoupled. That is true for implementation details, but false for orchestration.

The UserService currently has two reasons to change:

1. Core Domain Logic: "We now require a username in addition to email."
2. Notification Policy: "Marketing wants to send an SMS in addition to the Email."

The UserService should strictly be responsible for the state change (creating the user). It should not be responsible for orchestrating the side effects of that change.

Level 1: Logical Decoupling with Domain Events

The first step to fixing this is to invert the control. Instead of the UserService commanding other services to do things, it should simply announce that something happened.

We can use Domain Events to achieve this.

Here is the refactored UserService:

public class UserService(
        IUserRepository userRepository,
        IDomainEventDispatcher dispatcher,
        IUnitOfWork unitOfWork)
{
    public async Task RegisterUser(string email, string password)
    {
        // 1. Create the User Entity
        var user = new User(email, password);

        // 2. Capture the side effect as an event object
        var userRegisteredEvent = new UserRegisteredEvent(user.Id, user.Email);

        // 3. Add the entity to the repository
        await userRepository.AddAsync(user);

        // 4. Dispatch the event (Assuming in-process dispatching here for simplicity)
        // Note: Handlers for Email and Analytics are now completely separate classes.
        await dispatcher.Dispatch(userRegisteredEvent);

        await unitOfWork.SaveChangesAsync();
    }
}

The UserService is now stable. Adding a "Loyalty Points" feature later doesn't require touching this method. You just add a new handler for the UserRegisteredEvent.

However, we haven't solved the reliability problem yet. If the process crashes immediately after Dispatch but before SaveChangesAsync completes, we might send an email for a user that failed to save. Or, if we save first and dispatch later, we might save the user but lose the event if the server crashes.

Level 2: Reliability with the Outbox Pattern

To fix this, we need Atomicity. Atomicity means that a set of operations either all succeed or all fail together.

We need to guarantee that if the User is saved, the UserRegisteredEvent is also saved.

Enter the Outbox Pattern.

Instead of publishing the event immediately to a message bus, we save the event to an OutboxMessages table in the same database transaction as the user.

Here is the complete implementation logic:

public async Task RegisterUser(string email, string password)
{
    // 1. Create the Domain Event
    var user = new User(email, password);
    var domainEvent = new UserRegisteredEvent(user.Id, user.Email);

    // 2. Open a Transaction
    using var transaction = dbContext.Database.BeginTransaction();

    try
    {
        // 3. Save the User to the Users Table
        dbContext.Users.Add(user);

        // 4. Serialize the Event and Save to Outbox Table
        var outboxMessage = new OutboxMessage
        {
            Id = Guid.NewGuid(),
            Type = nameof(UserRegisteredEvent),
            Content = JsonSerializer.Serialize(domainEvent),
            OccurredOn = DateTime.UtcNow,
            ProcessedOn = null // Null means it hasn't been handled yet
        };

        dbContext.OutboxMessages.Add(outboxMessage);

        // 5. Commit BOTH changes atomically
        await dbContext.SaveChangesAsync();
        await transaction.CommitAsync();
    }
    catch
    {
        await transaction.RollbackAsync();
        throw;
    }
}

Now, a background worker (running in a separate process) polls the OutboxMessages table. It picks up the message and publishes it to your message bus (RabbitMQ, Azure Service Bus, etc.).

If the email service is down, the background worker just retries later. We have achieved At-Least-Once delivery.

Level 3: Distributed Consistency with Sagas

The Outbox pattern is perfect for side effects (fire-and-forget actions like emails). But what if the subsequent action is mandatory?

Scenario: When a user registers, we must create a crypto-wallet for them in the WalletService. If the wallet creation fails (e.g., due to regulations), we cannot allow the user to exist in our system.

We can't just "retry later" if the WalletService says "Fraud Detected." We need to undo the user creation.

This is a distributed transaction, and we handle it with the Saga Pattern. A Saga coordinates a series of steps. If one fails, it executes Compensating Transactions to undo the previous work.

Here is how the failure scenario looks when using a Choreography-based Saga:

Here's the step-by-step breakdown of the flow:

1. UserService: Creates User → Publishes UserCreated
2. WalletService: Listens to UserCreated → Tries to create wallet
   • Failure: Wallet creation fails
   • Action: Publishes WalletCreationFailed
3. UserService: Listens to WalletCreationFailed → Deletes/Deactivates the User

This ensures Eventual Consistency. The system might be inconsistent for a few seconds (the user exists without a wallet), but it will eventually settle into a valid state (the user is removed).

Summary: A Heuristic for Decision Making

You don't need Sagas for everything. Over-engineering is just as bad as tight coupling. Use this simple rule of thumb:

1. Is it a simple notification? (Email, Analytics, Cache Invalidation)
   • Use Domain Events + Outbox. It's okay if it happens 5 seconds later.
2. Is it a critical business dependency? (Payments, Inventory, Account Status)
   • Use a Saga. If step B fails, step A must be reverted.

Coupling isn't just about code structure. It's about understanding and managing failure boundaries. If your Analytics Service goes down, it shouldn't prevent a user from registering. Build your systems to survive the unhappy path.

Hope this was helpful.

See you next week.

Well, Microsoft finally heard us. With .NET 10, they've introduced file-based apps. And honestly, it's about time.

What are File-based Apps?

The idea is simple: write your C# code in a single .cs file and run it directly. That's it.

No need to set up a whole project structure for that quick utility script you need to parse some CSV files or test an API endpoint.

You get to keep everything that makes C# great: the type safety, the performance, the rich standard library. But now you can use it for those throwaway scripts where setting up a full project would've been overkill. And yes, you can still reference NuGet packages, reference other C# projects, target specific SDKs, and configure project properties, all from within that single file using special directives that start with #:.

The feature builds on top-level statements (remember those from C# 9?) and takes them to their logical conclusion. If we're already letting people skip the class and Main method ceremony, why not let them skip the project ceremony too?

Getting Started with File-based Apps

Let's say you want to quickly check what day of the week a specific date falls on. Create a file called date-checker.cs:

var targetDate = new DateTime(2025, 12, 31);
Console.WriteLine($"New Year's 2025 falls on a {targetDate.DayOfWeek}");
Console.WriteLine($"That's {(targetDate - DateTime.Today).Days} days from now");

Run it with:

dotnet run date-checker.cs

The first time you run this, the CLI does some behind-the-scenes magic. It creates a virtual project, compiles your code, and caches everything. Subsequent runs are nearly instant because it's smart enough to know when nothing has changed.

Real-world Example: Quick Data Processing

Here's where things get interesting. Say you need to quickly process some JSON data and generate a report.

Let's do something practical with System.Text.Json and CsvHelper:

#:package CsvHelper@33.1.0
using System.Text.Json;
using CsvHelper;
using System.Globalization;

var json = await File.ReadAllTextAsync("sales_data.json");
var sales = JsonSerializer.Deserialize<List<SaleRecord>>(json);

var topProducts = sales
    .GroupBy(s => s.Product)
    .Select(g => new {
        Product = g.Key,
        TotalRevenue = g.Sum(s => s.Amount),
        UnitsSold = g.Count()
    })
    .OrderByDescending(p => p.TotalRevenue)
    .Take(10);

using var writer = new StreamWriter("top_products.csv");
using var csv = new CsvWriter(writer, CultureInfo.InvariantCulture);
csv.WriteRecords(topProducts);

Console.WriteLine("Report generated! Check top_products.csv");

record SaleRecord(string Product, decimal Amount, DateTime Date);

Notice how we're mixing package references, async operations, LINQ, and record types, all in a single file that reads like a cohesive script. This is the kind of thing you'd typically reach for Python for, but now you can stay in C# land.

Building Something More Ambitious with Aspire

You can actually create an Aspire AppHost in a single file, which is pretty wild when you think about it:

#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.AppHost@13.0.0

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
    .WithDataVolume();

var postgres = builder.AddPostgres("postgres")
    .WithDataVolume()
    .AddDatabase("tododb");

var todoApi = builder.AddProject<Projects.TodoApi>("api")
    .WithReference(cache)
    .WithReference(postgres);

builder.AddNpmApp("frontend", "../TodoApp")
    .WithReference(todoApi)
    .WithReference("api")
    .WithHttpEndpoint(env: "PORT")
    .WithExternalHttpEndpoints();

builder.Build().Run();

With the #:sdk Aspire.AppHost.Sdk@13.0.0 directive, your single file becomes a full orchestrator for a distributed application. You're defining infrastructure, wiring up dependencies, and setting up a complete development environment, all without creating a project file. It's particularly useful when you're prototyping architectures or need to quickly spin up a test environment.

Migrating to a Full Project

Eventually, some scripts outgrow their single-file roots. Maybe you need to split things into multiple files, or maybe you want proper IDE support for debugging. The transition is painless:

dotnet project convert MyUtility.cs

This generates a proper project structure while preserving all your package references and SDK choices. Your code moves to Program.cs, and you get a .csproj that reflects all those #: directives you were using.

Current Limitations

Right now, it's strictly single-file. If you need multiple files, you'll have to wait for .NET 11 or convert to a full project. Of course, you can still reference other projects or packages, but the main script has to be in one file.

The caching mechanism can occasionally get confused if you're rapidly iterating on package versions. And while the IDE support is getting better, it's not quite at the same level as full projects yet, especially for IntelliSense with dynamically referenced packages.

But for what it's designed to do (make C# approachable for scripting scenarios), it works remarkably well. You can use it for build scripts, data migration one-offs, quick API tests, or even teaching C# without overwhelming beginners with project structure.

Where This Leaves Us

File-based apps feel like C# finally acknowledging that not every piece of code needs to be an enterprise application. Sometimes you just need to parse a log file, sometimes you want to quickly test an algorithm, and sometimes you're teaching someone programming and don't want to explain what a solution file is on day one.

The feature doesn't revolutionize C# development, but it fills a gap that's been annoying developers for years. If you've been keeping a folder of scripts for quick tasks because C# felt too heavy, maybe it's time to give your favorite language another shot.

After all, the best language for a quick script is the one you already know, and now C# makes that argument a lot more compelling.

I always recommend reading about the Fallacies of Distributed Computing to understand the common pitfalls.

One of the key challenges is ensuring that messages are processed exactly once. Theoretically, that's impossible to guarantee in most systems. I won't dive into the CAP theorem or the Two Generals Problem here, but suffice to say:

• Messages can arrive out of order
• Messages can be duplicated
• Deliveries can be delayed

If you design your system assuming every message will be processed exactly once, you're setting yourself up for subtle data corruption.

But we can design our system to apply side effects exactly once using the Idempotent Consumer pattern.

Let's unpack what can go wrong, how brokers help with idempotency, and how you can build an idempotent consumer in .NET.

What Can Go Wrong When Publishing

Let's say your service publishes an event when a new note is created:

await publisher.PublishAsync(new NoteCreated(note.Id, note.Title, note.Content));

We don't have to worry about the specific implementation of publisher or the message broker here. It could be RabbitMQ, SQS, Azure Service Bus, etc.

Now imagine:

• The publisher sends the message to the broker
• The broker stores it and sends an ACK
• Network glitch: the ACK never reaches the producer
• Producer times out and retries the publish
• The broker now has two NoteCreated events

From the producer's perspective, it "fixed" a timeout. But from the consumer's perspective, it received two events for the same note creation.

And that's just one failure path. You can also get duplicates from:

• Broker redeliveries
• Consumer failures + retries

So even if you do everything "right" on the publisher, the consumer still has to be defensive.

Publisher-Side Idempotency (Let the Broker Handle It)

Many message brokers already support idempotent publishing via message deduplication if you include a unique message ID. Azure Service Bus, for instance, can detect duplicates and ignore re-publishes for the same message ID within a configured window. Amazon SQS and other brokers also offer similar guarantees.

You don't need to reinvent this logic in your application. The key is to assign each message a stable identifier that uniquely represents the logical event you're sending.

For example, when publishing a NoteCreated event:

var message = new NoteCreated(note.Id, note.Title, note.Content)
{
    MessageId = Guid.NewGuid() // or you can use note.Id
};

await publisher.PublishAsync(message);

If the network drops after you send the message, your app might retry. But when the broker sees the same MessageId, it knows this is a duplicate and safely discards it. You get deduplication without any custom tracking tables or extra state in your service.

This broker-level idempotency solves a large class of producer-side issues: network retries, transient failures, and duplicated publishes.

What it doesn't handle are consumer retries, which happen when messages are redelivered or your service crashes mid-processing.

That's where the idempotent consumer pattern comes in.

Implementing an Idempotent Consumer in .NET

Here's an example of an idempotent consumer for a NoteCreated event:.

internal sealed class NoteCreatedConsumer(
    TagsDbContext dbContext,
    HybridCache hybridCache,
    ILogger<Program> logger) : IConsumer<NoteCreated>
{
    public async Task ConsumeAsync(ConsumeContext<NoteCreated> context)
    {
        // 1. Check if we've already processed this message for this consumer
        if (await dbContext.MessageConsumers.AnyAsync(c =>
                c.MessageId == context.MessageId &&
                c.ConsumerName == nameof(NoteCreatedConsumer)))
        {
            return;
        }

        var request = new AnalyzeNoteRequest(
            context.Message.NoteId,
            context.Message.Title,
            context.Message.Content);

        try
        {
            using var transaction = await dbContext.Database.BeginTransactionAsync();

            // 2. Deterministic processing: derive tags from note content
            var tags = AnalyzeContentForTags(request.Title, request.Content);

            // 3. Persist tags
            var tagEntities = tags.Select(ProjectToTagEntity(request.NoteId)).ToList();
            dbContext.Tags.AddRange(tagEntities);

            // 4. Record that this message was processed
            dbContext.MessageConsumers.Add(new MessageConsumer
            {
                MessageId = context.MessageId,
                ConsumerName = nameof(NoteCreatedConsumer),
                ConsumedAtUtc = DateTime.UtcNow
            });

            await dbContext.SaveChangesAsync();
            await transaction.CommitAsync();

            // 5. Update cache
            await CacheNoteTags(request, tags);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Error analyzing note {NoteId}", request.NoteId);
            throw;
        }
    }
}

This is a typical idempotent consumer with a few important details.

1. The Idempotency Key

if (await dbContext.MessageConsumers.AnyAsync(c =>
        c.MessageId == context.MessageId &&
        c.ConsumerName == nameof(NoteCreatedConsumer)))
{
    return;
}

You use:

• MessageId from the transport (context.MessageId)
• ConsumerName (so multiple consumers can safely process the same message)

If a duplicate message arrives, you short-circuit and do nothing.

What's also important here is having a unique constraint on (MessageId, ConsumerName) in the MessageConsumers table to prevent race conditions. So even if you have concurrent processing of the same message, only one will succeed in inserting the record.

2. Atomic Side Effects + Idempotency Record

The processing and storing the message consumer record happen in the same transaction:

using var transaction = await dbContext.Database.BeginTransactionAsync();

// write tags
dbContext.Tags.AddRange(tagEntities);

// write message-consumer record
dbContext.MessageConsumers.Add(new MessageConsumer { ... });

await dbContext.SaveChangesAsync();
await transaction.CommitAsync();

Why this matters:

• If processing fails, there is no entry in MessageConsumers, so the message can be retried
• If processing succeeds, both the tags and the MessageConsumer row are committed together
• You never end up in a state where the work is done but the message is not marked as processed, or vice versa

This is the core of idempotency:

Do this work exactly once per message ID, even under retries.

3. Handling At-Least-Once Delivery

Most realistic setups are at-least-once:

• Consumer processes message
• ACK fails / times out
• Broker redelivers
• Your code runs again

With this pattern, the second run hits the MessageConsumers table and returns early.

No duplicate side effects.

This works, except for one caveat...

Deterministic vs Non-Deterministic Handlers

What happens when your handler calls something outside the database? An email API, a payment gateway, or a background job queue?

These are all common side effects that need to be idempotent too.

Those calls sit outside your transaction boundary. Your database might commit successfully, but if the network hiccups before the external service responds, you can't tell if the action happened or not. On retry, your consumer might send another email or charge the credit card twice.

You've now crossed into the messy territory of non-deterministic handlers: operations that can't be repeated safely.

There are two main strategies to deal with this.

1. Use an Idempotency Key in the External Call

If the external service supports it, pass a stable identifier, like the message's MessageId with every request. Many APIs, including payment processors and email platforms, let you specify an idempotency key header. The service ensures that identical requests with the same key only execute once.

For example:

await emailService.SendAsync(new SendEmailRequest
{
    To = user.Email,
    Subject = "Welcome!",
    Body = "Thanks for signing up.",
    IdempotencyKey = context.MessageId
});

Even if the request is retried, the provider will recognize the key and skip the duplicate. This is the simplest and most reliable approach, if your external dependency supports it.

2. Store the Intent Locally

If the external service doesn't support idempotency keys, you can simulate it. Store a record of the intended action in your database before calling the external system. For example, create a PendingEmails table that records which messages should be sent, keyed by message ID or user ID.

A background process can later read these pending records and perform the action once. This makes the process deterministic, but at the cost of more complexity, extra tables, and background workers. It's often overengineering unless the side effect is critical or irreversible, like payments or account provisioning.

The trade-off comes down to confidence. If repeating the action has real consequences, introduce idempotency explicitly. If not, retrying the operation might be acceptable.

When Idempotent Consumer Isn't Needed

Not every consumer needs the overhead of idempotency checks. If your operation is already naturally idempotent, you can often skip the extra table and transaction logic.

Updating a projection, setting a status flag, or refreshing a cache are all examples of deterministic actions that can safely run multiple times. For instance, "set user's status to Active" or "rebuild the read model" are operations that overwrite state rather than append to it.

Some handlers also use precondition checks to avoid duplication. If the handler updates an entity, it can first check whether that entity is already in the desired state and return early. That simple guard clause can be enough.

Don't blindly apply the Idempotent Consumer pattern everywhere. Apply it where it protects you from real harm, where duplicate processing causes financial or data inconsistencies.

For everything else, simpler is better.

Takeaway

Distributed systems are unpredictable. Retries, duplicates, and partial failures are part of normal operation. You can't avoid them, but you can design your system so they don't impact you as much.

Use your broker's built-in message deduplication to prevent duplicates from the producer side. For the consumer side, apply the Idempotent Consumer pattern to ensure side effects happen once, even under retries. Keep the record of processed messages and the actual side effect in the same transaction.

Not every message handler needs this. If your consumer is naturally idempotent or can short-circuit with a simple precondition, skip the extra complexity. But for anything that modifies persistent state or calls external systems, idempotency isn't optional, it's the only way to keep your system consistent.

Build your consumers to tolerate retries. And your distributed system will be that much more reliable. The interesting part is that once you understand this principle, you start seeing it everywhere in real-world systems.

If you want to dive deeper into messaging patterns and learn how this is implemented in a production-grade system, check out my Modular Monolith Architecture course. We'll build a full-featured application with distributed messaging, CQRS, and DDD patterns from scratch.

Hope this was helpful.

I like joins that read like what they do. Unfortunately, until now, LINQ didn't have a straightforward way to express left/right joins. You had to jump through hoops with GroupJoin and DefaultIfEmpty, which made the code harder to read and maintain.

But .NET 10 finally fixes this with the brand new LeftJoin and RightJoin methods.

What's a LEFT JOIN (in plain words)?

A LEFT JOIN returns all rows from the left side and the matching rows from the right side. If there's no match, the right side is null. Why we use it: to keep "owners" even when they have no related rows (e.g., show all products even if some don't have a review).

The Old Way (GroupJoin + DefaultIfEmpty)

Before .NET 10, a left join in LINQ needed a group join (GroupJoin), then DefaultIfEmpty to keep left rows with no match. It worked, but the intent was buried in noise.

There are two ways you could write it: query syntax and method syntax.

Query syntax

var query =
    from product in dbContext.Products
    join review in dbContext.Reviews on product.Id equals review.ProductId into reviewGroup
    from subReview in reviewGroup.DefaultIfEmpty()
    orderby product.Id, subReview.Id
    select new
    {
        ProductId = product.Id,
        product.Name,
        product.Price,
        ReviewId = (int?)subReview.Id ?? 0,
        Rating = (int?)subReview.Rating ?? 0,
        Comment = subReview.Comment ?? "N/A"
    };

Here's the SQL generated by EF Core for the above query:

SELECT
    p."Id" AS "ProductId",
    p."Name",
    p."Price",
    COALESCE(r."Id", 0) AS "ReviewId",
    COALESCE(r."Rating", 0) AS "Rating",
    COALESCE(r."Comment", 'N/A') AS "Comment"
FROM "Products" AS p
LEFT JOIN "Reviews" AS r ON p."Id" = r."ProductId"
ORDER BY p."Id", COALESCE(r."Id", 0)

Method syntax

var query = dbContext.Products
    .GroupJoin(
        dbContext.Reviews,
        product => product.Id,
        review => review.ProductId,
        (product, reviewList) => new { product, subgroup = reviewList })
    .SelectMany(
        joinedSet => joinedSet.subgroup.DefaultIfEmpty(),
        (joinedSet, review) => new
        {
            ProductId = joinedSet.product.Id,
            joinedSet.product.Name,
            joinedSet.product.Price,
            ReviewId = (int?)review!.Id ?? 0,
            Rating = (int?)review!.Rating ?? 0,
            Comment = review!.Comment ?? "N/A"
        })
    .OrderBy(result => result.ProductId)
    .ThenBy(result => result.ReviewId);

Why this works: GroupJoin matches rows, DefaultIfEmpty inserts a single default (null) when no matches exist, so the left row still appears. We then flatten with SelectMany.

I think we can all agree that this is way too verbose for something as common as a left join.

The New Way in EF 10: LeftJoin

Now we can write what we mean. LeftJoin is first-class LINQ and EF Core translates it to a LEFT JOIN in SQL.

var query = dbContext.Products
    .LeftJoin(
        dbContext.Reviews,
        product => product.Id,
        review => review.ProductId,
        (product, review) => new
        {
            ProductId = product.Id,
            product.Name,
            product.Price,
            ReviewId = (int?)review.Id ?? 0,
            Rating = (int?)review.Rating ?? 0,
            Comment = review.Comment ?? "N/A"
        })
    .OrderBy(x => x.ProductId)
    .ThenBy(x => x.ReviewId)

The generated SQL is identical to the previous example.

Why this is better:

• Intent is clear: you see LeftJoin, you know what to expect.
• Less code, fewer moving parts (no GroupJoin, no DefaultIfEmpty, no SelectMany).
• Same result: all products kept, reviews may be null.

Also New: RightJoin

RightJoin keeps all rows from the right side and only matching rows from the left. EF Core translates it to RIGHT JOIN. It's handy when the "must keep" side is the second sequence.

Conceptually:

var query = dbContext.Reviews
    .RightJoin(
        dbContext.Products,
        review => review.ProductId,
        product => product.Id,
        (review, product) => new
        {
            ProductId = product.Id,
            product.Name,
            product.Price,
            ReviewId = (int?)review.Id ?? 0,
            Rating = (int?)review.Rating ?? 0,
            Comment = review.Comment ?? "N/A"
        });

Why use RightJoin: when your reporting starts from Reviews (keep all), and bring in matching Products if they exist.

Here's the generated SQL:

SELECT
    p."Id" AS "ProductId",
    p."Name",
    p."Price",
    COALESCE(r."Id", 0) AS "ReviewId",
    COALESCE(r."Rating", 0) AS "Rating",
    COALESCE(r."Comment", 'N/A') AS "Comment"
FROM "Reviews" AS r
RIGHT JOIN "Products" AS p ON r."ProductId" = p."Id"

Wrapping Up

Think about how often you need left joins. Showing all users with optional profile settings. All products with optional reviews. All orders with optional shipping info. It's everywhere!

Before, developers would sometimes skip the proper left join and do two separate queries instead. Or worse, they'd use an inner join and miss data. Now there's no excuse - it's just as easy as any other LINQ method.

A few quick tips when writing LINQ queries:

• In the projection, guard nullable side: review.Comment ?? "N/A"
• Keep projections small to avoid pulling more columns than needed
• Add indexes on the join keys for better query plans

That's it. With LeftJoin and RightJoin, the code finally matches the mental model.

See you next Saturday.

One of the questions has stayed with me ever since:

A user clicks a button on the UI to generate an Excel or PDF report. The report generation takes around five minutes (time can be arbitrary). The user has to wait for it to finish. How would you optimize this flow?

At the time, I focused on what I knew best: performance. I started thinking about how to make the report generation faster. Maybe I could optimize the SQL queries, reduce data transformations, or cache parts of the result. If I could get the process down from five minutes to one, that felt like a big win.

But even if I made it five times faster, the user still had to wait. If the browser crashed, they lost everything. If the network dropped, the process stopped. If they closed the tab, all progress was gone.

It wasn't really a performance issue at all, it was a design issue.

What I Missed Back Then

Looking back, I realize I was stuck in the mindset of "make the code faster". Not that there's anything wrong with that, performance optimization is a valuable skill. What I didn't see immediately was the bigger problem. The app was doing all this work synchronously, holding the user hostage until it finished. I did eventually figure it out, with a few nudges from the interviewer.

The better question wasn't "How can I make this faster?"

It was "Why is the user waiting in the first place?"

If something takes minutes (or hours, days) to complete, it shouldn't block the user. It should happen in the background, out of the main request flow, while the user moves on with their work.

Still, don't forget to optimize the code itself. Database queries, data processing, and file generation all matter. Maybe there's a missing index, an inefficient loop, or a better library for creating Excel files. But those optimizations are just part of the solution, not the whole picture.

How I'd Solve It Today

Today, I'd still start with the same UI button. The user clicks "Generate Report," but instead of waiting, the backend accepts the request, saves it somewhere (maybe as a job record in a database), and returns right away. This is the essence of building asynchronous APIs. The job is then picked up by a background worker.

The worker can be a hosted service, a Quartz job, or even an AWS Lambda Function triggered by a queue message. It handles the heavy lifting: pulling the data, building the file, and uploading it to storage like S3 or Azure Blob.

Once the report is ready, the worker updates the job status to "completed" and notifies the user. That could be an email with a download link or a real-time SignalR message that shows up in the app. The link points to the stored report, served securely from the backend.

Now, the user isn't waiting on a long-running HTTP request. The server isn't holding open connections for minutes. If something fails, it can be retried automatically. You also have the option to track progress or cancel the job if needed. And if a hundred users request reports at once, the system can scale without locking up.

The experience feels faster, even if the actual report generation time hasn't changed. Because in the end, users don't care about performance metrics, they care about responsiveness.

Why I Still Use This Question

A few years later, I started using this exact question when interviewing other developers. Not to trick anyone, but because it reveals how people think.

Some candidates go straight to optimizing code and queries, just like I did back then. This is a good sign that they know their way around performance tuning. I can proceed with further technical questions around algorithms, data structures, or database optimization.

Others pause for a moment and start thinking about user experience, background processing, and fault tolerance. That's when the real conversation begins: queues, retries, notifications, secure file sharing, etc. There are so many ways you can spin off this one scenario into a broader system design discussion.

There's no single right answer. But there's a big difference between someone who focuses only on code and someone who can design a scalable system.

The Lesson

When I first heard this question, I thought about making the code faster. Now I think about making the experience better.

Optimizing a query or loop can help, but it doesn't fix waiting, failures, or scalability. If many users start the same report at once, a synchronous design breaks down fast. An asynchronous flow keeps the system responsive and resilient, no matter the load.

That shift from optimizing functions to designing scalable systems is the difference between a good developer and a great one.

If you want to go deeper into building systems that scale, my Clean Architecture course walks you through exactly that. You'll learn how to structure applications, separate concerns, and design systems that grow without breaking.

Hope this was helpful.

See you next week.

Before you write your first line of business logic, there are a few key setup steps that make your life (and your teammates) much easier later on.

Here's how I usually set up a new .NET project in six simple steps.

1. Enforce a Consistent Code Style

The first thing I add is an .editorconfig file.

This file ensures everyone on your team uses the same formatting and naming conventions, reducing inconsistent indents or random naming rules.

You can create one directly in Visual Studio:

The default configuration is a great start. But you can customize it further to fit your team's preferences.

Place it at the solution root so all projects follow the same rules. You can still override specific settings in subfolders if needed by placing an .editorconfig file there.

Here are two sample .editorconfig files you can use:

• From the .NET runtime repo
• Created by me for general .NET projects

2. Centralize Build Configuration

Next, I add a Directory.Build.props file to the solution root. This file lets you define build settings that apply to every project in the solution.

Here's an example:

<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>

This keeps your .csproj files clean and consistent, since there's no need to repeat these properties in every project.

If you later want to enable static analyzers or tweak build options, you can do it once here.

What's cool about this is your .csproj files become basically empty, with only NuGet package references most of the time.

3. Centralize Package Management

As your solution grows, managing NuGet package versions across multiple projects gets painful.

That's where central package management helps.

Create a file named Directory.Packages.props at the root:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
    <PackageVersion Include="SonarAnalyzer.CSharp" Version="10.15.0.120848" />
  </ItemGroup>
</Project>

Now, when you reference a NuGet package in your project, you don't specify the version. You can only use the package name like this:

<PackageReference Include="Microsoft.AspNetCore.OpenApi" />

All versioning is handled centrally. This makes dependency upgrades trivial and avoids version drift between projects.

You can still override versions in individual projects if needed.

4. Add Static Code Analysis

Static code analysis helps catch potential bugs and maintain code quality. .NET has a set of built-in analyzers, but I like to add SonarAnalyzer.CSharp for more comprehensive checks.

Let's install SonarAnalyzer.CSharp to catch potential code issues early:

Install-Package SonarAnalyzer.CSharp

Add it as a global package reference inside your Directory.Build.props:

<ItemGroup>
  <PackageReference Include="SonarAnalyzer.CSharp" />
</ItemGroup>

Combine this with:

<Project>
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest</AnalysisLevel>
    <AnalysisMode>All</AnalysisMode>
    <CodeAnalysisTreatWarningsAsErrors>true</CodeAnalysisTreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  </PropertyGroup>
</Project>

…and your build will fail on serious code quality issues. This can be a great safety net.

But it can also be noisy at first. If some rules don't fit your context, you can adjust or suppress them in .editorconfig by setting the rule severity to none.

5. Set Up Local Orchestration

For a consistent local environment across your team, you'll want container orchestration.

You have two main options:

Option 1: Docker Compose

Add Docker Compose support in Visual Studio. It will scaffold a docker-compose.yml file where you can define services like:

services:
  webapi:
    build: .
  postgres:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: password

This lets every developer spin up the same stack locally with one command.

Option 2: .NET Aspire

.NET Aspire takes orchestration a step further. It provides service discovery, telemetry, and streamlined configuration, all integrated with your .NET projects. It's become a personal favorite of mine.

You can add a .NET project and a Postgres resource with a few lines of code:

var postgres = builder.AddPostgres("demo-db");

builder.AddProject<WebApi>("webapi")
       .WithReference(postgres)
       .WaitFor(postgres);

builder.Build().Run();

Aspire still uses Docker under the hood but provides a richer developer experience.

Whether you pick Docker Compose or Aspire, the goal is the same: a repeatable, reliable local setup that works the same on every machine.

6. Automate Builds with CI

Finally, I set up a simple GitHub Actions workflow to validate each commit.

Example .github/workflows/build.yml:

name: Build

on:
  push:
    # Filter to only run on main branch
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v5
        with:
          dotnet-version: 10.0.x
      - run: dotnet restore
      - run: dotnet build --no-restore --configuration Release
      - run: dotnet test --no-build --configuration Release

This ensures your project always builds and passes tests, and it catches issues before they reach production. If the CI build fails, you know something's wrong right away.

When it comes to testing, I highly recommend exploring:

• Architecture testing to enforce architectural rules in your codebase
• Integration testing with Testcontainers to spin up real dependencies in Docker during tests (you can run this locally and in CI)

This will give you confidence that your code works as expected in an (as close as possible) production-like environment.

Wrapping Up

That's a wrap. Your new .NET project is now set up with:

• consistent code style
• centralized build and package management
• code quality enforcement
• reproducible local orchestration
• continuous integration

These small setup steps save countless hours down the road and keep your codebase clean, predictable, and ready to scale.

Once your project setup is solid, the next step is designing scalable boundaries. In my Modular Monolith Architecture course, I show how to grow a .NET application without turning it into a tangled mess, through clear module boundaries, messaging, and domain isolation.

If you're looking for a practical walkthrough of these steps, check out this video.

Thanks for reading.

And stay awesome!

AWS Lambda lets you run code on-demand, and with the Amazon.Lambda.AspNetCoreServer.Hosting library, you can plug an ASP.NET Core Minimal APIs straight into AWS Lambda.

In this article we'll set up a minimal API, deploy it, and discuss how it performs.

Don't worry if you're new to serverless, I'll keep everything simple enough to follow along.

Getting Your Minimal APIs Lambda-Ready

Let's start with the basics. You need just three things to turn your Minimal API into a Lambda function.

First, create your API:

dotnet new webapi -n MyLambdaApi
cd MyLambdaApi

Second, add Amazon's hosting package:

Install-Package Amazon.Lambda.AspNetCoreServer.Hosting

Third, add one line to your Program.cs:

var builder = WebApplication.CreateBuilder(args);

// This line does all the Lambda magic
builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi);

var app = builder.Build();

app.MapGet("/", () => "Hello from Lambda!");

app.Run();

That's it. Your API now runs both locally (for testing) and in Lambda (for production). When you run locally, it uses Kestrel like normal. When you deploy the app to AWS, Lambda takes over.

Ship It to AWS

You'll need the Lambda tools installed:

dotnet tool install -g Amazon.Lambda.Tools

Then deploy with one command:

dotnet lambda deploy-function

The tool asks you a few questions (like the function name, which IAM role to use). Pick the defaults if you're just testing. In a minute or two, your API is live with a URL like: https://[abc123xyz].lambda-url.[region-name].on.aws/.

From the AWS Management Console, you can find your function with its URL and all the other details.

Measuring Cold Starts

Here's where things become interesting (and problematic). Lambda functions "go to sleep" when nobody uses them. Waking them up takes time, this is the famous "cold start" problem.

I ran some simple tests with a basic Minimal API:

• First request (cold): 2,153 ms
• Second request (warm): 154 ms
• Third request (warm): 143 ms
• After 10 minutes idle (cold again): 2,074 ms

As you can see, the first request is slow due to the cold start. Subsequent requests are much faster, around 150 ms. After 10 minutes of inactivity, the function goes cold again, and the next request takes over 2 seconds. There's an optimization feature called SnapStart that can help reduce cold start times, but it has its own tradeoffs and isn't always suitable for every application.

Another thing to note is that I'm in Europe, and my Lambda function is in the US East (N. Virginia) region. This adds network latency, so your results may vary based on your location and the region you choose.

Even when warm, the latency is higher than a typical server-hosted API. This may be acceptable for low-traffic or non-critical endpoints, but it's something to consider.

Let's move beyond a "Hello World" example to something more realistic.

CRUD Operations Benchmark

To see how a simple API performs in the real world, I built a tiny CRUD app that creates a record, fetches it, updates it and then deletes it. First I ran each operation once to see the raw latency. Then I used a load-testing tool with 100 virtual users (VUs) to measure average latency under a bit more stress.

// POST /products - Create new product
app.MapPost("/products", async (CreateProductRequest request, NpgsqlDataSource dataSource) =>
{
    const string sql =
        """
        INSERT INTO Products (Name, Description, Price, CreatedAt)
        VALUES (@Name, @Description, @Price, @CreatedAt)
        RETURNING Id, Name, Description, Price, CreatedAt
        """;

    await using var connection = await dataSource.OpenConnectionAsync();
    var product = await connection.QueryFirstAsync<Product>(sql, new
    {
        request.Name,
        request.Description,
        request.Price,
        CreatedAt = DateTime.UtcNow
    });

    return Results.Created(
        $"/products/{product.Id}",
        new ProductResponse(
            product.Id,
            product.Name,
            product.Description,
            product.Price,
            product.CreatedAt));
});
// Other endpoints omitted for brevity:
// - GET /products/{id} - Get product by ID
// - PUT /products/{id} - Update product
// - DELETE /products/{id} - Delete product

The application uses .NET 8, Npgsql and Dapper to interact with a PostgreSQL database running on Amazon RDS. You can find the source code for this example (and the previous one) in this repository.

Here are the results:

Single-call latency

| Operation  | Latency (ms) | Notes                           |
| ---------- | ------------ | ------------------------------- |
| Create     |     537      | Cold start plus object creation |
| Read       |     134      | Simple GET of the new record    |
| Update     |     140      | Changing one property           |
| Delete     |     167      | Removing the record             |

The create call took half a second because it included a cold start and initialization overhead. Once the function was warmed up, the other operations completed in under two hundred milliseconds.

Load test with 100 virtual users

During the load test, I simulated 100 clients hitting the API at once. AWS automatically scaled the Lambda function to handle the traffic, and average latencies dropped because the functions were already warm. Here are the averages:

• CREATE avg: 129 ms
• READ avg: 132 ms
• UPDATE avg: 152 ms
• DELETE avg: 144 ms

These numbers show that once your function is up and running, Lambda can respond quite quickly even when many users are making requests. Of course, actual times will vary depending on what your API does and how it stores data.

Remember that each of these operations involves network calls to the database, which adds latency. Overall, I don't find these numbers bad for a serverless setup.

Summary

Hosting minimal APIs in AWS Lambda is surprisingly straightforward. With one library and a single method call, your ASP.NET Core code can run "without servers". You pay only for the compute you use. Also, the AWS Lambda free tier includes one million free requests per month, which is great for testing and light usage.

However, there are tradeoffs. Because of cold starts and the overhead of starting the .NET runtime, latency isn't as low as hosting on a dedicated server. If your API is mission-critical or requires sub-100 ms responses at all times, you may need to look at provisioned concurrency, containers, or a traditional host.

Lambda shines for small, event-driven or intermittent workloads that don't justify a full-time server. But it's less suitable for latency-sensitive or heavy, long-running applications. For occasional or low-traffic API endpoints, though, Lambda offers a cost-effective and simple option.

That's all for today.

See you next week.

Maybe you have a complex report that joins five tables with aggregations and window functions. Your LINQ query generates SQL that's slower than you'd like, and you know you could write better SQL by hand.

Or maybe you need to update inventory with proper locking to prevent race conditions. You could manage transactions and explicit locks in C#, but it feels like you're fighting the framework.

Here's what usually happens: you search for "EF Core stored procedures" and find conflicting advice. Some articles say avoid raw SQL at all costs. Others suggest abandoning EF entirely and writing ADO.NET. Neither feels right.

Actually, EF Core works great with database functions and procedures. You get the database's power for what it does best, and EF's convenience for everything else. Let me show you how this actually works.

I'll use PostgreSQL for examples, but the same principles apply to SQL Server and other relational databases.

When Should You Even Use Raw SQL?

Let's be honest: most of the time, LINQ is fine. EF Core translates your C# into decent SQL, and you get type safety and refactoring support.

But there are times when raw SQL makes more sense:

You need performance you can't get from LINQ. Complex aggregations with multiple joins, window functions, or reporting queries often run faster when written directly in SQL. You can test and tune the query in your database tool before bringing it into your code.

You're using database-specific features. PostgreSQL has powerful capabilities like full-text search, JSON operators, and common table expressions (CTEs) that don't always have clean LINQ equivalents. Sometimes the straightest path is just writing the SQL.

You have existing database logic. If your database already has stored procedures and functions (maybe from a legacy system), calling them directly beats rewriting everything in C#.

You need atomic operations with proper locking. A stored procedure that coordinates multiple updates with FOR UPDATE locks (here's a good use case) is simpler and safer than trying to manage that from application code.

You want to reduce round trips. One function call that aggregates data from five tables is more efficient than five separate LINQ queries.

Now let's see how to actually do this.

Example 1: Simple Scalar Function

Here's a straightforward function that tells you how many tickets are left:

CREATE OR REPLACE FUNCTION ticketing.tickets_left(p_ticket_type_id uuid)
RETURNS numeric
LANGUAGE sql
AS $$
  SELECT tt.available_quantity
  FROM ticketing.ticket_types tt
  WHERE tt.id = p_ticket_type_id
$$;

Nothing fancy, just a query wrapped in a function.

Calling it from EF Core is straightforward:

app.MapGet("ticket-types/{ticketTypeId}/available-quantity",
async (Guid ticketTypeId, EventManagementContext dbContext) =>
{
    var result = await dbContext.Database.SqlQuery<int>(
            $"""
             SELECT ticketing.tickets_left({ticketTypeId}) AS "Value"
             """)
        .FirstAsync();

    return Results.Ok(result);
});

Notice the AS "Value" alias. When EF Core maps to a primitive type, it expects a property named Value. The quotes preserve the exact casing (PostgreSQL lowercases unquoted identifiers by default).

The interpolated string syntax ($"{ticketTypeId}") might look dangerous, but EF Core converts this into a parameterized query automatically. You're not building SQL strings, you're using C# interpolation as a convenient syntax for parameters.

Example 2: Table-Valued Function

Functions can return entire result sets, which is where they really shine:

CREATE OR REPLACE FUNCTION ticketing.customer_order_summary(p_customer_id uuid)
RETURNS TABLE (
    order_id uuid,
    created_at_utc timestamptz,
    total_price numeric,
    currency text,
    item_count numeric
)
LANGUAGE sql
AS $$
SELECT
    o.id,
    o.created_at_utc,
    o.total_price,
    o.currency,
    COALESCE(SUM(oi.quantity), 0) AS item_count
FROM ticketing.orders o
LEFT JOIN ticketing.order_items oi ON oi.order_id = o.id
WHERE o.customer_id = p_customer_id
GROUP BY o.id, o.created_at_utc, o.total_price, o.currency
ORDER BY o.created_at_utc DESC
$$;

This function joins orders with their items, aggregates quantities, and returns multiple rows. You could write this in LINQ, but the SQL is clearer and you can test it directly in your database tool.

To use it from C#, create a DTO that matches the function's output:

public class OrderSummaryDto
{
    public Guid OrderId { get; set; }
    public DateTime CreatedAtUtc { get; set; }
    public decimal TotalPrice { get; set; }
    public string Currency { get; set; }
    public int ItemCount { get; set; }
}

Then query the function like any other table:

app.MapGet("customers/{customerId}/order-summary",
async (Guid customerId, EventManagementContext dbContext) =>
{
    var orders = await dbContext.Database
        .SqlQuery<OrderSummaryDto>(
            $"""
             SELECT
                order_id AS OrderId,
                created_at_utc AS CreatedAtUtc,
                total_price AS TotalPrice,
                currency AS Currency,
                item_count AS ItemCount
             FROM ticketing.customer_order_summary({customerId})
             """)
        .ToListAsync();

    return Results.Ok(orders);
});

The key is mapping column names to your DTO properties using aliases. EF Core handles the rest automatically.

This is a simple case without joins, but you can use this pattern in more complex queries too. However, you will have to project into DTOs manually since EF Core can't translate joins in raw SQL into entity graphs. Usually, you'll return a flat structure from functions anyway, and then map to richer models in C# if needed.

Understanding PostgreSQL Functions vs Procedures

PostgreSQL distinguishes between functions and procedures in important ways:

Functions are designed to return values. They can return scalar values, tables, or even complex JSON objects. You call them with SELECT and can use them in queries like any other expression. Functions run within a transaction and can be used in WHERE clauses, joins, and other query contexts.

Procedures are designed for side effects. They don't return values directly but can modify data and have OUT parameters. You call them with CALL and they're ideal for complex operations that need to manage transactions explicitly or perform multiple related updates.

Think of it this way: use functions when you need data, use procedures when you need to change something.

This distinction matters because it affects how you design your database logic and how you call these routines from C#.

Let's see an example of a procedure.

Example 3: Stored Procedure with Validation

Here's where procedures really prove their worth. Let's say you need to adjust ticket inventory, but you want to prevent race conditions and validate the operation:

CREATE OR REPLACE PROCEDURE ticketing.adjust_available_quantity(
    p_ticket_type_id uuid,
    p_delta numeric,
    p_reason text DEFAULT 'manual-adjust'
)
LANGUAGE plpgsql
AS $$
DECLARE
    v_qty numeric;
    v_avail numeric;
    v_new_avail numeric;
BEGIN
    SELECT quantity, available_quantity
    INTO v_qty, v_avail
    FROM ticketing.ticket_types
    WHERE id = p_ticket_type_id
    FOR UPDATE;

    IF NOT FOUND THEN
        RAISE EXCEPTION 'ticket_type % not found', p_ticket_type_id;
    END IF;

    v_new_avail := v_avail + p_delta;

    IF v_new_avail < 0 THEN
        RAISE EXCEPTION 'Cannot reduce below zero';
    END IF;

    IF v_new_avail > v_qty THEN
        RAISE EXCEPTION 'Cannot exceed quantity';
    END IF;

    UPDATE ticketing.ticket_types
    SET available_quantity = v_new_avail
    WHERE id = p_ticket_type_id;
END;
$$;

This procedure does several important things:

• Locks the row with FOR UPDATE so no other transaction can modify it until we're done
• Validates business rules before making changes
• Provides clear error messages when something goes wrong
• Keeps everything atomic in a single database round trip

You could do all this in C# with manual transaction management and explicit locking, but it's more complex and error-prone. Let the database handle what it's good at.

Here's how you call it from EF Core:

app.MapPut("ticket-types/{ticketTypeId}/available-quantity", async (
    Guid ticketTypeId,
    int quantity,
    EventManagementContext dbContext) =>
{
    try
    {
        await dbContext.Database.ExecuteSqlAsync(
            $"""
             CALL ticketing.adjust_available_quantity({ticketTypeId},{quantity})
             """);

        return Results.Ok(result);
    }
    catch (Exception e)
    {
        return Results.BadRequest(e.Message);
    }
});

The procedure doesn't return a value, but if it raises an exception (with RAISE EXCEPTION), PostgreSQL will propagate that to your C# code. You can catch it and return a proper error response.

About SQL Injection (Don't Panic)

You might be looking at those interpolated strings and thinking "wait, isn't this SQL injection waiting to happen?"

It's not.

When you write:

$"SELECT * FROM users WHERE id = {userId}"

EF Core doesn't concatenate strings. It converts this into:

SELECT * FROM users WHERE id = @p0

The actual value is sent as a parameter, completely separate from the SQL text. This works for all the examples in this article.

The interpolation syntax is just a convenient way to write parameterized queries.

The reason why is we're not actually passing in a string to the SqlQuery method, but a FormattableString. This is a special type that captures the format and arguments separately, allowing EF Core to handle parameters.

Everything in this article works with SQL Server, MySQL, SQLite, and other databases EF Core supports. The differences are mostly syntax.

A Quick Word on Views

Database views are like functions without parameters. They're saved queries you can reference by name.

You can query them using SqlQuery<T> just like functions:

var results = await dbContext.Database
    .SqlQuery<ActiveCustomerDto>(
        $"SELECT * FROM ticketing.active_customers")
    .ToListAsync();

Or you can map them to entity types in your DbContext for full LINQ support.

Views are great for frequently-used queries that don't need parameters. Functions give you the flexibility of parameterization.

Wrapping Up

We've covered how to use PostgreSQL functions and procedures with EF Core, from simple scalar functions to complex procedures with validation and locking.

You learned when to use functions (when you need data back) versus procedures (when you need to modify data). You saw how EF Core's SqlQuery<T> and ExecuteSqlAsync give you type safety while letting you write the SQL you need. And you learned when raw SQL makes sense: complex aggregations, database-specific features, atomic operations with locking, and reducing round trips.

EF Core doesn't force you to choose between LINQ and raw SQL. You can use both.

Use functions when you need to return data, procedures when you need to modify data with complex logic, and raw SQL queries when LINQ doesn't capture your requirements efficiently. The combination of EF Core's convenience and the database's power gives you the flexibility to choose the right tool for each scenario.

That's all for today. Hope this was helpful.

Most .NET developers start with simple role-based checks: "Is this user an Admin?" But as your application grows, you quickly realize that roles alone aren't enough. You need granular permissions that can be combined and assigned flexibly.

That's where Role-Based Access Control (RBAC) shines. Instead of hardcoding role checks everywhere, you define specific permissions and let roles carry those permissions. A user might be a Manager role, but what matters is whether they have the users:delete permission.

Let me show you how to build a flexible, permission-based authorization system in ASP.NET Core.

Understanding RBAC Components

RBAC has three key components that work together:

Users → assigned to → Roles → which contain → Permissions

Here's how it flows:

• Users: Individual people using your system
• Roles: Groups of related permissions (Admin, Manager, Editor)
• Permissions: Specific actions users can perform (users:read, orders:create, reports:delete)

The beauty is in the flexibility. You can assign multiple roles to a user, and roles can be modified without touching user assignments. Need to give all Managers the ability to export reports? Just add the reports:export permission to the Manager role.

This is much more maintainable than checking if someone is specifically an Admin or Super Manager in your code.

It also adds an extra extension point: you can implement custom permissions for some users without creating new roles.

Building a Custom Authorization Handler

ASP.NET Core's authorization system is built around policies and requirements. Let's create a custom handler that checks permissions stored in the user's claims:

public class PermissionAuthorizationRequirement(params string[] allowedPermissions)
    : AuthorizationHandler<PermissionAuthorizationRequirement>, IAuthorizationRequirement
{
    public string[] AllowedPermissions { get; } = allowedPermissions;

    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        PermissionAuthorizationRequirement requirement)
    {
        foreach (var permission in requirement.AllowedPermissions)
        {
            bool found = context.User.FindFirst(c =>
                c.Type == CustomClaimTypes.Permission &&
                c.Value == permission) is not null;

            if (found)
            {
                context.Succeed(requirement);
                break;
            }
        }
        return Task.CompletedTask;
    }
}

Here's what's happening under the hood:

The class combines both the requirement (what permissions are needed) and the handler (how to check them). This keeps related logic together and reduces boilerplate.

The handler looks through the user's claims for any claim with type Permission that matches one of the required permissions. It's an OR operation - the user only needs one of the specified permissions to proceed.

If a matching permission is found, we call context.Succeed(requirement) and break out early. No need to check the remaining permissions.

Alternatively, you could implement an AND operation if your use case requires all permissions to be present.

You'll need to define your custom claim type:

public static class CustomClaimTypes
{
    public const string Permission = "permission";
}

And then you'll use this when issuing JWT tokens or setting up user claims.

var permissions = await (
        from role in dbContext.Roles
        join permission in dbContext.RolePermissions on role.Id equals permission.RoleId
        where roles.Contains(role.Name)
        select permission.Name)
    .Distinct()
    .ToArrayAsync();

List<Claim> claims =
[
    new(JwtRegisteredClaimNames.Sub, user.Id),
    new(JwtRegisteredClaimNames.Email, user.Email!),
    ..roles.Select(r => new Claim(ClaimTypes.Role, r)),
    ..permissions.Select(p => new Claim(CustomClaimTypes.Permission, p))
];

var tokenDescriptor = new SecurityTokenDescriptor
{
    Subject = new ClaimsIdentity(claims),
    Expires = DateTime.UtcNow.AddMinutes(configuration.GetValue<int>("Jwt:ExpirationInMinutes")),
    SigningCredentials = credentials,
    Issuer = configuration["Jwt:Issuer"],
    Audience = configuration["Jwt:Audience"]
};

var tokenHandler = new JsonWebTokenHandler();

string accessToken = tokenHandler.CreateToken(tokenDescriptor);

Creating Clean APIs with Extension Methods

Raw authorization policies work, but they're verbose. Let's create extension methods that make the developer experience much cleaner:

public static class PermissionExtensions
{
    public static void RequirePermission(
        this AuthorizationPolicyBuilder builder,
        params string[] allowedPermissions)
    {
        builder.AddRequirements(new PermissionAuthorizationRequirement(allowedPermissions));
    }
}

Now you can use this with Minimal APIs:

public static class Permissions
{
    public const string UsersRead = "users:read";
    public const string UsersUpdate = "users:update";
    public const string UsersDelete = "users:delete";
}

app.MapGet("me", (ApplicationDbContext dbContext) =>
{
    var user = await dbContext.Users
        .AsNoTracking()
        .Where(u => u.Id == int.Parse(User.FindFirstValue(JwtRegisteredClaimNames.Sub)!))
        .Select(u => new UserDto
        {
            u.Id,
            u.Email,
            u.FirstName,
            u.LastName
        })
        .SingleOrDefaultAsync();

    return Results.Ok(user);
})
.RequireAuthorization(policy => policy.RequirePermission(Permissions.UsersRead));

For MVC Controllers, create an attribute:

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class RequirePermissionAttribute(params string[] permissions) : AuthorizeAttribute
{
    public RequirePermissionAttribute(params string[] permissions)
        : base(policy: string.Join(",", permissions))
    {
    }
}

Then register the policy in your DI container:

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("users:read", policy => policy.RequirePermission(Permissions.UsersRead))
    .AddPolicy("users:update", policy => policy.RequirePermission(Permissions.UsersUpdate));

Usage becomes clean:

[RequirePermission(Permissions.UsersUpdate)]
public async Task<IActionResult> UpdateUser(int id, UpdateUserRequest request)
{
    // Your logic here
}

Extension Points for Production

The basic implementation works great, but we could improve it further. Here are two key extension points:

Type-Safe Permissions with Enums

Instead of magic strings, use enums for compile-time safety:

public enum Permission
{
    UsersRead,
    UsersUpdate,
    UsersDelete,
    OrdersCreate,
    ReportsExport
}

You'll have to convert these to strings when issuing claims and checking permissions. And also convert from a string to an enum, when reading from claims and validating the permissions.

Server-Side Permission Resolution

Rather than storing all permissions in JWT tokens (which can get large), fetch them server-side using IClaimsTransformation:

public class PermissionClaimsTransformation(IPermissionService permissionService)
    : IClaimsTransformation
{
    public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        if (principal.Identity?.IsAuthenticated != true)
        {
            return principal;
        }

        var userId = principal.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        if (userId == null)
        {
            return principal;
        }

        // Fetch permissions from database, then cache
        // IMPORTANT: Cache these results to avoid DB hits on every request
        var permissions = await permissionService.GetUserPermissionsAsync(userId);

        var claimsIdentity = (ClaimsIdentity)principal.Identity;
        foreach (var permission in permissions)
        {
            claimsIdentity.AddClaim(new Claim(CustomClaimTypes.Permission, permission));
        }

        return principal;
    }
}

Register it in your DI container:

builder.Services.AddScoped<IClaimsTransformation, PermissionClaimsTransformation>();

This approach keeps your JWTs lightweight while still providing fast authorization checks through claims.

You can learn more about claims transformation in my previous article.

Takeaway

RBAC transforms authorization from a maintenance headache into a flexible, scalable system.

Start with permissions: Define what actions users can perform, not what roles they have.

Custom authorization handlers give you complete control over how permissions are validated.

Extension methods make the developer experience clean and consistent across your API.

For production systems, consider type-safe enums and server-side permission resolution to keep your tokens lean and your code maintainable.

The result? Authorization logic that's easy to understand, test, and modify as your application evolves.

.NET provides excellent concurrency control primitives for single-process scenarios, like lock, SemaphoreSlim, and Mutex. But when your application is scaled out across multiple instances, these primitives don't work anymore.

That's where distributed locking comes in.

Distributed locking provides a solution by ensuring only one node (application instance) can access a critical section at a time, preventing race conditions and maintaining data consistency across your distributed system.

Why and When You Need Distributed Locking

In a single-process app, you can just use lock or the new Lock class in .NET 10. But once you scale out, that's not enough, because each process has its own memory space.

A few common cases where distributed locks are valuable:

• Background jobs: ensuring only one worker processes a particular job or resource at a time.
• Leader election: choosing a single process to perform periodic work (like applying async database projections).
• Avoiding double execution: ensuring scheduled tasks don't run multiple times when deployed to multiple instances.
• Coordinating shared resources: e.g., only one service instance performing a migration or cleanup at a time.
• Cache stampede prevention: ensuring only one instance refreshes the cache when a given cache key expires.

The key value: consistency and safety across distributed environments. Without this, you risk duplicate operations, corrupted state, or unnecessary load.

Now you know why distributed locking is important.

Let's look at some implementation options.

DIY Distributed Locking with PostgreSQL Advisory Locks

Let's start simple. PostgreSQL has a feature called advisory locks that's perfect for distributed locking. Unlike table locks, these don't interfere with your data - they're purely for coordination.

Here's an example:

public class NightlyReportService(NpgsqlDataSource dataSource)
{
    public async Task ProcessNightlyReport()
    {
        await using var connection = dataSource.OpenConnection();

        var key = HashKey("nightly-report");

        var acquired = await connection.ExecuteScalarAsync<bool>(
            "SELECT pg_try_advisory_lock(@key)",
            new { key });

        if (!acquired)
        {
            throw new ConflictException("Another instance is already processing the nightly report");
        }

        try
        {
            await DoWork();
        }
        finally
        {
            await connection.ExecuteAsync(
                "SELECT pg_advisory_unlock(@key)",
                new { key });
        }
    }

    private static long HashKey(string key) =>
        BitConverter.ToInt64(SHA256.HashData(Encoding.UTF8.GetBytes(key)), 0);

    private static Task DoWork() => Task.Delay(5000); // Your actual work here
}

Here's what's happening under the hood.

First, we convert our lock name into a number. PostgreSQL advisory locks need numeric keys, so we hash nightly-report into a 64-bit integer. Every node (application instance) must generate the same number for the same string, or this won't work.

Next, pg_try_advisory_lock() attempts to grab an exclusive lock on that number. It returns true if successful, false if another connection already holds it. This call doesn't block - it tells you immediately whether you got the lock.

If we get the lock, we do our work. If not, we return a conflict response and let the other instance handle it.

The finally block ensures we always release the lock, even if something goes wrong. PostgreSQL also automatically releases advisory locks when connections close, which is a nice safety net.

SQL Server has a similar feature with sp_getapplock.

Exploring the DistributedLock Library

While the DIY approach works, production applications need more sophisticated features. The DistributedLock library handles the edge cases and provides multiple backend options (Postgres, Redis, SqlServer, etc.). You know I'm a fan of not reinventing the wheel, so this is a great choice.

Install the package:

Install-Package DistributedLock

I'll use the approach with IDistributedLockProvider which works nicely with DI. You can acquire a lock without having to know anything about the underlying infrastructure. All you have to do is register a lock provider implementation in your DI container.

For example, using Postgres:

// Register the distributed lock provider
builder.Services.AddSingleton<IDistributedLockProvider>(
    (_) =>
    {
        return new PostgresDistributedSynchronizationProvider(
            builder.Configuration.GetConnectionString("distributed-locking")!);
    });

Or if you want to use Redis with the Redlock algorithm:

// Requires StackExchange.Redis
builder.Services.AddSingleton<IConnectionMultiplexer>(
    (_) =>
    {
        return ConnectionMultiplexer.Connect(
            builder.Configuration.GetConnectionString("redis")!);
    });

// Register the distributed lock provider
builder.Services.AddSingleton<IDistributedLockProvider>(
    (sp) =>
    {
        var connectionMultiplexer = sp.GetRequiredService<IConnectionMultiplexer>();

        return new RedisDistributedSynchronizationProvider(connectionMultiplexer.GetDatabase());
    });

The usage is straightforward:

// You can also pass in a timeout, where the provider will keep retrying to acquire the lock
// until the timeout is reached.
IDistributedSynchronizationHandle? distributedLock = distributedLockProvider
    .TryAcquireLock("nightly-report");

// If we didn't get the lock, the object will be null
if (distributedLock is null)
{
    return Results.Conflict();
}

// It's important to wrap the lock in a using statement to ensure it's released properly
using (distributedLock)
{
    await DoWork();
}

The library handles all the tricky parts: timeouts, retries, and ensuring locks are released even in failure scenarios.

It also supports many backends (SQL Server, Azure, ZooKeeper, etc.), making it a solid choice for production workloads.

Wrapping Up

Distributed locking isn't something you need every day. But when you do, it saves you from subtle, painful bugs that only appear under load or in production.

Start simple: if you're already using Postgres, advisory locks are a powerful tool.

For a cleaner developer experience, reach for the DistributedLock library.

Choose the backend that fits your infrastructure (Postgres, Redis, SQL Server, etc.).

The right lock at the right time ensures your system stays consistent, reliable, and resilient, even across multiple processes and servers.

In your current layered architecture with a technical folder structure, you'll probably touch six different folders: Controllers, Services, Models, DTOs, Repositories, and Validators. You'll scroll up and down your solution explorer, lose your train of thought, and wonder why adding one feature requires editing files scattered across your entire codebase.

If this sounds familiar, you're not alone. Most .NET developers start with the "standard" layered architecture, organizing code by technical concerns rather than business features.

But there's a better way: Vertical Slice Architecture.

What is Vertical Slice Architecture?

Instead of organizing your code by technical layers (Controllers, Services, Repositories), Vertical Slice Architecture organizes it by business features. Each feature becomes a self-contained "slice" that includes everything needed for that specific functionality.

Think of it this way: traditional layered architecture is like organizing a library by book size or color, while vertical slices are like organizing by subject. When you want to learn about history, you don't want to hunt through the entire library, you want all the history books in one place.

Let's look at a practical example.

The Traditional Approach vs. Vertical Slices

Let's look at our data export example. Here's how a typical .NET project would structure this feature:

Traditional Layered Structure:

📁 Controllers/
└── UsersController.cs (export endpoint)
📁 Services/
├── IDataExportService.cs
├── DataExportService.cs
├── ICloudStorageService.cs
├── CloudStorageService.cs
├── IEmailService.cs
└── EmailService.cs
📁 Models/
├── ExportDataRequest.cs
└── ExportDataResponse.cs
📁 Repositories/
├── IUserRepository.cs
└── UserRepository.cs

Now here's the same functionality organized as vertical slices:

Vertical Slice Structure:

📁 Features/
└──📁 Users/
   └──📁 ExportData/
      ├── ExportUserData.cs
      └── ExportUserDataEndpoint.cs
      📁 Create/
      └── CreateUser.cs
      📁 GetById/
      └── GetUserById.cs

The ExportData folder contains everything related to exporting user data: the request, response, business logic, and API endpoint.

Notice I'm still injecting ICloudStorageClient and IEmailSender rather than putting that logic directly in the handler. These are genuine cross-cutting concerns that multiple features will use. The key is distinguishing between 'shared because it should be' vs 'shared because this pattern told me to'.

Show Me the Code

I organize by domain first (Users), then by feature (ExportData). Some teams prefer Features/ExportUserData directly, but I find the domain grouping helps when you have many features. Related features stay visually grouped.

Here's what our data export feature slice looks like using a request, handler, and minimal APIs:

Features/Users/ExportData/ExportUserData.cs

public static class ExportUserData
{
    public record Request(Guid UserId) : IRequest<Response>;

    public record Response(string DownloadUrl, DateTime ExpiresAt);

    public class Handler(
        AppDbContext dbContext,
        ICloudStorageClient storageClient,
        IEmailSender emailSender)
        : IRequestHandler<Request, Response>
    {
        public async Task<Response> Handle(Request request, CancellationToken ct = default)
        {
            // Get user data
            var user = await dbContext.Users
                .Include(u => u.Orders)
                .Include(u => u.Preferences)
                .FirstOrDefaultAsync(u => u.Id == request.UserId, ct);

            if (user == null)
            {
                throw new NotFoundException($"User {request.UserId} not found");
            }

            // Generate export data
            var exportData = new
            {
                user.Email,
                user.Name,
                user.CreatedAt,
                Orders = user.Orders.Select(o => new { o.Id, o.Total, o.Date }),
                Preferences = user.Preferences
            };

            // Upload to cloud storage
            var fileName = $"user-data-{user.Id}-{DateTime.UtcNow:yyyyMMdd}.json";
            var expiresAtUtc = DateTime.UtcNow.AddDays(7);

            var downloadUrl = await storageClient.UploadAsJsonAsync(
                fileName,
                exportData,
                expiresAtUtc,
                ct);

            // Send email notification
            await emailSender.SendDataExportEmailAsync(user.Email, downloadUrl, ct);

            return new Response(downloadUrl, expiresAtUtc);
        }
    }

    // Simple validation using FluentValidation
    public sealed class Validator : AbstractValidator<Request>
    {
        public Validator()
        {
            RuleFor(r => r.UserId).NotEmpty();
        }
    }
}

Everything related to exporting user data is in one place: the database query, validation, business logic, cloud storage integration, and email notification.

The minimal API endpoint is straightforward:

public static class ExportUserDataEndpoint
{
    public static void Map(IEndpointRouteBuilder app)
    {
        app.MapPost("/users/{userId}/export", async (
            Guid userId,
            IRequestHandler<ExportUserData.Request, ExportUserData.Response> handler) =>
        {
            var response = await handler.Handle(new ExportUserData.Request(userId));
            return Results.Ok(response);
        });
    }
}

We could even define the endpoint inside the ExportUserData.cs file if we wanted to keep everything together. This is more a matter of preference and team conventions. Either approach works well, from my experience.

One File vs. Multiple Files: Your Choice

You might have noticed something: I put everything in a single file. This is a design choice with trade-offs.

Single File Approach (ExportUserData.cs):

public static class ExportUserData
{
    public record Request(Guid UserId) : IRequest<Response>;
    public record Response(string DownloadUrl, DateTime ExpiresAt);
    public class Handler : IRequestHandler<Request, Response> { /* ... */ }
    public class Validator : AbstractValidator<Request> { /* ... */ }
}

Multiple Files Approach:

📁 ExportData/
├── ExportUserDataCommand.cs
├── ExportUserDataResponse.cs
├── ExportUserDataHandler.cs
├── ExportUserDataValidator.cs
└── ExportUserDataEndpoint.cs

Single file is great when: the feature is straightforward, you want maximum locality, and the file doesn't exceed a few hundred lines of code.

Lines of code isn't a strict rule, but if a file grows beyond 300-400 lines, consider splitting it up for readability. Again, this is a matter of team preference and not a hard rule I go by. It's important to trust your instincts and what feels right for your team.

Multiple files work better when: you have complex validation logic, multiple response types, or when the handler grows large enough that you want to focus on one concern at a time.

You can even mix both approaches within the same project.

Both approaches keep related code together. And this is what matters most in Vertical Slice Architecture.

Why This Actually Works (And How to Start)

The benefits of vertical slices become obvious once you try it. Your brain doesn't have to remember which files are related to which features. Everything lives together.

Need to modify the data export feature? Everything's in the ExportData folder. No hunting across Controllers, Services, and Repositories layers. Each slice can evolve independently, so simple CRUD operations stay simple while complex features like data export can use sophisticated approaches.

You don't need to rewrite your entire application overnight. Start with new features using vertical slices. As you touch existing code, gradually move related pieces into feature folders.

Good architecture is about making your codebase easier to understand and modify. When all the code for a feature lives together, you spend less mental energy navigating your solution and more time solving actual problems.

Here are a few resources if you want to learn more:

• Clean Architecture: The Missing Chapter
• Modular Monolith Architecture
• Screaming Architecture

All of these concepts tie together to help you build maintainable, scalable .NET applications.

Amazon S3 is now also a vector database, and it's 90% cheaper (according to the announcement) than the alternatives.

For those of us running static sites or simple web apps, it means we can finally add semantic search without the operational overhead of running a vector database like Pinecone, Weaviate, or Qdrant.

Instead, we can just use S3 buckets that understand vectors.

I'm adding it alongside my existing full-text search implementation, and the whole thing took an afternoon to build.

How Semantic Search Works

The entire semantic search flow is straightforward:

You have to start with some data. In my case, this data comes from the articles I've written over the years.

Then we need an embedding model. Amazon Bedrock offers many to choose from. You use an embedding model to convert text into vectors. Vectors are numerical representations of your data that capture semantic meaning.

Finally, we store these vectors in an S3 Vector Bucket, a new type of S3 bucket designed specifically for vector storage and search. When someone searches, we convert their query into a vector and find the closest matches in the bucket.

If you want to understand the fundamentals, I wrote an article explaining what vector search is.

Generating Embeddings with Semantic Kernel

Microsoft's Semantic Kernel makes working with Bedrock surprisingly clean.

We'll need to install a few NuGet packages:

# Semantic kernel packages
Install-Package Microsoft.SemanticKernel
Install-Package Microsoft.SemanticKernel.Connectors.Amazon

# AWS SDK for Bedrock
Install-Package AWSSDK.BedrockRuntime

We have to configure the embedding generator in our application. Here we can specify which model to use for generating embeddings. I'll use the Amazon Titan embedding model (amazon.titan-embed-text-v2:0) which produces 1024-dimensional vectors.

builder.Services.AddBedrockEmbeddingGenerator("amazon.titan-embed-text-v2:0");

builder.Services.AddTransient(sp =>
{
    return new Kernel(sp);
});

And then we can use the IEmbeddingGenerator abstraction to generate embeddings:

var kernel = app.Services.GetRequiredService<Kernel>();

var embeddingGenerator = kernel.Services
    .GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();

var articleContent = await blogService.GetBlogContentAsync(articleUrl);

Embedding<float> embedding = await embeddingGenerator.GenerateAsync(articleContent);

embeddings.Add((articleUrl, embedding.Vector.ToArray()));

The number of dimensions varies depending on the embedding model you choose. You can find more information about that in the documentation for your specific model.

Creating Your S3 Vector Bucket

S3 Vectors uses an entirely new bucket type, not a feature you enable on existing buckets. They're a fundamentally different storage system optimized for vector operations. Creating one feels familiar if you've used S3 before:

Pick a unique name for your vector bucket:

And finally, you can create a vector index for your bucket. You get to choose the number of dimensions in each vector. This is dictated by the embedding model you use. All vectors within a vector index should use the same embedding model. Otherwise, you won't get the correct results when searching. You also have to choose the distance metric (e.g., cosine similarity, Euclidean distance) for your vector index. I went with cosine similarity, which is a common choice for text embeddings. The additional settings let you configure non-filterable metadata. By default, all metadata is filterable.

The UI is not polished at all, and you can't do much else. I expect this will improve over time, but for now, everything else is done via the SDK or CLI. There are certain limitations to be aware of, you can check out the docs here.

Storing Vectors with Metadata

Now that we have our vector index, we can start storing vector embeddings with metadata. Metadata is interesting because it enables filtered searches. Want to search only recent posts? Posts in a specific category? The metadata makes it possible.

Here's how you can store vectors:

public async Task IndexBlogPost(BlogPost post)
{
    List<float> embedding = await GenerateEmbedding(post.Content);

    await s3VectorsClient.PutVectorsAsync(new PutVectorsRequest
    {
        VectorBucketName = "mjtech-articles-semantic-search",
        IndexName = "mjtech-article-content",
        Vectors = new List<Vector>
        {
            new PutInputVector
            {
                Key = post.Slug,
                Data = new VectorData
                {
                    Float32 = embedding
                },
                Metadata = new Document(new Dictionary<string, Document>
                {
                    ["title"] = post.Title,
                    ["date"] = post.PublishedDate.ToString("yyyy-MM-dd"),
                    ["category"] = post.Category,
                    ["url"] = $"/posts/{post.Slug}"
                })
            }
        }
    });
}

But if you're indexing your entire blog archive, doing it one post at a time is costly. You can batch together multiple posts and index them in a single API call. The SDK makes it easy to do this by accepting a list of vectors.

Querying Vector Indexes

When someone searches your site, you convert their query into a vector and find the closest matches.

Here's how you can implement semantic search:

public async Task<List<SearchResult>> SemanticSearch(
    string query,
    int topK = 10)
{
    // Convert search query to vector (use same model as vectors!)
    List<float> queryEmbedding = await GenerateEmbedding(query);

    var request = new QueryVectorsRequest
    {
        VectorBucketName = "mjtech-articles-semantic-search",
        IndexName = "mjtech-article-content",
        QueryVector = new VectorData
        {
            Float32 = queryEmbedding
        },
        TopK = topK,
        ReturnMetadata = true,
        ReturnDistance = true
    };

    QueryVectorsResponse response = await s3VectorsClient.QueryVectorsAsync(request);

    return response.Vectors.Select(v => new SearchResult
    {
        Distance = v.Distance,
        Title = v.Metadata.AsDictionary()["title"].ToString(),
        Url = v.Metadata.AsDictionary()["url"].ToString(),
        Category = v.Metadata.AsDictionary()["category"].ToString()
    }).ToList();
}

I omitted metadata filtering here, but you can explore the documentation for more details.

Next Steps

Would I migrate from an existing vector database? Probably not if everything's working. The operational overhead would have to justify the switch.

But if you're adding semantic search for the first time, or your vector database bills are getting uncomfortable, S3 Vectors is a viable choice. The setup takes an afternoon, the ongoing maintenance is zero, and your users get search that actually understands what they're looking for.

Don't forget that S3 Vectors is still in preview, so we can expect some changes before general availability.

Here's what I'm planning to do next:

1. Automatically update the vector index when I publish a new post. I can do this in my CI/CD pipeline, where I can detect new posts and trigger a re-indexing.
2. Expose a search endpoint that uses the new semantic search capabilities. Combine the results with the full-text search results.
3. Make sure everything is performant and cost-effective. Acceptable latency is under 500ms.
4. Share details about the implementation and any challenges faced. Especially around the costs of using an embedding model and vector storage.

That's all for today.

See you next week.

The Aspire Dashboard runs perfectly as a standalone container, giving you distributed tracing, structured logs, and real-time metrics without the full orchestration framework.

While Aspire's orchestration is incredibly powerful for managing distributed applications, sometimes you just need the observability piece. Maybe you're already using Docker Compose or Kubernetes. Maybe you're debugging an existing system. The standalone dashboard gives you valuable telemetry visualization with minimal setup.

Let's get it running in under 5 minutes.

Why Run the Aspire Dashboard Standalone?

Most teams already have their deployment story figured out. Docker Compose, Kubernetes, or some platform-specific orchestration. You don't want to rewrite everything just to get observability.

The standalone Aspire Dashboard hits a sweet spot for development:

• Drop-in observability - Just add a container to your existing setup
• Full OpenTelemetry support - Works with any OTLP-compatible application
• Developer-friendly - Designed for local development and debugging
• Immediate value - See traces, logs, and metrics within minutes

One caveat: it's in-memory only. Perfect for development and debugging, not for production. For production, you'll want something like Jaeger, Prometheus, or a commercial APM solution.

But for understanding what your code is doing right now? It's exactly what you need.

Step 1: Add the Dashboard Container

Drop this into your docker-compose.yml:

aspire-dashboard:
  container_name: aspire-dashboard
  image: mcr.microsoft.com/dotnet/aspire-dashboard:13.0
  ports:
    - 18888:18888

That's it. The dashboard is running. Navigate to http://localhost:18888 and... you'll need a token.

Check the container logs for the login link. The dashboard generates a unique authentication token on startup:

Click that link, and you're in. Empty for now, but not for long.

Step 2: Wire Up Your .NET Services

Your services need to know where to send their telemetry. Add these environment variables to your API containers:

users.api:
  image: ${DOCKER_REGISTRY-}usersapi
  build:
    context: .
    dockerfile: Users.Api/Dockerfile
  ports:
    - 5100:5100
    - 5101:5101
  environment:
    - OTEL_EXPORTER_OTLP_ENDPOINT=http://aspire-dashboard:18889
    - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
  depends_on:
    - users.database

Notice port 18889? That's the OTLP ingestion endpoint. The dashboard listens on 18888 for the UI, 18889 for telemetry data.

Step 3: Configure OpenTelemetry in Your Code

Install the necessary OpenTelemetry packages:

<PackageReference Include="Npgsql.OpenTelemetry" Version="9.0.3" />
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />

Then configure OpenTelemetry in your Program.cs:

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService(builder.Environment.ApplicationName))
    .WithTracing(tracing => tracing
        .AddHttpClientInstrumentation()
        .AddAspNetCoreInstrumentation()
        .AddNpgsql())
    .WithMetrics(metrics => metrics
        .AddHttpClientInstrumentation()
        .AddAspNetCoreInstrumentation());

builder.Logging.AddOpenTelemetry(options =>
{
    options.IncludeScopes = true;
    options.IncludeFormattedMessage = true;
});

builder.Services.AddOpenTelemetry().UseOtlpExporter();

This configuration:

• Traces HTTP calls, ASP.NET Core requests, and database queries
• Collects metrics on request duration, response codes, and throughput
• Structured logging with full context and formatted messages
• Exports everything to the Aspire Dashboard via OTLP

The UseOtlpExporter() method automatically picks up the OTEL_EXPORTER_OTLP_ENDPOINT environment variable you configured earlier.

What You Get

Start your application and make a few requests. The dashboard immediately lights up with data.

Structured Logs

Every log entry includes full context: trace IDs, request paths, user identities. Click any log to see the complete structured data.

Distributed Traces

See the complete request flow across all your services. Which database query is slow? Which HTTP call is failing? The trace view shows you exactly where time is spent.

You can click into a trace to see the individual spans and any metadata associated with them.

Real-Time Metrics

Response times, error rates, throughput, all updating live. Perfect for load testing or understanding traffic patterns.

Summary

The standalone Aspire Dashboard is perfect for local development and debugging. Spin up your stack, make requests, and instantly see what's happening across all your services. Find bottlenecks in the trace view, correlate logs with requests, watch metrics update in real-time.

Remember: this is for development only since data is in-memory and disappears on restart. That last part might be fixed soon, according to the Aspire roadmap. For production, you'll want proper solutions like Jaeger for tracing, Prometheus for metrics, or a commercial APM like Application Insights.

But for that immediate "what is my code actually doing?" question during development? You've got professional observability in under 5 minutes.

Just add the container, configure OpenTelemetry, and start debugging like a pro.

That's all for today.

See you next Saturday.

Every abstraction is a loan. You pay interest the moment you write it.

Some abstractions earn their keep by isolating real volatility and protecting your system from change. Others quietly pile up complexity, slow down onboarding, and hide performance problems behind layers of indirection.

Let's explore when abstractions pay dividends and when they become technical debt.

When Abstractions Pay Off

The best abstractions isolate true volatility, the parts of your system that you genuinely expect to change.

Example: Payment Processing

Your core business logic shouldn't depend directly on Stripe's SDK. If you ever switch to Adyen or Braintree, you don't want that decision rippling through every corner of your codebase. Here, an abstraction makes perfect sense:

public interface IPaymentProcessor
{
    Task ProcessAsync(Order order, CancellationToken ct);
}

public class StripePaymentProcessor : IPaymentProcessor
{
    public async Task ProcessAsync(Order order, CancellationToken ct)
    {
        // Stripe-specific implementation
        // Handle webhooks, error codes, etc.
    }
}

public class AdyenPaymentProcessor : IPaymentProcessor
{
    public async Task ProcessAsync(Order order, CancellationToken ct)
    {
        // Adyen-specific implementation
        // Different API, same business outcome
    }
}

Now your business logic can stay focused on the domain:

public class CheckoutService(IPaymentProcessor processor)
{
    public Task CheckoutAsync(Order order, CancellationToken cancellationToken) =>
        processor.ProcessAsync(order, cancellationToken);
}

This abstraction isolates a genuinely unstable dependency (the payment provider) while keeping checkout logic independent. When Stripe changes their API or you switch providers, only one class needs to change.

That's a good abstraction. It buys you optionality where you actually need it.

When Abstractions Become Technical Debt

Problems arise when we abstract things that aren't actually volatile. We end up wrapping stable libraries or creating layers that don't add real value. The "clean" layer you added today becomes tomorrow's maintenance burden.

The Repository That Lost Its Way

Most teams start with something reasonable:

public interface IUserRepository
{
    Task<IEnumerable<User>> GetAllAsync();
}

But as requirements evolve, so does the interface:

public interface IUserRepository
{
    Task<IEnumerable<User>> GetAllAsync();
    Task<User?> GetByEmailAsync(string email);
    Task<IEnumerable<User>> GetActiveUsersAsync();
    Task<IEnumerable<User>> GetUsersByRoleAsync(string role);
    Task<IEnumerable<User>> SearchAsync(string keyword, int page, int pageSize);
    Task<IEnumerable<User>> GetUsersWithRecentActivityAsync(DateTime since);
    // ...and it keeps growing
}

Suddenly, the repository is leaking query logic into its interface. Every new way of fetching users means another method, and your "abstraction" becomes a grab bag of every possible query.

Meanwhile, Entity Framework already gives you all of this through LINQ: strongly typed queries that map directly to SQL. Instead of leveraging that power, you've introduced an indirection layer that hides query performance characteristics and often performs worse. The repository pattern made sense when ORMs were immature. Today, it's often just ceremony.

I've been guilty of this myself. But part of maturing as a developer is recognizing when patterns become anti-patterns. Repositories make sense when they encapsulate complex query logic or provide a unified API over multiple data sources. But you should strive to keep them focused on domain logic. As soon as they explode into a myriad of methods for every possible query, it's a sign that the abstraction has failed.

Service Wrappers: The Good and The Ugly

Not all service wrappers are problematic. Context matters.

✅ Good Example: External API Integration

When integrating with external APIs, a wrapper provides genuine value by centralizing concerns:

public interface IGitHubClient
{
    Task<UserDto?> GetUserAsync(string username);
    Task<IReadOnlyList<RepoDto>> GetRepositoriesAsync(string username);
}

public class GitHubClient(HttpClient httpClient) : IGitHubClient
{
    public Task<UserDto?> GetUserAsync(string username) =>
        httpClient.GetFromJsonAsync<UserDto>($"/users/{username}");

    public Task<IReadOnlyList<RepoDto>> GetRepositoriesAsync(string username) =>
        httpClient.GetFromJsonAsync<IReadOnlyList<RepoDto>>($"/users/{username}/repos");
}

This wrapper isolates GitHub's API details. When authentication changes or endpoints evolve, you update one place. Your business logic never needs to know about HTTP headers, base URLs, or JSON serialization.

❌ Bad Example: Pass-Through Services

The trouble starts when we wrap our own stable services without adding business value:

public class UserService(IUserRepository userRepository)
{
    // Just forwarding calls with no added value
    public Task<User?> GetByIdAsync(Guid id) => userRepository.GetByIdAsync(id);
    public Task<IEnumerable<User>> GetAllAsync() => userRepository.GetAllAsync();
    public Task SaveAsync(User user) => userRepository.SaveAsync(user);
}

This UserService is pure indirection. All it does is forward calls to the IUserRepository. It doesn't enforce business rules, add validation, implement caching, or provide any real functionality. It's a layer that exists only because "services are good architecture."

As these anemic wrappers multiply, your codebase becomes a maze. Developers waste time navigating layers instead of focusing on where business logic actually lives.

Making Better Decisions

Here's how to think about when abstractions are worth the investment:

Abstract Policies, Not Mechanics

• Policies are decisions that might change: which payment provider to use, how to handle caching, retry strategies for external calls
• Mechanics are stable implementation details: EF Core's LINQ syntax, HttpClient configuration, JSON serialization

Abstract policies because they give you flexibility. Don't abstract mechanics, they're already stable APIs that rarely change in breaking ways.

Wait for the Second Implementation

If you only have one implementation, resist the interface urge. A single implementation doesn't justify abstraction, it's premature generalization that adds complexity without benefit.

Consider this evolution:

// Step 1: Start concrete
public class EmailNotifier
{
    public async Task SendAsync(string to, string subject, string body)
    {
        // SMTP implementation
    }
}

// Step 2: Need SMS? Now abstract
public interface INotifier
{
    Task SendAsync(string to, string subject, string body);
}

public class EmailNotifier : INotifier { /* ... */ }
public class SmsNotifier : INotifier { /* ... */ }

The abstraction emerges naturally when you actually need it. The interface reveals itself through real requirements, not imaginary ones.

Keep Implementations Inside, Abstractions at Boundaries

Inside your application, prefer concrete types. Use Entity Framework directly, configure HttpClient as typed clients, work with domain entities. Only introduce abstractions where your system meets the outside world: external APIs, third-party SDKs, infrastructure services.

That's where change is most likely, and where abstractions earn their keep.

Refactoring Out Bad Abstractions

Regularly review your abstractions with this question: If I removed this abstraction, would the code become simpler or more complex?

If removing an interface or service layer would make the code clearer and more direct, that abstraction is probably costing more than it's worth. Don't be afraid to delete unnecessary layers. Simpler code is often better code.

When you identify problematic abstractions, here's how to safely remove them:

1. Identify the real consumers. Who actually needs the abstraction?
2. Inline the interface. Replace abstract calls with concrete implementations.
3. Delete the wrapper. Remove the unnecessary indirection.
4. Simplify the calling code. Take advantage of the concrete API's features.

For example, replacing a repository with direct EF Core usage:

// Before: Hidden behind repository
var users = await _userRepo.GetActiveUsersWithRecentOrders();

// After: Direct, optimized query
var users = await _context.Users
    .Where(u => u.IsActive)
    .Where(u => u.Orders.Any(o => o.CreatedAt > DateTime.Now.AddDays(-30)))
    .Include(u => u.Orders.Take(5))
    .ToListAsync();

The concrete version is more explicit about what data it fetches and how, making performance characteristics visible and optimization possible. If you need the same query in multiple places, you could move it into an extension method to make it shareable.

The Bottom Line

Abstractions are powerful tools for managing complexity and change, but they're not free. Each one adds indirection, cognitive overhead, and maintenance burden.

The cleanest architecture isn't the one with the most layers. It's the one where each layer has a clear, justified purpose.

Before adding your next abstraction, ask yourself:

• Am I abstracting a policy or just a mechanic?
• Do I have two implementations, or am I speculating about future needs?
• Will this make my system more adaptable, or just harder to follow?
• If I removed this layer, would the code become simpler?

Remember: abstractions are loans that accrue interest over time. Make sure you're borrowing for the right reasons, not just out of habit.

The goal is to use abstractions intentionally, where they solve real problems and protect against genuine volatility. Build abstractions that earn their keep. Delete the ones that don't.

Thanks for reading.

And stay awesome!

Every week, I publish blog posts covering different topics - architecture patterns, cloud services, programming techniques, business insights. Sometimes I write about DevOps, other times about security. After years of writing, I realized I had no systematic way to categorize my content. Sure, I could manually tag each post, but where's the fun in that?

So I built a simple AI-powered blog analyzer. It fetches any blog post, extracts the content, and uses AI to automatically categorize it. The entire thing took less than an hour to build thanks to .NET Aspire 9.4 and it's new GitHub Models integration.

What surprised me wasn't just how easy it was to build, but how the integration completely removes the typical AI service complexity. No juggling API keys in configuration files, no manual HTTP client setup, no wrestling with different SDK patterns for different AI providers. You declare an AI model in your AppHost just like you would a database, and Aspire handles the rest.

Here's what I learned building this simple app, and how you can use the same patterns to add AI to your applications.

What are GitHub Models?

GitHub Models is a service that provides access to AI models from OpenAI, Microsoft, Meta, and others through a single API. You get free tier access for prototyping (with rate limits), an interactive playground for testing prompts, and pay-per-use billing when you're ready for production.

The models range from cost-effective options like GPT-4o-mini to more advanced models. Each model has different strengths - some excel at reasoning, others at code generation or creative writing.

When you combine GitHub Models with .NET Aspire's orchestration, you get:

• Automatic API key management via external parameters
• Service discovery between your components
• Built-in health checks and telemetry
• Consistent configuration patterns

Setting Up the Integration

The GitHub Models integration splits into two parts: configuring models in your AppHost and consuming them in your services.

AppHost Configuration

In your AppHost project, you define AI models as resources alongside your other services:

var builder = DistributedApplication.CreateBuilder(args);

var blogService = builder.AddExternalService("dotnet-blog", "https://www.milanjovanovic.tech/blog");
var aiModel = builder.AddGitHubModel("ai-model", "openai/gpt-4o-mini");

builder.AddProject<Projects.GitHub_Models_Demo>("github-models-demo")
    .WithReference(blogService)
    .WithReference(aiModel);

Notice how the AI model sits alongside the external blog service. Both are resources that your main application depends on. Aspire handles the connection details - you just declare what you need.

Make sure to install the Aspire.Hosting.GitHub.Models NuGet package to enable this integration.

To call the GitHub Models inference API you need a personal access token with the models:read permission. When you call AddGitHubModel, Aspire automatically creates a parameter named {resourceName}-gh-apikey (for example, ai-model-gh-apikey)

You can populate the parameter through user secrets for local development:

{
  "Parameters": {
    "ai-model-gh-apikey": "github_pat_YOUR_PERSONAL_ACCESS_TOKEN"
  }
}

If you don't provide this value from configuration, Aspire will prompt you to enter it when you run the application. You'll have an option to store the access token securely in user secrets.

Client Setup

In your consuming service, add the Azure AI client (which works with GitHub Models):

builder
    .AddAzureChatCompletionsClient("ai-model")
    .AddChatClient();

That's it. No manual HTTP client configuration, no hardcoded endpoints. The ai-model name matches what you defined in the AppHost, and Aspire wires everything together.

You'll need to install the Aspire.Azure.AI.Inference NuGet package to enable this integration. It also exposes an integration with MEAI using the AddChatClient method. This simplifies the process of interacting with LLMs in your applications.

Building the Blog Analyzer

Now let's build something useful. We'll create a service that fetches blog posts and uses AI to categorize them.

Fetching Blog Content

First, we need to extract readable content from blog posts:

public async Task<string> GetBlogContentAsync(string slug)
{
    var response = await httpClient.GetAsync(slug);
    response.EnsureSuccessStatusCode();
    var htmlContent = await response.Content.ReadAsStringAsync();

    return ExtractArticleContent(htmlContent);
}

The ExtractArticleContent method (not shown) uses HtmlAgilityPack to pull out the main article text, stripping away navigation, ads, and other page elements.

AI-Powered Categorization

Here's where it gets interesting. We'll use the AI model to analyze the content and assign a category:

public async Task<string> SummarizeBlogAsync(string blogContent)
{
    var prompt =
        @"""
        You are a blog content assistant. Summarize the following blog post
        as one of the following categories: Technology, Business, Programming,
        Architecture, DevOps, Cloud, Security, General.
        Only those eight values are allowed. Be as concise as possible.
        I want a 1-word response with one of these options: Technology, Business,
        Programming, Architecture, DevOps, Cloud, Security, General.

        The blog content is: {blogContent}
        """;

    var response = await chatClient.GetResponseAsync(prompt);

    if (!response.Messages.Any())
    {
        return "General";
    }

    var category = response.Messages.First().Text switch
    {
        var s when s.Contains("Technology", StringComparison.OrdinalIgnoreCase) => "Technology",
        var s when s.Contains("Business", StringComparison.OrdinalIgnoreCase) => "Business",
        var s when s.Contains("Programming", StringComparison.OrdinalIgnoreCase) => "Programming",
        var s when s.Contains("Architecture", StringComparison.OrdinalIgnoreCase) => "Architecture",
        var s when s.Contains("DevOps", StringComparison.OrdinalIgnoreCase) => "DevOps",
        var s when s.Contains("Cloud", StringComparison.OrdinalIgnoreCase) => "Cloud",
        var s when s.Contains("Security", StringComparison.OrdinalIgnoreCase) => "Security",
        var s when s.Contains("General", StringComparison.OrdinalIgnoreCase) => "General",
        _ => "General"
    };

    return category;
}

A few things make this work reliably:

• The prompt is explicit about allowed categories
• We request a single-word response to avoid parsing complex output
• The switch expression handles variations in the AI's response
• There's always a fallback to "General"

Exposing the API

Finally, we wrap everything in a simple API endpoint:

app.MapPost("/summarize-blog", async (
    string slug,
    BlogService blogService,
    BlogSummarizer blogSummarizer) =>
{
    var content = await blogService.GetBlogContentAsync(slug);
    var category = await blogSummarizer.SummarizeBlogAsync(content);

    return Results.Ok(new
    {
        slug,
        category,
        content = $"{content.Substring(0, 50)}..."
    });
});

Call this endpoint with a blog post URL slug, and you get back the category and a preview of the content. The dependency injection handles service resolution, and Aspire manages the AI model connection behind the scenes.

Here's an example response:

{
  "slug": "screaming-architecture", // https://www.milanjovanovic.tech/blog/screaming-architecture
  "category": "Architecture",
  "content": "If you were to glance at the folder structure of y..."
}

Here's the distributed trace in Aspire showing the request and response flow. You can see the request to the blog service and the AI model.

Wrapping Up

The GitHub Models integration with .NET Aspire removes much of the complexity from adding AI to your applications. You get:

• Simple configuration through the AppHost pattern
• Automatic service discovery and connection management
• Access to multiple AI models without vendor lock-in
• The same observability and deployment benefits as other Aspire resources

Whether you're adding AI to an existing system or building something new, this integration provides the foundation you need. Start with simple categorization or summarization, then expand as you learn what works for your use case.

Thanks for reading.

And stay awesome!

Here are 5 common mistakes I see repeatedly, why they cause problems, and how to avoid them with pragmatic, battle-tested solutions.

1. Inconsistent Naming and Structure

Naming is the first thing consumers see. Inconsistency here leads to constant documentation lookups, broken expectations, and more bugs.

Look, we've all been there. You successfully call /users and /products, so naturally you try /orders. But nope, this API uses /order-list for some reason. Now you're back to the docs, breaking your flow, wondering why anyone would do this. Multiply this friction by dozens of endpoints, and you've built an API that makes developers want to flip tables.

I get it, deep URL hierarchies like /users/{id}/habits/{habitId}/entries/{entryId}/comments/{commentId} feel satisfying. They mirror your beautiful domain model! But here's the thing: you've just hardcoded your entire data structure into your URLs. When business requirements change (and they will), you can't reorganize without breaking clients.

Plus, what happens when someone only has a comment ID? They need to somehow figure out the user, habit, and entry IDs just to fetch one comment. That's ridiculous.

Keep it simple with plural nouns: /users, /habits, /entries. No more guessing if it's user or users.

Only nest when something truly belongs to something else. User settings belong to and die with the user, so /users/{id}/settings makes sense. Comments can exist independently, so /users/{id}/posts/{postId}/comments can be simplified.

Instead, flatten with filters:

# Instead of deep nesting
GET /users/{userId}/habits/{habitId}/entries

# Use filters for flexibility
GET /entries?userId={userId}&habitId={habitId}
GET /entries?habitId={habitId}  # Now you can get entries without knowing the user

And please, for the love of all that is holy, wrap your arrays:

{
  "data": [
    {
      "id": "e_8YH",
      "habitId": "code-review",
      "at": "2025-08-08T09:17:34Z",
      "value": 5,
      "unit": "reviews",
      "tags": ["team"]
    },
    {
      "id": "e_8Z2",
      "habitId": "deep-work",
      "at": "2025-08-07T07:00:00Z",
      "value": 2,
      "unit": "pomodoros",
      "note": "EF filters optimized"
    }
  ],
  "total": 42,
  "hasMore": true,
  "nextCursor": "cursor_01J9KaBcd"
}

I know it feels like pointless boilerplate now, but trust me, when you need to add pagination info six months from now, you'll thank yourself for not having to break every client that expects a raw array.

Yeah, the REST purists will complain that filters aren't "RESTful enough." Let them. Your API will be flexible, maintainable, and actually pleasant to use. I'll take that over conceptual purity any day.

2. Poor Versioning Strategy

Everyone defaults to versioning (/v1/users) thinking they're being smart about future changes. Spoiler: they're not. They're creating a maintenance nightmare.

Here's what actually happens when you have v1, v2, and v3 running:

• Every bug needs to be fixed three times
• Every security patch needs three deployments
• Your docs become a choose-your-own-adventure novel
• Support has no idea which version that angry customer is using
• You spend weekends maintaining code you wrote two years ago

But the worst part? Versioning makes you lazy. Instead of thinking "how can I evolve this without breaking clients?" you just think "eh, I'll bump the version." Now your clients have to rewrite their entire integration because you wanted to rename a field.

Watch this disaster unfold:

v1: GET /users returns {id, name, email}
v2: GET /users returns {id, fullName, emailAddress}  // "looks cleaner!"
v3: GET /users returns {id, firstName, lastName, email}  // "we need split names!"

Congrats, you're now maintaining three different response formats for the same damn data. That v1 client? They'll never get new features unless they rewrite everything. Found a critical bug? Hope you enjoy patching it three times!

Here's the radical idea: don't version at all. I'm serious.

Add fields, don't replace them:

// What you ship first
{ "id": 1, "name": "John Doe" }

// What you ship later (keeping the old field)
{
  "id": 1,
  "name": "John Doe",  // Still there! Mark it deprecated in docs
  "firstName": "John",
  "lastName": "Doe"
}

Need optional features? Use query parameters:

GET /users/{id}?include=habits,entries
GET /users/{id}?format=detailed

If you absolutely must make a breaking change (and really think about this), create a new resource:

# Old faithful, unchanged
GET /users/{id}

# New hotness
GET /userProfiles/{id}

When breaking changes are truly unavoidable, at least be a decent human about it. Give people 6-12 months notice. Run both versions in parallel. Write a migration guide that doesn't suck. And for crying out loud, monitor who's still using the old stuff so you can reach out before pulling the plug.

Yes, this means you need to actually think about your API design upfront. You can't just YOLO field names and fix them later. But that constraint will make you design better APIs, and future-you will buy present-you a beer.

If you want to learn more about this, I recommend reading API Change Management.

3. Ignoring Pagination, Filtering, and Searching

That GET /entries endpoint works great with your 10 test records. Then you launch, get actual users, and suddenly you're returning 100,000 entries in a single response. Your API times out, your mobile users on crappy connections hate you, and your cloud bill makes you cry.

"We'll add pagination later," you said. Well, now it's later, and adding pagination means breaking every client that expects an array. Nice job.

Without filtering, your clients are downloading thousands of records to find the five they actually need. It's like making someone download all of Wikipedia to read one article. Your servers are melting, serializing data nobody wants. Your users are burning through their data plans. Everyone loses.

Filtering is for when you know exactly what you want:

GET /entries?habitId=123&date=2025-08-01&status=completed

Searching is for when you kinda know what you want:

GET /entries/search?q=morning+run+park

Don't try to be clever and combine them. Filtering uses your database indexes efficiently. Searching needs full-text magic. Mix them and you'll end up with something that does neither well.

For pagination, you've got two choices, and they both kinda suck in different ways.

Offset/limit is what everyone starts with:

GET /entries?offset=100&limit=50
             # or you can call them skip and take
             # or you can call them page and pageSize
             # use whatever you like best

It's dead simple and lets users jump to page 5, but here's the fun part: add or delete an item while someone's paginating, and they'll either skip entries or see duplicates. Plus, asking for offset=10000 makes your database cry as it counts through all those rows.

Cursor-based pagination is the "proper" solution:

GET /entries?limit=50&cursor=eyJpZCI6MTIzfQ==

Rock solid, no skipped items, consistent performance. But you can't jump to arbitrary pages and cursors can become invalid if underlying data changes significantly.

Yeah, implementing all this is a pain. You need cursor encoding, parameter validation, query optimization. But trying to add it after launch? Wouldn't recommend. Just build it right the first time.

4. Unclear or Inconsistent Error Handling

{"error": "An error occurred"} — if you return this, I hate you.

Seriously, when your API spits out these useless errors, here's what happens: I try random stuff hoping something works. I add defensive code everywhere because I don't trust you. I flood your support channel asking what's wrong. Then I complain about your API on social media (any publicity is good publicity, eh?).

A good error tells me three things: what broke, why it broke, and how to fix it. Is that so hard?

Stop inventing your own janky error format. Use Problem Details (RFC 9457) like a civilized developer:

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The request body contains invalid fields",
  "instance": "/habits/123",
  "errors": [
    {
      "field": "name",
      "reason": "Must be between 1 and 100 characters",
      "value": ""
    },
    {
      "field": "frequency",
      "reason": "Must be one of: daily, weekly, monthly",
      "value": "sometimes"
    }
  ]
}

See how that actually helps me fix the problem? Revolutionary, I know.

And please use the right status codes. It's not that hard:

• 400 Bad Request: You sent garbage
• 401 Unauthorized: Who are you?
• 403 Forbidden: I know who you are, but no
• 404 Not Found: That thing doesn't exist
• 409 Conflict: That conflicts with something
• 422 Unprocessable Entity: I understand what you want, but it's wrong
  (I don't use this personally, and prefer returning 400 for validation failures)
• 429 Too Many Requests: Slow down, cowboy
• 500 Internal Server Error: We screwed up
• 503 Service Unavailable: We're drowning, try again later

Now, don't go leaking your entire stack trace in production like an amateur. Give friendly errors to users, detailed errors in dev/staging, and log the gory details server-side where you can actually use them.

5. Ignoring Security Until It's Too Late

"We'll add auth in phase 2" — famous last words before your API becomes a data buffet for hackers. Ask the Tea app how that worked out for them.

Here's what happens when you try to bolt on security later: Every client breaks when you add authentication. That data you've been leaking? It's probably been scraped already. Your compliance audit? Failed. That one security incident? Your users will bring it up for years.

Authentication (who are you?) and Authorization (what can you do?) are different things. I've seen so many APIs that check if you're logged in but never check if you should actually access that data. Don't be that person.

Rate limiting isn't just about stopping abuse, it's about fairness. Start simple: 1000 requests per hour per API key. When they hit the limit, return 429 with headers showing when they can try again. Then get fancy: different limits for different endpoints, higher limits for paying customers, lower limits for that one client who keeps doing weird stuff.

HTTPS everywhere. Yes, even for your internal "no one will ever find this" API. It's 2025, not 2005. Let's Encrypt is free. You have no excuse.

Look, security makes things slower and more complex. Auth checks on every request, encryption overhead, state management for rate limiting, it all adds up. But you know what's worse? Explaining to your users why their data is being sold on the dark web. Build security in from the start, or prepare for a world of pain.

Final Thoughts

Good API design isn't about perfection, it's about making intentional, informed decisions. Every choice is a tradeoff. Consistency might limit flexibility. Security will impact performance. Stability means slower innovation.

Here's what actually matters: know your tradeoffs and own them. Document why you made these choices (future you will thank you). Stay consistent even when it's tempting not to. Design for evolution, not some imaginary perfect future. And listen to your users, but don't turn your API into a frankenstein monster trying to please everyone.

Your API is a promise to other developers. Every time you break that promise (with a breaking change, an inconsistent pattern, or a useless error message) you lose their trust. And trust me, developers hold grudges.

Build the API you'd want to use. Your developers will thank you, your support team will thank you, and honestly, you'll thank yourself six months from now when you have to maintain this thing.

Want to dive deeper? Check out my Pragmatic REST APIs course where I cover all of this (and more).

P.S. Any sharp language here is just me being snarky for emphasis. I'm critiquing patterns, not people. Don't take the strong wording too seriously.

Nothing stops a developer from running a rogue JOIN across tables or bypassing a public API.

In previous articles, I described four levels of data isolation (table, schema, database and alternative persistence) and argued that modules should expose explicit APIs to access their data.

This article goes deeper on the database side. You'll learn how to carve out logical and physical boundaries using PostgreSQL schemas and roles and EF Core, why those choices matter, and how to handle cross-cutting queries without breaking encapsulation.

Why enforce database boundaries?

In a modular monolith each module owns its data. If Module A reaches into Module B's tables, you lose this constraint and your modules become tightly coupled. Instead, B exposes a public API and hides its persistence logic from consumers.

Beyond clean code, enforcing boundaries at the database level protects you against mistakes and makes it easier to extract a module into its own service later.

Database schemas act like folders: they let you organise objects and share a database among many users, but a user can access any schema only if they have privileges. This means we can deliberately lock each module to its own schema.

The strategy

• Create a schema per module and a dedicated database role.
• Grant that role privileges only on its schema and set its default search path.
• Use EF with one DbContext per module, setting a default schema and connection string per module.
• For cross-cutting queries, publish a read-only database view that acts like a public API.
• Optional: Use row-level security policies to restrict access within a table.

These practices give us enforceable boundaries while keeping the operational overhead low.

Schemas, roles and search paths

PostgreSQL lets you create multiple schemas within a single database. A module can define its own schema and a role that owns it. The role only has usage and table-level privileges on that schema. For example, for an orders module:

-- create a user for the module and its schema
CREATE ROLE orders_role LOGIN PASSWORD 'orders_secret';
CREATE SCHEMA orders AUTHORIZATION orders_role;
GRANT USAGE ON SCHEMA orders TO orders_role;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA orders TO orders_role;
ALTER ROLE orders_role SET search_path = orders;

The ALTER ROLE command sets the role's default search path so unqualified names resolve to the module's schema. If you don't want to rely on the search path, always qualify table names (orders.table_name).

Row-level security (RLS) allows you to filter rows based on a policy expression. You enable RLS on a table and define a policy referencing current_user or columns:

RLS is powerful for multi-tenant scenarios or sensitive data, but it adds complexity. Start with schemas and roles and add RLS only when necessary.

Configuring EF schemas and multiple DbContexts

I assume readers are comfortable with EF Core, so we'll skip the basics and focus on what matters for modular monoliths:

• Use one DbContext per module. Each context contains only the entities of its module, and you call modelBuilder.HasDefaultSchema("orders") in OnModelCreating to map entities to the correct schema. Setting a default schema also affects sequences and migrations.
• Provide a connection string per module using the module's role. Even if modules share the same database, separate credentials ensure that a misconfigured context cannot access another schema.
• Configure the migrations history table in each context using MigrationsHistoryTable("__EFMigrationsHistory", "orders") so that EF's migration metadata stays within the module's schema.

These settings ensure EF Core queries and migrations respect the boundaries established by the database.

Step-by-step: Enforcing module boundaries

Suppose we have two modules (Orders and Shipping) and we want to enforce boundaries between them. Here's what we need to do:

1. Create schemas and roles. Use SQL to create orders and shipping schemas and their corresponding roles (orders_role, shipping_role). Grant each role privileges only on its schema.

   -- Orders schema and role
   CREATE ROLE orders_role LOGIN PASSWORD 'orders_secret';
   CREATE SCHEMA orders AUTHORIZATION orders_role;
   GRANT USAGE ON SCHEMA orders TO orders_role;
   GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA orders TO orders_role;
   ALTER ROLE orders_role SET search_path = orders;
   
    -- Shipping schema and role
    CREATE ROLE shipping_role LOGIN PASSWORD 'shipping_secret';
    CREATE SCHEMA shipping AUTHORIZATION shipping_role;
    GRANT USAGE ON SCHEMA shipping TO shipping_role;
    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA shipping TO shipping_role;
    ALTER ROLE shipping_role SET search_path = shipping;
   

2. Add connection strings. In configuration, define separate connection strings per module:

   {
     "ConnectionStrings": {
       "Orders": "Host=localhost;Database=appdb;Username=orders_role;Password=orders_secret",
       "Shipping": "Host=localhost;Database=appdb;Username=shipping_role;Password=shipping_secret"
     }
   }
   

3. Define DbContexts. Each module defines its own context and sets the default schema. For the Orders module:

   public class OrdersDbContext : DbContext
   {
       public DbSet<Order> Orders { get; set; } = default!;
       public DbSet<OrderLine> OrderLines { get; set; } = default!;
   
       public OrdersDbContext(DbContextOptions<OrdersDbContext> options) : base(options) { }
   
       protected override void OnModelCreating(ModelBuilder modelBuilder)
       {
           // set default schema for all entities in this context
           modelBuilder.HasDefaultSchema("orders");
           // optional: configure tables explicitly
           modelBuilder.Entity<Order>().ToTable("orders");
           modelBuilder.Entity<OrderLine>().ToTable("order_lines");
           base.OnModelCreating(modelBuilder);
       }
   }
   

   Register each context with its connection string and specify the migrations history table:

   builder.Services.AddDbContext<OrdersDbContext>(options =>
       options.UseNpgsql(builder.Configuration.GetConnectionString("Orders"),
           o => o.MigrationsHistoryTable("__EFMigrationsHistory", "orders")));
   
   builder.Services.AddDbContext<ShippingDbContext>(options =>
       options.UseNpgsql(builder.Configuration.GetConnectionString("Shipping"),
           o => o.MigrationsHistoryTable("__EFMigrationsHistory", "shipping")));
   

4. Maintain migrations separately. Because each module has its own context and schema, you maintain migrations separately. When generating a migration, specify the context:

   dotnet ef migrations add InitialOrders --context OrdersDbContext --output-dir Data/Migrations/Orders
   

   Repeat this for the Shipping context. EF Core will generate migration classes that create tables within the specified schema (because of HasDefaultSchema). Remember to apply the migrations in the correct order when deploying. You can automate this by having a migration runner iterate through the contexts.

With schemas, roles and multiple contexts in place, the data boundary becomes enforceable at the database level:

• The Orders module's DbContext knows only about the orders schema and uses credentials that have no privileges on the Shipping schema.
• The Shipping module cannot query orders.orders directly because its role lacks the necessary privileges.
• Cross-module communication must go through the module's public API (or an asynchronous event). This explicit coupling makes dependencies obvious and maintainable.

Cross-cutting queries

Even in a modular system you occasionally need a screen that spans multiple modules, such as an Order History page that shows order and shipping data. Resist the temptation to JOIN across schemas. Two approaches can help:

• Dedicated read model. One module owns a view model and subscribes to events from others. This pattern works well when modules might be extracted later.

• Database views with privileges. Since our modules share a database, we can create a read-only view in the public schema that joins the relevant tables. We grant SELECT on the view to a special role or module. This view acts like a controlled public API. Consumers query the view but cannot access the underlying tables directly. The trade-off is similar to calling a synchronous API: if you later split the database, the view will have to be replaced with a service call.

For example:

CREATE VIEW public.order_summary AS
SELECT o.id, o.total, s.status
FROM orders.orders o
JOIN shipping.shipments s ON s.order_id = o.id;

-- grant read access to a reporting role
GRANT SELECT ON public.order_summary TO reporting_role;

This approach lets you build dashboards or admin screens without breaking boundaries.

Conclusion

By giving each module its own schema, role and DbContext, and by controlling cross-module access via views or APIs, you ensure that boundaries in your modular monolith are enforceable rather than aspirational. This discipline makes it easier to evolve your system and paves the way for a future microservice extraction.

If you found this article valuable, check out my previous posts on modular monoliths:

• What Is a Modular Monolith?
• Modular Monolith Data Isolation
• Internal vs Public APIs in Modular Monoliths

If you want a structured, hands-on approach to building modular systems, from defining boundaries to extracting services, check out my Modular Monolith Architecture course. Join more than 2,100+ students who have mastered modular monoliths with it. The course walks through these patterns in depth and shows how to apply them in a real codebase.

Thanks for reading.

And stay awesome!

Previous versions of EF Core, however, suffered from one big limitation: each entity type could only have one filter defined. If you needed to combine multiple conditions (for example, soft-delete and tenant isolation) you either had to write explicit && expressions or manually disable and reapply filters in specific queries.

With EF 10, that changes. The new named query filters feature lets you attach multiple filters to a single entity and reference them by name. You can then disable individual filters as needed, rather than turning off all filters at once.

Let's explore this new capability, why it matters, and some practical ways to use it.

What Are Query Filters?

If you've used EF Core for a while, you may already be familiar with global query filters. A query filter is a condition that EF automatically applies to all queries for a particular entity type. Under the hood, EF adds a WHERE clause whenever that entity is queried. Typical uses include:

• Soft deletion: filtering out rows where IsDeleted is true so that deleted records don't show up in queries by default
• Multi-tenancy: filtering by a TenantId so that each tenant only sees its own data

For example, a soft-delete filter might be configured like this:

modelBuilder.Entity<Order>()
    .HasQueryFilter(order => !order.IsDeleted);

With the filter in place, every query on Orders automatically excludes soft-deleted records. To include deleted data (say, for an admin report), you can call IgnoreQueryFilters() on the query. The downside is that all filters on that entity are disabled, which opens the door to accidentally leaking data you don't intend to show.

Using Multiple Query Filters

Until now, EF permitted only one query filter per entity. If you called HasQueryFilter twice on the same entity, the second call overwrote the first. To combine filters you had to write a single expression with &&:

modelBuilder.Entity<Order>()
    .HasQueryFilter(order => !order.IsDeleted && order.TenantId == tenantId);

This works but makes it impossible to selectively disable one condition. IgnoreQueryFilters() disables both, forcing you to manually re-apply whichever filter you still need. EF 10 introduces a better alternative: named query filters.

To attach multiple filters to an entity, call HasQueryFilter with a name for each filter:

modelBuilder.Entity<Order>()
    .HasQueryFilter("SoftDeletionFilter", order => !order.IsDeleted)
    .HasQueryFilter("TenantFilter", order => order.TenantId == tenantId);

Under the hood, EF creates separate filters identified by the names you provide. You can now turn off just the soft-delete filter while keeping the tenant filter in place:

// Returns all orders (including soft‑deleted) for the current tenant
var allOrders = await context.Orders.IgnoreQueryFilters(["SoftDeletionFilter"]).ToListAsync();

If you omit the parameter array, IgnoreQueryFilters() disables all filters for the entity.

Tip: Using Constants for Filter Names

Named filters use string keys. Hard-coding those names throughout your codebase makes it easy to introduce typos and brittle magic strings. To avoid this, define constants or enums for your filter names and reuse them wherever needed. For example:

public static class OrderFilters
{
    public const string SoftDelete = nameof(SoftDelete);
    public const string Tenant = nameof(Tenant);
}

modelBuilder.Entity<Order>()
    .HasQueryFilter(OrderFilters.SoftDelete, order => !order.IsDeleted)
    .HasQueryFilter(OrderFilters.Tenant, order => order.TenantId == tenantId);

// Later in your query
var allOrders = await context.Orders.IgnoreQueryFilters([OrderFilters.SoftDelete]).ToListAsync();

Having the filter names defined in a single place reduces duplication and improves maintainability. Another best practice is to wrap the ignore call in an extension method or repository so that consumers don't directly interact with filter names at all. For example:

public static IQueryable<Order> IncludeSoftDeleted(this IQueryable<Order> query)
    => query.IgnoreQueryFilters([OrderFilters.SoftDelete]);

This makes your intent explicit and centralizes the filter logic in one place.

Wrapping Up

The introduction of named query filters in EF 10 removes one of the longstanding limitations of EF's global query filters feature. You can now:

• Attach multiple filters to a single entity and manage them individually
• Selectively disable specific filters in a LINQ query using IgnoreQueryFilters(["FilterName"])
• Simplify common patterns like soft deletion plus multi-tenancy without resorting to complicated conditional logic

Named query filters can become a powerful tool to keep your queries clean and your domain logic encapsulated.

Whether you're building SaaS applications that isolate tenant data or ensuring that deleted records stay hidden until you explicitly need them, EF 10's named query filters offer the flexibility you've been waiting for.

Give them a try in the preview and start thinking about how they can simplify your codebase.

That's all for today.

See you next week.

My go-to method?

HTML to PDF conversion. It's:

• Simple to implement
• Very flexible
• Ideal for stylized reports

But many popular libraries require a commercial license. This post walks you through a completely free approach using:

• Handlebars.NET for templating
• PuppeteerSharp for headless rendering

This gives you full control over layout, styling, and content. It's perfect for invoices, dashboards, and exports.

We'll start from scratch and build up to a complex, dynamic invoice report with full styling, images, and even headers and footers.

Why HTML + Headless Browser?

Pros:

• Rich styling with CSS
• Easy to preview/debug in browser
• Supports charts/images via JS/CSS
• Full control over layout (media queries, page breaks, etc.)

Cons:

• Requires bundling a browser (e.g. Chromium)
• Slower than native PDF libraries
• Slightly more setup complexity

Setting Up the Project

We'll start by installing the NuGet packages we need for Handlebars and PuppeteerSharp:

Install-Package Handlebars.Net
Install-Package PuppeteerSharp

Next, we'll create our first template. It's a simple HTML document with some Handlebars placeholders. You'll notice them with the {{variable}} syntax. These placeholders will be replaced with actual data when rendering the template.

<!-- Templates/InvoiceTemplate.html -->
<!-- The file extension doesn't really matter. -->
<html lang="en">
  <head>
    <style>
      body {
        font-family: Arial;
      }
    </style>
  </head>
  <body>
    <h1>Invoice #{{Number}}</h1>

    <p>Date: {{formatDate IssuedDate}}</p>

    <h2>From:</h2>
    <p>{{SellerAddress.CompanyName}}</p>
    <p>{{SellerAddress.Email}}</p>

    <h2>To:</h2>
    <p>{{CustomerAddress.CompanyName}}</p>
    <p>{{CustomerAddress.Email}}</p>

    <h2>Items:</h2>
    <table>
      <tr>
        <th>Name</th>
        <th>Price</th>
      </tr>
      {{#each LineItems}}
      <tr>
        <td>{{Name}}</td>
        <td>{{formatCurrency Price}}</td>
      </tr>
      {{/each}}
    </table>

    <p><strong>Total: {{formatCurrency Total}}</strong></p>
  </body>
</html>

The function calls, like {{formatDate IssuedDate}}, are custom helpers we can define in Handlebars. You register them like this:

Handlebars.RegisterHelper("formatDate", (context, arguments) =>
{
    if (arguments[0] is DateOnly date)
    {
        return date.ToString("dd/MM/yyyy");
    }
    return arguments[0]?.ToString() ?? "";
});

This allows us to format dates, currencies, or any other data type as needed. You register these helpers before compiling the template, once per application start is enough.

Rendering the Template and PDF

How do we render this template and convert it to PDF? We'll use Handlebars.NET to compile the template with data, then PuppeteerSharp to render it to PDF.

First, we read the template file and compile it with Handlebars:

var template = File.ReadAllText("Templates/InvoiceTemplate.html");
var data = new {
    customer = "Milan Jovanović",
    items = new[] {
        new { description = "Software License", price = 99 },
        new { description = "Support Plan", price = 49 }
    }
};

var compiledTemplate = Handlebars.Compile(template);

string html = compiledTemplate(data);

This gives us the final HTML with all placeholders replaced by actual data.

Note: You don't necessarily need to use Handlebars. You can use any templating engine that suits your needs, like Razor or Scriban.

Next, we need to convert this HTML to PDF using PuppeteerSharp. We'll launch a headless browser, set the content to our HTML, and then generate the PDF. Here's how we do it:

// Ensure PuppeteerSharp has the browser binaries
var browserFetcher = new BrowserFetcher();
await browserFetcher.DownloadAsync(BrowserFetcher.DefaultChromiumRevision);

// Launch the browser and create a new page
using var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });
using var page = await browser.NewPageAsync();

// Set the content of the page to our compiled HTML
await page.SetContentAsync(html);

// Optional: wait for fonts to load if using custom fonts
await page.EvaluateExpressionHandleAsync("document.fonts.ready");

byte[] pdf = await page.PdfDataAsync(new PdfOptions {
    Format = PaperFormat.A4,
    PrintBackground = true,
    MarginOptions = new MarginOptions
    {
        Top = "50px",
        Right = "20px",
        Bottom = "50px",
        Left = "20px"
    }
});

This gives us a byte array containing the PDF data. You can then save it to a file or return it from an API endpoint.

Here's a simple example of returning it from a Minimal API endpoint:

return Results.File(pdf, "application/pdf", "invoice.pdf");

Here's what the document looks like when rendered:

Enhancements: Images, Header/Footer, Styling

What are some improvements we can make to this basic setup?

For example, you can add images to your template using the <img> tag. A simple approach is to use a base64-encoded image directly in the HTML. Note that we're passing the image data using the LogoBase64 variable.

<img
  src="data:image/png;base64,{{LogoBase64}}"
  alt="Logo"
  style="height:50px; max-width:200px; object-fit:contain;"
/>

We can also render dynamic headers and footers using PuppeteerSharp's built-in support. You can define these in the PdfOptions object when generating the PDF. Here's an example:

var pdfOptions = new PdfOptions
{
    HeaderTemplate =
        @"""
        <div style='font-size: 14px; text-align: center; padding: 10px;'>
            <span style='margin-right: 20px;'><span class='title'></span></span>
            <span><span class='date'></span></span>
        </div>
        """,
    FooterTemplate =
        @"""
        <div style='font-size: 14px; text-align: center; padding: 10px;'>
            <span style='margin-right: 20px;'>Generated on <span class='date'></span></span>
            <span>Page <span class='pageNumber'></span> of <span class='totalPages'></span></span>
        </div>
        """,
    DisplayHeaderFooter = true
};

PuppeteerSharp uses CSS classes like title, date, pageNumber, and totalPages to inject dynamic values. This could be different for some other libraries, so check the documentation.

Lastly, I want to mention that you can use CSS for advanced styling. This can be inline in the HTML or in a separate CSS file. You can also reference external stylesheets if needed, using the <link> tag.

Here's a complete example of a more complex template with images, headers, and footers:

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Invoice #{{Number}}</title>
    <style>
      /* Omitted for brevity */
    </style>
  </head>
  <body>
    <div class="invoice-container">
      <!-- Header with Logo -->
      <div
        style="display: flex; justify-content: space-between; align-items: flex-start;"
      >
        <div>
          <h1 class="invoice-title">Invoice #{{Number}}</h1>
          <div class="invoice-dates">
            <p><strong>Issued:</strong> {{formatDate IssuedDate}}</p>
            <p><strong>Due:</strong> {{formatDate DueDate}}</p>
          </div>
        </div>
        <div>
          {{#if LogoBase64}}
          <img
            src="data:image/png;base64,{{LogoBase64}}"
            alt="Logo"
            style="height:50px; max-width:200px; object-fit:contain;"
          />
          {{/if}}
        </div>
      </div>
      <hr
        style="margin: 20px 0; border: none; border-top: 1px solid #e9ecef;"
      />

      <!-- Addresses - Side by Side -->
      <div class="addresses">
        <!-- Seller Address -->
        <div class="address-box">
          <h3 class="address-title">From:</h3>
          <div class="address-content">
            <p class="company-name">{{SellerAddress.CompanyName}}</p>
            <p>{{SellerAddress.Street}}</p>
            <p>{{SellerAddress.City}}, {{SellerAddress.State}}</p>
            <p class="email">{{SellerAddress.Email}}</p>
          </div>
        </div>

        <!-- Customer Address -->
        <div class="address-box">
          <h3 class="address-title">Bill To:</h3>
          <div class="address-content">
            <p class="company-name">{{CustomerAddress.CompanyName}}</p>
            <p>{{CustomerAddress.Street}}</p>
            <p>{{CustomerAddress.City}}, {{CustomerAddress.State}}</p>
            <p class="email">{{CustomerAddress.Email}}</p>
          </div>
        </div>
      </div>

      <!-- Items Table -->
      <div class="items-section">
        <h2 class="items-title">Items</h2>
        <table class="items-table">
          <thead>
            <tr>
              <th>#</th>
              <th>Description</th>
              <th>Price</th>
              <th>Qty</th>
              <th>Total</th>
            </tr>
          </thead>
          <tbody>
            {{#each LineItems}}
            <tr>
              <td>{{@index}}</td>
              <td>{{Name}}</td>
              <td>{{formatCurrency Price}}</td>
              <td>{{formatNumber Quantity}}</td>
              <td>{{formatCurrency (multiply Price Quantity)}}</td>
            </tr>
            {{/each}}
          </tbody>
        </table>
      </div>

      <!-- Totals -->
      <div class="totals">
        <div class="totals-container">
          <div class="totals-row subtotal">
            <span>Subtotal:</span>
            <span>{{formatCurrency Subtotal}}</span>
          </div>
          <div class="totals-row">
            <span>Tax:</span>
            <span>{{formatCurrency 0}}</span>
          </div>
          <div class="totals-row total">
            <span>Total:</span>
            <span>{{formatCurrency Total}}</span>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>

And the rendered PDF looks like this:

Downloading Binaries at Application Start

Here's a small tip: PuppeteerSharp requires the Chromium browser binaries to be downloaded at runtime. You can do this by calling BrowserFetcher.DownloadAsync() before launching the browser. This ensures the required browser version is available when you run your application.

A simple way to do this is to add it to your application startup code or a background service:

public class BrowserSetupService : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();
    }
}

Then register this service in your Program.cs:

builder.Services.AddHostedService<BrowserSetupService>();

Performance Considerations

Let's talk about performance. How fast is this approach and can you use it at scale?

The first thing to consider is the use a headless browser like Chromium. This can be slower than native PDF libraries, especially for large documents or high concurrency. It also adds overhead at runtime since the browser binaries need to be downloaded and launched.

You should definitely consider moving this out of your main application. You can use a background service or a separate microservice to handle PDF generation. Event a cloud function can be a good fit if you need to scale.

But as with anything performance-related, it depends on your specific use case. So measure and profile your application to see if this approach meets your needs.

Here are some benchmarks I ran on a sample invoice template. It's nothing scientific, but it gives you an idea of the performance. I didn't test this with concurrent requests, but rather just the time it takes to generate a single PDF.

Cold Start: ~12s spent downloading + launching Chromium

Warm Run: ~580ms

• Template + HTML generation: ~13ms
• Browser reuse + rendering: ~550ms

Summary

HTML + PuppeteerSharp is one of the most pragmatic approaches for PDF reporting in .NET.

It lets you:

• Design pixel-perfect layouts using familiar web technologies
• Inject dynamic data cleanly with Handlebars.NET
• Output high-quality PDFs with full styling, tables, and images

And all of this without relying on commercial libraries.

I've also written about PDF generation in the past, with libraries like QuestPdf or IronPdf. You can take a look at those if you want to compare approaches.

The cold start can be expensive, but once warmed up, rendering is fast and reliable. You get total layout control, CSS styling, and even dynamic headers and footers with page numbers and timestamps.

If you're building internal dashboards, invoice generators, or export endpoints, this approach delivers excellent value.

If you need pixel-perfect PDF reports in .NET and want full design control, combining Handlebars.NET with PuppeteerSharp is a powerful approach.

You'll trade some performance and setup cost for flexibility, but for most internal tools, dashboards, or customer-facing reports, it's worth it.

When something breaks in production, the last thing you want is a cryptic 500 error with zero context. Proper error handling isn't just about logging exceptions. It's about making sure your app fails gracefully and gives useful info to the caller (and you).

In this article, I'll walk through the main options for global error handling in ASP.NET Core.

We'll look at how I used to do it, what ASP.NET Core 9 offers now, and where each approach makes sense.

Middleware-Based Error Handling

The classic way to catch unhandled exceptions is with custom middleware. This is where most of us start, and honestly, it still works great for most scenarios.

internal sealed class GlobalExceptionHandlerMiddleware(
    RequestDelegate next,
    ILogger<GlobalExceptionHandlerMiddleware> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled exception occurred");

            // Make sure to set the status code before writing to the response body
            context.Response.StatusCode = ex switch
            {
                ApplicationException => StatusCodes.Status400BadRequest,
                _ => StatusCodes.Status500InternalServerError
            };

            await context.Response.WriteAsJsonAsync(
                new ProblemDetails
                {
                    Type = ex.GetType().Name,
                    Title = "An error occured",
                    Detail = ex.Message
                });
        }
    }
}

Don't forget to add the middleware to the request pipeline:

app.UseMiddleware<GlobalExceptionHandlerMiddleware>();

This approach is solid and works everywhere in your pipeline. The beauty is its simplicity: wrap everything in a try-catch, log the error, and return a consistent response.

But once you start adding specific rules for different exception types (e.g. ValidationException, NotFoundException), this becomes a mess. You end up with long if / else chains or more abstractions to handle each exception type.

Plus, you're manually crafting JSON responses, which means you're probably not following RFC 9457 (Problem Details) standards.

Enter IProblemDetailsService

Microsoft recognized this pain point and gave us IProblemDetailsService to standardize error responses. Instead of manually serializing our own error objects, we can use the built-in Problem Details format.

internal sealed class GlobalExceptionHandlerMiddleware(
    RequestDelegate next,
    IProblemDetailsService problemDetailsService,
    ILogger<GlobalExceptionHandlerMiddleware> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled exception occurred");

            // Make sure to set the status code before writing to the response body
            context.Response.StatusCode = ex switch
            {
                ApplicationException => StatusCodes.Status400BadRequest,
                _ => StatusCodes.Status500InternalServerError
            };

            await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
            {
                HttpContext = context,
                Exception = ex,
                ProblemDetails = new ProblemDetails
                {
                    Type = ex.GetType().Name,
                    Title = "An error occured",
                    Detail = ex.Message
                }
            });
        }
    }
}

This is much cleaner. We're now using a standard format that API consumers expect, and we're not manually fiddling with JSON serialization. But we're still stuck with that growing switch statement problem. You can learn more about using Problem Details in .NET here.

The Modern Way: IExceptionHandler

ASP.NET Core 8 introduced IExceptionHandler, and it's a game-changer. Instead of one massive middleware handling everything, we can create focused handlers for specific exception types.

Here's how it works:

internal sealed class GlobalExceptionHandler(
    IProblemDetailsService problemDetailsService,
    ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        logger.LogError(exception, "Unhandled exception occurred");

        httpContext.Response.StatusCode = exception switch
        {
            ApplicationException => StatusCodes.Status400BadRequest,
            _ => StatusCodes.Status500InternalServerError
        };

        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            Exception = exception,
            ProblemDetails = new ProblemDetails
            {
                Type = exception.GetType().Name,
                Title = "An error occured",
                Detail = exception.Message
            }
        });
    }
}

The key here is the return value. If your handler can deal with the exception, return true. If not, return false and let the next handler try.

Don't forget to register it with DI and the request pipeline:

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// And in your pipeline
app.UseExceptionHandler();

This approach is so much cleaner. Each handler has one job, and the code is easy to test and maintain.

Chaining Exception Handlers

You can chain multiple exception handlers together, and they'll run in the order you register them. ASP.NET Core will use the first one that returns true from TryHandleAsync.

Example: One for validation errors, one global fallback.

builder.Services.AddExceptionHandler<ValidationExceptionHandler>();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

Let's say you're using FluentValidation (and you should be). Here's a complete setup:

internal sealed class ValidationExceptionHandler(
    IProblemDetailsService problemDetailsService,
    ILogger<ValidationExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        if (exception is not ValidationException validationException)
        {
            return false;
        }

        logger.LogError(exception, "Unhandled exception occurred");

        httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        var context = new ProblemDetailsContext
        {
            HttpContext = httpContext,
            Exception = exception,
            ProblemDetails = new ProblemDetails
            {
                Detail = "One or more validation errors occurred",
                Status = StatusCodes.Status400BadRequest
            }
        };

        var errors = validationException.Errors
            .GroupBy(e => e.PropertyName)
            .ToDictionary(
                g => g.Key.ToLowerInvariant(),
                g => g.Select(e => e.ErrorMessage).ToArray()
            );
        context.ProblemDetails.Extensions.Add("errors", errors);

        return await problemDetailsService.TryWriteAsync(context);
    }
}

And in your app, just throw like this:

// In your controller or service - IValidator<CreateUserRequest>
public async Task<IActionResult> CreateUser(CreateUserRequest request)
{
    await _validator.ValidateAndThrowAsync(request);

    // Your business logic here
}

The execution order is important. The framework will try each handler in the order you registered them. So put your most specific handlers first, and your catch-all handler last.

Summary

We've come a long way from the days of manually crafting error responses in middleware. The evolution looks like this:

• Middleware: Simple, works everywhere, but gets complex fast
• IProblemDetailsService: Standardizes response format, still manageable
• IExceptionHandler: Modern, testable, and scales beautifully

For new projects, I'd go straight to IExceptionHandler. It's cleaner, more maintainable, and gives you the flexibility to handle different exception types exactly how you want.

The key takeaway? Don't let error handling be an afterthought. Set it up early, make it consistent, and your users (and your future self) will thank you when things inevitably go wrong.

Thanks for reading.

And stay awesome!

It brings a fresh, modern approach to building cloud-native apps, with a focus on developer productivity, great defaults, and tight integration across your entire stack.

One of the most asked-for features is the ability to publish your app to Docker Compose. This is now available in the latest preview, and I'm excited to share how it works.

In this post, I'll walk you through how I used Aspire's Docker publisher to spin up a demo app that includes an API, a Postgres database, and a Redis cache. Everything runs using Docker Compose, and Aspire generates the whole thing from C# code.

I'll show you how to set it up, explain what it's doing behind the scenes, and give you a glimpse into how easy it is to take that setup and run it on a VPS or cloud server.

The Demo App

The app is intentionally simple, just enough to demonstrate how Aspire wires things together.

• API project: a minimal .NET Web API
• Postgres: used for data storage
• Redis: used for caching

In a traditional setup, you'd manually connect these services, manage configuration files, handle environment variables, and write a docker-compose.yml from scratch.

With Aspire, you declare everything in C# inside the AppHost project. Here's a quick look at the setup:

var builder = DistributedApplication.CreateBuilder(args);

// Enables Docker publisher
builder.AddDockerComposeEnvironment("aspire-docker-demo");

var postgres = builder.AddPostgres("database")
    .WithDataVolume();

var database = postgres.AddDatabase("demo-db");

var redis = builder.AddRedis("cache");

var webApi = builder.AddProject<Projects.Web_Api>("web-api")
    .WithReference(database).WaitFor(postgres)
    .WithReference(redis).WaitFor(redis);

builder.Build().Run();

This gives you a development environment where Aspire runs Postgres and Redis in containers, and connects your API to them.

The AddDockerComposeEnvironment method enables the Docker publisher. It's available in the Aspire.Hosting.Docker NuGet package, which is currently in preview.

Install-Package Aspire.Hosting.Docker -Version 9.3.1-preview.1.25305.6

Installing the Aspire CLI

To publish your app to Docker Compose, install the Aspire CLI:

dotnet tool install --global aspire.cli --prerelease

Then you can run the publish command:

aspire publish -o docker-compose-artifacts

This command will scan your solution for the Aspire project and generate a Docker Compose file and an .env file based on the services you've defined.

The Docker Compose File

Let's examine what Aspire created for us:

services:
  database:
    image: 'docker.io/library/postgres:17.4'
    environment:
      POSTGRES_HOST_AUTH_METHOD: 'scram-sha-256'
      POSTGRES_INITDB_ARGS: '--auth-host=scram-sha-256 --auth-local=scram-sha-256'
      POSTGRES_USER: 'postgres'
      POSTGRES_PASSWORD: '${DATABASE_PASSWORD}'
    ports:
      - '8000:5432'
    volumes:
      - type: 'volume'
        target: '/var/lib/postgresql/data'
        source: 'aspire.apphost-1f0ed76b33-database-data'
        read_only: false
    networks:
      - 'aspire'
  redis:
    image: 'docker.io/library/redis:7.4'
    command:
      - '-c'
      - 'redis-server --requirepass $$REDIS_PASSWORD'
    entrypoint:
      - '/bin/sh'
    environment:
      REDIS_PASSWORD: '${REDIS_PASSWORD}'
    ports:
      - '8001:6379'
    networks:
      - 'aspire'
  web-api:
    image: '${WEB_API_IMAGE}'
    environment:
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: 'true'
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: 'true'
      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: 'in_memory'
      ASPNETCORE_FORWARDEDHEADERS_ENABLED: 'true'
      HTTP_PORTS: '8002'
      ConnectionStrings__demo-db: 'Host=database;Port=5432;Username=postgres;Password=${DATABASE_PASSWORD};Database=demo-db'
      ConnectionStrings__redis: 'redis:6379,password=${REDIS_PASSWORD}'
    ports:
      - '8003:8002'
      - '8005:8004'
    depends_on:
      database:
        condition: 'service_started'
      redis:
        condition: 'service_started'
    networks:
      - 'aspire'
networks:
  aspire:
    driver: 'bridge'
volumes:
  aspire.apphost-1f0ed76b33-database-data:
    driver: 'local'

This docker-compose file is generated from the C# code we wrote earlier. It defines the services, their images, environment variables, ports, and dependencies.

The .env file contains some of the configuration we need:

# Parameter database-password
DATABASE_PASSWORD=<YOUR_STRONG_PASSWORD>

# Container image name for web-api
# Change this to the imaage name in the container registry
WEB_API_IMAGE=web-api:latest

# Parameter redis-password
REDIS_PASSWORD=<YOUR_STRONG_PASSWORD>

It contains the passwords for the database and Redis, as well as the image name for the API. You'll need to replace the placeholders with actual values. For the API image, you can build and tag the image yourself, or use a pre-built one from a registry.

Publishing and Running on a VPS

Aspire doesn't deploy the app for you, but it gives you everything you need.

Once the Compose file is ready, deployment to a VPS is straightforward:

1. Copy the artifacts to your server using (scp or git).
2. SSH into the VPS.
3. Run docker compose up -d inside the artifact directory.

Make sure Docker and Docker Compose are installed on the server.

You can expose ports with a reverse proxy like Nginx or Caddy, and secure it with HTTPS using Let's Encrypt.

I'll cover this in more detail in a future post.

Wrapping Up

.NET Aspire with Docker Compose provides a smooth developer experience and a simple way to deploy full-stack apps.

You define everything in C#, test it locally, and publish it with one command. No need to write Compose files or manage infrastructure manually. This opens up new possibilities for deploying and managing cloud-native apps. You're not locked into a specific cloud provider, and you can easily move between environments.

Can I just say how much I love this? I'm really excited about the future of cloud-native development with .NET and Aspire.

If you liked this article and want to learn how I structure larger apps, check out Modular Monolith Architecture. It walks you through building clean, scalable .NET applications with strong internal boundaries and maintainability in mind.

Thanks for reading and stay awesome!

I've seen teams struggle with flaky tests, slow test suites, and configuration headaches that could have been avoided with better practices from the start.

Today, I'll show you the patterns that make Testcontainers tests reliable, fast, and easy to maintain.

How Testcontainers Changes Integration Testing

Traditional integration tests often rely on shared test databases or in-memory alternatives that don't match production behavior. You either deal with test pollution between runs or sacrifice realism for speed.

Testcontainers solves this by spinning up real Docker containers for your dependencies. Your tests run against actual PostgreSQL, Redis, or any other service you use in production. When tests complete, containers are destroyed, giving you a clean slate every time.

The magic happens through Docker's API. Testcontainers manages the entire lifecycle: pulling images, starting containers, waiting for readiness, and cleanup. Your test code just needs to know how to connect.

Prerequisites

First, make sure you have the necessary packages:

Install-Package Microsoft.AspNetCore.Mvc.Testing
Install-Package Testcontainers.PostgreSql
Install-Package Testcontainers.Redis

If you want to learn more about the basic setup, check out my article on integrating testing with Testcontainers.

Creating Test Containers

Here's how to set up your containers with proper configuration:

PostgreSqlContainer _postgresContainer = new PostgreSqlBuilder()
    .WithImage("postgres:17")
    .WithDatabase("devhabit")
    .WithUsername("postgres")
    .WithPassword("postgres")
    .Build();

RedisContainer _redisContainer = new RedisBuilder()
    .WithImage("redis:latest")
    .Build();

To start and stop containers cleanly across your test suite, implement IAsyncLifetime in your WebApplicationFactory:

public sealed class IntegrationTestWebAppFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
    public async Task InitializeAsync()
    {
        await _postgresContainer.StartAsync();
        await _redisContainer.StartAsync();
        // Start other dependencies here
    }

    public async Task DisposeAsync()
    {
        await _postgresContainer.StopAsync();
        await _redisContainer.StopAsync();
    }
}

This ensures containers are ready before tests run and cleaned up afterward. This means no leftover Docker state or race conditions.

A tip: pin your image versions (like postgres:17) to avoid surprises from upstream changes

I learned this the hard way when a minor version update caused my tests to fail unexpectedly.

Pass Configuration to Your App

The biggest mistake I see is hardcoding connection strings. Testcontainers assigns dynamic ports. Don't hardcode anything.

Instead, inject values via WebApplicationFactory.ConfigureWebHost:

protected override void ConfigureWebHost(IWebHostBuilder builder)
{
    builder.UseSetting("ConnectionStrings:Database", _postgresContainer.GetConnectionString());
    builder.UseSetting("ConnectionStrings:Redis", _redisContainer.GetConnectionString());
}

The key is to use the UseSetting method to pass connection strings dynamically. It also avoids any race conditions or conflicts with other tests that might run in parallel.

This ensures your tests always connect to the right ports, regardless of what Docker assigns.

There's no need to remove services from the service collection or manually configure them (contrary to what you might find online). Just set the connection strings, and your application will use them automatically.

Share Expensive Setup with xUnit Collection Fixtures

What's a test fixture? A fixture is a shared context for your tests, allowing you to set up expensive resources like databases or message brokers once and reuse them across multiple tests.

This is where most teams get tripped up. The choice between class and collection fixtures affects both test performance and isolation.

Class Fixture - One container per test class:

Use class fixtures when tests modify global state or when debugging test interactions becomes difficult.

public class AddItemToCartTests : IClassFixture<DevHabitWebAppFactory>
{
    private readonly DevHabitWebAppFactory _factory;

    public AddItemToCartTests(DevHabitWebAppFactory factory)
    {
        _factory = factory;
    }

    [Fact]
    public async Task Should_ReturnFailure_WhenNotEnoughQuantity() { ... }
}

Collection Fixture - One container shared across multiple test classes:

Use collection fixtures when your tests don't modify shared state or when you can reliably clean up between tests.

[CollectionDefinition(nameof(IntegrationTestCollection))]
public sealed class IntegrationTestCollection : ICollectionFixture<DevHabitWebAppFactory>
{
}

Then apply it to your test classes:

[Collection(nameof(IntegrationTestCollection))]
public class AddItemToCartTests : IntegrationTestFixture
{
    public AddItemToCartTests(DevHabitWebAppFactory factory) : base(factory) { }

    [Fact]
    public async Task Should_ReturnFailure_WhenNotEnoughQuantity()
    {
        Guid customerId = await Sender.CreateCustomerAsync(Guid.NewGuid());
        var command = new AddItemToCartCommand(customerId, ticketTypeId, Quantity + 1);

        Result result = await Sender.Send(command);

        result.Error.Should().Be(TicketTypeErrors.NotEnoughQuantity(Quantity));
    }
}

When to use which:

• Class fixtures when you need full isolation between test classes (slower but safer)
• Collection fixtures when test classes don't interfere with each other (faster but requires discipline)

With collection fixtures, you have to take care of cleaning up any state that might persist between tests. This could include resetting databases, clearing caches, or removing test data. If you don't do this, you risk tests affecting each other, leading to flaky results.

Utility Methods for Auth and Cleanup

Your fixture can expose helpers to simplify test writing:

public async Task<HttpClient> CreateAuthenticatedClientAsync() { ... }

protected async Task CleanupDatabaseAsync() { ... }

These methods can handle authentication setup and database cleanup, so you don't have to repeat boilerplate code in every test. This lets your test code focus on assertions, not setup.

Writing Maintainable Integration Tests

With the infrastructure properly configured, your actual tests should focus on business logic:

[Fact]
public async Task Should_ReturnFailure_WhenNotEnoughQuantity()
{
    //Arrange
    Guid customerId = await Sender.CreateCustomerAsync(Guid.NewGuid());
    var eventId = Guid.NewGuid();
    var ticketTypeId = Guid.NewGuid();

    await Sender.CreateEventWithTicketTypeAsync(eventId, ticketTypeId, Quantity);

    var command = new AddItemToCartCommand(customerId, ticketTypeId, Quantity + 1);

    //Act
    Result result = await Sender.Send(command);

    //Assert
    result.Error.Should().Be(TicketTypeErrors.NotEnoughQuantity(Quantity));
}

Notice how the tests focus on business rules rather than infrastructure concerns. The container complexity is hidden behind well-designed base classes and helper methods. You're not mocking Postgres or Redis, you're testing real behavior.

Conclusion

Testcontainers transforms integration testing by giving you the confidence that comes from testing against real dependencies. No more wondering if your in-memory database behavior matches production, or dealing with shared test environments that break when someone else runs their tests.

Start simple: pick one integration test that currently uses mocks or in-memory databases, and convert it to use Testcontainers. You'll immediately notice the difference in confidence when that test passes. Then gradually expand to cover your critical business flows.

If you want to learn how to structure your applications for testability from day one, my Pragmatic Clean Architecture course covers integration testing with Testcontainers alongside domain modeling, API design, and the architectural decisions that make applications maintainable over time.

That's all for today.

See you next week.

When something breaks, you're stuck digging through logs, guessing at performance bottlenecks, and trying to piece together what actually happened across your distributed system.

That ends today.

Grafana is a complete observability platform that unifies metrics, logs, and traces in one place.

With Grafana, you get:

• Unified dashboards that combine metrics, logs, and traces
• Advanced alerting that actually works when things go wrong
• Deep trace analysis to understand request flows across services
• Log correlation that connects your traces to the exact log entries that matter

Grafana Cloud makes this even easier. No infrastructure to manage, automatic scaling, and built-in integrations with OpenTelemetry. There's a generous free tier that allows you to get started without any upfront costs.

When you combine Grafana with OpenTelemetry, you get vendor-neutral observability that actually delivers insights instead of just pretty charts.

Setting Up OpenTelemetry in .NET

First, install the core OpenTelemetry packages:

Install-Package OpenTelemetry.Extensions.Hosting
Install-Package OpenTelemetry.Exporter.OpenTelemetryProtocol
Install-Package OpenTelemetry.Instrumentation.AspNetCore
Install-Package OpenTelemetry.Instrumentation.Http

You can also add instrumentation for other libraries as needed:

Install-Package OpenTelemetry.Instrumentation.EntityFrameworkCore
Install-Package OpenTelemetry.Instrumentation.StackExchangeRedis
Install-Package Npgsql.OpenTelemetry

Configure OpenTelemetry in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService(serviceName))
    .WithTracing(tracing =>
    {
        tracing
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddEntityFrameworkCoreInstrumentation()
            .AddRedisInstrumentation()
            .AddNpgsql();

        tracing.AddOtlpExporter();
    });

builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeScopes = true;
    logging.IncludeFormattedMessage = true;

    logging.AddOtlpExporter();
});

var app = builder.Build();

// Your app configuration...

app.Run();

This configuration:

• Sets up tracing with OpenTelemetry
• Sets up automatic instrumentation for ASP.NET Core and HTTP requests
• Adds Entity Framework Core and Redis instrumentation
• Configures PostgreSQL instrumentation if you're using Npgsql
• Configures OTLP export for traces and logs (we can also add metrics later)

Configuring OTLP Export to Grafana Cloud

Get your Grafana Cloud credentials:

1. Log into Grafana Cloud

2. Go to My Account → Stack Details

3. Find your OTLP endpoint (looks like https://otlp-gateway-prod-eu-west-2.grafana.net/otlp)

4. Generate an API token with permissions

You should also see the environment variables you can use to configure OpenTelemetry:

Configure the OTLP exporter in your appsettings.json:

{
  "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp",
  "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Basic <your-base64-encoded-token>"
}

You can also set these as environment variables in your hosting environment.

Viewing and Analyzing Data in Grafana

Start your application and generate some traffic. Now head to your Grafana Cloud instance.

Traces

If everything is set up correctly, you should see traces from your application in the Traces section.

Here's an example of a trace view in Grafana Cloud. It's a POST users/register request that contains multiple spans:

Here's another example of a trace that includes messages sent to a message broker (like RabbitMQ or Kafka).

Logs

You can also view logs in Grafana Cloud.

Here's an example of a log view that shows multiple log entries for our application.

You can drill down into individual log entries, filter by severity, and search for specific terms.

OpenTelemetry automatically correlates your logs with traces. In the trace detail view, click Logs to see all log entries that occurred during that request.

Your logs will include trace and span IDs.

Conclusion

You now have full observability for your .NET application.

When something goes wrong in production, you won't be guessing anymore. You'll see exactly which requests were slow, what errors occurred, and how they propagated through your system.

Grafana gives you the dashboards and alerting to catch problems before users do. OpenTelemetry gives you the detailed traces to understand exactly what happened.

This setup scales from a single service to hundreds of microservices without changing your instrumentation code.

Ready to take your observability further?

This article showed you the basics, but modern applications need advanced patterns like distributed tracing across event-driven architectures, custom instrumentation strategies, and observability-driven development practices.

I cover all of this in-depth in my Modular Monolith Architecture course, where you'll learn how to implement OpenTelemetry across complex, event-driven systems that actually scale in production.

That's all for today.

See you next Saturday.

You can now run a C# file directly with:

dotnet run app.cs

That's it. No .csproj. No Program.cs. No solution files. Just a single C# file.

This new feature, introduced in .NET 10 Preview 4, is a big step toward making C# more script-friendly, especially for quick utilities, dev tooling, and CLI-based workflows.

Why This Matters

For years, C# has been perceived as heavyweight for small scripts. Compare that to Python, Bash, or even JavaScript, where you can just write a file and run it.

That barrier is now gone.

You can now:

• Write one-off scripts in .cs files
• Use top-level statements
• Reference NuGet packages inline
• Share minimal reproducible examples without scaffolding a project

And it runs on any OS with the .NET SDK installed.

Minimal Example

Here's a simple script that prints today's date:

Console.WriteLine($"Today is {DateTime.Now:dddd, MMM dd yyyy}");

Run it:

dotnet run app.cs

Output:

Today is Saturday, Jun 14 2025

That's it. No boilerplate, no boring Main() method. Just top-level programs and C# code.

Referencing NuGet Packages

Let's say you want to make an HTTP request using Flurl.Http.

You can do this inline:

#:package Flurl.Http@4.0.2

using Flurl.Http;

var response = await "https://api.github.com"
    .WithHeader("Accept", "application/vnd.github.v3+json")
    .WithHeader("User-Agent", "dotnet-script")
    .GetAsync();

Console.WriteLine($"Status code: {response.StatusCode}");

Console.WriteLine(await response.GetJsonAsync<object>());

To run it:

dotnet run fetch.cs

Behind the scenes, the compiler downloads and restores NuGet dependencies automatically.

Real-World Use Case: Seeding SQL Data

Here's a script I recently used to seed some test data into my Postgres database.

#:package Dapper@2.1.66
#:package Npgsql@9.0.3

using Dapper;
using Npgsql;

const string connectionString = "Host=localhost;Port=5432;Username=postgres;Password=postgres";

using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();

using var transaction = connection.BeginTransaction();

Console.WriteLine("Creating tables...");

await connection.ExecuteAsync(@"
    CREATE TABLE IF NOT EXISTS users (
        id SERIAL PRIMARY KEY,
        name TEXT NOT NULL
    );
");

Console.WriteLine("Inserting users...");

for (int i = 1; i <= 10_000; i++)
{
    await connection.ExecuteAsync(
        "INSERT INTO users (name) VALUES (@Name);",
        new { Name = $"User {i}" });

    if (i % 1000 == 0)
    {
        Console.WriteLine($"Inserted {i} users...");
    }
}

transaction.Commit();

Console.WriteLine("Done!");

Why did I write this as a script? I didn't want to clutter my app with throwaway seed logic. I just needed a quick way to populate my database with test data. This script does exactly that, and I can run it with:

dotnet run seed.cs

File-Level Directives: The Magic Behind It

The real power comes from file-level directives. These let you configure your app without leaving the .cs file:

Package References

#:package Dapper@2.1.66
#:package Npgsql@9.0.3

SDK Selection

#:sdk Microsoft.NET.Sdk.Web

This tells .NET to treat your file as a web application, enabling ASP.NET Core features:

#:sdk Microsoft.NET.Sdk.Web
#:package Microsoft.AspNetCore.OpenApi@9.*

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello from a file-based API!");
app.MapGet("/users/{id}", (int id) => new { Id = id, Name = $"User {id}" });

app.Run();

You now have a running web API. No project file. No Startup.cs. Just C# that does what you want.

MSBuild Properties

You can also set MSBuild properties directly in the file:

#:property LangVersion preview
#:property Nullable enable

When Your Script Grows Up

The brilliant part? When your file-based app gets complex enough to need project structure, converting is seamless:

dotnet project convert api.cs

This creates:

• A new folder named after your file
• A proper .csproj file with all your directives converted to MSBuild properties
• Your code moved to api.cs (or Program.cs if you prefer)
• Everything ready for full project development

Given our API example above, the generated .csproj looks like:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*" />
  </ItemGroup>
</Project>

Your file-based app evolves naturally into a project-based app. No need to rewrite or restructure everything. This makes it easy to start small and grow as needed, without losing the simplicity of the initial script.

Takeaway

The bottom line is this: C# just became significantly more approachable. The barrier to entry dropped from "learn project files and MSBuild" to "write C# and run it."

For experienced developers, this is a productivity boost for scripting and prototyping. For newcomers, this removes the biggest stumbling block to getting started with C#.

The best part? Microsoft didn't create a separate scripting language or runtime. They made regular C# easier to use. Your file-based apps are real .NET applications that can grow into full projects when needed.

The ceremony is dead. Long live practical C#.

"Filter Early, JOIN Later"

The claim goes like this: instead of joining tables first and then filtering, you should filter in a subquery first, then join.

The supposed benefit?

The database filtered the smaller table first, then did the JOIN — saving time and memory.

Here is the thing - this advice is completely wrong for modern databases.

Let me show you why with actual data.

The Supposed "Optimization"

The article shows two queries. Here is the "bad" version:

SELECT *
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.total > 500;

And the "optimized" version:

SELECT *
FROM (
  SELECT * FROM orders WHERE total > 500
) o
JOIN users u ON u.id = o.user_id;

The claim is that the second query is faster because it "filters first, then joins."

Sounds logical, right? Wrong.

Testing with Real Data

I tested both queries on a PostgreSQL database with:

• 10,000 users
• 5,000,000 orders (500 per user)
• Filtering for orders > $500

Let me run EXPLAIN ANALYZE on both queries to see what actually happens.

The Results

Here are the execution plans for both queries:

"Bad" Query Execution Plan:

Hash Join  (cost=280.00..96321.92 rows=2480444 width=27) (actual time=1.014..641.202 rows=2499245 loops=1)
  Hash Cond: (o.user_id = u.id)
  ->  Seq Scan on orders o  (cost=0.00..89528.00 rows=2480444 width=14) (actual time=0.006..368.857 rows=2499245 loops=1)
        Filter: (total > '500'::numeric)
        Rows Removed by Filter: 2500755
  ->  Hash  (cost=155.00..155.00 rows=10000 width=13) (actual time=0.998..0.999 rows=10000 loops=1)
        Buckets: 16384  Batches: 1  Memory Usage: 577kB
        ->  Seq Scan on users u  (cost=0.00..155.00 rows=10000 width=13) (actual time=0.002..0.341 rows=10000 loops=1)
Planning Time: 0.121 ms
Execution Time: 685.818 ms

"Optimized" Query Execution Plan:

Hash Join  (cost=280.00..96321.92 rows=2480444 width=27) (actual time=1.019..640.613 rows=2499245 loops=1)
  Hash Cond: (orders.user_id = u.id)
  ->  Seq Scan on orders  (cost=0.00..89528.00 rows=2480444 width=14) (actual time=0.005..368.260 rows=2499245 loops=1)
        Filter: (total > '500'::numeric)
        Rows Removed by Filter: 2500755
  ->  Hash  (cost=155.00..155.00 rows=10000 width=13) (actual time=1.004..1.005 rows=10000 loops=1)
        Buckets: 16384  Batches: 1  Memory Usage: 577kB
        ->  Seq Scan on users u  (cost=0.00..155.00 rows=10000 width=13) (actual time=0.003..0.348 rows=10000 loops=1)
Planning Time: 0.118 ms
Execution Time: 685.275 ms

The execution plans are identical.

Both queries took ~685ms. The "optimization" did absolutely nothing.

Here's the simplified execution plan, where I removed some details:

Hash Join
  Hash Cond: (o.user_id = u.id)
  ->  Seq Scan on orders o
        Filter: (total > '500'::numeric)
        Rows Removed by Filter
  ->  Hash
        ->  Seq Scan on users u

The core operations are:

1. Sequential Scan on orders table with filter applied
2. Sequential Scan on users table
3. Hash operation to build hash table from users
4. Hash Join using the hash condition on user_id

Query Optimizers Are Smarter Than You

Modern databases use cost-based optimizers. Here is what happens when you run a query:

1. Parser turns your SQL into an abstract syntax tree
2. Optimizer rewrites your query into the most efficient form
3. Executor runs the optimized plan

The optimizer looks at your query and says: "I don't care how you wrote this. I will figure out the best way to execute it."

Both of our queries get rewritten to the same optimal plan:

• Filter the orders table first (because that eliminates rows early)
• Build a hash table from users (the smaller table)
• Hash join the filtered orders with users

The optimizer already does the "optimization" automatically.

Your manual subquery does not make it faster - it just makes your SQL harder to read.

How Cost-Based Optimization Works

The query optimizer has statistics about your tables:

• Row counts
• Data distribution
• Index availability
• Column selectivity

It uses these stats to estimate the cost of different execution strategies:

• Which table to scan first
• Which join algorithm to use (hash, nested loop, merge)
• When to apply filters
• Which indexes to use

Then it picks the cheapest plan. Your well-intentioned manual "optimization" gets ignored because the optimizer knows better.

Summary

The "Filter Early, JOIN Later" advice is a relic from ancient database systems that did not have sophisticated optimizers.

Modern databases like PostgreSQL, MySQL, and SQL Server already do predicate pushdown and join reordering automatically. Your manual "optimizations" are pointless and make code harder to maintain.

Write clear, readable SQL. Let the optimizer do its job.

The real lesson? Stop believing every performance tip you read online. Use EXPLAIN ANALYZE to understand what your database is actually doing.

Here's the thing - everyone talks about which one is "better," but rarely do you see actual numbers. So I decided to put both through the same tests and see what happens.

I'll test both proxies using the exact same API, same hardware, and same load testing approach. No bias, just data.

The Test API

I kept the test API super simple on purpose. This way, we're measuring proxy performance, not how fast the backend can process complex requests:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello", () =>
{
    return Results.Ok("Hello world!");
});

app.Run();

This basic endpoint means we're testing the proxy itself, not waiting for complex business logic to run.

YARP Configuration

YARP is pretty nice to work with if you're already in the .NET world. The setup is straightforward:

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();
app.MapReverseProxy();
app.Run();

It's equally simple to configure load balancing or authentication.

The routing setup is clean and uses a **catch-all pattern to forward everything:

{
  "ReverseProxy": {
    "Routes": {
      "default": {
        "ClusterId": "hello",
        "Match": { "Path": "{**catch-all}" }
      }
    },
    "Clusters": {
      "hello": {
        "Destinations": {
          "destination1": {
            "Address": "http://hello.api:8080"
          }
        }
      }
    }
  }
}

Nginx Setup

For Nginx, I went with Docker to keep things simple. The configuration does the same job as YARP:

nginx.proxy:
  image: nginx:alpine
  ports:
    - '3001:80'
  volumes:
    - ./nginx-proxy.conf:/etc/nginx/nginx.conf:ro
  depends_on:
    - hello.api

The Nginx config does exactly what YARP does - just with different syntax:

events {}

http {
    upstream backend {
        server hello.api:8080;
    }

    server {
        listen 80;
        location / {
            proxy_pass http://backend;
        }
    }
}

Full Docker Compose Setup

Here's the complete docker-compose.yml that ties everything together:

services:
  hello.api:
    image: ${DOCKER_REGISTRY-}helloapi
    build:
      context: .
      dockerfile: Hello.Api/Dockerfile

  yarp.proxy:
    image: ${DOCKER_REGISTRY-}yarpproxy
    build:
      context: .
      dockerfile: Yarp.Proxy/Dockerfile
    ports:
      - 3000:8080
    depends_on:
      - hello.api

  nginx.proxy:
    image: nginx:alpine
    ports:
      - '3001:80'
    volumes:
      - ./nginx-proxy.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - hello.api

Load Testing with k6

I used k6 to hit both proxies with the same load patterns. I repeated the test with different numbers of virtual users (VUs) to see how each proxy handles increasing traffic. This keeps things fair - same test, same conditions:

YARP Test Script:

import http from 'k6/http';
import { check } from 'k6';

export let options = {
  scenarios: {
    yarp: {
      executor: 'per-vu-iterations',
      vus: 200, // 10, 50, 100, 200
      iterations: 1000,
      exec: 'testYarp',
      startTime: '0s'
    }
  }
};

export function testYarp() {
  let res = http.get('http://localhost:3000/hello');
  check(res, {
    'YARP: status 200': (r) => r.status === 200
  });
}

Nginx Test Script:

import http from 'k6/http';
import { check } from 'k6';

export let options = {
  scenarios: {
    nginx: {
      executor: 'per-vu-iterations',
      vus: 200, // 10, 50, 100, 200
      iterations: 1000,
      exec: 'testNginx',
      startTime: '0s'
    }
  }
};

export function testNginx() {
  let res = http.get('http://localhost:3001/hello');
  check(res, {
    'NGINX: status 200': (r) => r.status === 200
  });
}

Performance Results

Here's where things get interesting. The numbers show a clear pattern:

| VUs  | YARP RPS | NGINX RPS | YARP p90 Latency (ms) | NGINX p90 Latency (ms) | YARP p95 Latency (ms) | NGINX p95 Latency (ms) |
|------|----------|-----------|-----------------------|------------------------|-----------------------|------------------------|
| 10   | 12692    | 9756      | 1.04                  | 1.10                   | 1.06                  | 1.52                   |
| 50   | 27080    | 10614     | 2.70                  | 5.23                   | 3.18                  | 5.68                   |
| 100  | 32432    | 10324     | 4.66                  | 10.61                  | 5.43                  | 10.96                  |
| 200  | 36662    | 10169     | 7.77                  | 21.23                  | 8.81                  | 21.92                  |

Request per second (RPS) is how many requests each proxy handled per second.

p90 latency is the time it took for 90% of requests to complete.

p95 latency is the time it took for 95% of requests to complete.

Throughput Analysis

YARP really shines here. It handles way more requests - almost 3.6x more at 200 users. What's cool is how it scales up as you add more load. Nginx stays pretty much flat around 10k requests per second, but YARP keeps climbing from 12k all the way to 36k.

Latency Comparison

The latency story is even more impressive for YARP. At 200 users, YARP keeps response times under 8ms while Nginx hits 21ms. That's a big difference when you're trying to keep your app fast.

Hold Up - That's Not Fair

Looking at these results, we're missing something important: this comparison isn't fair to Nginx.

The default Nginx configuration I used is fine for basic setups, but it's not optimized for high-throughput scenarios. Nginx uses conservative defaults that work everywhere but don't push performance limits.

So let me fix the Nginx configuration and re-run the tests.

Here's the updated Nginx config with some tweaks to improve performance:

worker_processes auto;

events {
    worker_connections 65536;
    multi_accept on;
    use epoll;
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 30;
    keepalive_requests 1000;
    types_hash_max_size 4096;

    upstream backend {
        server hello.api:8080;
        keepalive 512;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

Performance Results - After Tuning

Here are the results after re-running the tests:

| VUs  | YARP RPS | NGINX RPS | YARP p90 Latency (ms) | NGINX p90 Latency (ms) | YARP p95 Latency (ms) | NGINX p95 Latency (ms) |
|------|----------|-----------|-----------------------|------------------------|-----------------------|------------------------|
| 10   | 12692    | 17572     | 1.04                  | 0.58                   | 1.06                  | 0.74                   |
| 50   | 27080    | 36687     | 2.70                  | 1.81                   | 3.18                  | 2.09                   |
| 100  | 32432    | 43289     | 4.66                  | 3.18                   | 5.43                  | 3.88                   |
| 200  | 36662    | 46850     | 7.77                  | 6.34                   | 8.81                  | 7.72                   |

Throughput Analysis

Now this is more interesting. Nginx actually edges out YARP in raw throughput - hitting 46k requests per second vs YARP's 36k at 200 users. Both proxies scale well as load increases, but Nginx shows why it's been the go-to choice for high-traffic sites.

Latency Comparison

The latency story is pretty close. At lower loads, Nginx actually has better response times. At 200 users, both proxies keep response times reasonable - YARP at 7.77ms and Nginx at 6.34ms for p90 latency. The difference isn't huge either way.

Key Takeaways

Configuration matters more than you think. The initial results showed YARP crushing Nginx, but that was with Nginx's conservative defaults. Once properly tuned, Nginx shows why it's been powering the internet for years.

Nginx wins on raw performance. With proper configuration, Nginx handles more requests and keeps latency slightly lower. That extra throughput matters when you're dealing with serious traffic.

YARP offers better integration. Even though Nginx edges out performance, YARP feels natural in .NET projects. Same configuration style, same patterns, same tooling. Sometimes that developer experience is worth more than a few extra requests per second.

Always tune your tools. This whole exercise shows why benchmarks with default configs can be misleading. If you're choosing between these two, make sure you're comparing optimized configurations, not defaults.

The choice isn't as clear-cut as I initially thought. Nginx wins on pure performance, but YARP wins on .NET integration. Pick based on what matters more for your specific situation.

In this article, we'll walk through how to implement a lightweight, custom domain event dispatcher in .NET. The core dispatching logic should not depend on third-party libraries.

We'll cover:

• Why you might want to use publish-subscribe in your application
• How to define basic domain event abstractions
• How to implement and register handlers
• How to build a domain events dispatcher
• Trade-offs and when to consider other options

Let's get started.

Why Domain Events Matter

Before diving into implementation, let's understand the problem domain events solve. Consider this tightly coupled code:

public class UserService
{
    public async Task RegisterUser(string email, string password)
    {
        var user = new User(email, password);
        await _userRepository.SaveAsync(user);

        // Directly coupled to email service
        await _emailService.SendWelcomeEmail(user.Email);

        // Directly coupled to analytics
        await _analyticsService.TrackUserRegistration(user.Id);

        // What if we need to add more features?
        // This method will keep growing...
    }
}

With domain events, we can decouple this:

public class UserService
{
    public async Task RegisterUser(string email, string password)
    {
        var user = new User(email, password);
        await _userRepository.SaveAsync(user);

        // Publish event - let other parts of the system react
        await _domainEventsDispatcher.DispatchAsync(
            [new UserRegisteredDomainEvent(user.Id, user.Email)]);
    }
}

Now the UserService focuses solely on user registration, while other concerns are handled through event handlers.

Basic Abstractions

Let's start by defining two simple interfaces that form the foundation of our event system:

// Marker interface for all domain events.
public interface IDomainEvent
{
    // We could add common properties here like:
    // DateTime OccurredAt { get; }
    // Guid EventId { get; }
}

// Generic interface for handling domain events.
public interface IDomainEventHandler<in T> where T : IDomainEvent
{
    Task Handle(T domainEvent, CancellationToken cancellationToken = default);
}

This design gives us type safety through generic constraints while keeping publishers and handlers completely decoupled. You can add new events or handlers without touching existing code, and everything remains easily testable in isolation.

Implementing Sample Handlers

Let's add some sample handlers that demonstrate how different parts of your system can react to the same event:

// Handles sending welcome emails when users register
internal sealed class SendWelcomeEmailHandler(IEmailService emailService)
    : IDomainEventHandler<UserRegisteredDomainEvent>
{
    public async Task Handle(
        UserRegisteredDomainEvent domainEvent,
        CancellationToken cancellationToken = default)
    {
        // Send welcome email
        var welcomeEmail = new WelcomeEmail(domainEvent.Email, domainEvent.UserId);

        await emailService.SendAsync(welcomeEmail, cancellationToken);
    }
}

// Handles analytics tracking for new user registrations
internal sealed class TrackUserRegistrationHandler(IAnalyticsService analyticsService)
    : IDomainEventHandler<UserRegisteredDomainEvent>
{
    public async Task Handle(
        UserRegisteredDomainEvent domainEvent,
        CancellationToken cancellationToken = default)
    {
        // Track registration in analytics
        await analyticsService.TrackEvent(
            "user_registered",
            new
            {
                user_id = domainEvent.UserId,
                registration_date = domainEvent.RegisteredAt
            },
            cancellationToken);
    }
}

To make this work, we need to register our handlers with the DI container.

Here's how to do it manually:

// In your Program.cs or Startup.cs
services.AddScoped<IDomainEventHandler<UserRegisteredDomainEvent>, SendWelcomeEmailHandler>();
services.AddScoped<IDomainEventHandler<UserRegisteredDomainEvent>, TrackUserRegistrationHandler>();

Or you can automate this registration using assembly scanning with Scrutor:

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

The important thing is that multiple handlers can react to the same event.

The Dispatcher (Strongly Typed)

Now we need something to orchestrate calling the handlers. The dispatcher will take the domain events and call the appropriate handlers for each event.

public interface IDomainEventsDispatcher
{
    Task DispatchAsync(
        IEnumerable<IDomainEvent> domainEvents,
        CancellationToken cancellationToken = default);
}

internal sealed class DomainEventsDispatcher(IServiceProvider serviceProvider)
    : IDomainEventsDispatcher
{
    private static readonly ConcurrentDictionary<Type, Type> HandlerTypeDictionary = new();
    private static readonly ConcurrentDictionary<Type, Type> WrapperTypeDictionary = new();

    public async Task DispatchAsync(
        IEnumerable<IDomainEvent> domainEvents,
        CancellationToken cancellationToken = default)
    {
        foreach (IDomainEvent domainEvent in domainEvents)
        {
            using IServiceScope scope = serviceProvider.CreateScope();

            Type domainEventType = domainEvent.GetType();

            Type handlerType = HandlerTypeDictionary.GetOrAdd(
                domainEventType,
                et => typeof(IDomainEventHandler<>).MakeGenericType(et));

            IEnumerable<object?> handlers = scope.ServiceProvider.GetServices(handlerType);

            foreach (object? handler in handlers)
            {
                if (handler is null) continue;

                var handlerWrapper = HandlerWrapper.Create(handler, domainEventType);

                await handlerWrapper.Handle(domainEvent, cancellationToken);
            }
        }
    }

    // Abstract base class for strongly-typed handler wrappers
    private abstract class HandlerWrapper
    {
        public abstract Task Handle(IDomainEvent domainEvent, CancellationToken cancellationToken);

        public static HandlerWrapper Create(object handler, Type domainEventType)
        {
            Type wrapperType = WrapperTypeDictionary.GetOrAdd(
                domainEventType,
                et => typeof(HandlerWrapper<>).MakeGenericType(et));

            return (HandlerWrapper)Activator.CreateInstance(wrapperType, handler)!;
        }
    }

    // Generic wrapper that provides strong typing for handler invocation
    private sealed class HandlerWrapper<T>(object handler) : HandlerWrapper where T : IDomainEvent
    {
        private readonly IDomainEventHandler<T> _handler = (IDomainEventHandler<T>)handler;

        public override async Task Handle(
            IDomainEvent domainEvent,
            CancellationToken cancellationToken)
        {
            await _handler.Handle((T)domainEvent, cancellationToken);
        }
    }
}

The dispatcher uses a wrapper to eliminate reflection during handler execution while maintaining type safety. When we encounter a UserRegisteredDomainEvent, we create a HandlerWrapper<UserRegisteredDomainEvent> that holds a strongly-typed reference to IDomainEventHandler<UserRegisteredDomainEvent>. The wrapper casts the generic IDomainEvent to the specific event type at runtime, but the actual handler invocation uses compile-time types.

This gives us the performance benefits of avoiding reflection in the hot path (handler execution) while only using reflection once during wrapper creation. The trade-off is additional complexity, but the performance gain is significant if you're dispatching many events.

Don't forget to register the dispatcher with DI:

services.AddTransient<IDomainEventsDispatcher, DomainEventsDispatcher>();

Usage Example

Here's how to use the domain events dispatcher in your application:

public class UserController(
    IUserService userService,
    IDomainEventsDispatcher domainEventsDispatcher) : ControllerBase
{
    [HttpPost("register")]
    public async Task<IActionResult> Register([FromBody] RegisterUserRequest request)
    {
        try
        {
            // Create the user
            var user = await userService.CreateUserAsync(request.Email, request.Password);

            // Publish the domain event
            var userRegisteredEvent = new UserRegisteredDomainEvent(user.Id, user.Email);

            await domainEventsDispatcher.DispatchAsync([userRegisteredEvent]);

            return Ok(new { UserId = user.Id, Message = "User registered successfully" });
        }
        catch (Exception ex)
        {
            return BadRequest(new { Error = ex.Message });
        }
    }
}

You could also integrate domain events directly into your domain entities.

Limitations and Tradeoffs

This implementation runs entirely in-process, which has important implications. All handlers execute synchronously within the same request context, but each gets its own DI scope. This means:

• Immediate feedback: If any handler fails, the exception bubbles up to the caller immediately. No silent failures or eventual consistency surprises.

• Caller control: The code that dispatches events decides how to handle failures — rollback transactions, retry operations, or continue despite errors. The dispatcher doesn't make these decisions for you.

• Reliability concerns: If the process crashes after some handlers succeed but before others complete, there's no automatic recovery. Events aren't persisted or retried.

For critical side effects that can't be lost, consider the Outbox pattern. Instead of dispatching events immediately, store them alongside your business data in the same transaction. A background service can later retry failed events, ensuring nothing gets lost. This decouples reliability from performance — your main operation completes quickly while events are processed reliably in the background.

Wrapping Up

Domain events are a powerful pattern for decoupling business logic, and you don't need a heavyweight framework to use them effectively. The implementation we've built here provides a solid foundation that you can extend as your needs grow.

The beauty of rolling your own solution is that you understand every piece, making debugging and customization straightforward. This pattern fits excellently in Domain-Driven Design and Clean Architecture systems where decoupling business logic is crucial.

For systems requiring bulletproof reliability or cross-service communication, invest in proper message infrastructure. But for many applications, this simple approach hits the sweet spot between coupling and complexity.

The key insight is understanding your trade-offs upfront rather than discovering them in production. Start simple, measure what matters, and evolve based on real requirements.

Jimmy Bogard recently announced that MediatR will adopt a commercial license model for companies above a certain size.

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

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

By removing MediatR, you gain:

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

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

We'll cover:

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

Let's get started.

Commands, Queries, and Handlers

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

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

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

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

The handler interfaces follow the same model:

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

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

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

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

You'll notice we're using a Result wrapper for all return types. This is optional, but it promotes explicit success/failure handling and encourages consistency across the application boundary. You can learn more about it in my previous article.

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

Practical Example: Command Handler

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

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

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

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

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

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

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

        await context.SaveChangesAsync(cancellationToken);

        return Result.Success();
    }
}

A few important things to note:

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

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

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

Decorators

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

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

using Serilog.Context;

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

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

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

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

        return result;
    }
}

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

Now a validation example with FluentValidation:

using FluentValidation;
using FluentValidation.Results;

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

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

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

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

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

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

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

        return validationFailures;
    }

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

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

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

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

DI Setup

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

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

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

Next, we apply decorators for validation and logging:

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

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

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

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

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

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

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

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

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

Usage from Minimal API

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

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

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

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

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

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

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

Conclusion

CQRS doesn't require a complex framework.

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

If you want to see this pattern applied in a complete solution, my free Clean Architecture template includes everything covered in this article (fully wired up).

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

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

In this article, we'll:

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

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

Starting Point: God-like Service Class

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

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

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

    var order = new Order { CustomerId = customerId };

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

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

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

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

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

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

What's Wrong Here?

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

Guiding Principles Before We Touch Code

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

Step-by-Step Refactor

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

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

Embed Creation & Validation Logic

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

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

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

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

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

    order.EnsureCreditWithinLimit(customer);

    return order;
}

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

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

💡 On Injecting Services into Domain Methods

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

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

Guard the Aggregate's Internal State

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

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

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

    RecalculateTotal();
}

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

Why bother?

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

Shrink the Application Layer to Pure Orchestration

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

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

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

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

What We Gained

Before the refactor

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

After the refactor

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

Wrapping Up

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

By moving business logic closer to the data, you:

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

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

That's how legacy systems evolve into maintainable architectures.

If you enjoyed this breakdown and want a hands-on, real-world guide to untangling messy services, check out my course Pragmatic Domain-Driven Design. It's packed with before-and-after examples like this one.

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

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

RabbitMQ Basics

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

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

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

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

Producer - Sending Events

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

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

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

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

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

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

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

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

What's happening here:

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

Now let's look at the consumer side.

Consumer - Receiving Events

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

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

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

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

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

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

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

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

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

What's important here:

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

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

Competing Consumers - Scaling Out

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

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

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

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

Fanout Exchange: Broadcast to Multiple Consumers

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

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

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

Producer:

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

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

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

Consumer:

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

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

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

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

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

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

Next Steps

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

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

Good luck out there, and see you next week.

This article is about tackling that mess. We'll walk through how to identify an overgrown bounded context, and refactor it step-by-step into smaller, well-defined contexts. You'll see practical techniques in action, with real .NET code and without theoretical fluff.

Identifying an Overgrown Context

You know you have a problem when:

• You're afraid to touch code because everything is interconnected
• The same entity is used for 4 unrelated use cases
• You see classes with 1000+ lines or services that do too much
• Business logic from different subdomains bleeds into each other

Here's a classic example.

We start with a BillingContext that now handles everything from notifications to reporting:

public class BillingService
{
    public void ChargeCustomer(int customerId, decimal amount) { ... }
    public void SendInvoice(int invoiceId) { ... }
    public void NotifyCustomer(int customerId, string message) { ... }
    public void GenerateMonthlyReport() { ... }
    public void DeactivateUserAccount(int userId) { ... }
}

This service has no clear boundaries. It mixes Billing, Notifications, Reporting, and User Management into a single, bloated class. Changing one feature could easily break another.

Step 1: Identify Logical Subdomains

We start by breaking this apart logically. Think like a product owner.

Just ask: "What domains are we really working with?"

Group the methods:

• Billing: ChargeCustomer, SendInvoice
• Notifications: NotifyCustomer
• Reporting: GenerateMonthlyReport
• User Management: DeactivateUserAccount

Code within a bounded context should model a coherent domain. When multiple domains are jammed into the same context, your architecture becomes misleading.

You can validate these groupings by checking:

• Which parts of the system change together?
• Do teams use different vocabulary for each area?
• Would you give each domain to a different team?

If yes, it's a sign you're dealing with distinct contexts.

Step 2: Extract One Context at a Time

Don't try to do it all at once. Start with something low-risk.

Let's begin by extracting Notifications.

Why Notifications? Because it's a pure side-effect. It doesn't impact business state, so it's easier to decouple safely.

Create a new module and move the logic there:

// New module: Notifications
public class NotificationService
{
    public void Send(int customerId, string message) { ... }
}

Then simplify the original BillingService:

public class BillingService
{
    private readonly NotificationService _notificationService;

    public BillingService(NotificationService notificationService)
    {
        _notificationService = notificationService;
    }

    public void ChargeCustomer(int customerId, decimal amount)
    {
        // Charge logic...
        _notificationService.Send(customerId, $"You were charged ${amount}");
    }
}

This works. But now Billing depends on Notifications. That's a coupling we want to avoid long-term.

Why? Because a failure in Notifications could block a billing operation. It also means Billing can't evolve independently.

Let's decouple with domain events:

public class CustomerChargedEvent
{
    public int CustomerId { get; init; }
    public decimal Amount { get; init; }
}

// Module: Billing
public class BillingService
{
    private readonly IDomainEventDispatcher _dispatcher;

    public BillingService(IDomainEventDispatcher dispatcher)
    {
        _dispatcher = dispatcher;
    }

    public void ChargeCustomer(int customerId, decimal amount)
    {
        // Charge logic...
        _dispatcher.Dispatch(new CustomerChargedEvent
        {
            CustomerId = customerId,
            Amount = amount
        });
    }
}

// Module: Notifications
public class CustomerChargedEventnHandler : IDomainEventHandler<CustomerChargedEvent>
{
    public Task Handle(CustomerChargedEvent @event)
    {
        // Send notification
    }
}

Now Billing doesn't even know about Notifications. That's real modularity. You can replace, remove, or enhance the Notifications module without touching Billing.

Step 3: Migrate Data (If Needed)

Most monoliths start with a single database. That's fine. But real modularity comes when each module controls its own schema.

Why? Because the database structure reflects ownership. If everything touches the same tables, it's hard to enforce boundaries.

You don't have to do it all at once. Start with:

• Creating a separate DbContext per module
• Gradually migrate the tables to their own schemas
• Read-only projections or database views for cross-context reads

// Module: Billing
public class BillingDbContext : DbContext
{
    public DbSet<Invoice> Invoices { get; set; }
}

// Module: Notifications
public class NotificationsDbContext : DbContext
{
    public DbSet<NotificationLog> Logs { get; set; }
}

This separation enables independent schema evolution. It also makes testing faster and safer.

When migrating, use a transitional phase where both contexts read from the same underlying data. Only switch write paths when confidence is high.

Step 4: Repeat for Other Areas

Apply the same playbook. Target a clean split per subdomain.

Next up: Reporting and User Management.

Before:

billingService.GenerateMonthlyReport();
billingService.DeactivateUserAccount(userId);

After:

reportingService.GenerateMonthlyReport();
userService.DeactivateUser(userId);

Or via events:

_dispatcher.Dispatch(new MonthEndedEvent());
_dispatcher.Dispatch(new UserInactiveEvent(userId));

The goal here isn't just technical cleanliness - it's clarity. Anyone looking at your solution should know what each module is responsible for.

And remember: boundaries should be enforced by code, not just by folder structure. Different projects, separate EF models, and explicit interfaces help enforce the split. Architecture tests can also help ensure that modules don't break their boundaries.

Takeaway

Once you've finished the refactor, you'll have:

• Smaller services focused on one job
• Decoupled modules that evolve independently
• Better tests and easier debugging
• Bounded contexts that actually match the domain

This is more than structure, it's design that supports change. You get loose coupling, testability, and clearer mental models.

You don't need microservices to get modularity. You need to treat your monolith like a set of cooperating, isolated parts.

Start with one module. Ship the change. Repeat.

Want to go deeper into modular monolith design? My full video course, Modular Monolith Architecture, walks you through building a real-world system from scratch - with clear boundaries, isolated modules, and practical patterns that scale. Join 1,800+ students and start building better systems today.

That's all for today.

See you next Saturday.

As someone who's implemented microservices in various organizations, I wanted to share some valuable insights I've gained through both study and practical experience.

What exactly are microservices, and why might they be the right architectural choice for your organization?

Let's dive into the core concepts and benefits of microservices architecture.

What Are Microservices?

Microservices are independently deployable services modeled around a business domain. Business domain is key here, but more on that later. They communicate with each other via networks and offer many options for solving complex architectural problems.

Think of microservices as small, focused teams rather than a large department. Each team has a specific responsibility, operates somewhat independently, and communicates clearly with other teams when needed. Instead of one massive codebase that handles everything, you have multiple smaller codebases, each focusing on a specific business capability.