DEV Community: Adrián Bailador

Uncle Bob's Agent Pipeline: From Informal Specs to Mutation-Tested .NET Code

Adrián Bailador — Sun, 07 Jun 2026 12:35:21 +0000

Robert C. Martin recently described an agent pipeline on X that cuts against the grain of how most developers use AI today. Instead of a single all-knowing agent that takes a vague request and produces code, his system is a sequence of disciplined transformations — each stage more formal than the last, each requiring less human oversight than the one before.

The goal is a codebase where the specifications are precise, the tests are meaningful, the complexity is controlled, and every line of production code is verified by mutation. Not because an agent promised it was correct, but because the system structurally cannot produce anything else.

Raw compute is the bottleneck, not intelligence. The mutation passes are CPU-intensive by design.

The Pipeline at a Glance

It is a transformation pipeline from the informal to the formal. Human interaction is heaviest at the beginning — you review the hard specs and spot-check the Gherkin. By the time the Architect runs mutation tests, the system runs unattended. Your job is to review the output at the end, not supervise every step.

Stage 1: You Write Informal Specs

This is the only stage that requires you. You write requirements the way you actually think — incomplete, conversational, ambiguous in places. A paragraph. A list of bullet points. A few handwritten notes.

We need a discount system for the product catalogue.
Products can have one active discount at a time.
Discounts can be percentage-based or fixed amount.
They expire after a configurable number of days.
No discount can reduce a price below zero.

The quality of everything downstream depends on the quality of this input — but you don't need to formalise it yourself. That's the Specifier's job.

Stage 2: Specifier Agent — Informal to Hard Specs

The Specifier converts your free text into structured, unambiguous specifications and breaks them into discrete tasks. You review this output.

Input: your informal notes

Output: a numbered task list with precise acceptance criteria

You: review and correct before anything moves forward

For the discount example, the Specifier might produce:

Task 1: ProductDiscount value object
  - Represents either a PercentageDiscount (0–100) or FixedAmountDiscount (> 0)
  - Invalid values are rejected at construction
  - PercentageDiscount cannot exceed 100
  - FixedAmountDiscount must be positive

Task 2: Apply discount to a product
  - A product may hold at most one active discount
  - Applying a second discount replaces the first
  - The discounted price = base price minus discount amount
  - The discounted price is never below 0.00

Task 3: Discount expiry
  - A discount has a configurable expiry duration in days
  - An expired discount is treated as absent
  - Retrieving the effective price checks for expiry at call time

This is where you invest the most attention. A wrong task here propagates through every downstream stage. The Specifier saves you the work of formalisation; you provide the judgment that the machine cannot.

Stage 3: Specifier Agent — Tasks to Gherkin

The Specifier takes each approved task and produces Gherkin feature files: Given / When / Then scenarios in plain language, one file per task. It also prunes Gherkin — removes redundant, overlapping, or impossible scenarios. You spot-check.

Input: approved task list

Output: .feature files, one per task

You: spot-check for missing scenarios, wrong edge cases

discount-value-object.feature:

Feature: ProductDiscount value object

  Scenario: Create a valid percentage discount
    Given a percentage discount of 20
    When the discount is created
    Then the discount type is Percentage
    And the value is 20

  Scenario: Reject a percentage discount above 100
    Given a percentage discount of 101
    When the discount is created
    Then a domain exception is thrown

  Scenario: Reject a fixed amount discount of zero
    Given a fixed amount discount of 0.00
    When the discount is created
    Then a domain exception is thrown

  Scenario: Create a valid fixed amount discount
    Given a fixed amount discount of 15.00
    When the discount is created
    Then the discount type is FixedAmount
    And the value is 15.00

apply-discount.feature:

Feature: Apply discount to a product

  Scenario: Apply a percentage discount
    Given a product with a base price of 100.00
    And a percentage discount of 20
    When the discount is applied
    Then the effective price is 80.00

  Scenario: Price cannot go below zero
    Given a product with a base price of 10.00
    And a fixed amount discount of 50.00
    When the discount is applied
    Then the effective price is 0.00

  Scenario: Applying a second discount replaces the first
    Given a product with an active 10% discount
    When a 25% discount is applied
    Then the active discount is 25%
    And the previous discount is no longer active

In .NET you run Gherkin through Reqnroll (the open-source successor to SpecFlow). Add the package to your test project:

dotnet add package Reqnroll.xUnit
dotnet add package Reqnroll

Stage 4: Coder Agent — Acceptance Tests, Unit Tests, Code

The Coder never sees your informal notes. It sees only the Gherkin. This is the constraint that makes the pipeline trustworthy: the Coder cannot fill gaps from context it was never given. If the Gherkin is ambiguous, the Coder asks for clarification rather than guessing.

The sequence within this stage is fixed:

1 — Acceptance tests from Gherkin

The Coder writes Reqnroll step definitions that bind to each scenario. At this point they are empty method bodies — the bindings exist but the assertions are pending.

[Binding]
public class ProductDiscountSteps
{
    private ProductDiscount? _discount;
    private Exception? _thrownException;

    [Given(@"a percentage discount of (.*)")]
    public void GivenAPercentageDiscountOf(decimal value)
    {
        try { _discount = ProductDiscount.Percentage(value); }
        catch (Exception ex) { _thrownException = ex; }
    }

    [Then(@"a domain exception is thrown")]
    public void ThenADomainExceptionIsThrown() =>
        _thrownException.Should().BeOfType<DomainException>();

    [Then(@"the discount type is Percentage")]
    public void ThenTheDiscountTypeIsPercentage() =>
        _discount!.Type.Should().Be(DiscountType.Percentage);
}

2 — Unit tests

With the acceptance boundaries defined, the Coder writes unit tests that cover internal logic the Gherkin doesn't reach: private calculations, boundary conditions, internal state transitions.

public class ProductDiscountTests
{
    [Theory]
    [InlineData(-1)]
    [InlineData(101)]
    public void Percentage_OutOfRange_ThrowsDomainException(decimal value) =>
        FluentActions.Invoking(() => ProductDiscount.Percentage(value))
            .Should().Throw<DomainException>();

    [Fact]
    public void FixedAmount_Zero_ThrowsDomainException() =>
        FluentActions.Invoking(() => ProductDiscount.FixedAmount(0))
            .Should().Throw<DomainException>();
}

3 — Implementation

Only now does the Coder write production code. The acceptance tests and unit tests are already defined — they all fail. The Coder writes the minimum code to make them pass.

public sealed record ProductDiscount
{
    public DiscountType Type { get; }
    public decimal Value { get; }

    private ProductDiscount(DiscountType type, decimal value)
    {
        Type = type;
        Value = value;
    }

    public static ProductDiscount Percentage(decimal value)
    {
        if (value <= 0 || value > 100)
            throw new DomainException($"Percentage discount must be between 1 and 100. Got: {value}");
        return new(DiscountType.Percentage, value);
    }

    public static ProductDiscount FixedAmount(decimal value)
    {
        if (value <= 0)
            throw new DomainException($"Fixed amount discount must be positive. Got: {value}");
        return new(DiscountType.FixedAmount, value);
    }
}

The Coder hands off only when dotnet test runs green — every acceptance test, every unit test.

Stage 5: Refactorer Agent — Complexity, Duplication, Property Tests

The Refactorer has no knowledge of the original requirements. It works only with the code and the tests. Its mandate is structural quality, not correctness.

Task 1: Reduce cyclomatic complexity to 6 or below.

Uncle Bob uses the term "crap" (Change Risk Anti-Patterns) — a metric that combines complexity with test coverage. The Refactorer identifies methods where complexity is above the threshold and refactors until each method is clean.

In .NET you can enforce this with Roslyn analysers or with a dedicated tool:

dotnet tool install -g dotnet-crap
dotnet crap --threshold 6

A method like this:

// complexity: 8
public decimal CalculateEffectivePrice(decimal basePrice, ProductDiscount? discount, DateTime now)
{
    if (discount is null) return basePrice;
    if (discount.ExpiresAt.HasValue && discount.ExpiresAt.Value < now) return basePrice;

    decimal amount = discount.Type switch
    {
        DiscountType.Percentage => basePrice * discount.Value / 100,
        DiscountType.FixedAmount => discount.Value,
        _ => throw new ArgumentOutOfRangeException()
    };

    decimal result = basePrice - amount;
    return result < 0 ? 0 : result;
}

becomes two methods, each under the threshold:

// complexity: 3
public decimal CalculateEffectivePrice(decimal basePrice, ProductDiscount? discount, DateTime now)
{
    if (!IsDiscountActive(discount, now)) return basePrice;
    return ApplyDiscount(basePrice, discount!);
}

// complexity: 3
private static bool IsDiscountActive(ProductDiscount? discount, DateTime now) =>
    discount is not null &&
    (!discount.ExpiresAt.HasValue || discount.ExpiresAt.Value >= now);

// complexity: 3
private static decimal ApplyDiscount(decimal basePrice, ProductDiscount discount)
{
    var amount = discount.Type == DiscountType.Percentage
        ? basePrice * discount.Value / 100
        : discount.Value;
    return Math.Max(0, basePrice - amount);
}

Task 2: Remove duplication.

The Refactorer identifies and eliminates structural duplication — not just copy-paste, but patterns repeated across the codebase that should live in a single location.

Task 3: Property tests.

After the code is clean, the Refactorer adds property-based tests. Where unit tests verify specific examples, property tests verify invariants across arbitrary inputs.

Install FsCheck for .NET:

dotnet add package FsCheck.Xunit

public class ProductDiscountPropertyTests
{
    [Property]
    public bool EffectivePrice_IsNeverNegative(decimal basePrice, decimal discountAmount)
    {
        if (basePrice < 0 || discountAmount <= 0) return true; // precondition

        var discount = ProductDiscount.FixedAmount(discountAmount);
        var product = Product.Create("Test", Math.Abs(basePrice));
        product.ApplyDiscount(discount);

        return product.EffectivePrice(DateTime.UtcNow) >= 0;
    }

    [Property]
    public bool PercentageDiscount_NeverExceedsBasePrice(PositiveDecimal basePrice)
    {
        var discount = ProductDiscount.Percentage(Arb.Generate<decimal>()
            .Where(v => v > 0 && v <= 100).Sample(0, 1).Head);
        var product = Product.Create("Test", basePrice.Get);
        product.ApplyDiscount(discount);

        return product.EffectivePrice(DateTime.UtcNow) <= basePrice.Get;
    }
}

Property tests pass when all the acceptance tests still pass on top of them.

Stage 6: Architect Agent — Mutation Testing

This is the stage that cannot be rushed. The Architect runs mutation testing — it deliberately introduces small errors into the production code and verifies that the test suite catches every one of them. This pass is CPU-intensive. It runs unattended.

There are two mutation passes.

Language Mutation

Stryker.NET mutates the C# source: flips > to >=, changes + to -, inverts boolean conditions, removes method calls. For each mutant it runs the full test suite. A mutant that survives — that passes the tests despite the introduced defect — indicates a gap in coverage.

dotnet tool install -g dotnet-stryker
dotnet stryker --project Domain/Domain.csproj --mutation-level Complete

The Architect covers any uncovered lines and kills all surviving mutants. When a mutant survives, the Architect writes the test that kills it — not arbitrarily, but by understanding what the surviving mutation implies about the missing behaviour.

A survivor like return result < 0 ? 0 : result → return result means no test verified that prices are floored at zero. The Architect writes exactly that test.

Gherkin Mutation

With the code mutation clean, the Architect mutates the Gherkin scenarios themselves. It modifies values in Given and Then steps, removes scenarios, inverts conditions. For each mutation it re-runs the acceptance test suite.

A Gherkin mutation that survives means a scenario exists that no test actually exercises — either the step bindings are wrong, or the scenario was never wired to the implementation.

# Gherkin mutation via a custom Stryker plugin or purpose-built tooling
dotnet stryker --gherkin-mutation --feature-files tests/Features/**/*.feature

Full Suite

When both mutation passes are clean, the Architect runs the complete test suite — unit tests, acceptance tests, property tests — one final time. When it passes, the result is handed back to the Specifier, Coder, and Refactorer for the next task.

dotnet test --logger "trx;LogFileName=results.trx" /p:CollectCoverage=true

Human Interaction Across the Pipeline

This is the design principle that separates this system from ordinary agent-assisted coding.

Stage	You do
Informal specs	Write them
Hard specs + tasks	Review and correct
Gherkin	Spot-check
Coder output	Nothing — it runs to completion
Refactorer output	Nothing — it runs to completion
Architect output	Spot-check the final code

You are heaviest at the front, where judgment matters most: deciding what the system should do and whether the specification captures it correctly. You are absent at the back, where mechanical verification takes over.

The consequence is that your time scales independently of the codebase. The CPU-intensive mutation passes run without you. You review the Gherkin for five minutes and return when the Architect is done.

The Shape of the Problem

The pipeline is a formalisation engine. Informal language is ambiguous by nature — words have multiple meanings, context is implicit, edge cases are invisible. Each transformation stage removes a layer of ambiguity:

Informal → hard specs: removes vagueness
Hard specs → Gherkin: removes implicit context
Gherkin → acceptance tests: removes implementation assumptions
Acceptance tests → unit tests: removes untested internals
Mutation tests: removes false confidence

By the time the Architect hands the result back, the code has been verified at every layer. The tests are not there because an agent generated them. They are there because the pipeline structurally could not advance without them.

Raw compute is the price of that guarantee. A mutation suite on a non-trivial domain can take minutes on a single machine. That is an acceptable trade for code you can trust without re-reading every line yourself.

Based on a description by Robert C. Martin (@unclebobmartin)

Full source code — the discount domain built exactly as the pipeline would produce it, with acceptance tests, unit tests, property tests and a Stryker mutation config: github.com/AdrianBailador/agent-pipeline-dotnet

Questions or suggestions? Open an issue on GitHub.

HybridCache in .NET 9: One Caching API, Stampede Protection Included

Adrián Bailador — Tue, 02 Jun 2026 19:37:54 +0000

A product page gets 50,000 requests a minute. Behind it sits a database query that takes 200ms. You add IMemoryCache — one line — and latency drops to nothing. Ship it.

Then traffic grows and you scale to three servers behind a load balancer. The cache hit rate quietly collapses. Each server keeps its own copy, each misses independently, and your database is taking three times the load you thought you'd eliminated. So you reach for IDistributedCache and Redis — and now every cache read is a network round-trip, you're writing serialization code by hand, and the day a popular entry expires, a thousand concurrent requests all miss at the same millisecond and stampede your database into the ground.

Neither cache is wrong. They solve different halves of the same problem. The gap between them is exactly where HybridCache lives.

Introduced in .NET 9, HybridCache is a single API that sits on top of both: a fast in-process layer backed by a shared distributed layer, with stampede protection and serialization handled for you. This article is how to use it without the footguns.

The Two Problems It Solves

Before the new API, you picked one of two tools, each with a known weakness.

IMemoryCache is per-process. It's extremely fast — objects live in the heap, no serialization, no network. But each server instance has its own copy. With three instances you have three independent caches, three independent miss rates, and no way to invalidate an entry across all of them. It also doesn't survive a restart.

IDistributedCache is shared but raw. Redis (or SQL Server, or Postgres) gives every instance the same view, surviving restarts and scaling horizontally. The cost: every read crosses the network, you serialize and deserialize byte[] yourself, and — critically — there's no stampede protection. The classic boilerplate looks like this:

public async Task<Product?> GetProductAsync(int id, CancellationToken ct)
{
    var key = $"product:{id}";
    var cached = await _distributedCache.GetAsync(key, ct);

    if (cached is not null)
        return JsonSerializer.Deserialize<Product>(cached);

    // Cache miss. So does every other concurrent request right now.
    var product = await _db.Products.FindAsync([id], ct);
    if (product is null) return null;

    var bytes = JsonSerializer.SerializeToUtf8Bytes(product);
    await _distributedCache.SetAsync(key, bytes,
        new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5) }, ct);

    return product;
}

It works. But every retrieval deserializes, you maintain the serialization yourself, and the "cache miss" branch has no coordination — when the entry expires under load, every concurrent caller runs the database query, serializes the result, and writes it back. That's a cache stampede, and it's the failure mode that takes a service down at exactly the moment it's busiest.

What HybridCache Actually Is

HybridCache is a unified abstraction over both layers:

Two-level caching (L1 + L2). L1 is in-process memory — fast, no serialization. L2 is your configured IDistributedCache (Redis, SQL Server, Postgres). A read checks L1, then L2, then the source. A computed value is written to both.
Stampede protection. For a given key, only one concurrent caller runs the factory. Everyone else waits for that single result. The thundering herd becomes one query.
Serialization handled for you. string and byte[] are handled internally; everything else uses System.Text.Json by default, swappable for protobuf, XML, or anything else.
Tag-based invalidation. Group related entries under tags and invalidate them as a unit.

The most important detail up front: L2 is optional. With no IDistributedCache registered, HybridCache still gives you in-memory caching and stampede protection. That alone makes it a better default than raw IMemoryCache even on a single server.

Step 1: Setup

Install the package:

dotnet add package Microsoft.Extensions.Caching.Hybrid

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHybridCache();

var app = builder.Build();

That's the minimum. You can configure global defaults and limits at registration:

builder.Services.AddHybridCache(options =>
{
    options.MaximumPayloadBytes = 1024 * 1024; // 1 MB — entries larger than this are not cached
    options.MaximumKeyLength = 1024;            // longer keys bypass the cache instead of saturating it

    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(5),       // L2 lifetime
        LocalCacheExpiration = TimeSpan.FromMinutes(2) // L1 lifetime
    };
});

MaximumPayloadBytes and MaximumKeyLength are guardrails, not suggestions. An oversized payload is logged and not stored — it won't throw, it just silently won't cache, which is a behaviour worth knowing before you debug a "why isn't this cached?" mystery in production.

Step 2: Basic Usage

The whole API mostly reduces to one method: GetOrCreateAsync. It takes a key and a factory; if the key isn't cached, it runs the factory, stores the result, and returns it.

public class ProductService(HybridCache cache, AppDbContext db)
{
    public async Task<Product?> GetProductAsync(int id, CancellationToken ct = default)
    {
        return await cache.GetOrCreateAsync(
            $"product:{id}", // unique key
            async token => await db.Products.FindAsync([id], token),
            cancellationToken: ct);
    }
}

Compare that to the IDistributedCache block earlier. No manual serialization, no miss branch, no SetAsync. The factory runs only on a genuine miss, and only once per key even under concurrent load.

A note on keys, straight from the design guidance: build them with interpolation inline in the call ($"product:{id}"), use a delimiter to avoid ambiguity (order:42:123, not order42123, which collides with order:421:23), and never put raw user input directly into a key. Untrusted keys are a denial-of-service vector — an attacker floods the cache with junk keys and evicts everything that matters.

Step 3: Entry Options — Two Expirations, Not One

This is the part people get wrong. HybridCacheEntryOptions has two separate expirations because there are two tiers:

var options = new HybridCacheEntryOptions
{
    Expiration = TimeSpan.FromMinutes(30),         // how long it lives in L2 (distributed)
    LocalCacheExpiration = TimeSpan.FromMinutes(5) // how long it lives in L1 (this server)
};

return await cache.GetOrCreateAsync(
    $"product:{id}",
    async token => await db.Products.FindAsync([id], token),
    options,
    cancellationToken: ct);

LocalCacheExpiration should usually be shorter than Expiration. The reasoning: L1 is per-server and can't be invalidated from another server (more on that below), so you want it to refresh from the shared L2 layer relatively often. A 5-minute L1 over a 30-minute L2 means each server trusts its local copy for 5 minutes, then re-checks the shared truth — bounding how stale any single instance can get without paying the database cost on every request.

Set both too long and a stale value sticks around per-server. Set L1 to zero and you've thrown away the fast path. The sweet spot is "L1 short enough that staleness is acceptable, L2 long enough that the source is rarely hit."

Step 4: Stampede Protection, the Headline Feature

This is the reason to adopt HybridCache even if you never touch a distributed cache.

Imagine a hot key expires while 500 requests per second are hitting it. With raw IMemoryCache or IDistributedCache, all 500 requests in that window see a miss, all 500 run the factory (the database query), and all 500 write the result back. Your database gets 500 identical expensive queries in a burst.

HybridCache collapses that: for a given key, exactly one caller executes the factory. The other 499 await the same in-flight operation and receive its result. One database query, not 500.

// 500 concurrent callers, same key, entry just expired.
// HybridCache runs the factory ONCE. The rest wait for it.
var product = await cache.GetOrCreateAsync(
    $"product:{id}",
    async token =>
    {
        // This body executes once, no matter how many callers raced in.
        return await db.Products.FindAsync([id], token);
    },
    cancellationToken: ct);

One subtlety: the CancellationToken your factory receives is the combined cancellation of all the callers waiting on that key. The factory is only cancelled if every waiting caller has cancelled. A single caller giving up doesn't abort the work that the other 499 still need — which is exactly the behaviour you want.

Step 5: Adding the Distributed Layer (L2)

Everything above works in-memory with zero extra setup. To make the cache shared across servers, register an IDistributedCache — HybridCache picks it up automatically as L2. With Redis:

dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
});

builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(30),
        LocalCacheExpiration = TimeSpan.FromMinutes(5)
    };
});

No changes to your GetProductAsync code. The exact same GetOrCreateAsync call now reads L1 → L2 → source and writes through both tiers. That's the real win of the abstraction: you develop against in-memory caching and add Redis later by registering one service, with no churn in the call sites.

Step 6: Invalidation — By Key and By Tag

When the underlying data changes, you evict explicitly. By key:

public async Task UpdateProductAsync(Product product, CancellationToken ct = default)
{
    db.Products.Update(product);
    await db.SaveChangesAsync(ct);

    // Removes from BOTH L1 (this server) and L2 (shared).
    await cache.RemoveAsync($"product:{product.Id}", ct);
}

Tags let you invalidate a group of entries at once. You attach tags when caching, then evict by tag:

public async Task<Product?> GetProductAsync(int id, int categoryId, CancellationToken ct = default)
{
    var tags = new[] { "products", $"category:{categoryId}" };

    return await cache.GetOrCreateAsync(
        $"product:{id}",
        async token => await db.Products.FindAsync([id], token),
        new HybridCacheEntryOptions { Expiration = TimeSpan.FromMinutes(30) },
        tags,
        cancellationToken: ct);
}

// Invalidate every product in a category in one call:
await cache.RemoveByTagAsync($"category:{categoryId}", ct);

// Or wipe everything (the reserved wildcard):
await cache.RemoveByTagAsync("*", ct);

Here's the crucial mental model, and it surprises people: tag invalidation is logical, not physical. Neither IMemoryCache nor IDistributedCache understands tags, so RemoveByTagAsync doesn't go and delete entries. It records that anything carrying that tag should now be treated as a miss. The bytes still sit in Redis and in memory until they expire naturally — but the next read for a tagged key sees a miss and re-runs the factory. Functionally it behaves like a delete; operationally nothing is actively purged. Don't expect your Redis memory usage to drop the instant you call it.

Step 7: Serialization

For L2, values must be serialized. string and byte[] are handled internally; everything else is System.Text.Json by default. For most apps that's all you need. When you want something faster or more compact — protobuf, say — register a serializer, chained off AddHybridCache:

// Type-specific serializer
builder.Services.AddHybridCache()
    .AddSerializer<ProductDto, ProductProtobufSerializer>();

// Or a general-purpose factory that handles many types
builder.Services.AddHybridCache()
    .AddSerializerFactory<ProtobufSerializerFactory>();

The serializer only matters for the distributed tier — L1 stores live objects. Which leads to the one performance nuance worth understanding.

Performance: Object Reuse

By default, HybridCache deserializes a fresh instance for each caller, mirroring how IDistributedCache behaved. That's the safe default: separate instances can't accidentally share mutable state across concurrent callers.

But if your cached type is genuinely immutable, that per-call deserialization is pure waste. You can tell HybridCache it's safe to hand out the same instance by doing two things: mark the type sealed, and apply [ImmutableObject(true)].

using System.ComponentModel; // ImmutableObjectAttribute lives here

[ImmutableObject(true)]
public sealed record ProductDto(int Id, string Name, decimal Price);

Now HybridCache can skip the per-call copy and reuse one instance, cutting CPU and allocations for hot, large objects. This only works because you've promised the object is never mutated — break that promise and you've reintroduced a shared-mutable-state bug across concurrent requests. Use it for DTOs and value objects, not for anything you mutate after caching.

For very hot paths, there's also a GetOrCreateAsync overload that takes explicit state plus a static lambda, avoiding the closure allocation a normal lambda captures:

return await cache.GetOrCreateAsync(
    $"product:{id}",
    (id, db),                              // state, passed in explicitly
    static async (state, token) =>         // static — captures nothing
        await state.db.Products.FindAsync([state.id], token),
    cancellationToken: ct);

It's more verbose and, for most code, the readability cost isn't worth it. Reach for it only when a profiler tells you that allocation matters on this path — not by default.

The Gotcha Nobody Mentions

The two-tier design has one sharp edge that will eventually bite you. Invalidation only reaches the current server and L2 — it does not touch L1 on other servers.

When you call RemoveAsync (or RemoveByTagAsync) on instance A, it clears A's local memory and marks the entry stale in the shared distributed cache. But instances B and C still hold their own L1 copies, and they'll keep serving them until their LocalCacheExpiration elapses. So immediately after an update, different servers can return different values for a window bounded by LocalCacheExpiration.

This is the real reason to keep LocalCacheExpiration short. It's the maximum staleness any single server can exhibit after an invalidation elsewhere. If your domain genuinely can't tolerate that window — pricing during a flash sale, say — keep the volatile data out of L1 (lean on L2 only) or invalidate through a backplane that fans the eviction out to every instance. For the overwhelming majority of read-heavy data, a short L1 window is a fine trade.

This is a documented, deliberate limitation rather than an oversight — the official guidance states plainly that "the in-memory cache in other servers isn't affected" by an invalidation. The L1/L2 split is designed so that a sufficiently capable L2 backend could one day broadcast invalidation messages to every node's local cache — a backplane, the same idea SignalR uses to fan messages across instances. As of .NET 9 that propagation isn't wired in out of the box, so the short-LocalCacheExpiration rule is your practical safety net today. The shape of the API leaves the door open for transparent cross-node invalidation later.

Common Mistakes

Mistake 1: Putting user input straight into the cache key

// ❌ Untrusted key — a DoS vector
var key = $"search:{userProvidedQuery}";
await cache.GetOrCreateAsync(key, ...);

An attacker sends thousands of unique junk queries, each creating a distinct entry, flooding the cache and evicting the entries that matter. Hash or constrain user-derived key parts, and only key on values you control or have validated against a known set.

Mistake 2: Identical L1 and L2 expirations

// ❌ No reason to have two tiers if they expire together
new HybridCacheEntryOptions
{
    Expiration = TimeSpan.FromMinutes(10),
    LocalCacheExpiration = TimeSpan.FromMinutes(10)
};

If L1 lives as long as L2, each server trusts its local copy for the full lifetime and never re-checks the shared layer — so cross-server staleness lasts the entire 10 minutes. Make LocalCacheExpiration meaningfully shorter than Expiration. That's the knob the whole design hinges on.

Mistake 3: Expecting RemoveByTagAsync to free memory

// ❌ Calling this and watching Redis memory, expecting it to drop
await cache.RemoveByTagAsync("products");

Tag invalidation is logical. Entries are treated as misses on the next read but aren't physically purged — they expire on their own schedule. It correctly stops stale data being served; it does not reclaim storage on the spot.

Mistake 4: Reusing instances of a mutable type

// ❌ Mutable type marked reusable — concurrent callers share one instance
[ImmutableObject(true)]
public sealed class CartDto
{
    public List<string> Items { get; set; } = []; // mutable!
}

[ImmutableObject(true)] is a promise you're making to the runtime, not something it verifies. If the "immutable" object is actually mutated, every concurrent caller is now sharing and racing on the same instance. Only apply it to types that truly can't change — records with init-only members, value objects, frozen collections.

Mistake 5: Letting negative results inherit your long TTL

// ❌ A null result is cached with the SAME long TTL as a real product
async token => await db.Products.FindAsync([id], token); // returns null for a missing id

This is the opposite of what most people assume. HybridCache caches whatever the factory returns — null included — using the same entry options as a valid hit. For repeated lookups of one missing id that's actually fine: it won't re-query the database. The danger is a scan. A client (or an attacker) requesting thousands of non-existent ids fills both tiers with null entries, each pinned for your full 30-minute TTL, evicting the entries that actually matter to make room for nothing.

The catch is that GetOrCreateAsync chooses its options before the factory runs, so you can't natively hand a null result a shorter TTL within the same call. Negative caching has to be a deliberate strategy, not a default you accept blindly:

Guard the input first — validate the id against a known range or set before it ever reaches the cache, so junk never gets stored.
Manage empty results explicitly — instead of caching a raw null, RemoveAsync the key when you know it's missing, or store a short-lived sentinel via SetAsync with its own brief expiration.

The point is to decide what happens to "not found" — not to let it silently inherit the lifetime you picked for real data.

Conclusion

HybridCache isn't a small convenience over the old APIs — it closes the specific gap that made caching in distributed .NET apps error-prone. IMemoryCache gave you speed without sharing. IDistributedCache gave you sharing without speed, stampede protection, or ergonomics. HybridCache gives you a fast L1 backed by a shared L2, one query per key under load instead of a herd, serialization handled, and tags for group invalidation — behind a single GetOrCreateAsync call.

The adoption path is unusually clean. Start with AddHybridCache() and nothing else: even with no distributed cache, you get in-memory caching plus stampede protection, which is already a strict upgrade over reaching for IMemoryCache. When you scale out, register a Redis IDistributedCache and your call sites don't change. Tune LocalCacheExpiration to bound per-server staleness, mark immutable DTOs as reusable, and you have a caching layer that holds up under the kind of load that exposes the seams in everything else.

The features that used to be your job — the miss branch, the serialization, the coordination that stops a stampede — are now the library's job. That's the whole point.

Full source code: github.com/AdrianBailador/hybrid-cache-dotnet

Questions or suggestions? Open an issue on GitHub.

Uber-like System in .NET: Driver Matching, Surge Pricing and the Complete Request Flow

Adrián Bailador — Mon, 25 May 2026 06:15:28 +0000

A rider opens the app and taps "Request". In the next two seconds, the system has to find which of the hundreds of nearby drivers to offer the trip to, calculate a price that reflects current demand, and send the offer — all before the rider's patience runs out.

Most of what makes that hard isn't the individual pieces. It's connecting them. The location pipeline doesn't know about trips. The trip state machine doesn't know about drivers. Surge pricing doesn't know about either. Making them work together, under load, without races or stale data — that's the engineering problem.

This is Part 3 of the Uber-like System Design in .NET series. In Part 1 we built real-time location tracking with Redis GEO and SignalR. In Part 2 we modelled the trip lifecycle with state machines and EF Core. Here we build driver matching, surge pricing, and trace the full request flow end to end.

The Full Architecture

Before the code, the picture:

The request flow at a high level:

Rider requests a trip → fare estimate with surge applied
System queries Redis GEO for nearby available drivers
Drivers are scored and ranked; top candidate receives the offer
Driver accepts → trip transitions through its state machine
Trip completes → payment fires, driver releases back to the pool

Each step is independent enough to test and deploy separately. The state machine from Part 2 is the spine — everything else connects to it through domain events or direct calls.

Step 1: Driver Availability State

The location pipeline from Part 1 knows where drivers are. Driver matching needs to know which drivers are available. These are separate concerns that share Redis.

public enum DriverStatus
{
    Offline,
    Available,
    OnTrip,
    Busy
}

public class DriverAvailabilityService
{
    private readonly IDatabase _redis;
    private const string StatusKeyPrefix = "driver:status:";
    private const string AvailableSet = "drivers:available";

    public DriverAvailabilityService(IConnectionMultiplexer redis)
        => _redis = redis.GetDatabase();

    public async Task SetAvailableAsync(string driverId)
    {
        await _redis.StringSetAsync($"{StatusKeyPrefix}{driverId}", "Available");
        await _redis.SetAddAsync(AvailableSet, driverId);
    }

    public async Task SetOnTripAsync(string driverId)
    {
        await _redis.StringSetAsync($"{StatusKeyPrefix}{driverId}", "OnTrip");
        await _redis.SetRemoveAsync(AvailableSet, driverId);
    }

    public async Task SetOfflineAsync(string driverId)
    {
        await _redis.StringSetAsync($"{StatusKeyPrefix}{driverId}", "Offline");
        await _redis.SetRemoveAsync(AvailableSet, driverId);
    }

    public async Task<bool> IsAvailableAsync(string driverId)
    {
        var status = await _redis.StringGetAsync($"{StatusKeyPrefix}{driverId}");
        return status == "Available";
    }
}

drivers:available is a Redis Set of driver IDs. When a driver goes online, their ID is added; when they accept a trip or go offline, it's removed. The availability check is O(1). The set intersection with the GEO query result is the core of matching.

Step 2: Finding Nearby Available Drivers

Redis GEO stores driver positions. GEOSEARCH returns drivers within a radius ordered by distance. The matching query intersects that result with the availability set:

public class DriverMatchingService
{
    private readonly IDatabase _redis;
    private readonly DriverAvailabilityService _availability;
    private const string GeoKey = "drivers:geo";

    public DriverMatchingService(
        IConnectionMultiplexer redis,
        DriverAvailabilityService availability)
    {
        _redis = redis.GetDatabase();
        _availability = availability;
    }

    public async Task<IReadOnlyList<DriverCandidate>> FindNearbyAsync(
        double pickupLat,
        double pickupLon,
        double radiusKm,
        int maxResults = 10)
    {
        var geoResults = await _redis.GeoSearchAsync(
            GeoKey,
            new GeoSearchCircle(pickupLon, pickupLat, radiusKm, GeoUnit.Kilometers),
            order: Order.Ascending,
            count: maxResults * 3); // fetch more than needed to account for unavailable ones

        var candidates = new List<DriverCandidate>();

        foreach (var result in geoResults)
        {
            var driverId = result.Member.ToString();

            if (!await _availability.IsAvailableAsync(driverId))
                continue;

            candidates.Add(new DriverCandidate(
                DriverId: driverId,
                DistanceKm: result.Distance ?? double.MaxValue));

            if (candidates.Count >= maxResults)
                break;
        }

        return candidates;
    }
}

public record DriverCandidate(string DriverId, double DistanceKm);

Fetching maxResults * 3 from Redis and filtering client-side avoids a round-trip per driver for the availability check. The trade-off: if most nearby drivers are unavailable (surge scenario), you might miss candidates at the edge of the radius. For a production system, you'd expand the search radius dynamically rather than fetching a fixed multiplier.

Production note — back-off radius: The * 3 multiplier is fragile under peak demand. On a Friday night after a concert, 95% of nearby drivers may be OnTrip. Redis returns 30 results, all unavailable, and the method returns an empty list even though free drivers exist 6 km out. The production fix is an expanding search loop: if the first query returns fewer candidates than needed, widen the radius and query again — stopping when you have enough candidates or reach a maximum radius threshold.

Step 3: Scoring and Ranking Drivers

Distance alone is a poor signal. A driver 500 metres away with a 3.2 rating is a worse match than a driver 800 metres away with a 4.8. The scoring function weights the factors that matter:

public class DriverScoringService
{
    public IReadOnlyList<ScoredDriver> Rank(
        IReadOnlyList<DriverCandidate> candidates,
        IReadOnlyDictionary<string, DriverProfile> profiles)
    {
        return candidates
            .Where(c => profiles.ContainsKey(c.DriverId))
            .Select(c =>
            {
                var profile = profiles[c.DriverId];
                var score = CalculateScore(c.DistanceKm, profile);
                return new ScoredDriver(c.DriverId, c.DistanceKm, profile.Rating, score);
            })
            .OrderByDescending(d => d.Score)
            .ToList();
    }

    private static double CalculateScore(double distanceKm, DriverProfile profile)
    {
        // Distance: closer is better, capped at 5 km; diminishing penalty past that
        var distanceFactor = Math.Max(0, 1 - (distanceKm / 5.0));

        // Rating: normalised 0–1 from 1–5 scale
        var ratingFactor = (profile.Rating - 1.0) / 4.0;

        // Acceptance rate: drivers who decline frequently get penalised
        var acceptanceFactor = profile.AcceptanceRate;

        // Weighted sum — adjust weights per product requirements
        return (distanceFactor * 0.5) + (ratingFactor * 0.35) + (acceptanceFactor * 0.15);
    }
}

public record ScoredDriver(string DriverId, double DistanceKm, double Rating, double Score);

public record DriverProfile(string DriverId, double Rating, double AcceptanceRate);

The weights are tunable. In a real system they'd be configured per city and time of day. During morning commutes, distance weight goes up — riders want the fastest pickup. Late at night, rating weight goes up — safety matters more than speed.

Step 4: Surge Pricing

Surge pricing is a supply/demand signal. When many riders are requesting and few drivers are available, the price rises to attract more drivers and reduce demand.

The simplest model uses a ratio:

public class SurgePricingService
{
    private readonly IDatabase _redis;
    private const string DemandKeyPrefix = "surge:demand:";
    private const string SupplyKeyPrefix = "surge:supply:";
    private static readonly TimeSpan Window = TimeSpan.FromMinutes(5);

    public SurgePricingService(IConnectionMultiplexer redis)
        => _redis = redis.GetDatabase();

    public async Task RecordRequestAsync(string gridCell)
    {
        var key = $"{DemandKeyPrefix}{gridCell}";
        var pipe = _redis.CreateBatch();
        _ = pipe.StringIncrementAsync(key);
        _ = pipe.KeyExpireAsync(key, Window);
        pipe.Execute();
    }

    public async Task RecordDriverAvailableAsync(string gridCell)
    {
        var key = $"{SupplyKeyPrefix}{gridCell}";
        var pipe = _redis.CreateBatch();
        _ = pipe.StringIncrementAsync(key);
        _ = pipe.KeyExpireAsync(key, Window);
        pipe.Execute();
    }

    public async Task<decimal> GetSurgeMultiplierAsync(string gridCell)
    {
        var demandTask = _redis.StringGetAsync($"{DemandKeyPrefix}{gridCell}");
        var supplyTask = _redis.StringGetAsync($"{SupplyKeyPrefix}{gridCell}");

        await Task.WhenAll(demandTask, supplyTask);

        var demand = (double)(long)(demandTask.Result.IsNullOrEmpty ? 1 : demandTask.Result);
        var supply = (double)(long)(supplyTask.Result.IsNullOrEmpty ? 1 : supplyTask.Result);

        if (supply == 0) return 3.0m; // no drivers → maximum surge

        var ratio = demand / supply;

        return ratio switch
        {
            <= 1.0 => 1.0m,
            <= 1.5 => 1.2m,
            <= 2.0 => 1.5m,
            <= 3.0 => 2.0m,
            <= 4.0 => 2.5m,
            _ => 3.0m  // cap at 3x
        };
    }
}

gridCell is an H3 or geohash cell identifier — a string that encodes a geographic area. You derive it from the rider's pickup coordinates. All riders and drivers in the same cell share the same demand/supply counters.

The 5-minute rolling window keeps surge responsive. Counters expire naturally; there's no cleanup job needed. The cap at 3x is a business decision — uncapped surge generates bad press and rider churn faster than it attracts drivers.

Step 5: Fare Estimation

Before confirming the request, the rider sees an estimated fare. The estimate uses the surge multiplier from Step 4 and a simple per-km/per-minute rate:

public class FareEstimationService
{
    private const decimal BaseRate = 1.50m;
    private const decimal PerKm = 1.20m;
    private const decimal PerMinute = 0.20m;

    public async Task<FareEstimate> EstimateAsync(
        double pickupLat, double pickupLon,
        double dropoffLat, double dropoffLon,
        string gridCell,
        SurgePricingService surge)
    {
        var distanceKm = HaversineDistance(pickupLat, pickupLon, dropoffLat, dropoffLon);
        var estimatedMinutes = distanceKm / 0.5; // rough 30 km/h average
        var surgeMultiplier = await surge.GetSurgeMultiplierAsync(gridCell);

        var baseFare = BaseRate + (PerKm * (decimal)distanceKm) + (PerMinute * (decimal)estimatedMinutes);
        var totalFare = Math.Round(baseFare * surgeMultiplier, 2);

        return new FareEstimate(totalFare, surgeMultiplier, distanceKm);
    }

    private static double HaversineDistance(
        double lat1, double lon1, double lat2, double lon2)
    {
        const double R = 6371;
        var dLat = ToRad(lat2 - lat1);
        var dLon = ToRad(lon2 - lon1);
        var a = Math.Sin(dLat / 2) * Math.Sin(dLat / 2)
              + Math.Cos(ToRad(lat1)) * Math.Cos(ToRad(lat2))
              * Math.Sin(dLon / 2) * Math.Sin(dLon / 2);
        return R * 2 * Math.Atan2(Math.Sqrt(a), Math.Sqrt(1 - a));
    }

    private static double ToRad(double deg) => deg * Math.PI / 180;
}

public record FareEstimate(decimal Total, decimal SurgeMultiplier, double DistanceKm);

The estimate is a range, not a commitment. The actual fare is calculated on trip completion based on real distance and time. What matters at request time is that the rider understands they're in a surge zone.

Step 6: The Trip Request Coordinator

This is where the pieces connect. The coordinator runs when a rider taps "Request". It's a service, not a controller — it orchestrates the other services and has no HTTP knowledge:

public class TripRequestCoordinator
{
    private readonly AppDbContext _db;
    private readonly DriverMatchingService _matching;
    private readonly DriverAvailabilityService _availability;
    private readonly SurgePricingService _surge;
    private readonly FareEstimationService _fares;
    private readonly IEventBus _events;
    private readonly ILogger<TripRequestCoordinator> _logger;

    public TripRequestCoordinator(
        AppDbContext db,
        DriverMatchingService matching,
        DriverAvailabilityService availability,
        SurgePricingService surge,
        FareEstimationService fares,
        IEventBus events,
        ILogger<TripRequestCoordinator> logger)
    {
        _db = db;
        _matching = matching;
        _availability = availability;
        _surge = surge;
        _fares = fares;
        _events = events;
        _logger = logger;
    }

    public async Task<TripRequestResult> RequestTripAsync(
        RequestTripCommand command,
        CancellationToken ct = default)
    {
        var gridCell = GeohashEncoder.Encode(command.PickupLat, command.PickupLon, precision: 5);

        // Estimate fare with surge before creating the trip
        var fareEstimate = await _fares.EstimateAsync(
            command.PickupLat, command.PickupLon,
            command.DropoffLat, command.DropoffLon,
            gridCell, _surge);

        // Find available drivers
        var candidates = await _matching.FindNearbyAsync(
            command.PickupLat, command.PickupLon,
            radiusKm: 5);

        if (candidates.Count == 0)
        {
            _logger.LogInformation("No drivers available near {Lat},{Lon}", 
                command.PickupLat, command.PickupLon);
            return TripRequestResult.NoDriversAvailable(fareEstimate);
        }

        // Create the trip in Requested state
        var trip = Trip.Create(command.RiderId);
        _db.Trips.Add(trip);
        await _db.SaveChangesAsync(ct);

        // Record demand for surge calculation
        await _surge.RecordRequestAsync(gridCell);

        // Offer to the best candidate
        var best = candidates[0];
        await _events.PublishAsync(new DriverOfferSent(trip.Id, best.DriverId, fareEstimate), ct);

        return TripRequestResult.Offered(trip.Id, fareEstimate, best.DriverId);
    }
}

public record RequestTripCommand(
    Guid RiderId,
    double PickupLat, double PickupLon,
    double DropoffLat, double DropoffLon);

public abstract record TripRequestResult
{
    public static TripRequestResult Offered(Guid tripId, FareEstimate fare, string driverId)
        => new TripOffered(tripId, fare, driverId);

    public static TripRequestResult NoDriversAvailable(FareEstimate fare)
        => new NoDrivers(fare);
}

public record TripOffered(Guid TripId, FareEstimate FareEstimate, string DriverId) : TripRequestResult;
public record NoDrivers(FareEstimate FareEstimate) : TripRequestResult;

The coordinator doesn't call AssignDriver directly — it publishes a DriverOfferSent event. The driver receives a push notification, taps "Accept", and that triggers AssignDriver through the TripService from Part 2. This matters: the driver might decline, the offer might time out, or the driver might go offline before responding. The trip stays in Requested until the driver actively accepts.

Step 7: The Driver Acceptance Flow

When the driver taps "Accept", we need to atomically check they're still available and assign the trip:

public class DriverAcceptanceService
{
    private readonly TripService _trips;
    private readonly DriverAvailabilityService _availability;

    public DriverAcceptanceService(TripService trips, DriverAvailabilityService availability)
    {
        _trips = trips;
        _availability = availability;
    }

    public async Task<Result> AcceptTripAsync(
        Guid tripId,
        string driverId,
        CancellationToken ct = default)
    {
        // Check availability before committing to the assignment
        if (!await _availability.IsAvailableAsync(driverId))
            return Result.Fail("Driver is no longer available.");

        // AssignDriver handles the concurrency case: if two drivers
        // somehow both try to accept the same trip, the second will
        // get DbUpdateConcurrencyException and fail cleanly.
        var result = await _trips.AssignDriverAsync(tripId, driverId, ct);

        if (result.Success)
            await _availability.SetOnTripAsync(driverId);

        return result;
    }
}

The TripService.AssignDriverAsync from Part 2 uses optimistic concurrency. Even if two drivers somehow both tap "Accept" at the same millisecond, only one write succeeds. The second gets a DbUpdateConcurrencyException, retries, finds the trip is already DriverAssigned, and fails cleanly with a meaningful error.

Step 8: The Complete Request Flow in Minimal API

Wiring the full flow into endpoints:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddStackExchangeRedisCache(o =>
    o.Configuration = builder.Configuration["Redis:ConnectionString"]);
builder.Services.AddSingleton<IConnectionMultiplexer>(sp =>
    ConnectionMultiplexer.Connect(builder.Configuration["Redis:ConnectionString"]!));
builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseNpgsql(builder.Configuration.GetConnectionString("Postgres")));

builder.Services.AddScoped<TripRequestCoordinator>();
builder.Services.AddScoped<TripService>();
builder.Services.AddScoped<DriverAcceptanceService>();
builder.Services.AddScoped<DriverAvailabilityService>();
builder.Services.AddScoped<DriverMatchingService>();
builder.Services.AddScoped<SurgePricingService>();
builder.Services.AddScoped<FareEstimationService>();
builder.Services.AddHostedService<TripTimeoutService>();

var app = builder.Build();

// 1. Rider requests a trip
app.MapPost("/trips/request", async (
    RequestTripCommand command,
    TripRequestCoordinator coordinator,
    CancellationToken ct) =>
{
    var result = await coordinator.RequestTripAsync(command, ct);

    return result switch
    {
        TripOffered offered => Results.Accepted($"/trips/{offered.TripId}", offered),
        NoDrivers noDrivers => Results.Ok(new { message = "No drivers nearby", fare = noDrivers.FareEstimate }),
        _ => Results.Problem("Unexpected state")
    };
});

// 2. Driver accepts the trip
app.MapPost("/trips/{tripId:guid}/accept", async (
    Guid tripId,
    AcceptTripDto dto,
    DriverAcceptanceService acceptance,
    CancellationToken ct) =>
{
    var result = await acceptance.AcceptTripAsync(tripId, dto.DriverId, ct);
    return result.Success ? Results.Ok() : Results.Conflict(new { error = result.Error });
});

// 3. Driver en route to pickup
app.MapPost("/trips/{tripId:guid}/en-route", async (
    Guid tripId,
    AppDbContext db,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();
    try { trip.DriverEnRoute(); await db.SaveChangesAsync(ct); return Results.Ok(); }
    catch (InvalidTripTransitionException ex) { return Results.Conflict(new { error = ex.Message }); }
});

// 4. Trip starts (driver and rider both at pickup)
app.MapPost("/trips/{tripId:guid}/start", async (
    Guid tripId,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();
    try
    {
        trip.Start();
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events) await events.PublishAsync(evt, ct);
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex) { return Results.Conflict(new { error = ex.Message }); }
});

// 5. Trip completes
app.MapPost("/trips/{tripId:guid}/complete", async (
    Guid tripId,
    CompleteTripDto dto,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();
    try
    {
        trip.Complete(dto.FareAmount);
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events) await events.PublishAsync(evt, ct);
        // Driver release happens in the TripCompleted event handler — not inline.
        // This keeps cancels and completes consistent: both paths release the driver
        // through the same event subscriber, never through the API layer.
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex) { return Results.Conflict(new { error = ex.Message }); }
});

// 6. Get surge multiplier for an area (shown to rider before confirming)
app.MapGet("/surge", async (
    double lat,
    double lon,
    SurgePricingService surge) =>
{
    var gridCell = GeohashEncoder.Encode(lat, lon, precision: 5);
    var multiplier = await surge.GetSurgeMultiplierAsync(gridCell);
    return Results.Ok(new { multiplier });
});

// 7. Driver goes online
app.MapPost("/drivers/{driverId}/online", async (
    string driverId,
    DriverAvailabilityService availability,
    SurgePricingService surge,
    GoOnlineDto dto) =>
{
    await availability.SetAvailableAsync(driverId);
    var gridCell = GeohashEncoder.Encode(dto.Lat, dto.Lon, precision: 5);
    await surge.RecordDriverAvailableAsync(gridCell);
    return Results.Ok();
});

app.Run();

Step 9: The Offer Timeout

When we send a DriverOfferSent event, the driver has a limited window to accept. If they don't respond, we need to offer the trip to the next candidate. This is the same background pattern as trip timeouts, but at the offer level:

public class DriverOfferTimeoutService : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private static readonly TimeSpan OfferTimeout = TimeSpan.FromSeconds(15);
    private static readonly TimeSpan CheckInterval = TimeSpan.FromSeconds(5);

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(CheckInterval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            using var scope = _scopeFactory.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var matching = scope.ServiceProvider.GetRequiredService<DriverMatchingService>();
            var events = scope.ServiceProvider.GetRequiredService<IEventBus>();

            var cutoff = DateTimeOffset.UtcNow - OfferTimeout;

            // Find trips still Requested (offer not accepted) past the timeout
            var stalled = await db.Trips
                .Where(t => t.Status == TripStatus.Requested && t.RequestedAt < cutoff)
                .ToListAsync(stoppingToken);

            foreach (var trip in stalled)
            {
                // Re-run matching — the original candidate may have gone offline
                var nextCandidates = await matching.FindNearbyAsync(
                    trip.PickupLat, trip.PickupLon, radiusKm: 7); // slightly wider radius

                if (nextCandidates.Count == 0)
                {
                    // Cancel trip — no drivers available
                    try
                    {
                        trip.Cancel("No drivers available after timeout.", "system");
                        await db.SaveChangesAsync(stoppingToken);
                    }
                    catch (Exception) { /* Already transitioned */ }
                    continue;
                }

                var next = nextCandidates[0];
                await events.PublishAsync(new DriverOfferSent(trip.Id, next.DriverId, null), stoppingToken);
            }
        }
    }
}

Each retry widens the search radius slightly. After a configurable number of retries with no acceptance, the trip cancels. The TripTimeoutService from Part 2 acts as the final backstop if this service somehow misses a trip.

What Uber Actually Does

The architecture here is the right shape, but Uber's implementation at scale differs in important ways.

Driver matching uses their own geospatial index, not stock Redis GEO. Redis GEO uses a geohash-based sorted set — fast, but the precision is fixed. Uber uses H3, Uber's own hexagonal geospatial indexing system, which allows dynamic resolution changes and makes aggregations (like surge pricing per cell) much cleaner.

Offer dispatch in this article publishes one offer at a time. Uber uses parallel dispatch — the trip is offered to several candidates simultaneously, and the first to accept wins. This significantly reduces the time-to-assignment at the cost of occasionally "wasting" an offer when multiple drivers accept and all but one have to be rejected.

Surge pricing in production is a learned model, not a ratio table. Demand predictions are based on historical patterns, current events, and weather. The surge multiplier is calculated at fine-grained H3 cells and interpolated at boundaries to avoid the "why is 10 metres away cheaper?" problem.

Trip assignment uses a saga pattern, not the direct state machine calls here. The assignment orchestrator in Cadence/Temporal handles driver acceptance, timeouts, fallback sequences, and cancellation compensation as a durable workflow — if the service restarts mid-assignment, the workflow resumes from where it left off.

None of that changes the concepts: find drivers, score them, present a price, enforce valid transitions, handle failure cases. The scale changes the implementation, not the model.

Common Mistakes

Mistake 1: Querying the database for driver locations

// ❌ SQL can't do this efficiently at volume
var nearbyDrivers = await db.Drivers
    .Where(d => d.Status == "Available"
             && HaversineDistance(d.Lat, d.Lon, pickupLat, pickupLon) < 5)
    .ToListAsync();

PostGIS makes this feasible, but you're still doing a disk read for every request. At high volume, Redis GEO handles millions of position updates per second and returns nearby entries in single-digit milliseconds.

Mistake 2: Surge pricing with a global counter

// ❌ One counter for the whole city
await _redis.StringIncrementAsync("total:requests");

Surge pricing is hyper-local. A city-wide surplus of drivers doesn't help a rider in a neighbourhood where every driver is on a trip. Granular grid cells (geohash or H3) are the primitive, not city-level aggregates.

Mistake 3: Assigning a driver without checking availability in the same operation

// ❌ Gap between availability check and state change
if (await _availability.IsAvailableAsync(driverId))
{
    // Another request comes in here and assigns this driver elsewhere
    await _trips.AssignDriverAsync(tripId, driverId);
}

The optimistic concurrency on the trip assignment (Part 2) protects against two trips racing for one driver only if the AssignDriver call is atomic with the database write. The Redis availability check is a separate system — there's always a gap. Handle it: the TripService retry loop will surface the stale state and fail cleanly.

Mistake 4: Not handling the "no drivers" case in the UI

The no-drivers scenario is not an error. It's an expected outcome that should show the rider a useful message, the current surge level, and an estimated wait time if they want to retry. Returning a 500 or leaving the rider on a spinner for 30 seconds is a product failure, not just a technical one.

Mistake 5: Forgetting to release the driver on cancellation

// ❌ Driver is stuck OnTrip in Redis even after cancel
trip.Cancel("Rider cancelled.", "rider");
await db.SaveChangesAsync(ct);
// Driver never goes back to Available

Every Cancel — whether by the rider, the system timeout, or payment failure — must release the driver back to Available. Wire it through the TripCancelled domain event handler, not inline, so it happens consistently regardless of which code path triggers the cancel.

Conclusion

Three articles, three layers. The location pipeline in Part 1 knows where drivers are. The state machine in Part 2 knows what a trip is. The matching and pricing logic in this article knows how to connect a rider to a driver with a price that reflects current supply and demand.

The pieces stay independent by design. Driver availability is Redis state, not a database flag. Surge pricing reads the same Redis cells without knowing about trips. The trip state machine doesn't know about Redis. Each service can be replaced or scaled independently.

What holds it together is the event bus. DriverOfferSent, TripStarted, TripCompleted, TripCancelled — these are the contracts between parts of the system. When a trip completes, the state machine doesn't call the payment service. It publishes TripCompleted, and every system that cares — payment, notifications, availability release, surge adjustment — responds independently.

That separation is what makes this architecture maintainable at scale. Add a new reaction to TripCompleted and nothing else changes. Add a new driver scoring factor and only DriverScoringService changes. The Uber-like system you've built in these three articles isn't a tutorial CRUD app — it's a structural approach that holds up when the requirements get complicated.

Part 3 of the Uber-like System Design in .NET series.

Parts 1 and 2: Real-time Location Tracking · Trip State Machine

Full source code: github.com/AdrianBailador/uber-driver-matching-dotnet

Questions or suggestions? Open an issue on GitHub.

State Machines in .NET: Modelling Uber's Trip Lifecycle with EF Core

Adrián Bailador — Sun, 17 May 2026 09:37:36 +0000

A rider opens the app and requests a trip. A driver accepts. The driver is already moving toward the pickup when a bug in the assignment service fires a second time — and assigns a different driver to the same trip.

Now two drivers are heading to the same address, both thinking they have a fare. One of them will arrive, wait, and leave confused. The other will complete the trip. Depending on which one gets marked as completed first, the rider might be charged twice — or not at all.

This is what happens when you store trip data as a plain row in a database without enforcing valid state transitions. It's not a theoretical problem. It's the kind of bug that appears in production at 2am on a Friday, after months of working fine in development.

State machines solve this. Not because they're elegant (though they are) — because they make illegal transitions impossible, not just unlikely.

This is Part 2 of the Uber-like System Design in .NET series. In Part 1 we built the real-time location pipeline. Here we model the trip lifecycle: the states, the transitions, the persistence, and the race conditions.

The Trip Lifecycle

A trip moves through a defined sequence of states. Each state has a limited set of valid transitions — and any other transition is a bug.

The transitions that matter most are the ones that aren't allowed. A trip cannot go from Completed back to InProgress. A Cancelled trip cannot be assigned a driver. A payment cannot fire on a Requested trip. These aren't edge cases — they're the boundaries that define what a trip is.

Step 1: Modelling the States

Start with an enum that expresses the full lifecycle:

public enum TripStatus
{
    Requested,
    DriverAssigned,
    DriverEnRoute,
    InProgress,
    Completed,
    Cancelled,
    PaymentFailed
}

And a record for the transitions you want to raise as domain events:

public abstract record TripEvent
{
    public Guid TripId { get; init; }
    public DateTimeOffset OccurredAt { get; init; } = DateTimeOffset.UtcNow;
}

public record DriverAssigned(Guid TripId, string DriverId) : TripEvent;
public record TripStarted(Guid TripId) : TripEvent;
public record TripCompleted(Guid TripId, decimal FareAmount) : TripEvent;
public record TripCancelled(Guid TripId, string Reason, string CancelledBy) : TripEvent;
public record PaymentFailed(Guid TripId, string Reason) : TripEvent;

Step 2: The Transition Rules

The state machine is just a set of rules: given the current state, which transitions are valid?

public static class TripTransitions
{
    private static readonly Dictionary<TripStatus, HashSet<TripStatus>> _allowed = new()
    {
        [TripStatus.Requested]      = [TripStatus.DriverAssigned, TripStatus.Cancelled],
        [TripStatus.DriverAssigned] = [TripStatus.DriverEnRoute, TripStatus.Cancelled],
        [TripStatus.DriverEnRoute]  = [TripStatus.InProgress, TripStatus.Cancelled],
        [TripStatus.InProgress]     = [TripStatus.Completed, TripStatus.Cancelled],
        [TripStatus.Completed]      = [TripStatus.PaymentFailed],
        [TripStatus.PaymentFailed]  = [TripStatus.Completed, TripStatus.Cancelled],
        [TripStatus.Cancelled]      = [],
    };

    public static bool IsAllowed(TripStatus from, TripStatus to)
        => _allowed.TryGetValue(from, out var targets) && targets.Contains(to);

    public static void Validate(TripStatus from, TripStatus to)
    {
        if (!IsAllowed(from, to))
            throw new InvalidTripTransitionException(from, to);
    }
}

public class InvalidTripTransitionException : Exception
{
    public InvalidTripTransitionException(TripStatus from, TripStatus to)
        : base($"Cannot transition trip from {from} to {to}.") { }
}

This is the entire state machine. A dictionary. When you add a new state or a new transition, you change one line. When someone tries an illegal transition, they get an exception immediately — not a silent data corruption.

One design note: Validate throws an exception, which means under high concurrent load the stack trace generation has a small but measurable cost. If illegal transitions are genuinely expected at volume (e.g., a retry storm hitting an already-cancelled trip), consider replacing the exception with a Result type — the same pattern used in the service layer below. The IsAllowed method already exists for exactly that check without allocating an exception. For most systems the exception path is fine; for very high-throughput services it's worth considering.

Step 3: The Trip Aggregate

The Trip class owns the state transitions and raises domain events. Nothing outside it can change its status directly. The private set on every property isn't just about encapsulation — it's a guarantee of invariant consistency. DriverId is only ever set during AssignDriver, FareAmount only during Complete, CompletedAt only when the trip actually finishes. There is no way to create a Trip in a state where Status is Completed but FareAmount is null, or DriverId is set on a Cancelled trip. The class makes those combinations structurally impossible:

public class Trip
{
    public Guid Id { get; private set; }
    public string RiderId { get; private set; }
    public string? DriverId { get; private set; }
    public TripStatus Status { get; private set; }
    public decimal? FareAmount { get; private set; }
    public DateTimeOffset RequestedAt { get; private set; }
    public DateTimeOffset? CompletedAt { get; private set; }
    public byte[] RowVersion { get; private set; } = [];

    private readonly List<TripEvent> _events = [];
    public IReadOnlyList<TripEvent> Events => _events.AsReadOnly();

    private Trip() { }

    public static Trip Create(Guid riderId)
    {
        return new Trip
        {
            Id = Guid.NewGuid(),
            RiderId = riderId.ToString(),
            Status = TripStatus.Requested,
            RequestedAt = DateTimeOffset.UtcNow
        };
    }

    public void AssignDriver(string driverId)
    {
        TripTransitions.Validate(Status, TripStatus.DriverAssigned);
        DriverId = driverId;
        Status = TripStatus.DriverAssigned;
        _events.Add(new DriverAssigned(Id, driverId));
    }

    public void DriverEnRoute()
    {
        TripTransitions.Validate(Status, TripStatus.DriverEnRoute);
        Status = TripStatus.DriverEnRoute;
    }

    public void Start()
    {
        TripTransitions.Validate(Status, TripStatus.InProgress);
        Status = TripStatus.InProgress;
        _events.Add(new TripStarted(Id));
    }

    public void Complete(decimal fareAmount)
    {
        TripTransitions.Validate(Status, TripStatus.Completed);
        Status = TripStatus.Completed;
        FareAmount = fareAmount;
        CompletedAt = DateTimeOffset.UtcNow;
        _events.Add(new TripCompleted(Id, fareAmount));
    }

    public void FailPayment(string reason)
    {
        TripTransitions.Validate(Status, TripStatus.PaymentFailed);
        Status = TripStatus.PaymentFailed;
        _events.Add(new PaymentFailed(Id, reason));
    }

    public void Cancel(string reason, string cancelledBy)
    {
        TripTransitions.Validate(Status, TripStatus.Cancelled);
        Status = TripStatus.Cancelled;
        _events.Add(new TripCancelled(Id, reason, cancelledBy));
    }
}

The RowVersion property is not just metadata — it's the key to preventing the race condition we opened with. We'll use it in a moment.

Step 4: Persisting State with EF Core

The trip needs a table. The RowVersion column is what makes concurrent updates safe:

public class TripConfiguration : IEntityTypeConfiguration<Trip>
{
    public void Configure(EntityTypeBuilder<Trip> builder)
    {
        builder.HasKey(t => t.Id);

        builder.Property(t => t.Status)
            .HasConversion<string>();

        builder.Property(t => t.RowVersion)
            .IsRowVersion();

        builder.Property(t => t.RiderId).IsRequired();
        builder.Property(t => t.FareAmount).HasColumnType("decimal(10,2)");
    }
}

IsRowVersion() tells EF Core to include this column in every UPDATE statement's WHERE clause. SQL Server uses rowversion; PostgreSQL uses xmin. Either way, if the row has been modified since you read it, the update will affect 0 rows and EF Core throws DbUpdateConcurrencyException.

For the domain events, add a separate table that acts as an audit trail:

public class TripEventLog
{
    public long Id { get; set; }
    public Guid TripId { get; set; }
    public string EventType { get; set; } = string.Empty;
    public string Payload { get; set; } = string.Empty;
    public DateTimeOffset OccurredAt { get; set; }
}

Step 5: Handling the Race Condition

This is where most implementations fall apart. Two requests arrive at the same millisecond — one from the rider cancelling, one from the assignment service assigning a driver. Both read the trip as Requested. Both attempt a transition. Without protection, both succeed, leaving the trip in an undefined state.

The service that assigns a driver:

public class TripService
{
    private readonly AppDbContext _db;
    private readonly IEventBus _events;

    public TripService(AppDbContext db, IEventBus events)
    {
        _db = db;
        _events = events;
    }

    public async Task<Result> AssignDriverAsync(
        Guid tripId,
        string driverId,
        CancellationToken ct = default)
    {
        const int maxRetries = 3;

        for (var attempt = 0; attempt < maxRetries; attempt++)
        {
            var trip = await _db.Trips.FindAsync([tripId], ct);

            if (trip is null)
                return Result.Fail("Trip not found.");

            if (trip.Status == TripStatus.Cancelled)
                return Result.Fail("Trip was already cancelled.");

            try
            {
                trip.AssignDriver(driverId);
                await _db.SaveChangesAsync(ct);

                // Publish domain events after successful save
                foreach (var evt in trip.Events)
                    await _events.PublishAsync(evt, ct);

                return Result.Ok();
            }
            catch (InvalidTripTransitionException ex)
            {
                return Result.Fail(ex.Message);
            }
            catch (DbUpdateConcurrencyException)
            {
                // Another process modified this trip between our read and write.
                // Refresh and retry — the state we read is stale.
                if (attempt == maxRetries - 1)
                    return Result.Fail("Trip is being modified concurrently. Please retry.");

                await Task.Delay(TimeSpan.FromMilliseconds(50 * (attempt + 1)), ct);
            }
        }

        return Result.Fail("Failed to assign driver after retries.");
    }
}

The retry loop is important. DbUpdateConcurrencyException means someone else got there first — the trip was modified between when we read it and when we tried to write it. We don't give up: we reload the current state and retry, up to three times. If the trip was cancelled while we were retrying, the InvalidTripTransitionException will stop us cleanly.

This pattern — read, modify, save, catch concurrency exception, retry — is optimistic concurrency. It assumes conflicts are rare and handles them when they happen, rather than locking the row for the duration of the operation.

Step 6: Domain Events Driving Side Effects

When a trip completes, several things need to happen: charge the payment method, send the receipt, update the driver's stats, release the driver back to the available pool. None of these belong in TripService. They're separate concerns, triggered by the TripCompleted event.

public class TripCompletedHandler
{
    private readonly IPaymentService _payments;
    private readonly INotificationService _notifications;
    private readonly IDriverAvailabilityService _availability;

    public async Task HandleAsync(TripCompleted evt, CancellationToken ct = default)
    {
        // Each of these is independent — one failure shouldn't block the others
        var paymentResult = await _payments.ChargeAsync(evt.TripId, evt.FareAmount, ct);

        if (!paymentResult.Success)
        {
            // Publish PaymentFailed — TripService will handle the state transition
            await PublishPaymentFailedAsync(evt.TripId, paymentResult.Error, ct);
            return;
        }

        await Task.WhenAll(
            _notifications.SendReceiptAsync(evt.TripId, evt.FareAmount, ct),
            _availability.ReleaseDriverAsync(evt.TripId, ct));
    }
}

The TripCompletedHandler doesn't know how trips work. It knows what to do when one completes. This separation means you can add a new reaction to TripCompleted — a loyalty points award, a surge pricing adjustment, a data pipeline event — without touching any trip logic.

The gap you should know about. Dispatching events after SaveChangesAsync is the right order — you never want to publish an event for a write that didn't commit. But it leaves a window: if the process crashes after the database write succeeds but before IEventBus.PublishAsync completes, the trip is Completed in the database and the payment event was never dispatched. The rider won't be charged.

For 100% reliability, use the Outbox Pattern: instead of publishing to the event bus directly, save the event payload to an OutboxMessages table in the same database transaction as the state change. A background worker then reads and dispatches those events, marking each as processed. If the process crashes mid-dispatch, the worker retries. The event is never lost because it was committed atomically with the state.

The implementation in this article is correct for most systems. If missed payments or missed notifications are genuinely unacceptable, the Outbox Pattern is the next step.

Step 7: Handling Timeouts

A Requested trip that doesn't get a driver within 60 seconds should be automatically cancelled. This is a background concern, not part of the trip's own logic:

public class TripTimeoutService : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<TripTimeoutService> _logger;
    private static readonly TimeSpan CheckInterval = TimeSpan.FromSeconds(15);
    private static readonly TimeSpan RequestTimeout = TimeSpan.FromSeconds(60);

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(CheckInterval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            using var scope = _scopeFactory.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var events = scope.ServiceProvider.GetRequiredService<IEventBus>();

            var cutoff = DateTimeOffset.UtcNow - RequestTimeout;

            var timedOut = await db.Trips
                .Where(t => t.Status == TripStatus.Requested && t.RequestedAt < cutoff)
                .ToListAsync(stoppingToken);

            foreach (var trip in timedOut)
            {
                try
                {
                    trip.Cancel("No driver found within timeout.", "system");
                    await db.SaveChangesAsync(stoppingToken);

                    foreach (var evt in trip.Events)
                        await events.PublishAsync(evt, stoppingToken);
                }
                catch (DbUpdateConcurrencyException)
                {
                    // A driver was assigned at the same moment we tried to cancel.
                    // The driver won — that's the right outcome. Skip.
                    _logger.LogInformation("Trip {TripId} was assigned during timeout window, skipping cancel.", trip.Id);
                }
                catch (InvalidTripTransitionException)
                {
                    // Trip was already transitioned by another process. Skip.
                }
            }
        }
    }
}

Note how DbUpdateConcurrencyException here is not an error — it means the trip was assigned just as we were about to cancel it. The driver won the race. That's exactly the right outcome, and we log it and move on.

Step 8: Wiring It Up

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Postgres")));

builder.Services.AddScoped<TripService>();
builder.Services.AddHostedService<TripTimeoutService>();

var app = builder.Build();

// Request a trip
app.MapPost("/trips", async (
    RequestTripDto request,
    TripService service,
    AppDbContext db,
    CancellationToken ct) =>
{
    var trip = Trip.Create(request.RiderId);
    db.Trips.Add(trip);
    await db.SaveChangesAsync(ct);
    return Results.Created($"/trips/{trip.Id}", new { tripId = trip.Id });
});

// Assign a driver
app.MapPost("/trips/{tripId:guid}/assign", async (
    Guid tripId,
    AssignDriverDto request,
    TripService service,
    CancellationToken ct) =>
{
    var result = await service.AssignDriverAsync(tripId, request.DriverId, ct);
    return result.Success ? Results.Ok() : Results.Conflict(new { error = result.Error });
});

// Start the trip
app.MapPost("/trips/{tripId:guid}/start", async (
    Guid tripId,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();

    try
    {
        trip.Start();
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events)
            await events.PublishAsync(evt, ct);
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex)
    {
        return Results.Conflict(new { error = ex.Message });
    }
});

// Complete the trip
app.MapPost("/trips/{tripId:guid}/complete", async (
    Guid tripId,
    CompleteTripDto request,
    AppDbContext db,
    IEventBus events,
    CancellationToken ct) =>
{
    var trip = await db.Trips.FindAsync([tripId], ct);
    if (trip is null) return Results.NotFound();

    try
    {
        trip.Complete(request.FareAmount);
        await db.SaveChangesAsync(ct);
        foreach (var evt in trip.Events)
            await events.PublishAsync(evt, ct);
        return Results.Ok();
    }
    catch (InvalidTripTransitionException ex)
    {
        return Results.Conflict(new { error = ex.Message });
    }
});

app.Run();

What Uber Actually Does

Uber's trip state machine is significantly more complex. They have intermediate states for driver arrival confirmation, route deviation handling, stop requests, and partial ride cancellations. Their concurrency is handled not with database row versions but with distributed locks and event sourcing — every state change is an immutable event appended to a stream, and the current state is derived by replaying those events.

Their timeout system is part of a broader orchestration layer (they've written publicly about using Cadence/Temporal for this) that handles retries, compensating transactions, and saga-style distributed coordination.

What we've built is the correct structural shape: explicit states, validated transitions, optimistic concurrency, domain events as the integration mechanism. At Uber's scale, the same concepts apply with more moving parts and higher fault-tolerance requirements.

Common Mistakes

Mistake 1: Status as a raw string with no transition enforcement

// ❌ Nothing prevents any value being set
public class Trip
{
    public string Status { get; set; } = "Requested";
}

// Anywhere in the codebase...
trip.Status = "Completed"; // No validation. No events. Silent corruption.

If the status field is publicly settable, you don't have a state machine — you have a string column. Any code anywhere can put the trip into any state, bypassing every rule you thought you had.

Mistake 2: Checking status in the service instead of the aggregate

// ❌ Business rule leaking out of the domain
public async Task AssignDriverAsync(Guid tripId, string driverId)
{
    var trip = await _db.Trips.FindAsync(tripId);

    if (trip.Status != "Requested") // magic string
        throw new Exception("Cannot assign driver");

    trip.DriverId = driverId;
    trip.Status = "DriverAssigned"; // still a raw string
}

When transition logic lives in the service, it will be duplicated. The second endpoint that assigns a driver will either copy the check or forget it. The aggregate owns the rules.

Mistake 3: Dispatching events before SaveChangesAsync succeeds

// ❌ Event published before state is confirmed committed
await _events.PublishAsync(new TripCompleted(trip.Id, fare));
await db.SaveChangesAsync(); // if this fails, the event is already out

If the database write fails, the event is already in the bus. A payment handler somewhere has received TripCompleted for a trip the database doesn't recognise as completed. The rider gets charged for a trip that didn't finish.

Always save state first, publish after. But be honest with yourself: dispatching after SaveChangesAsync still leaves a gap — if the process dies after the DB write but before the publish, the event is lost. That gap is acceptable in many systems. When it isn't — when a missed payment or a missed notification is genuinely unacceptable — the fix is the Outbox Pattern described in Step 6.

Mistake 4: Ignoring DbUpdateConcurrencyException

// ❌ The exception propagates as a 500 error
trip.AssignDriver(driverId);
await db.SaveChangesAsync(); // throws DbUpdateConcurrencyException under load

Under load, concurrent modifications are expected, not exceptional. Handle them explicitly: retry with fresh state, or return a meaningful conflict response to the caller.

Mistake 5: No timeout for stuck trips

A trip stuck in Requested forever because no driver accepted is invisible without active monitoring. Add the background service. Add an alert if the timeout queue grows beyond a threshold.

Conclusion

A trip's lifecycle is a contract. It makes promises: a Completed trip was once InProgress, a Cancelled trip will never become Completed, a driver will only be assigned once. Enforcing those promises at the code level — through the aggregate's transition rules, the RowVersion concurrency token, and domain events as the integration point — is what turns a status column into a proper state machine.

The race condition from the opening isn't patched by adding more checks. It's solved structurally: the database rejects the second write at the data layer, and the retry logic handles it gracefully. No locks. No distributed coordination. Just a WHERE RowVersion = @expected clause doing its job.

In the next article we'll bring everything together: the full Uber-like system design, combining the location pipeline from Part 1 and the trip lifecycle from this article into a complete architecture with driver matching, surge pricing, and the full request flow.

Part 2 of the Uber-like System Design in .NET series.

Full source code: github.com/AdrianBailador/trip-state-machine-dotnet

Questions or suggestions? Open an issue on GitHub.

Real-time Driver Location Tracking in .NET: Redis GEO, State Buffer and SignalR

Adrián Bailador — Mon, 11 May 2026 19:51:51 +0000

Every four seconds, every active Uber driver sends their GPS coordinates to a server.

At peak, that's roughly 5 million updates per minute — before you even count the riders watching their driver move on a map in real time. The location pipeline is the heartbeat of the entire platform. If it slows down, drivers and riders fall out of sync. If it falls over, the app is effectively useless.

Building something like this in .NET is a good exercise in knowing when not to reach for a database. Location data is high-frequency, short-lived, and geospatial. A relational database would collapse under the write load. What you need is Redis.

This is the first article in a mini-series on designing an Uber-like system in .NET. Here we build the location tracking pipeline. In the next two articles we'll cover the trip state machine and the full system design.

The Problem in Concrete Terms

Before writing any code, it helps to make the numbers real:

5 million active drivers at peak, each sending a GPS update every 4 seconds
~1.25 million writes per second at the Redis layer
Riders watching a moving dot on a map — updates should feel instant (under 1 second latency)
Driver matching — when a rider requests a trip, the system needs to find available drivers within a radius in milliseconds

A naive implementation stores each update in a SQL table. After two minutes of load it becomes a 150-million-row table with a write queue backed up to the horizon. That's not the bottleneck you want to debug at 11pm.

The architecture we'll build instead:

Step 1: Modelling the Location Update

Keep it simple. A location update is a thin message:

public record LocationUpdate(
    string DriverId,
    double Latitude,
    double Longitude,
    DateTimeOffset Timestamp);

The driver sends this every four seconds. We don't store history here — that's a separate concern for analytics. What we store is current position.

Step 2: The Location State Buffer

The first instinct here is to use a queue — Channel<T>, a message bus, something that holds updates until they can be processed. That instinct is wrong for this problem.

A queue implies every item matters. In location tracking, only the latest position per driver matters. If a driver sends 10 updates while the processor is busy, 9 of them are noise — you only need the most recent. A queue retains all 10 and processes them in order; by the time it reaches update 10 it's processing history, not the present.

The right model is mutable state per driver. A ConcurrentDictionary<string, LocationUpdate> where each write simply overwrites the previous value:

public class LocationStateBuffer
{
    private readonly ConcurrentDictionary<string, LocationUpdate> _latest = new();
    private readonly ConcurrentDictionary<string, byte> _dirty = new();

    public void Update(LocationUpdate update)
    {
        _latest[update.DriverId] = update;
        _dirty[update.DriverId] = 0;
    }

    public IReadOnlyList<LocationUpdate> TakeSnapshot()
    {
        var snapshot = new List<LocationUpdate>();
        foreach (var driverId in _dirty.Keys.ToArray())
        {
            if (_dirty.TryRemove(driverId, out _) && _latest.TryGetValue(driverId, out var update))
                snapshot.Add(update);
        }
        return snapshot;
    }
}

The _dirty set tracks which drivers have sent updates since the last flush. TakeSnapshot returns only those drivers — if a driver hasn't moved, there's nothing to write to Redis. This means the flush is proportional to activity, not total driver count.

The endpoint writes are O(1) and never block regardless of what the background processor is doing:

app.MapPost("/drivers/{driverId}/location", (
    string driverId,
    LocationUpdateRequest request,
    LocationStateBuffer buffer) =>
{
    buffer.Update(new LocationUpdate(driverId, request.Latitude, request.Longitude, DateTimeOffset.UtcNow));
    return Results.Accepted();
});

No overflow. No stale updates blocking newer ones. Natural rate limiting built in — if a driver sends 10 updates between flushes, only 1 Redis write happens.

Step 3: Redis GEO

Redis has a native geospatial data type backed by sorted sets. The key commands:

GEOADD key longitude latitude member — store or update a position
GEOSEARCH key FROMMEMBER member BYRADIUS radius unit — find all members within a radius
GEOPOS key member — get the current position of a member

In StackExchange.Redis:

public class RedisLocationStore
{
    private readonly IDatabase _db;
    private const string DriversKey = "drivers:locations";

    public RedisLocationStore(IConnectionMultiplexer redis)
    {
        _db = redis.GetDatabase();
    }

    public async Task UpdateAsync(LocationUpdate update)
    {
        await _db.GeoAddAsync(DriversKey, new GeoEntry(
            longitude: update.Longitude,
            latitude: update.Latitude,
            member: update.DriverId));
    }

    public async Task<IEnumerable<NearbyDriver>> FindNearbyAsync(
        double latitude,
        double longitude,
        double radiusKm)
    {
        var results = await _db.GeoSearchAsync(
            DriversKey,
            longitude, latitude,
            new GeoSearchCircle(radiusKm, GeoUnit.Kilometers),
            options: GeoRadiusOptions.WithDistance | GeoRadiusOptions.WithCoordinates);

        return results.Select(r => new NearbyDriver(
            DriverId: r.Member.ToString(),
            DistanceKm: r.Distance ?? 0,
            Latitude: r.Position?.Latitude ?? 0,
            Longitude: r.Position?.Longitude ?? 0));
    }
}

public record NearbyDriver(string DriverId, double DistanceKm, double Latitude, double Longitude);

GEOSEARCH returns drivers sorted by distance and is fast enough to query on every rider request — it runs in O(N+log(M)) where N is the result set size, not the total driver count.

One important note: Redis GEO stores positions as compressed floats, so there's a small precision loss (~0.6mm error). For navigation that's irrelevant. What matters is that a GEOSEARCH returning the 10 nearest drivers within 5km finishes in under a millisecond even with millions of stored positions.

Step 4: The Background Processor

The BackgroundService flushes the state buffer to Redis every 500ms using PeriodicTimer:

public class LocationProcessorService : BackgroundService
{
    private readonly LocationStateBuffer _buffer;
    private readonly ILocationStore _store;
    private readonly IHubContext<DriverLocationHub> _hub;
    private readonly ILogger<LocationProcessorService> _logger;

    private static readonly TimeSpan FlushInterval = TimeSpan.FromMilliseconds(500);

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(FlushInterval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            var updates = _buffer.TakeSnapshot();
            if (updates.Count == 0) continue;

            foreach (var update in updates)
            {
                try
                {
                    await _store.UpdateAsync(update);

                    await _hub.Clients
                        .Group($"watching:{update.DriverId}")
                        .SendAsync("DriverMoved", new
                        {
                            update.DriverId,
                            update.Latitude,
                            update.Longitude,
                            update.Timestamp
                        }, stoppingToken);
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Failed flushing location for driver {DriverId}", update.DriverId);
                }
            }
        }
    }
}

PeriodicTimer is the idiomatic .NET 6+ way to run periodic work in a hosted service — it doesn't drift (each tick is measured from the previous tick's start, not end) and cancellation is handled automatically.

Each flush only touches drivers that sent updates since the last tick. If no driver moved, TakeSnapshot returns an empty list and the loop skips immediately. The Redis write and SignalR push are independent — a failed push doesn't block the Redis update, and a single missed UI notification is invisible to the rider.

Step 5: SignalR Hub

The rider opens a WebSocket connection when they're watching a trip. They join a group named after the driver they're tracking:

public class DriverLocationHub : Hub
{
    public async Task WatchDriver(string driverId)
    {
        // Leave any previous group first
        var previousDriver = Context.Items["watchingDriver"] as string;
        if (previousDriver is not null)
            await Groups.RemoveFromGroupAsync(Context.ConnectionId, $"watching:{previousDriver}");

        await Groups.AddToGroupAsync(Context.ConnectionId, $"watching:{driverId}");
        Context.Items["watchingDriver"] = driverId;
    }

    public async Task StopWatching()
    {
        var driverId = Context.Items["watchingDriver"] as string;
        if (driverId is not null)
            await Groups.RemoveFromGroupAsync(Context.ConnectionId, $"watching:{driverId}");
    }
}

On the client side (minimal TypeScript):

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/hubs/driver-location")
    .withAutomaticReconnect()
    .build();

connection.on("DriverMoved", (data) => {
    updateDriverMarker(data.driverId, data.latitude, data.longitude);
});

await connection.start();
await connection.invoke("WatchDriver", driverId);

The withAutomaticReconnect() is critical: mobile connections drop constantly. Without it, a brief network hiccup leaves the rider with a frozen map and no indication anything is wrong.

Step 6: Wiring It Up

var builder = WebApplication.CreateBuilder(args);

// Redis
var redis = await ConnectionMultiplexer.ConnectAsync(builder.Configuration["Redis:ConnectionString"]!);
builder.Services.AddSingleton<IConnectionMultiplexer>(redis);
builder.Services.AddSingleton<ILocationStore, RedisLocationStore>();

// Location state buffer — mutable per-driver state, flushed periodically
builder.Services.AddSingleton<LocationStateBuffer>();

// SignalR — add .AddStackExchangeRedis(...) when scaling horizontally
builder.Services.AddSignalR();

// Background processor
builder.Services.AddHostedService<LocationProcessorService>();

var app = builder.Build();

app.MapPost("/drivers/{driverId}/location", (
    string driverId,
    LocationUpdateRequest request,
    LocationStateBuffer buffer) =>
{
    buffer.Update(new LocationUpdate(driverId, request.Latitude, request.Longitude, DateTimeOffset.UtcNow));
    return Results.Accepted();
});

app.MapHub<DriverLocationHub>("/hubs/driver-location");

app.MapGet("/drivers/nearby", async (
    double lat, double lon, double radius,
    ILocationStore store) =>
{
    var drivers = await store.FindNearbyAsync(lat, lon, radius);
    return Results.Ok(drivers);
});

app.Run();

Handling Scale

The single-instance version above works fine up to a few thousand concurrent drivers. When you need to scale horizontally, two things change:

SignalR backplane. By default SignalR only pushes to connections on the same server instance. With multiple instances, a driver update arriving at instance A won't reach a rider connected to instance B. The fix is a Redis backplane:

builder.Services.AddSignalR()
    .AddStackExchangeRedis(builder.Configuration["Redis:ConnectionString"]!);

One line, and SignalR uses Redis pub/sub to fan out messages across all instances.

The state buffer is per-instance. LocationStateBuffer is in-memory — it doesn't survive restarts and doesn't span instances. For this use case that's fine: drivers resend their position every 4 seconds, so after a restart the buffer refills in seconds and no user-visible impact occurs.

What Uber Actually Does

Uber's real architecture is more complex — they use a custom geospatial sharding system called H3 (hexagonal hierarchical geospatial indexing), partition driver updates by city and region, and process location data through a streaming pipeline (Apache Kafka → Flink). Their dispatch system is a separate service with its own matching algorithm.

What we've built captures the essential shape: a fast write path that doesn't block on persistence, a Redis geospatial index that answers "who's nearby?" in milliseconds, and a WebSocket channel that keeps the rider map live.

The differences are scale and operational complexity, not architectural direction. The building blocks are the same.

Common Mistakes

Mistake 1: Writing location directly to SQL

// ❌ Every GPS update hits the database
await _dbContext.DriverLocations.AddAsync(new DriverLocation
{
    DriverId = update.DriverId,
    Latitude = update.Latitude,
    Longitude = update.Longitude,
    Timestamp = update.Timestamp
});
await _dbContext.SaveChangesAsync();

This works in development and collapses in production. Location is ephemeral data — you only need the current position, not every position. If you need history for analytics, write to a time-series store or an append-only stream asynchronously, not inline in the request path.

Mistake 2: Blocking the HTTP thread on Redis

// ❌ Driver request blocks until Redis confirms the write
await _redis.GeoAddAsync(DriversKey, new GeoEntry(lon, lat, driverId));
return Results.Ok();

Redis is fast, but adding network I/O to every driver request serialises your throughput. The state buffer decouples the HTTP response time from the Redis write time — the driver gets 202 in microseconds and Redis catches up on the next flush tick.

Mistake 3: Using a queue when you need mutable state

// ❌ Channel queues every update — processes stale positions
Channel.CreateBounded<LocationUpdate>(new BoundedChannelOptions(10_000)
{
    FullMode = BoundedChannelFullMode.DropOldest
});

A queue with DropOldest drops unpredictably under load and processes intermediate positions that are already outdated by the time the consumer reaches them. Location tracking is a state problem, not a message-passing problem. Model it as state.

Mistake 4: One SignalR group per trip instead of per driver

// ❌ Naming the group after the trip
await Groups.AddToGroupAsync(connectionId, $"trip:{tripId}");

Trip IDs change across retries and reassignments. Driver IDs don't. Name the group after the driver and the rider joins/leaves as the assignment changes.

Mistake 5: Forgetting the backplane when scaling SignalR

// ❌ Multiple instances, no backplane
// Driver updates arrive at instance A, rider is connected to instance B
// → rider map freezes
builder.Services.AddSignalR(); // missing .AddStackExchangeRedis(...)

This is the most common production bug in SignalR deployments. Everything works on a single instance in development and silently breaks when you scale to two.

Conclusion

The location tracking pipeline is a good example of matching the abstraction to the problem. GPS updates are high-frequency, short-lived, and geospatial — so we model them as mutable state (not a queue), index them in Redis GEO (not a relational table), and push changes in real time via SignalR (not polling).

None of this required a heavy framework or a distributed systems PhD. It's a ConcurrentDictionary, a Redis sorted set, and a WebSocket group — standard .NET primitives composed to handle a genuinely hard scale problem.

In the next article we'll build the trip state machine: how a ride moves from Requested to Completed, how to handle concurrent state transitions, and how to persist the lifecycle with EF Core.

Part 1 of the Uber-like System Design in .NET series.

Full source code: github.com/AdrianBailador/realtime-driver-location-dotnet

Questions or suggestions? Open an issue on GitHub.

CQRS Without MediatR: Hand-Rolled Command and Query Handlers in .NET

Adrián Bailador — Mon, 04 May 2026 09:56:45 +0000

For years, opening a new .NET project meant the same opening ritual: dotnet add package MediatR. The library became so synonymous with CQRS in the .NET community that many developers couldn't tell where the pattern ended and the package began.

Then MediatR moved to a commercial license. Suddenly, every team that had built their architecture around it was asking the same question: do we actually need this?

This isn't a criticism of MediatR or of Jimmy Bogard — the library shaped how a generation of .NET developers think about handlers, pipelines, and clean separation of concerns, and the community owes him a real debt. The licensing change is just an opportunity to look at what's underneath, and to notice how little of it actually needs to be a library at all.

Most teams don't need MediatR. CQRS is a pattern, not a library — and the .NET DI container has everything you need to implement it cleanly. This article shows how.

What CQRS Actually Is

Command Query Responsibility Segregation has two parts:

Commands change state. They have side effects. They might return a result, but their primary purpose is to modify the system.
Queries read state. They have no side effects. They return data and nothing else.

That's it. Everything else — the dispatcher, the handlers, the pipeline behaviors — is implementation detail. None of it requires a library.

The reason MediatR became the default is convenience: it gave you handler discovery, a dispatcher, and a behavior pipeline in three lines of Program.cs. But all of those things are about ten lines of code each, and writing them yourself gives you something MediatR never could: full control over the abstraction.

The Minimal Abstraction

Start with two interface families. One for commands, one for queries.

// Marker interfaces — they exist only for the type system
public interface ICommand { }
public interface ICommand<TResult> { }

public interface IQuery<TResult> { }

// Handlers
public interface ICommandHandler<TCommand>
    where TCommand : ICommand
{
    Task HandleAsync(TCommand command, CancellationToken ct = default);
}

public interface ICommandHandler<TCommand, TResult>
    where TCommand : ICommand<TResult>
{
    Task<TResult> HandleAsync(TCommand command, CancellationToken ct = default);
}

public interface IQueryHandler<TQuery, TResult>
    where TQuery : IQuery<TResult>
{
    Task<TResult> HandleAsync(TQuery query, CancellationToken ct = default);
}

Five interfaces. No external dependencies. No reflection magic. The compiler enforces the relationship between commands, queries, and their handlers.

A note on the empty ICommand and IQuery interfaces: some developers consider marker interfaces an anti-pattern, and in many cases they're right — an attribute or a naming convention is usually enough. Here, they earn their keep. They give the assembly scanner an unambiguous anchor (AssignableTo(typeof(ICommand<>)) is impossible without them), and they let the dispatcher constrain its generic parameters so misuse is a compile error instead of a runtime one. They're not decoration — they're the type-system contract that makes everything else type-safe.

A concrete command and handler look like this:

public record CreateOrder(string CustomerEmail, List<OrderLine> Lines) : ICommand<OrderId>;

public class CreateOrderHandler : ICommandHandler<CreateOrder, OrderId>
{
    private readonly IOrderRepository _orders;
    private readonly IEventBus _events;

    public CreateOrderHandler(IOrderRepository orders, IEventBus events)
    {
        _orders = orders;
        _events = events;
    }

    public async Task<OrderId> HandleAsync(CreateOrder command, CancellationToken ct = default)
    {
        var order = Order.Create(command.CustomerEmail, command.Lines);

        await _orders.SaveAsync(order, ct);
        await _events.PublishAsync(new OrderCreated(order.Id), ct);

        return order.Id;
    }
}

And a query:

public record GetOrderById(Guid OrderId) : IQuery<OrderDto?>;

public class GetOrderByIdHandler : IQueryHandler<GetOrderById, OrderDto?>
{
    private readonly IOrderReadModel _reads;

    public GetOrderByIdHandler(IOrderReadModel reads)
    {
        _reads = reads;
    }

    public Task<OrderDto?> HandleAsync(GetOrderById query, CancellationToken ct = default)
        => _reads.GetByIdAsync(query.OrderId, ct);
}

That's the entire pattern. Everything from here on is plumbing.

The Dispatcher

The dispatcher resolves the handler for a given command or query and invokes it. It exists so callers don't have to inject every handler they want to use — they inject one dispatcher and send messages through it.

public interface ICommandDispatcher
{
    Task SendAsync(ICommand command, CancellationToken ct = default);
    Task<TResult> SendAsync<TResult>(ICommand<TResult> command, CancellationToken ct = default);
}

public interface IQueryDispatcher
{
    Task<TResult> SendAsync<TResult>(IQuery<TResult> query, CancellationToken ct = default);
}

The implementation is short. It uses the runtime type of the message to find the right handler in the DI container.

public class CommandDispatcher : ICommandDispatcher
{
    private readonly IServiceProvider _provider;

    public CommandDispatcher(IServiceProvider provider)
    {
        _provider = provider;
    }

    public Task SendAsync(ICommand command, CancellationToken ct = default)
    {
        var handlerType = typeof(ICommandHandler<>).MakeGenericType(command.GetType());
        dynamic handler = _provider.GetRequiredService(handlerType);
        return handler.HandleAsync((dynamic)command, ct);
    }

    public Task<TResult> SendAsync<TResult>(ICommand<TResult> command, CancellationToken ct = default)
    {
        var handlerType = typeof(ICommandHandler<,>)
            .MakeGenericType(command.GetType(), typeof(TResult));
        dynamic handler = _provider.GetRequiredService(handlerType);
        return handler.HandleAsync((dynamic)command, ct);
    }
}

public class QueryDispatcher : IQueryDispatcher
{
    private readonly IServiceProvider _provider;

    public QueryDispatcher(IServiceProvider provider)
    {
        _provider = provider;
    }

    public Task<TResult> SendAsync<TResult>(IQuery<TResult> query, CancellationToken ct = default)
    {
        var handlerType = typeof(IQueryHandler<,>)
            .MakeGenericType(query.GetType(), typeof(TResult));
        dynamic handler = _provider.GetRequiredService(handlerType);
        return handler.HandleAsync((dynamic)query, ct);
    }
}

The dynamic calls are the trick. Without them you'd need reflection (MethodInfo.Invoke) and the cost is similar — but dynamic keeps the code readable and the call site cached after the first invocation.

If you want to avoid dynamic entirely, the alternative is one extra method per generic arity using MethodInfo.Invoke. The performance difference is negligible for everything except hot loops, and CQRS handlers are not a hot loop. From .NET 8 onwards, the JIT compiler is remarkably good at devirtualising and inlining generic dispatch — the "hand-rolled" version performs identically to MediatR for the vast majority of applications, which is one more reason not to be intimidated by writing this yourself.

One subtlety worth flagging in the dispatcher code: command.GetType() returns the runtime type of the command instance. If you build a command hierarchy where a derived class is sent through the pipeline but only a handler for the base type is registered, the resolution will fail at runtime — the container looks for a handler of the concrete type. In practice this is rarely a problem because commands are usually sealed record types, but it's worth knowing if you ever consider sharing handlers across command variants.

Wiring Everything Up

You need three things in Program.cs:

Register the dispatchers
Register all handlers
(Optionally) register pipeline behaviors

Manual registration works for small projects:

builder.Services.AddScoped<ICommandDispatcher, CommandDispatcher>();
builder.Services.AddScoped<IQueryDispatcher, QueryDispatcher>();

builder.Services.AddScoped<ICommandHandler<CreateOrder, OrderId>, CreateOrderHandler>();
builder.Services.AddScoped<IQueryHandler<GetOrderById, OrderDto?>, GetOrderByIdHandler>();
// ...one line per handler

This works, but for a real codebase you want auto-registration. The cleanest way is Scrutor, which adds assembly scanning to the standard DI container.

builder.Services.AddScoped<ICommandDispatcher, CommandDispatcher>();
builder.Services.AddScoped<IQueryDispatcher, QueryDispatcher>();

builder.Services.Scan(scan => scan
    .FromAssemblyOf<CreateOrder>()
    .AddClasses(c => c.AssignableTo(typeof(ICommandHandler<>)))
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(c => c.AssignableTo(typeof(ICommandHandler<,>)))
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(c => c.AssignableTo(typeof(IQueryHandler<,>)))
        .AsImplementedInterfaces()
        .WithScopedLifetime());

Three blocks of scanning, and every handler in your project is registered. Adding a new handler means writing the class — no Program.cs change required.

If you don't want a Scrutor dependency, you can scan manually with reflection:

public static IServiceCollection AddCqrsHandlers(this IServiceCollection services, Assembly assembly)
{
    var handlerInterfaces = new[]
    {
        typeof(ICommandHandler<>),
        typeof(ICommandHandler<,>),
        typeof(IQueryHandler<,>)
    };

    var handlerTypes = assembly.GetTypes()
        .Where(t => !t.IsAbstract && !t.IsInterface)
        .SelectMany(t => t.GetInterfaces()
            .Where(i => i.IsGenericType && handlerInterfaces.Contains(i.GetGenericTypeDefinition()))
            .Select(i => new { Implementation = t, Service = i }));

    foreach (var handler in handlerTypes)
        services.AddScoped(handler.Service, handler.Implementation);

    return services;
}

Call it once: builder.Services.AddCqrsHandlers(typeof(CreateOrder).Assembly);. About thirty lines of code that replaces an entire dependency.

Pipeline Behaviors Without Magic

This is where most people assume they need MediatR. They don't. The decorator pattern + Scrutor gives you the same thing with no surprises.

Suppose you want every command to be logged and validated. Define behaviors as decorators of ICommandHandler<,>:

public class LoggingCommandHandler<TCommand, TResult> : ICommandHandler<TCommand, TResult>
    where TCommand : ICommand<TResult>
{
    private readonly ICommandHandler<TCommand, TResult> _inner;
    private readonly ILogger<TCommand> _logger;

    public LoggingCommandHandler(ICommandHandler<TCommand, TResult> inner, ILogger<TCommand> logger)
    {
        _inner = inner;
        _logger = logger;
    }

    public async Task<TResult> HandleAsync(TCommand command, CancellationToken ct = default)
    {
        var sw = Stopwatch.StartNew();
        _logger.LogInformation("Handling {Command}", typeof(TCommand).Name);

        try
        {
            var result = await _inner.HandleAsync(command, ct);
            _logger.LogInformation("Handled {Command} in {Elapsed}ms", typeof(TCommand).Name, sw.ElapsedMilliseconds);
            return result;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed handling {Command} after {Elapsed}ms", typeof(TCommand).Name, sw.ElapsedMilliseconds);
            throw;
        }
    }
}

public class ValidationCommandHandler<TCommand, TResult> : ICommandHandler<TCommand, TResult>
    where TCommand : ICommand<TResult>
{
    private readonly ICommandHandler<TCommand, TResult> _inner;
    private readonly IEnumerable<IValidator<TCommand>> _validators;

    public ValidationCommandHandler(
        ICommandHandler<TCommand, TResult> inner,
        IEnumerable<IValidator<TCommand>> validators)
    {
        _inner = inner;
        _validators = validators;
    }

    public async Task<TResult> HandleAsync(TCommand command, CancellationToken ct = default)
    {
        var failures = _validators
            .Select(v => v.Validate(command))
            .SelectMany(r => r.Errors)
            .Where(e => e is not null)
            .ToList();

        if (failures.Count != 0)
            throw new ValidationException(failures);

        return await _inner.HandleAsync(command, ct);
    }
}

Wire them with Scrutor.Decorate:

builder.Services.Decorate(typeof(ICommandHandler<,>), typeof(ValidationCommandHandler<,>));
builder.Services.Decorate(typeof(ICommandHandler<,>), typeof(LoggingCommandHandler<,>));

Order matters: the last Decorate call is the outermost layer. With the configuration above, every command flows through Logging → Validation → actual handler.

The benefit over MediatR's IPipelineBehavior is that you can see exactly what's happening. There's no next() delegate hiding behind a generic type — just plain decorators with their dependencies visible at the constructor.

Skipping the Dispatcher in Minimal APIs

Here's a question worth asking: do you even need the dispatcher?

If you're using Minimal APIs, the endpoint handler is already a function with access to DI. You can inject the command handler directly:

app.MapPost("/orders", async (
    CreateOrder command,
    ICommandHandler<CreateOrder, OrderId> handler,
    CancellationToken ct) =>
{
    var orderId = await handler.HandleAsync(command, ct);
    return Results.Created($"/orders/{orderId.Value}", new { orderId });
});

app.MapGet("/orders/{id:guid}", async (
    Guid id,
    IQueryHandler<GetOrderById, OrderDto?> handler,
    CancellationToken ct) =>
{
    var dto = await handler.HandleAsync(new GetOrderById(id), ct);
    return dto is null ? Results.NotFound() : Results.Ok(dto);
});

No dispatcher, no dynamic, no runtime type resolution. The compiler knows exactly which handler is being injected. Decorators still apply because they wrap the registered handler interface.

When does the dispatcher earn its keep? When you have callers that don't know the concrete command type at compile time — background workers reading from a queue, retry pipelines, or generic API endpoints that map a JSON envelope to a command. For typed endpoints, direct injection is simpler and faster.

A reasonable default: skip the dispatcher in your web layer, keep it for infrastructure code that handles message envelopes.

What You Lose Without MediatR

It's worth being honest about this:

Notification publishing. MediatR's IPublisher lets one event fan out to multiple handlers. If you need this, write it — it's about twenty lines.

public interface IDomainEventPublisher
{
    Task PublishAsync<TEvent>(TEvent @event, CancellationToken ct = default)
        where TEvent : IDomainEvent;
}

public class DomainEventPublisher : IDomainEventPublisher
{
    private readonly IServiceProvider _provider;

    public DomainEventPublisher(IServiceProvider provider) => _provider = provider;

    public async Task PublishAsync<TEvent>(TEvent @event, CancellationToken ct = default)
        where TEvent : IDomainEvent
    {
        var handlers = _provider.GetServices<IDomainEventHandler<TEvent>>();
        foreach (var handler in handlers)
            await handler.HandleAsync(@event, ct);
    }
}

Streaming requests. IStreamRequestHandler returns IAsyncEnumerable. If you need streaming, define an interface for it. Most apps don't.

Community familiarity. New developers will recognise MediatR. A custom abstraction means a paragraph in the README.

What you gain: no third-party dependency, no licensing concerns, no upgrade treadmill, total transparency about how messages get from sender to handler. For most projects, that's a fair trade.

Common Mistakes

Mistake 1: Treating CQRS as Two Databases

CQRS doesn't require separate read and write models, separate databases, or eventual consistency. Those are choices that can be made on top of CQRS, but the pattern itself is just about separating commands from queries at the code level.

You can have one database, one ORM, one set of tables, and still benefit from the separation. CreateOrderHandler writes through EF Core; GetOrderByIdHandler reads through Dapper. Same database, different optimisation strategies.

Mistake 2: Putting Logic in Commands or Queries

// ❌ Command with logic
public record CreateOrder(...)
{
    public bool IsValid() => Lines.Count > 0 && CustomerEmail.Contains("@");
    public decimal CalculateTotal() => Lines.Sum(l => l.Price * l.Quantity);
}

Commands and queries are messages. They carry data; they don't process it. All logic belongs in the handler or the domain. If a record starts growing methods, you've created a hidden service.

Mistake 3: Handlers That Call Other Handlers

// ❌ Handler invoking another handler
public class CreateOrderHandler : ICommandHandler<CreateOrder, OrderId>
{
    private readonly ICommandDispatcher _dispatcher;

    public async Task<OrderId> HandleAsync(CreateOrder command, CancellationToken ct = default)
    {
        var customerId = await _dispatcher.SendAsync(new EnsureCustomerExists(command.CustomerEmail), ct);
        // ...
    }
}

This is how you end up with implicit dependency graphs nobody can trace. If CreateOrderHandler needs to ensure a customer exists, inject ICustomerService and call a method. Handlers should be leaves of the call tree, not branches.

Mistake 4: Reusing Commands as DTOs

The shape that arrives from the API is rarely the shape your handler should accept. Validate, transform, and then construct the command:

// ❌ Treating the request body as a command
app.MapPost("/orders", (CreateOrderRequest req, ICommandDispatcher d) =>
    d.SendAsync(new CreateOrder(req.Email, req.Lines)));

If CreateOrderRequest and CreateOrder end up identical, that's fine — but they're allowed to diverge, and that ability is what makes the pattern useful.

Best Practices

Keep commands and queries flat. A command should be a record with primitive or value-object fields. If you're nesting domain entities inside, you're sending state through a command bus instead of identifiers.

One handler per command. Multiple handlers per command create ordering and ownership questions that don't have good answers. If you need fan-out, that's an event, not a command.

Make handlers thin. A handler orchestrates: load aggregate, call domain method, save, publish events. The domain method does the work. If your handler is 80 lines of logic, the logic belongs in the domain.

Test handlers as units. Handlers are easy to test — they're just classes with constructor dependencies. Mock the repository, call HandleAsync, assert the result and the side effects.

[Fact]
public async Task CreateOrderHandler_PersistsOrder_AndPublishesEvent()
{
    var orders = Substitute.For<IOrderRepository>();
    var events = Substitute.For<IEventBus>();
    var handler = new CreateOrderHandler(orders, events);

    var result = await handler.HandleAsync(new CreateOrder("a@b.com", [new OrderLine("SKU1", 1, 10)]));

    await orders.Received(1).SaveAsync(Arg.Any<Order>(), Arg.Any<CancellationToken>());
    await events.Received(1).PublishAsync(Arg.Any<OrderCreated>(), Arg.Any<CancellationToken>());
}

Keep your dispatcher dumb. Resist the urge to add caching, retries, or "smart" routing inside the dispatcher. Those are decorators, registered as such. The dispatcher's job is to find a handler and invoke it.

When MediatR Still Makes Sense

The licensing change is real, but if your team already pays for the commercial license and has years of code built around it, ripping it out is rarely the right call. The pattern doesn't change — just the package.

There are also legitimate alternatives if you want a maintained library: Wolverine, Brighter, and MassTransit all do CQRS with extras (durable messaging, sagas, transports). They're worth a look if you're crossing process boundaries.

But for the vast majority of monoliths and modular monoliths, the code in this article is the entire toolkit. Five interfaces, two dispatchers, decorator-based pipeline. No third-party dependency, no breaking changes to track, no surprises about how messages reach their handlers.

Conclusion

CQRS was always a pattern about separating writes from reads, not a library about routing messages. MediatR's commercial pivot was a useful forcing function — it made teams ask whether they actually needed the indirection, and a lot of them realised they didn't.

The hand-rolled version isn't a downgrade. It's the same pattern with the implementation visible. You can read every line of how a command reaches its handler. You can step through it in the debugger. You can change it when your needs change. The DI container does the heavy lifting; the rest is interfaces and a decorator or two.

If your codebase already has MediatR and works well, leave it. If you're starting fresh, or if licensing is a problem, this is a clean alternative — and you'll probably find that explicit handlers are easier to reason about than a generic mediator anyway.

The pattern was never the package. The package was just the convenience.

Full source code: github.com/AdrianBailador/cqrs-without-mediatr-dotnet

Questions or suggestions? Open an issue on GitHub.

Anti-Corruption Layer in .NET: Protecting Your Domain from External APIs

Adrián Bailador — Sun, 26 Apr 2026 10:55:26 +0000

We had a clean domain. Orders, customers, payments — all modelled carefully, all speaking the same language. Then we integrated with a payment provider.

Six months later, the PaymentStatus enum had values like PSPCONFIRMED, PSPREJECTED_RETRY, and AUTHORISED_3DS. Our Order entity had a StripeChargeId field. Our service layer was calling MapFromStripeWebhookPayload(). And every developer who touched payments had to understand Stripe's object model before they could understand ours.

The domain hadn't changed. But it had been contaminated.

The Anti-Corruption Layer is the pattern that prevents this. Here's how it works and how to implement it in .NET.

What Is the Anti-Corruption Layer?

The term comes from Eric Evans' Domain-Driven Design. When two systems need to communicate, the boundary between them is dangerous. The external system has its own model, its own vocabulary, its own assumptions about the world — and if you let those concepts bleed into your domain, you end up modelling their world instead of yours.

The Anti-Corruption Layer (ACL) is a translation boundary. It sits between your domain and the external system, converting the external model into your domain model — and vice versa. Your domain never sees the external types. The external system never sees your domain types.

It's not just a mapper. It's an architectural boundary that says: everything on this side speaks our language, everything on that side speaks theirs, and this layer translates between the two.

The Difference Between ACL and Adapter Pattern

You already know the Adapter Pattern — it wraps an incompatible interface to make it compatible. The ACL does something deeper: it translates between two different conceptual models, not just two different interfaces.

An Adapter changes the shape of a call. An ACL changes the meaning.

	Adapter Pattern	Anti-Corruption Layer
Purpose	Interface compatibility	Conceptual model translation
Operates at	Infrastructure level	Domain boundary
Handles	Method signatures	Domain concepts and language
Complexity	Low	Medium-high

In practice, an ACL often uses adapters internally — but its intent is model translation, not interface adaptation.

The Problem Without an ACL

Let's start with the contamination. You're building an e-commerce platform and integrating with a payment provider. Without an ACL, this is what happens:

// ❌ Domain entity contaminated by external concepts
public class Order
{
    public Guid Id { get; private set; }
    public decimal Total { get; private set; }

    // Stripe concepts leaking into the domain
    public string? StripePaymentIntentId { get; set; }
    public string? StripeCustomerId { get; set; }
    public string? StripeStatus { get; set; }  // "requires_payment_method", "succeeded", etc.
}

// ❌ Service layer that understands Stripe better than your own domain
public class OrderService
{
    private readonly StripeClient _stripe;

    public async Task ProcessPaymentAsync(Guid orderId, string paymentMethodId)
    {
        var order = await _repository.GetByIdAsync(orderId);

        // Stripe-specific logic inside domain service
        var paymentIntent = await _stripe.PaymentIntents.CreateAsync(new PaymentIntentCreateOptions
        {
            Amount = (long)(order.Total * 100), // Stripe uses cents
            Currency = "gbp",
            PaymentMethod = paymentMethodId,
            Confirm = true,
        });

        // Mapping Stripe statuses directly in domain logic
        order.StripePaymentIntentId = paymentIntent.Id;
        order.StripeStatus = paymentIntent.Status;

        if (paymentIntent.Status == "succeeded")
            order.MarkAsPaid();
        else if (paymentIntent.Status == "requires_action")
            order.MarkAsAwaitingAction();
    }
}

The problems:

Your domain knows what a PaymentIntent is. It shouldn't.
Every developer needs to know Stripe's status strings to understand your order logic.
If you switch payment providers, you rewrite the domain.
If Stripe renames a status, you hunt through domain code to find the references.

Building the Anti-Corruption Layer

The ACL has three responsibilities:

Translate external models into domain models
Isolate domain code from external API contracts
Absorb changes — when the external API changes, only the ACL changes

Step 1: Define Your Domain Model

First, define what your domain needs, in your language:

// Your domain concepts — no external dependencies
public record Payment
{
    public PaymentId Id { get; init; }
    public Money Amount { get; init; }
    public PaymentStatus Status { get; init; }
    public PaymentProvider Provider { get; init; }
    public string ExternalReference { get; init; } = string.Empty;
    public DateTimeOffset ProcessedAt { get; init; }
}

public enum PaymentStatus
{
    Pending,
    Authorised,
    Captured,
    Declined,
    RequiresAction,
    Refunded
}

public enum PaymentProvider
{
    Stripe,
    PayPal
}

public record Money(decimal Amount, string Currency)
{
    public static Money GBP(decimal amount) => new(amount, "GBP");
    public static Money USD(decimal amount) => new(amount, "USD");
}

public record PaymentId(string Value)
{
    public static PaymentId New() => new(Guid.NewGuid().ToString());
}

Step 2: Define the Domain Port

The domain declares what it needs through an interface — it doesn't care how it's implemented:

// The domain's view of payment processing — no external types
public interface IPaymentGateway
{
    Task<PaymentResult> ChargeAsync(PaymentRequest request, CancellationToken ct = default);
    Task<PaymentResult> RefundAsync(string externalReference, Money amount, CancellationToken ct = default);
    Task<Payment?> GetPaymentAsync(string externalReference, CancellationToken ct = default);
}

public record PaymentRequest(
    Money Amount,
    string PaymentMethodToken,
    string OrderReference,
    string CustomerEmail);

public record PaymentResult(
    bool Success,
    Payment? Payment,
    string? ErrorMessage,
    bool RequiresAction,
    string? ActionUrl);

Step 3: Implement the ACL Translator

This is the heart of the pattern. The ACL implementation knows about Stripe — but your domain never will:

// Infrastructure layer — the only place that knows about Stripe
public class StripePaymentGateway : IPaymentGateway
{
    private readonly PaymentIntentService _paymentIntentService;
    private readonly RefundService _refundService;
    private readonly ILogger<StripePaymentGateway> _logger;

    public StripePaymentGateway(
        PaymentIntentService paymentIntentService,
        RefundService refundService,
        ILogger<StripePaymentGateway> logger)
    {
        _paymentIntentService = paymentIntentService;
        _refundService = refundService;
        _logger = logger;
    }

    public async Task<PaymentResult> ChargeAsync(
        PaymentRequest request,
        CancellationToken ct = default)
    {
        try
        {
            // Translate domain request → Stripe request
            var options = TranslateToStripeOptions(request);
            var intent = await _paymentIntentService.CreateAsync(options, cancellationToken: ct);

            // Translate Stripe response → domain Payment
            var payment = TranslateFromStripe(intent);
            var requiresAction = intent.Status == "requires_action";

            return new PaymentResult(
                Success: intent.Status is "succeeded" or "requires_action",
                Payment: payment,
                ErrorMessage: null,
                RequiresAction: requiresAction,
                ActionUrl: intent.NextAction?.RedirectToUrl?.Url);
        }
        catch (StripeException ex)
        {
            _logger.LogWarning(ex, "Stripe charge failed for order {OrderReference}", request.OrderReference);

            // Translate Stripe error → domain result
            return new PaymentResult(
                Success: false,
                Payment: null,
                ErrorMessage: TranslateStripeError(ex.StripeError),
                RequiresAction: false,
                ActionUrl: null);
        }
    }

    public async Task<PaymentResult> RefundAsync(
        string externalReference,
        Money amount,
        CancellationToken ct = default)
    {
        try
        {
            var refund = await _refundService.CreateAsync(new RefundCreateOptions
            {
                PaymentIntent = externalReference,
                Amount = ToStripeCents(amount),
            }, cancellationToken: ct);

            return new PaymentResult(
                Success: refund.Status == "succeeded",
                Payment: null,
                ErrorMessage: null,
                RequiresAction: false,
                ActionUrl: null);
        }
        catch (StripeException ex)
        {
            _logger.LogError(ex, "Stripe refund failed for {ExternalReference}", externalReference);
            return new PaymentResult(false, null, TranslateStripeError(ex.StripeError), false, null);
        }
    }

    public async Task<Payment?> GetPaymentAsync(
        string externalReference,
        CancellationToken ct = default)
    {
        try
        {
            var intent = await _paymentIntentService.GetAsync(externalReference, cancellationToken: ct);
            return TranslateFromStripe(intent);
        }
        catch (StripeException ex) when (ex.HttpStatusCode == System.Net.HttpStatusCode.NotFound)
        {
            return null;
        }
    }

    // ── Translation methods ───────────────────────────────────────────────────
    // These are the core of the ACL. All Stripe-specific knowledge lives here.

    private static PaymentIntentCreateOptions TranslateToStripeOptions(PaymentRequest request) =>
        new()
        {
            Amount = ToStripeCents(request.Amount),
            Currency = request.Amount.Currency.ToLowerInvariant(),
            PaymentMethod = request.PaymentMethodToken,
            Confirm = true,
            ReceiptEmail = request.CustomerEmail,
            Metadata = new Dictionary<string, string>
            {
                ["order_reference"] = request.OrderReference
            }
        };

    private static Payment TranslateFromStripe(PaymentIntent intent) =>
        new()
        {
            Id = new PaymentId(intent.Id),
            Amount = new Money(intent.Amount / 100m, intent.Currency.ToUpperInvariant()),
            Status = TranslateStripeStatus(intent.Status),
            Provider = PaymentProvider.Stripe,
            ExternalReference = intent.Id,
            ProcessedAt = intent.Created
        };

    private static PaymentStatus TranslateStripeStatus(string stripeStatus) =>
        stripeStatus switch
        {
            "requires_payment_method" => PaymentStatus.Pending,
            "requires_confirmation"   => PaymentStatus.Pending,
            "requires_action"         => PaymentStatus.RequiresAction,
            "processing"              => PaymentStatus.Pending,
            "succeeded"               => PaymentStatus.Captured,
            "canceled"                => PaymentStatus.Declined,
            _ => PaymentStatus.Pending
        };

    private static string TranslateStripeError(StripeError? error) =>
        error?.Code switch
        {
            "card_declined"           => "Your card was declined.",
            "insufficient_funds"      => "Insufficient funds on your card.",
            "incorrect_cvc"           => "The security code is incorrect.",
            "expired_card"            => "Your card has expired.",
            "processing_error"        => "A processing error occurred. Please try again.",
            _ => "Payment could not be processed. Please try again."
        };

    private static long ToStripeCents(Money money) => (long)(money.Amount * 100);
}

Step 4: The Clean Domain Service

Now look at how clean your domain service becomes:

// ✅ Domain service that knows nothing about Stripe
public class OrderPaymentService
{
    private readonly IOrderRepository _orders;
    private readonly IPaymentGateway _paymentGateway;  // domain interface, not Stripe
    private readonly ILogger<OrderPaymentService> _logger;

    public OrderPaymentService(
        IOrderRepository orders,
        IPaymentGateway paymentGateway,
        ILogger<OrderPaymentService> logger)
    {
        _orders = orders;
        _paymentGateway = paymentGateway;
        _logger = logger;
    }

    public async Task<PaymentOutcome> ProcessPaymentAsync(
        Guid orderId,
        string paymentMethodToken,
        CancellationToken ct = default)
    {
        var order = await _orders.GetByIdAsync(orderId, ct)
            ?? throw new OrderNotFoundException(orderId);

        var request = new PaymentRequest(
            Amount: Money.GBP(order.Total),
            PaymentMethodToken: paymentMethodToken,
            OrderReference: order.Reference,
            CustomerEmail: order.CustomerEmail);

        var result = await _paymentGateway.ChargeAsync(request, ct);

        if (!result.Success)
        {
            _logger.LogWarning("Payment failed for order {OrderId}: {Error}", orderId, result.ErrorMessage);
            return PaymentOutcome.Failed(result.ErrorMessage!);
        }

        if (result.RequiresAction)
        {
            order.AwaitCustomerAction(result.Payment!);
            await _orders.SaveAsync(order, ct);
            return PaymentOutcome.RequiresAction(result.ActionUrl!);
        }

        order.MarkAsPaid(result.Payment!);
        await _orders.SaveAsync(order, ct);

        return PaymentOutcome.Succeeded(result.Payment!);
    }
}

public record PaymentOutcome
{
    public bool IsSuccess { get; init; }
    public bool NeedsAction { get; init; }
    public string? ActionUrl { get; init; }
    public string? Error { get; init; }
    public Payment? Payment { get; init; }

    public static PaymentOutcome Succeeded(Payment payment) =>
        new() { IsSuccess = true, Payment = payment };

    public static PaymentOutcome RequiresAction(string actionUrl) =>
        new() { IsSuccess = true, NeedsAction = true, ActionUrl = actionUrl };

    public static PaymentOutcome Failed(string error) =>
        new() { IsSuccess = false, Error = error };
}

No PaymentIntent. No StripeException. No requires_payment_method. The domain service is readable by anyone who understands the business, not just developers who know Stripe.

Step 5: Wiring It Up

// Program.cs
builder.Services.AddScoped<IPaymentGateway, StripePaymentGateway>();

// If you want to swap providers without touching the domain:
// builder.Services.AddScoped<IPaymentGateway, PayPalPaymentGateway>();

builder.Services.AddScoped<OrderPaymentService>();

// Stripe SDK services
builder.Services.AddSingleton<PaymentIntentService>();
builder.Services.AddSingleton<RefundService>();

StripeConfiguration.ApiKey = builder.Configuration["Stripe:SecretKey"];

Handling Webhooks Through the ACL

Webhooks are where contamination is most dangerous — you receive a raw external payload and have to decide what it means for your domain.

// ❌ Without ACL — Stripe webhook logic inside domain
[HttpPost("webhooks/stripe")]
public async Task<IActionResult> StripeWebhook()
{
    var payload = await new StreamReader(Request.Body).ReadToEndAsync();
    var stripeEvent = EventUtility.ConstructEvent(payload, Request.Headers["Stripe-Signature"], _secret);

    if (stripeEvent.Type == "payment_intent.succeeded")
    {
        var intent = stripeEvent.Data.Object as PaymentIntent;
        // Now you're writing domain logic inside a Stripe webhook handler
    }
}

// ✅ With ACL — the domain sees a domain event
public interface IPaymentWebhookTranslator
{
    Task<DomainPaymentEvent?> TranslateAsync(string payload, string signature, CancellationToken ct = default);
}

public record DomainPaymentEvent(
    DomainPaymentEventType Type,
    string ExternalReference,
    Money? Amount);

public enum DomainPaymentEventType
{
    PaymentSucceeded,
    PaymentFailed,
    PaymentRefunded,
    DisputeOpened
}

// ACL implementation — knows about Stripe
public class StripeWebhookTranslator : IPaymentWebhookTranslator
{
    private readonly string _webhookSecret;

    public StripeWebhookTranslator(IConfiguration config)
    {
        _webhookSecret = config["Stripe:WebhookSecret"]!;
    }

    public Task<DomainPaymentEvent?> TranslateAsync(
        string payload,
        string signature,
        CancellationToken ct = default)
    {
        Event stripeEvent;

        try
        {
            stripeEvent = EventUtility.ConstructEvent(payload, signature, _webhookSecret);
        }
        catch (StripeException)
        {
            return Task.FromResult<DomainPaymentEvent?>(null);
        }

        var domainEvent = stripeEvent.Type switch
        {
            "payment_intent.succeeded" => TranslateSucceeded(stripeEvent),
            "payment_intent.payment_failed" => TranslateFailed(stripeEvent),
            "charge.refunded" => TranslateRefunded(stripeEvent),
            "charge.dispute.created" => TranslateDispute(stripeEvent),
            _ => null
        };

        return Task.FromResult(domainEvent);
    }

    private static DomainPaymentEvent? TranslateSucceeded(Event e)
    {
        if (e.Data.Object is not PaymentIntent intent) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.PaymentSucceeded,
            ExternalReference: intent.Id,
            Amount: new Money(intent.Amount / 100m, intent.Currency.ToUpperInvariant()));
    }

    private static DomainPaymentEvent? TranslateFailed(Event e)
    {
        if (e.Data.Object is not PaymentIntent intent) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.PaymentFailed,
            ExternalReference: intent.Id,
            Amount: null);
    }

    private static DomainPaymentEvent? TranslateRefunded(Event e)
    {
        if (e.Data.Object is not Charge charge) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.PaymentRefunded,
            ExternalReference: charge.PaymentIntentId,
            Amount: new Money(charge.AmountRefunded / 100m, charge.Currency.ToUpperInvariant()));
    }

    private static DomainPaymentEvent? TranslateDispute(Event e)
    {
        if (e.Data.Object is not Dispute dispute) return null;

        return new DomainPaymentEvent(
            Type: DomainPaymentEventType.DisputeOpened,
            ExternalReference: dispute.ChargeId,
            Amount: new Money(dispute.Amount / 100m, dispute.Currency.ToUpperInvariant()));
    }
}

// Clean controller — receives domain events, not Stripe events
[HttpPost("webhooks/payments")]
public async Task<IActionResult> PaymentWebhook()
{
    var payload = await new StreamReader(Request.Body).ReadToEndAsync();
    var signature = Request.Headers["Stripe-Signature"].ToString();

    var domainEvent = await _webhookTranslator.TranslateAsync(payload, signature);

    if (domainEvent is null)
        return BadRequest();

    await _paymentEventHandler.HandleAsync(domainEvent);
    return Ok();
}

Switching Providers Without Touching the Domain

This is where the investment pays off. If you need to switch from Stripe to PayPal:

// New ACL implementation — everything Stripe is gone from this file
public class PayPalPaymentGateway : IPaymentGateway
{
    private readonly PayPalHttpClient _client;

    public async Task<PaymentResult> ChargeAsync(
        PaymentRequest request,
        CancellationToken ct = default)
    {
        // Translate domain request → PayPal request
        var paypalOrder = TranslateToPayPalOrder(request);
        var response = await _client.Execute(new OrdersCreateRequest().RequestBody(paypalOrder));

        // Translate PayPal response → domain result
        return TranslateFromPayPal(response.Result<Order>());
    }

    private static PaymentResult TranslateFromPayPal(Order order) =>
        new(
            Success: order.Status == "COMPLETED",
            Payment: new Payment
            {
                Id = new PaymentId(order.Id),
                Status: TranslatePayPalStatus(order.Status),
                Provider = PaymentProvider.PayPal,
                ExternalReference = order.Id,
                // ...
            },
            ErrorMessage: null,
            RequiresAction: order.Status == "PAYER_ACTION_REQUIRED",
            ActionUrl: order.Links?.FirstOrDefault(l => l.Rel == "payer-action")?.Href);

    private static PaymentStatus TranslatePayPalStatus(string status) =>
        status switch
        {
            "CREATED"  => PaymentStatus.Pending,
            "SAVED"    => PaymentStatus.Pending,
            "APPROVED" => PaymentStatus.Authorised,
            "COMPLETED" => PaymentStatus.Captured,
            "VOIDED"   => PaymentStatus.Declined,
            _ => PaymentStatus.Pending
        };
}

Change one line in Program.cs:

// Before
builder.Services.AddScoped<IPaymentGateway, StripePaymentGateway>();

// After
builder.Services.AddScoped<IPaymentGateway, PayPalPaymentGateway>();

The domain, the service layer, the controllers — unchanged. The ACL absorbed the migration.

Common Mistakes

Mistake 1: Putting translation logic in the domain

// ❌ Domain entity knows how to parse Stripe responses
public class Order
{
    public void ApplyStripeWebhook(StripeEvent e)
    {
        if (e.Type == "payment_intent.succeeded")
            Status = OrderStatus.Paid;
    }
}

The domain should never import external SDK types. If you see using Stripe; in a domain class, the ACL is missing.

Mistake 2: Leaking IDs across the boundary

// ❌ External ID stored as a first-class domain concept
public class Order
{
    public string StripePaymentIntentId { get; set; }  // Stripe concept in domain
}

// ✅ Store as an opaque external reference
public class Order
{
    public string? ExternalPaymentReference { get; private set; }  // domain concept
}

The domain doesn't know or care that ExternalPaymentReference is a Stripe PaymentIntent ID. It's just a reference to something external.

Mistake 3: Making the ACL a thin pass-through

// ❌ No translation — just wrapping the call
public class StripePaymentGateway : IPaymentGateway
{
    public async Task<PaymentIntent> ChargeAsync(PaymentIntentCreateOptions options)
    {
        return await _stripe.PaymentIntents.CreateAsync(options);
    }
}

If your ACL exposes external types in its return values or parameters, it's not an ACL. It's just a facade that provides a false sense of protection.

Mistake 4: One ACL for everything

If your system integrates with a payment provider, a shipping API, a CRM, and an email service, each deserves its own ACL. Mixing them creates the same coupling problem you were trying to solve.

Domain
├── Payments/
│   ├── IPaymentGateway.cs           ← domain port
│   └── Infrastructure/
│       └── StripePaymentGateway.cs  ← ACL for Stripe
├── Shipping/
│   ├── IShippingProvider.cs         ← domain port
│   └── Infrastructure/
│       └── DhlShippingProvider.cs   ← ACL for DHL
└── Notifications/
    ├── IEmailSender.cs              ← domain port
    └── Infrastructure/
        └── SendGridEmailSender.cs   ← ACL for SendGrid

Best Practices

Keep external types out of domain interfaces. If IPaymentGateway has a method that accepts or returns a Stripe type, the ACL has failed. Domain interfaces use only domain types.

Put all translation in one place. The mapping from Stripe statuses to PaymentStatus should live in exactly one method. When Stripe adds a new status, you change one switch expression.

Name the ACL after what it provides, not what it wraps. IPaymentGateway is better than IStripeAdapter. Your domain doesn't know it's talking to Stripe.

Write tests for the translation logic. The ACL is where subtle bugs hide — a missing status mapping, a wrong currency conversion, a misinterpreted error code. Unit test the translation methods directly.

[Theory]
[InlineData("succeeded", PaymentStatus.Captured)]
[InlineData("requires_action", PaymentStatus.RequiresAction)]
[InlineData("canceled", PaymentStatus.Declined)]
[InlineData("processing", PaymentStatus.Pending)]
public void TranslateStripeStatus_MapsCorrectly(string stripeStatus, PaymentStatus expected)
{
    var result = StripeStatusTranslator.Translate(stripeStatus);
    Assert.Equal(expected, result);
}

Let the ACL absorb errors too. Don't let StripeException propagate into the domain. Catch it in the ACL and translate it into a domain result. The domain should never handle payment provider exceptions.

Conclusion

The contamination I described at the start — StripeChargeId on Order, PSPCONFIRMED in the status enum, MapFromStripeWebhookPayload() in the service layer — wasn't inevitable. It happened gradually, one shortcut at a time, each one reasonable in isolation.

The Anti-Corruption Layer is the structural decision that makes those shortcuts impossible. It says: this is the boundary. On this side, we speak our language. On that side, they speak theirs. Here is where the translation happens.

The benefits accumulate slowly and then pay off all at once: when Stripe deprecates an endpoint, only the ACL changes. When you add a second payment provider, you add a second ACL. When a new developer joins the team, they can understand the payment flow without knowing Stripe's object model.

The domain stays clean. The external system stays external. The translation layer absorbs the chaos so everything else doesn't have to.

Full source code: github.com/AdrianBailador/anti-corruption-layer-dotnet

Questions or suggestions? Open an issue on GitHub.

Kubernetes Probes + .NET: Liveness, Readiness and Startup in Production

Adrián Bailador — Wed, 22 Apr 2026 18:49:01 +0000

I once watched a .NET service restart in a loop for twenty minutes while every other signal said it was fine. The readiness probe was passing. The liveness probe was passing. The pod was being killed anyway.

The problem was that both probes pointed to the same /health endpoint — one that checked the database. The database was slow during a migration. The pod failed liveness, got killed, restarted, tried to connect to the database again, failed liveness again. A perfectly healthy process was being murdered by its own health check.

Here's what I wish someone had explained before I deployed that.

Why One `/health` Endpoint Is Not Enough

The instinct is understandable. You add a /health endpoint, map it to Kubernetes probes, and feel responsible. But a single endpoint can't serve three fundamentally different questions:

Is this process alive and worth keeping? (Liveness)
Is this process ready to serve user traffic right now? (Readiness)
Has this process finished its startup sequence? (Startup)

Using the same endpoint for all three is like having one traffic light that controls both the pedestrian crossing and the highway on-ramp. The signals mean different things and the consequences of getting them wrong are different.

The consequences of mixing probes:

What goes wrong	What Kubernetes does	What actually happens
Database is slow	Liveness fails	Pod restarts — making the problem worse
Redis is unreachable	Liveness fails	Pod restarts — Redis is still unreachable
App is starting up	Liveness fires too early	Pod killed before it's even ready
Pod is overwhelmed	Readiness fails	Pod stops receiving traffic — correct behaviour

The right mental model: liveness is about the process, readiness is about the dependencies.

The Three Probes, Explained

Liveness Probe

Question it answers: Is this container alive enough to keep running?

Action on failure: Kubernetes restarts the container.

What to check: Only things that indicate the process itself is broken — a deadlock, an unrecoverable panic, a corrupted internal state. Not external dependencies. If your database is down, that's not a reason to restart your process. Restarting won't fix the database.

A liveness check that fails should answer yes to: "Would restarting this process fix the problem?"

Readiness Probe

Question it answers: Should this container receive traffic right now?

Action on failure: Kubernetes removes the pod from the Service endpoints. No traffic is routed to it. The pod keeps running.

What to check: Everything the pod needs to serve a request successfully — database connectivity, dependent services, cache availability. When readiness fails, traffic stops flowing to this pod until it recovers.

Startup Probe

Question it answers: Has this container finished starting up?

Action on failure: Kubernetes kills the container (same as liveness).

What it replaces: initialDelaySeconds on liveness/readiness probes.

The startup probe runs until it succeeds, then hands control to liveness and readiness. While the startup probe is running, liveness and readiness are suspended. This means your slow-starting container won't be killed before it's ready, without having to set dangerously long initialDelaySeconds values on all other probes.

A .NET service that runs EF Core migrations, warms up caches, and establishes connection pools at startup might need 30–90 seconds. The startup probe handles this cleanly.

Setting Up Health Checks in .NET

The foundation is tagging. Each health check gets one or more tags, and each Kubernetes probe maps to an endpoint that only runs checks with matching tags.

Installing the Packages

dotnet add package AspNetCore.HealthChecks.SqlServer
dotnet add package AspNetCore.HealthChecks.NpgSql
dotnet add package AspNetCore.HealthChecks.Redis
dotnet add package AspNetCore.HealthChecks.Uris

Registering Checks with Tags

builder.Services.AddHealthChecks()
    // Liveness: only checks the process itself
    .AddCheck<SelfHealthCheck>(
        name: "self",
        tags: ["live"])

    // Readiness + Liveness: disk space affects both
    .AddCheck<DiskSpaceHealthCheck>(
        name: "disk-space",
        tags: ["live", "ready"])

    // Readiness only: external dependencies
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        name: "sql-server",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["ready"])

    .AddNpgSql(
        connectionString: builder.Configuration.GetConnectionString("Postgres")!,
        name: "postgresql",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["ready"])

    .AddRedis(
        redisConnectionString: builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        failureStatus: HealthStatus.Degraded, // cache miss is survivable
        tags: ["ready"])

    .AddUrlGroup(
        uri: new Uri("https://api.stripe.com/v1/"),
        name: "stripe-api",
        failureStatus: HealthStatus.Degraded,
        tags: ["ready"])

    // Startup: checks that migrations have run and caches are warm
    .AddCheck<StartupHealthCheck>(
        name: "startup-complete",
        tags: ["startup"]);

The SelfHealthCheck

The liveness check for the process itself. It should almost always return healthy — if it doesn't, the container will be restarted.

public class SelfHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        // Check for conditions that indicate the process is fundamentally broken.
        // Most of the time, this is just: I'm running, therefore I'm alive.
        var allocatedMemoryMb = GC.GetTotalMemory(forceFullCollection: false) / 1_048_576;

        if (allocatedMemoryMb > 2048)
        {
            return Task.FromResult(HealthCheckResult.Unhealthy(
                $"Memory usage critical: {allocatedMemoryMb} MB allocated. Possible memory leak.",
                data: new Dictionary<string, object> { ["allocated_mb"] = allocatedMemoryMb }));
        }

        return Task.FromResult(HealthCheckResult.Healthy(
            data: new Dictionary<string, object> { ["allocated_mb"] = allocatedMemoryMb }));
    }
}

The StartupHealthCheck

Tracks whether the application has completed its initialisation sequence. You set a flag when startup is done; the probe checks the flag.

public class StartupHealthCheck : IHealthCheck
{
    private static bool _startupComplete = false;

    // Call this from your startup logic when everything is ready
    public static void MarkStartupComplete() => _startupComplete = true;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (!_startupComplete)
        {
            return Task.FromResult(HealthCheckResult.Unhealthy(
                "Application has not completed startup sequence yet."));
        }

        return Task.FromResult(HealthCheckResult.Healthy("Startup complete."));
    }
}

Mark it done in Program.cs after migrations, cache warm-up, or whatever your startup sequence involves:

var app = builder.Build();

// Run migrations
using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
}

// Warm up caches, establish connection pools, etc.
await WarmUpCachesAsync(app.Services);

// Signal that startup is complete
StartupHealthCheck.MarkStartupComplete();

app.Run();

Mapping the Three Endpoints

// Liveness — is the process alive?
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,  // degraded = still alive
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

// Readiness — can it serve traffic?
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,  // degraded can still serve
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

// Startup — has initialisation finished?
app.MapHealthChecks("/health/startup", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("startup"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status503ServiceUnavailable, // not ready yet
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Kubernetes YAML

Here's a complete Deployment spec with all three probes configured for a typical .NET API.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-dotnet-api
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-dotnet-api
  template:
    metadata:
      labels:
        app: my-dotnet-api
    spec:
      containers:
        - name: api
          image: myregistry/my-dotnet-api:latest
          ports:
            - containerPort: 8080

          # Startup probe: runs until the app finishes initialising.
          # Liveness and readiness are suspended while this is running.
          # 30 attempts × 5s interval = up to 150 seconds to start.
          startupProbe:
            httpGet:
              path: /health/startup
              port: 8080
            initialDelaySeconds: 0   # start checking immediately
            periodSeconds: 5         # check every 5 seconds
            failureThreshold: 30     # allow up to 150 seconds to start
            successThreshold: 1
            timeoutSeconds: 3

          # Liveness probe: runs after startup succeeds.
          # Failure → container restart.
          # Only check what a restart would actually fix.
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8080
            initialDelaySeconds: 0   # startup probe already handled the delay
            periodSeconds: 15        # don't hammer it — 15s is usually enough
            failureThreshold: 3      # 3 consecutive failures → restart
            successThreshold: 1
            timeoutSeconds: 5

          # Readiness probe: runs after startup succeeds.
          # Failure → pod removed from Service, no traffic routed.
          # Check all dependencies needed to serve a request.
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            initialDelaySeconds: 0
            periodSeconds: 10        # check more frequently than liveness
            failureThreshold: 3      # 3 failures → stop sending traffic
            successThreshold: 2      # 2 successes to re-add to rotation
            timeoutSeconds: 5

          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "500m"

          env:
            - name: ASPNETCORE_URLS
              value: "http://+:8080"
            - name: ConnectionStrings__DefaultConnection
              valueFrom:
                secretKeyRef:
                  name: my-dotnet-api-secrets
                  key: db-connection-string

Understanding the Numbers

periodSeconds — how often Kubernetes checks. Too low and you add unnecessary load; too high and you react slowly to failures.

Liveness: 15–30 seconds. A stuck process doesn't need sub-second detection.
Readiness: 5–10 seconds. You want traffic to re-route quickly when a pod recovers.
Startup: 5 seconds. You want to know as soon as the app is ready.

failureThreshold — how many consecutive failures before action is taken.

Set this to 3 minimum. A transient network hiccup or a momentary slow query shouldn't kill your pod. failureThreshold: 1 is almost always wrong in production.
For startup: set it to maxStartupSeconds / periodSeconds. If your app might take 90 seconds to start: 90 / 5 = 18 failures.

successThreshold — how many consecutive successes to consider the probe passing.

For readiness: setting this to 2 prevents a pod that's still recovering from being re-added to rotation after one fluke success. Default is 1.
For liveness: must be 1 (Kubernetes enforces this).

timeoutSeconds — how long Kubernetes waits for the probe to respond.

Your health check must complete within this time or it counts as a failure. Make sure your checks have timeouts shorter than this value.

Common Mistakes

Mistake 1: Checking external dependencies in the liveness probe

# ❌ This will cause restart loops
livenessProbe:
  httpGet:
    path: /health  # checks database
    port: 8080

If the database is down or slow, the liveness probe fails, the pod restarts, reconnects to the same database, fails again. You've created a restart loop that makes the incident worse.

# ✅ Liveness only checks the process
livenessProbe:
  httpGet:
    path: /health/live  # only checks self and disk
    port: 8080

Mistake 2: Using `initialDelaySeconds` instead of a startup probe

# ❌ Guessing how long startup takes
livenessProbe:
  initialDelaySeconds: 60  # hope it's enough

This creates two problems. If startup takes 61 seconds, the pod gets killed. If startup usually takes 10 seconds but you set 60, every pod is unavailable for 60 seconds unnecessarily — this matters during rolling updates.

# ✅ Let the startup probe determine when the app is ready
startupProbe:
  httpGet:
    path: /health/startup
    port: 8080
  periodSeconds: 5
  failureThreshold: 30  # up to 150 seconds, no guessing

Mistake 3: Setting `failureThreshold: 1`

# ❌ Any single timeout kills the pod
livenessProbe:
  failureThreshold: 1

A single slow response, a momentary GC pause, a brief network hiccup — all of these become pod restarts. In a high-traffic system, this creates cascades: one pod restarts, more traffic hits the remaining pods, they slow down, they restart, and so on.

# ✅ Require consecutive failures before action
livenessProbe:
  failureThreshold: 3  # three consecutive failures required

Mistake 4: The probe timeout is longer than the check timeout

livenessProbe:
  timeoutSeconds: 10

// ❌ The health check has no timeout — it can block for 30+ seconds
public async Task<HealthCheckResult> CheckHealthAsync(
    HealthCheckContext context,
    CancellationToken cancellationToken = default)
{
    var response = await _httpClient.GetAsync("/ping"); // no timeout
    // ...
}

If the check takes 15 seconds, Kubernetes considers it a timeout failure at 10 seconds — but the check is still running in the background, consuming resources and holding connections.

// ✅ Always add an explicit timeout inside your health check
public async Task<HealthCheckResult> CheckHealthAsync(
    HealthCheckContext context,
    CancellationToken cancellationToken = default)
{
    using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
    cts.CancelAfter(TimeSpan.FromSeconds(3)); // well under the probe's timeoutSeconds

    try
    {
        var response = await _httpClient.GetAsync("/ping", cts.Token);
        return response.IsSuccessStatusCode
            ? HealthCheckResult.Healthy()
            : HealthCheckResult.Degraded($"Returned {(int)response.StatusCode}");
    }
    catch (OperationCanceledException)
    {
        return HealthCheckResult.Degraded("Timed out after 3 seconds.");
    }
}

Mistake 5: Not setting `successThreshold` on readiness

When a pod recovers from a readiness failure, Kubernetes re-adds it to the Service after the first successful probe. That pod might be in the middle of warming up caches or draining a backlog. Setting successThreshold: 2 gives you an extra check before traffic returns.

readinessProbe:
  successThreshold: 2  # two consecutive successes before re-adding to rotation

Mistake 6: Exposing health check internals to the internet

The /health/ready endpoint can return database names, connection strings fragments in exception messages, and internal IP addresses. Don't expose it publicly.

// Route it through an internal ingress only
app.MapHealthChecks("/health/live").RequireHost("*.internal");
app.MapHealthChecks("/health/ready").RequireHost("*.internal");
app.MapHealthChecks("/health/startup").RequireHost("*.internal");

Or, if your service mesh makes RequireHost unreliable, use network policies at the Kubernetes level to restrict access to the health endpoints from outside the cluster.

Best Practices

One responsibility per probe. Liveness = process health. Readiness = traffic eligibility. Startup = initialisation complete. Never mix these concerns in a single endpoint.

Make liveness checks trivial. The liveness probe should fail only when a restart would actually help. That's a small set: deadlocks, unrecoverable panics, memory leaks, corrupted internal state. If you're unsure whether a condition should trigger a restart, it probably shouldn't.

Make readiness checks comprehensive. The readiness probe should reflect whether the pod can actually serve a request end-to-end. If a request needs the database and the database is down, readiness should fail. That's the correct behaviour — stop sending traffic to that pod.

Always set Degraded for non-critical dependencies. Redis down → Degraded, not Unhealthy. If readiness maps Degraded to 200 OK (which it should for most services), the pod stays in rotation and serves requests without caching. The alternative — taking the pod out of rotation because Redis is down — is usually worse.

Cache expensive checks. Probes run every 5–15 seconds. A health check that runs a database query on every call adds measurable load. Cache results for 15–30 seconds:

public class CachedDatabaseHealthCheck : IHealthCheck
{
    private readonly IDbConnectionFactory _factory;
    private HealthCheckResult _cached = HealthCheckResult.Healthy();
    private DateTimeOffset _lastRun = DateTimeOffset.MinValue;
    private static readonly TimeSpan CacheDuration = TimeSpan.FromSeconds(20);

    public CachedDatabaseHealthCheck(IDbConnectionFactory factory)
    {
        _factory = factory;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (DateTimeOffset.UtcNow - _lastRun < CacheDuration)
            return _cached;

        try
        {
            await using var conn = await _factory.CreateConnectionAsync(cancellationToken);
            await conn.ExecuteAsync("SELECT 1");
            _cached = HealthCheckResult.Healthy();
        }
        catch (Exception ex)
        {
            _cached = HealthCheckResult.Unhealthy("Database unreachable.", ex);
        }

        _lastRun = DateTimeOffset.UtcNow;
        return _cached;
    }
}

Log probe failures. Kubernetes logs probe failures in pod events, but they don't always surface well. Add structured logging inside your health checks so you get context when things go wrong:

public async Task<HealthCheckResult> CheckHealthAsync(
    HealthCheckContext context,
    CancellationToken cancellationToken = default)
{
    try
    {
        await _connection.ExecuteAsync("SELECT 1");
        return HealthCheckResult.Healthy();
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Database health check failed for {CheckName}", context.Registration.Name);
        return HealthCheckResult.Unhealthy("Database check failed.", ex);
    }
}

Test your probes in staging. Kill your database, take down Redis, fill up the disk. Verify that:

Readiness fails and pods stop receiving traffic
Liveness does not fail (and therefore pods are not restarted)
The service degrades gracefully instead of crashing
Traffic re-routes to healthy pods automatically

Don't discover that your probe configuration is wrong during a real incident.

Putting It All Together

Here's the complete Program.cs with everything wired up:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
    .AddCheck<SelfHealthCheck>(
        name: "self",
        tags: ["live"])
    .AddCheck<DiskSpaceHealthCheck>(
        name: "disk-space",
        tags: ["live", "ready"])
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        name: "sql-server",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["ready"])
    .AddRedis(
        redisConnectionString: builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        failureStatus: HealthStatus.Degraded,
        tags: ["ready"])
    .AddCheck<StartupHealthCheck>(
        name: "startup-complete",
        tags: ["startup"]);

var app = builder.Build();

// Run startup sequence
using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
}

StartupHealthCheck.MarkStartupComplete();

// Map probe endpoints
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

app.MapHealthChecks("/health/startup", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("startup"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status503ServiceUnavailable,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

app.Run();

Conclusion

The restart loop I described at the start was caused by a single wrong decision: using one endpoint for three different questions. The fix was twenty lines of code and ten minutes of work.

The mental model to take away:

Liveness asks: "Is this process broken beyond repair?" Only restart if the answer is yes.
Readiness asks: "Is this process ready to handle a request right now?" Remove from rotation if the answer is no.
Startup asks: "Has this process finished initialising?" Don't send liveness or readiness probes until the answer is yes.

Three questions. Three endpoints. Three probes. Each one doing exactly one job, with consequences matched to the answer.

Once you have this in place, Kubernetes becomes a genuine safety net — not something that makes incidents worse by restarting healthy pods in the middle of a database outage.

Have questions or found an issue with the examples? Open an issue on GitHub.

🚀 I've been quietly building new features into The Coffee Timer ☕ — my Pomodoro productivity app — and I'm excited to share what's new!

Adrián Bailador — Sun, 12 Apr 2026 19:24:04 +0000

Here's what just shipped:

☕ Focus Stats Dashboard — See your last 7 days of focus time, top tasks by

pomodoros, and key productivity metrics. (Premium)

🗺️ Interactive Onboarding Tour — A step-by-step guided tour with spotlight

tooltips so new users know exactly what everything does from day one.

🌍 Spanish / English toggle — One click to switch the entire UI between EN
and ES. Building for a global audience from the start.

All of this on top of Spotify integration, ambient sounds, streak tracking, and a beautiful coffee cup that fills as you work. ☕

If you're curious, give it a try → https://thecoffeetimer.com/

Built with React, TypeScript, .NET 8, Supabase & Stripe. Solo project, shipping fast. 🛠️

Health Checks in ASP.NET Core: Beyond the Basic /health Endpoint

Adrián Bailador — Sun, 12 Apr 2026 11:09:54 +0000

A service returning 200 OK on /health doesn't mean it's healthy. It means the process is alive and the route handler executed. Your database could be unreachable, your message broker offline, your disk at 99% capacity — and /health would still return green.

I've seen this exact situation cause a silent outage. The load balancer was happy, Kubernetes wasn't restarting anything, and the monitoring dashboard showed all services up. Meanwhile, every request that touched the database was failing. The health check was lying.

Here's how to make it tell the truth.

The Setup Everyone Has

// Program.cs — the version that gives you false confidence
app.MapGet("/health", () => "Healthy");

Or slightly better, using the built-in middleware:

builder.Services.AddHealthChecks();
app.MapHealthChecks("/health");

Both return 200 OK as long as the process is running. Neither checks anything meaningful.

What ASP.NET Core Health Checks Actually Give You

The Microsoft.AspNetCore.Diagnostics.HealthChecks package (included in the ASP.NET Core metapackage) provides an extensible pipeline where each check implements IHealthCheck:

public interface IHealthCheck
{
    Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default);
}

A HealthCheckResult is one of three states:

HealthCheckResult.Healthy() — everything is fine
HealthCheckResult.Degraded() — working but not at full capacity
HealthCheckResult.Unhealthy() — something is broken

The overall status of the endpoint is the worst status across all registered checks. One Unhealthy check makes the whole endpoint return 503 Service Unavailable.

Checking What Actually Matters

Database Connectivity

The most critical check for most APIs. Install the NuGet package for your database:

dotnet add package AspNetCore.HealthChecks.SqlServer
dotnet add package AspNetCore.HealthChecks.NpgSql       # PostgreSQL
dotnet add package AspNetCore.HealthChecks.MySql         # MySQL

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        healthQuery: "SELECT 1",
        name: "sql-server",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["database", "sql"])
    .AddNpgSql(
        connectionString: builder.Configuration.GetConnectionString("Postgres")!,
        name: "postgresql",
        tags: ["database", "postgres"]);

A note on SELECT 1: It's the industry standard for this check — fast, universally supported, and harmless. Some purists argue it only verifies the connection, not whether the database is locked or whether the application user has write permissions. They're right. For most services, connectivity is enough. If you need deeper assurance, replace it with a lightweight query against a known table: SELECT TOP 1 1 FROM Orders WITH (NOLOCK). Just don't go overboard — a health check query that takes 500ms under load is worse than SELECT 1.

Redis Cache

dotnet add package AspNetCore.HealthChecks.Redis

builder.Services.AddHealthChecks()
    .AddRedis(
        redisConnectionString: builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        failureStatus: HealthStatus.Degraded, // degraded, not unhealthy — cache miss is survivable
        tags: ["cache"]);

Notice I'm using Degraded here. If Redis is down, my app still works — it'll be slower, but it won't fail. This distinction matters for Kubernetes probes, as we'll see later.

External HTTP Dependencies

dotnet add package AspNetCore.HealthChecks.Uris

builder.Services.AddHealthChecks()
    .AddUrlGroup(
        uri: new Uri("https://api.stripe.com/v1/"),
        name: "stripe-api",
        failureStatus: HealthStatus.Degraded,
        tags: ["external"]);

Writing a Custom Health Check

When a package doesn't exist for your dependency, write your own. It's straightforward:

public class OrderServiceHealthCheck : IHealthCheck
{
    private readonly IOrderRepository _orderRepository;

    public OrderServiceHealthCheck(IOrderRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        try
        {
            var canConnect = await _orderRepository.CanConnectAsync(cancellationToken);

            if (!canConnect)
            {
                return HealthCheckResult.Unhealthy("Order repository is unreachable.");
            }

            var pendingOrders = await _orderRepository.GetPendingCountAsync(cancellationToken);

            // Degraded if queue is building up — not broken, but worth knowing
            if (pendingOrders > 10_000)
            {
                return HealthCheckResult.Degraded(
                    $"Order queue is growing: {pendingOrders} pending orders.",
                    data: new Dictionary<string, object> { ["pending_orders"] = pendingOrders });
            }

            return HealthCheckResult.Healthy(
                data: new Dictionary<string, object> { ["pending_orders"] = pendingOrders });
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy(
                "Order service check threw an exception.",
                exception: ex);
        }
    }
}

builder.Services.AddHealthChecks()
    .AddCheck<OrderServiceHealthCheck>(
        name: "order-service",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["orders", "database"]);

Disk Space

A check that's almost always missing — and that bites you at the worst moment:

public class DiskSpaceHealthCheck : IHealthCheck
{
    private readonly long _minimumFreeBytesThreshold;

    public DiskSpaceHealthCheck(long minimumFreeMegabytes = 500)
    {
        _minimumFreeBytesThreshold = minimumFreeMegabytes * 1024 * 1024;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var drive = DriveInfo.GetDrives()
            .FirstOrDefault(d => d.IsReady && d.Name == "/");

        if (drive is null)
        {
            return Task.FromResult(HealthCheckResult.Unhealthy("Root drive not found."));
        }

        var freeBytes = drive.AvailableFreeSpace;
        var freeMb = freeBytes / (1024 * 1024);

        var data = new Dictionary<string, object>
        {
            ["free_mb"] = freeMb,
            ["total_mb"] = drive.TotalSize / (1024 * 1024)
        };

        if (freeBytes < _minimumFreeBytesThreshold)
        {
            return Task.FromResult(
                HealthCheckResult.Unhealthy($"Low disk space: {freeMb} MB free.", data: data));
        }

        if (freeBytes < _minimumFreeBytesThreshold * 2)
        {
            return Task.FromResult(
                HealthCheckResult.Degraded($"Disk space getting low: {freeMb} MB free.", data: data));
        }

        return Task.FromResult(HealthCheckResult.Healthy(data: data));
    }
}

Tagging Checks for Kubernetes Probes

This is where health checks go from useful to essential. Kubernetes uses three probes:

Probe	Purpose	Consequence if failing
Liveness	Is the process alive?	Restart the container
Readiness	Can it serve traffic?	Remove from load balancer
Startup	Has it finished starting up?	Don't check liveness/readiness yet

You don't want a slow Redis to restart your pod. You want it to stop receiving traffic until Redis recovers. Tags let you route different checks to different endpoints:

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString: connectionString,
        name: "sql-server",
        tags: ["ready"])                        // readiness only
    .AddRedis(
        redisConnectionString: redisConnection,
        name: "redis",
        failureStatus: HealthStatus.Degraded,
        tags: ["ready"])                        // readiness only
    .AddCheck<DiskSpaceHealthCheck>(
        name: "disk-space",
        tags: ["live", "ready"])                // both
    .AddCheck<OrderServiceHealthCheck>(
        name: "order-service",
        tags: ["ready"]);                       // readiness only

Map separate endpoints filtered by tag:

// Liveness — only checks the process is alive and has disk space
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,    // degraded still alive
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

// Readiness — checks everything needed to serve requests
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,    // degraded can still serve
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Kubernetes configuration:

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

startupProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 0
  periodSeconds: 5
  failureThreshold: 30   # 30 * 5s = 150 seconds to start up

Rich JSON Responses

By default, the health endpoint returns plain text (Healthy, Degraded, Unhealthy). For monitoring dashboards and debugging, you want JSON:

app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
});

static Task WriteHealthCheckResponse(HttpContext context, HealthReport report)
{
    context.Response.ContentType = "application/json";

    var response = new
    {
        status = report.Status.ToString(),
        duration = report.TotalDuration.TotalMilliseconds,
        checks = report.Entries.Select(e => new
        {
            name = e.Key,
            status = e.Value.Status.ToString(),
            description = e.Value.Description,
            duration = e.Value.Duration.TotalMilliseconds,
            data = e.Value.Data,
            exception = e.Value.Exception?.Message
        })
    };

    return context.Response.WriteAsync(
        JsonSerializer.Serialize(response, new JsonSerializerOptions
        {
            WriteIndented = true,
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
        }));
}

Output:

{
  "status": "Degraded",
  "duration": 142.5,
  "checks": [
    {
      "name": "sql-server",
      "status": "Healthy",
      "duration": 12.3,
      "data": {}
    },
    {
      "name": "redis",
      "status": "Degraded",
      "description": "Redis connection timeout after 5000ms",
      "duration": 5001.2,
      "data": {}
    },
    {
      "name": "disk-space",
      "status": "Healthy",
      "duration": 0.8,
      "data": {
        "free_mb": 42301,
        "total_mb": 102400
      }
    }
  ]
}

Adding a Timeout per Check

A health check that hangs is worse than one that fails fast. Add a timeout so a slow dependency doesn't block the entire health endpoint:

public class ExternalPaymentApiHealthCheck : IHealthCheck
{
    private readonly HttpClient _httpClient;

    public ExternalPaymentApiHealthCheck(IHttpClientFactory factory)
    {
        _httpClient = factory.CreateClient("payment-api");
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        cts.CancelAfter(TimeSpan.FromSeconds(3)); // never wait more than 3 seconds

        try
        {
            var response = await _httpClient.GetAsync("/ping", cts.Token);

            return response.IsSuccessStatusCode
                ? HealthCheckResult.Healthy()
                : HealthCheckResult.Degraded($"Payment API returned {(int)response.StatusCode}");
        }
        catch (OperationCanceledException)
        {
            return HealthCheckResult.Degraded("Payment API timed out after 3 seconds.");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Payment API unreachable.", ex);
        }
    }
}

Common Mistakes

Mistake 1: Exposing health check details publicly

The JSON response with database names, connection info hints, and exception messages shouldn't be public. I've seen exception stack traces leak connection strings through a public /health/detail endpoint. Restrict it.

The simplest option is filtering by host:

// Public endpoint — minimal response
app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = (ctx, report) =>
    {
        ctx.Response.ContentType = "text/plain";
        return ctx.Response.WriteAsync(report.Status.ToString());
    }
});

// Internal endpoint — full details, restricted by host
app.MapHealthChecks("/health/detail", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
}).RequireHost("*.internal.mycompany.com");

But in corporate environments with a Service Mesh like Istio, filtering by host can be unreliable — the mesh rewrites headers and internal routing makes RequireHost unpredictable. In those cases, a simple API key middleware is more robust:

app.MapHealthChecks("/health/detail", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
}).AddEndpointFilter(async (context, next) =>
{
    var config = context.HttpContext.RequestServices.GetRequiredService<IConfiguration>();
    var expectedKey = config["HealthChecks:ApiKey"];
    var providedKey = context.HttpContext.Request.Headers["X-Health-Key"].FirstOrDefault();

    if (string.IsNullOrEmpty(expectedKey) || providedKey != expectedKey)
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status401Unauthorized;
        return Results.Unauthorized();
    }

    return await next(context);
});

Store the key in your secrets manager, not in appsettings.json. Your monitoring tool sends it as a header. No network topology assumptions needed.

Mistake 2: Running expensive checks too frequently

Kubernetes probes can run every 5-10 seconds. A check that runs a full database query on every probe request adds load you don't need. Cache the result:

public class CachedDatabaseHealthCheck : IHealthCheck
{
    private readonly IDbConnectionFactory _factory;
    private HealthCheckResult _cachedResult = HealthCheckResult.Healthy();
    private DateTime _lastCheck = DateTime.MinValue;
    private static readonly TimeSpan CacheDuration = TimeSpan.FromSeconds(30);

    public CachedDatabaseHealthCheck(IDbConnectionFactory factory)
    {
        _factory = factory;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (DateTime.UtcNow - _lastCheck < CacheDuration)
            return _cachedResult;

        try
        {
            await using var conn = await _factory.CreateConnectionAsync(cancellationToken);
            await conn.ExecuteAsync("SELECT 1");
            _cachedResult = HealthCheckResult.Healthy();
        }
        catch (Exception ex)
        {
            _cachedResult = HealthCheckResult.Unhealthy("Database check failed.", ex);
        }

        _lastCheck = DateTime.UtcNow;
        return _cachedResult;
    }
}

Mistake 3: Using the same endpoint for liveness and readiness

If your database is down and readiness returns 503, Kubernetes will also restart your pod if that same endpoint is used for liveness. You end up in a restart loop for a problem that has nothing to do with your process health. Always separate them.

Mistake 4: Not checking the things that actually fail

A health check that only verifies the process is running adds zero observability. Check the things that have actually caused incidents: the database, the message broker, the external APIs your service depends on, the file system if you write logs or uploads.

Best Practices

Name your checks clearly. sql-server, redis-cache, stripe-api — names that appear in logs and dashboards should be immediately recognizable.

Use Degraded generously. Not every problem is Unhealthy. A slow cache, a high queue depth, a non-critical external service being down — these deserve Degraded, not a pod restart.

Always include data in your results. Queue depth, free disk space, response times — the data dictionary in HealthCheckResult is your debugging surface when something goes wrong at 2am.

Test your health checks in staging. Deliberately take down your database and verify the readiness probe returns 503 and pods stop receiving traffic. Don't discover your health check doesn't work during an actual incident.

Register health checks as singletons or transient carefully. If your check holds state (like the cached result above), register it as a singleton. If it takes a scoped dependency like DbContext, register it as transient and resolve dependencies per-check execution.

Bonus: HealthCheck UI in Two Lines

If you want to impress a client or a manager with minimal effort, install the UI package:

dotnet add package AspNetCore.HealthChecks.UI
dotnet add package AspNetCore.HealthChecks.UI.InMemory.Storage

Configure it:

builder.Services.AddHealthChecksUI(options =>
{
    options.SetEvaluationTimeInSeconds(30); // poll every 30 seconds
    options.AddHealthCheckEndpoint("API", "/health/detail");
}).AddInMemoryStorage();

// After app.MapHealthChecks(...)
app.MapHealthChecksUI(options => options.UIPath = "/health-ui");

Navigate to /health-ui and you get a live dashboard showing the status of every check, historical trend, and response times — all generated from the JSON your endpoint already returns.

It's not something you'd expose publicly, but for internal dashboards, staging environments, or a demo to stakeholders it's genuinely useful. One caveat: AddInMemoryStorage resets history on restart. For persistent history use AspNetCore.HealthChecks.UI.SqlServer.Storage or the PostgreSQL equivalent.

Conclusion

A health endpoint that always returns 200 OK isn't a health check — it's a heartbeat. The difference matters at 2am when your database connection pool is exhausted, your Redis cluster is split-brained, or your disk is 98% full and nobody noticed.

The silent outage I described at the start? It cost us two hours of debugging because every signal said "healthy". Once we had real health checks in place, the next incident took ten minutes to diagnose — the Redis check was Degraded, the readiness probe had already removed that pod from rotation, and the logs had the exact connection timeout.

The setup takes an hour. The payoff is every incident after that.

One liveness endpoint — is the process worth keeping alive?
One readiness endpoint — is it ready to serve traffic right now?
Custom checks for every dependency that has caused an incident before
Rich JSON so you know why, not just that
And if you want bonus points with your team, the UI takes five minutes

Questions? Found an issue with the examples? Open an issue on GitHub.

IAsyncEnumerable in C#: Streaming Data Without Loading Everything into Memory

Adrián Bailador — Sun, 05 Apr 2026 11:38:54 +0000

My API crashed in production. 500,000 database records, a List, and a server with 8GB RAM. The math didn't work.

I spent two hours staring at the logs before I understood what happened. The fix took ten minutes. This is what I learned — and how it will save you the same headache.

The Problem We're Solving

I know, I know. You've written this a hundred times:

// ❌ The problem: 1 million records in memory
public async Task<List<LogEntry>> GetAllLogsAsync()
{
    return await _context.LogEntries.ToListAsync(); // Boom! Memory explosion
}

For a handful of records? Fine. But the day your dataset grows beyond what fits in RAM, that innocent ToListAsync() becomes a ticking bomb.

What Is IAsyncEnumerable?

Introduced in C# 8.0 (.NET Core 3.0), IAsyncEnumerable<T> lets you stream data asynchronously — processing items one by one as they arrive, without ever holding the full collection in memory. Think of it like reading a book page by page instead of photocopying the entire thing before you start.

// ✅ The solution: stream as data arrives
public IAsyncEnumerable<LogEntry> StreamLogsAsync()
{
    return _context.LogEntries.AsAsyncEnumerable(); // Memory-efficient
}

Production-Grade Patterns

These are the four patterns I reach for most often. Not theory — things I've actually shipped.

Pattern 1: Entity Framework Core Streaming

This is where most people start, and for good reason. If you have EF Core and a table that grows over time, you need this pattern sooner or later.

public class LogRepository
{
    private readonly AppDbContext _context;

    public LogRepository(AppDbContext context)
    {
        _context = context;
    }

    /// <summary>
    /// Streams logs matching criteria without loading all into memory.
    /// WARNING: Do NOT use with OrderBy/Limit without careful consideration.
    /// </summary>
    public async IAsyncEnumerable<LogEntry> StreamLogsAsync(
        DateTime from,
        DateTime to,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var log in _context.LogEntries
            .Where(l => l.Timestamp >= from && l.Timestamp <= to)
            .AsAsyncEnumerable()
            .WithCancellation(ct))
        {
            yield return log;
        }
    }

    /// <summary>
    /// Chunks large exports to prevent connection timeouts.
    /// </summary>
    public async IAsyncEnumerable<IReadOnlyList<LogEntry>> StreamBatchedLogsAsync(
        int batchSize = 1000,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        var query = _context.LogEntries
            .OrderBy(l => l.Id)
            .AsAsyncEnumerable();

        var batch = new List<LogEntry>(batchSize);

        await foreach (var log in query.WithCancellation(ct))
        {
            batch.Add(log);

            if (batch.Count >= batchSize)
            {
                yield return batch.ToList();
                batch.Clear();
            }
        }

        // Don't forget the partial batch
        if (batch.Count > 0)
        {
            yield return batch;
        }
    }
}

Pattern 2: HttpClient Streaming with JSON

Third-party APIs that return thousands of records in a single response are surprisingly common. Without streaming, you buffer the entire response before deserializing a single object. HttpCompletionOption.ResponseHeadersRead is the line that changes everything here — don't forget it.

public class StreamingApiClient
{
    private readonly HttpClient _httpClient;
    private readonly JsonSerializerOptions _jsonOptions;

    public StreamingApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _jsonOptions = new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true,
            DefaultBufferSize = 4096 // Tune for your payload size
        };
    }

    /// <summary>
    /// Streams items from an NDJSON endpoint.
    /// Each line is a separate JSON object.
    /// </summary>
    public async IAsyncEnumerable<T> StreamFromNdJsonAsync<T>(
        string url,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var response = await _httpClient.GetAsync(
            url, 
            HttpCompletionOption.ResponseHeadersRead, // Critical: stream, don't buffer
            ct);

        response.EnsureSuccessStatusCode();

        await using var stream = await response.Content.ReadAsStreamAsync(ct);
        using var reader = new StreamReader(stream, Encoding.UTF8);

        string? line;
        while ((line = await reader.ReadLineAsync(ct)) != null)
        {
            if (string.IsNullOrWhiteSpace(line))
                continue;

            // Deserialize each line independently
            var item = JsonSerializer.Deserialize<T>(line, _jsonOptions);

            if (item != null)
                yield return item;
        }
    }

    /// <summary>
    /// Streams using System.Text.Json's built-in async deserialization.
    /// Requires JSON array format: [{}, {}, {}]
    /// </summary>
    public async IAsyncEnumerable<T> StreamJsonArrayAsync<T>(
        string url,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var response = await _httpClient.GetAsync(
            url,
            HttpCompletionOption.ResponseHeadersRead,
            ct);

        response.EnsureSuccessStatusCode();

        await using var stream = await response.Content.ReadAsStreamAsync(ct);

        await foreach (var item in JsonSerializer.DeserializeAsyncEnumerable<T>(
            stream, 
            _jsonOptions, 
            ct))
        {
            if (item != null)
                yield return item;
        }
    }
}

Pattern 3: File Processing Pipeline

CSV imports, log analysis, data migrations — anything that reads a file line by line and does something with each row. The key insight here is that you can chain multiple IAsyncEnumerable<T> methods into a pipeline where memory stays flat regardless of file size.

public class LogFileProcessor
{
    /// <summary>
    /// Reads, transforms, and writes logs in a streaming pipeline.
    /// Memory usage stays constant regardless of file size.
    /// </summary>
    public async IAsyncEnumerable<ProcessedLog> ProcessLogFileAsync(
        string filePath,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var rawLog in ReadLinesAsync(filePath, ct))
        {
            // Transform on the fly - no memory buildup
            if (TryParseLog(rawLog, out var parsed))
            {
                var enriched = await EnrichLogAsync(parsed, ct);
                yield return enriched;
            }
        }
    }

    private static async IAsyncEnumerable<string> ReadLinesAsync(
        string path,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var reader = new StreamReader(path, Encoding.UTF8);

        string? line;
        while ((line = await reader.ReadLineAsync(ct)) != null)
        {
            yield return line;
        }
    }

    private static bool TryParseLog(string raw, out ParsedLog parsed)
    {
        // Your parsing logic here
        parsed = default!;
        return true;
    }

    private static async Task<ProcessedLog> EnrichLogAsync(
        ParsedLog log, 
        CancellationToken ct)
    {
        // Async enrichment (e.g., lookup user info)
        await Task.Delay(1, ct); // Simulate async work
        return new ProcessedLog(log);
    }
}

public record ParsedLog(string Timestamp, string Level, string Message);
public record ProcessedLog(ParsedLog Original);

Pattern 4: Controller Action with Streaming Response

ASP.NET Core handles IAsyncEnumerable<T> return types natively — it serializes as NDJSON and starts sending data to the client immediately. The client doesn't wait for the full dataset; it starts receiving records as soon as the first one is ready.

[ApiController]
[Route("api/[controller]")]
public class ReportsController : ControllerBase
{
    private readonly IReportService _reportService;

    public ReportsController(IReportService reportService)
    {
        _reportService = reportService;
    }

    /// <summary>
    /// Streams CSV data directly to the client.
    /// Client starts receiving data immediately, no server buffering.
    /// </summary>
    [HttpGet("export")]
    public IAsyncEnumerable<ReportRow> ExportData(
        [FromQuery] DateTime from,
        [FromQuery] DateTime to,
        CancellationToken ct)
    {
        // ASP.NET Core automatically serializes IAsyncEnumerable as NDJSON
        // or use custom formatting for CSV
        return _reportService.StreamReportAsync(from, to, ct);
    }

    /// <summary>
    /// Custom streaming for Server-Sent Events (SSE).
    /// </summary>
    [HttpGet("live-events")]
    public async IAsyncEnumerable<ServerSentEvent> GetLiveEvents(
        [EnumeratorCancellation] CancellationToken ct)
    {
        await foreach (var evt in _reportService.SubscribeToEventsAsync(ct))
        {
            yield return new ServerSentEvent
            {
                Id = evt.Id,
                Event = evt.Type,
                Data = JsonSerializer.Serialize(evt.Payload)
            };
        }
    }
}

public record ReportRow(string Id, string Name, decimal Value);
public record ServerSentEvent(string Id, string Event, string Data);

Before vs After: Performance Comparison

Let's make it concrete. Same data, same operation, two approaches.

The Old Way: List (Before)

public async Task<List<LargeRecord>> ProcessAllRecordsAsync()
{
    // Memory: O(n) - grows with dataset size
    // Time to first result: O(n) - wait for all
    var allRecords = await _repository.GetAllAsync();

    var processed = new List<LargeRecord>();
    foreach (var record in allRecords)
    {
        processed.Add(await ProcessAsync(record));
    }

    return processed;
}

// Usage - memory spikes here
var results = await ProcessAllRecordsAsync();
foreach (var item in results)
{
    await WriteToDiskAsync(item);
}

1M records at 100KB each — what actually happens:

Peak Memory: ~95 GB (yes, gigabytes)
Time to first output: 45 seconds of waiting
Result: OutOfMemoryException — your server gives up before you do

The New Way: IAsyncEnumerable (After)

public async IAsyncEnumerable<LargeRecord> ProcessAllRecordsAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    // Memory: O(1) - constant regardless of dataset size
    // Time to first result: O(1) - immediate streaming
    await foreach (var record in _repository.StreamAllAsync(ct))
    {
        yield return await ProcessAsync(record);
    }
}

// Usage - constant memory footprint
await foreach (var item in ProcessAllRecordsAsync().WithCancellation(ct))
{
    await WriteToDiskAsync(item);
}

Same 1M records — completely different story:

Peak Memory: ~150 MB (constant, regardless of dataset size)
Time to first output: 50ms — the client starts receiving data almost instantly
Result: Smooth streaming, server stays healthy

BenchmarkDotNet Results

Common Errors and How to Fix Them

I've made every single one of these. You don't have to.

Error 1: Forgetting CancellationToken

// ❌ Bad: No way to cancel mid-stream
public async IAsyncEnumerable<Item> GetItemsAsync()
{
    await foreach (var item in _source.GetAsync())
    {
        yield return item; // Can't cancel this!
    }
}

// ✅ Good: Always include cancellation support
public async IAsyncEnumerable<Item> GetItemsAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var item in _source.GetAsync().WithCancellation(ct))
    {
        yield return item;
    }
}

Error 2: Buffering with ToListAsync()

// ❌ Bad: You just defeated the purpose
public async Task<List<Item>> GetItemsAsync() // Returns List<T>, not IAsyncEnumerable
{
    var items = new List<Item>();
    await foreach (var item in _source.GetAsync())
    {
        items.Add(item);
    }
    return items;
}

// ✅ Good: Return IAsyncEnumerable<T> directly
public IAsyncEnumerable<Item> GetItemsAsync(CancellationToken ct)
{
    return _source.GetAsync(); // Stream through
}

Error 3: Disposing Resources Too Early

// ❌ Bad: reader disposed before streaming completes
public async IAsyncEnumerable<string> ReadFileAsync(string path)
{
    using var reader = new StreamReader(path); // Disposed on first yield!

    while (await reader.ReadLineAsync() is { } line)
    {
        yield return line; // reader is already disposed
    }
}

// ✅ Good: Keep scope alive
public async IAsyncEnumerable<string> ReadFileAsync(
    string path,
    [EnumeratorCancellation] CancellationToken ct = default)
{
    using var reader = new StreamReader(path);

    try
    {
        while (await reader.ReadLineAsync(ct) is { } line)
        {
            yield return line;
        }
    }
    finally
    {
        // reader disposed when iteration completes or breaks
    }
}

Error 4: Not Configuring DbContext Lifetime

// ❌ Bad: Scoped DbContext disposed mid-stream in ASP.NET Core
[HttpGet("stream")]
public async IAsyncEnumerable<Order> GetOrders()
{
    var db = _serviceProvider.GetRequiredService<OrderDbContext>();
    // db will be disposed after the action method returns!

    await foreach (var order in db.Orders.AsAsyncEnumerable())
    {
        yield return order; // DbContext disposed here
    }
}

// ✅ Good: Use factory pattern for streaming
public class StreamingOrderService
{
    private readonly IDbContextFactory<OrderDbContext> _contextFactory;

    public async IAsyncEnumerable<Order> StreamOrdersAsync(
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await using var db = await _contextFactory.CreateDbContextAsync(ct);

        await foreach (var order in db.Orders.AsAsyncEnumerable().WithCancellation(ct))
        {
            yield return order;
        }
        // DbContext properly disposed when iteration completes
    }
}

Error 5: Ignoring Transaction Timeouts

// ❌ Bad: Long-running query may timeout
public async IAsyncEnumerable<Item> GetItemsAsync()
{
    await foreach (var item in _context.Items.AsAsyncEnumerable())
    {
        yield return item; // Connection held open indefinitely
    }
}

// ✅ Good: Set explicit command timeout
public async IAsyncEnumerable<Item> GetItemsAsync(CancellationToken ct)
{
    _context.Database.SetCommandTimeout(TimeSpan.FromMinutes(5));

    await foreach (var item in _context.Items.AsAsyncEnumerable().WithCancellation(ct))
    {
        yield return item;
    }
}

Best Practices

A few rules I now follow without thinking.

1. Always Accept CancellationToken

public async IAsyncEnumerable<T> StreamAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var item in _source.WithCancellation(ct))
    {
        ct.ThrowIfCancellationRequested(); // Optional: check between operations
        yield return await TransformAsync(item, ct);
    }
}

2. Use WithCancellation in Callers

await foreach (var item in service.StreamAsync().WithCancellation(ct))
{
    // Proper cancellation propagation
}

3. Configure JSON Buffer Sizes for HttpClient

var options = new JsonSerializerOptions
{
    DefaultBufferSize = 8192 // Adjust based on average payload size
};

await foreach (var item in JsonSerializer.DeserializeAsyncEnumerable<T>(
    stream, options, ct))
{
    // Optimal memory usage
}

4. Add Backpressure with ConfigureAwait

await foreach (var item in source.ConfigureAwait(false))
{
    // false reduces context switching in high-throughput scenarios
    await SlowOperationAsync(item).ConfigureAwait(false);
}

5. Use IAsyncDisposable for Resource Cleanup

public async IAsyncEnumerable<byte[]> StreamFileChunksAsync(
    string path,
    int chunkSize = 8192,
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await using var fs = new FileStream(
        path, 
        FileMode.Open, 
        FileAccess.Read, 
        FileShare.Read,
        bufferSize: chunkSize, 
        useAsync: true);

    var buffer = new byte[chunkSize];
    int bytesRead;

    while ((bytesRead = await fs.ReadAsync(buffer, ct)) > 0)
    {
        yield return buffer.AsSpan(0, bytesRead).ToArray();
    }
}

6. Batch When Individual Items Are Too Small

public async IAsyncEnumerable<IReadOnlyList<T>> StreamBatchesAsync<T>(
    int batchSize = 100,
    [EnumeratorCancellation] CancellationToken ct = default)
    where T : class
{
    var batch = new List<T>(batchSize);

    await foreach (var item in _context.Set<T>().AsAsyncEnumerable().WithCancellation(ct))
    {
        batch.Add(item);

        if (batch.Count >= batchSize)
        {
            yield return batch;
            batch = new List<T>(batchSize);
        }
    }

    if (batch.Count > 0)
    {
        yield return batch;
    }
}

Conclusion

The mental shift is simple once it clicks:

Before: Load everything → Process everything → Return everything
After: Stream one item → Process it → Move to the next

That's it. No magic, no complex setup. Just a different way of thinking about data flow.

Reach for IAsyncEnumerable when:

✅ You're exporting database records by the thousands
✅ You're processing large files (CSV, logs, JSON dumps)
✅ You're consuming a streaming API
✅ Memory is a real concern on your server

Stick with List when:

❌ Your dataset is small (under ~1,000 items) — the overhead isn't worth it
❌ You need random access or multiple iterations
❌ You're chaining complex LINQ operations that don't support streaming

The 95% memory reduction I got wasn't theoretical. It was the difference between a service that crashed under load and one that handled the same data without breaking a sweat. Start with your EF Core queries and API clients — that's where you'll feel the impact immediately.

🚀 Big update drop for The Coffee Timer! ☕

Adrián Bailador — Mon, 30 Mar 2026 19:00:00 +0000

I've been heads-down building new features and polishing the experience — Here's what's new:

☕ Redesigned coffee cup: A fully SVG-based ceramic mug with realistic porcelain gradients, a 3D handle, crema/foam with latte art details, and smooth steam animations. It even fills up as your The Coffee Timer session progresses.

🎵 Spotify integration (Premium) Connect your Spotify account and play playlists, songs, or artists directly inside the app while you focus. Full search + library browsing — no need to switch tabs.

🔔 Background push notifications: The timer now sends a system notification even when the tab is closed or minimised. Never miss the end of a session again.

📱 Mobile responsiveness overhaul: Bigger touch targets, responsive layouts, no more overflow on small screens. The app now feels at home on any device.

⚡ Instant premium status Subscription state loads from cache instantly — no more waiting spinner before the UI unlocks.

🔒 Smart feature gating Non-premium users see a teaser of the Spotify player (blurred, with a lock icon) to show what they're missing. Guests get a "Sign in to unlock" CTA, and free users get "Upgrade to Premium".

The Coffee Timer is a productivity app built with React + TypeScript, .NET backend, Supabase, and Stripe — designed to make focused work feel a little more enjoyable.

https://thecoffeetimer.com/

If you want to try it or give feedback, drop a comment 👇