DEV Community: Adrián Bailador

GPT-6 Astra for .NET: What Changes in the API, and Where the SDK Hasn't Caught Up

Adrián Bailador — Sun, 06 Sep 2026 11:00:28 +0000

OpenAI released GPT-6 Astra on September 3, 2026 — described as a "new capability level" for computer use, browsing, coding, and long-running agentic work. It's rolling out in phases: first to a limited set of companies in OpenAI's Daybreak cybersecurity program, then to ChatGPT Plus/Pro/Business/Enterprise, the OpenAI API, Microsoft Foundry (Azure), and AWS Bedrock.

Announcement posts don't tell you what actually breaks when you point your .NET code at a new model ID. So I did what I did for Claude Fable 5 a few weeks back: checked the model's real API contract against OpenAI's live docs, then installed the actual OpenAI NuGet package (version 2.13.0, whatever dotnet add package OpenAI gives you today) and inspected what it actually exposes, rather than trusting a blog post's code sample. The gap between the two turned out to be the most useful part of this post.

Code

The three examples below are runnable end to end in a companion repo: gpt-6-astra-dotnet — one mode per client shape (chat, meai, responses), same prompt in all three. meai also sets reasoning effort through the higher-level abstraction covered later in this post, so it isn't a strict like-for-like comparison with the other two; the repo's README says exactly what each mode runs.

What's actually in the model

The model ID is gpt-6-astra. Context window is 1,050,000 tokens, max output is 128,000 — leaving roughly 922,000 for input, though that's my subtraction, not a number OpenAI states outright. Input takes text and images; output is text only. Knowledge cutoff is April 30, 2026. It's reachable through Chat Completions, Responses, and Batch, with streaming, structured outputs, image input, and prompt caching all supported everywhere. Reasoning effort takes five values: low, medium, high, xhigh, max.

Pricing, per the live pricing page

Requests over 272K input tokens are billed at 2x the input/cache rate and 1.5x the output rate for the whole request — not just the overflow. Batch and Flex both run at 50% of standard rates. There's also a Fast mode, priced at 2x the applicable rates — the docs commit to the price, not to a specific speedup, so I'm not going to invent one either.

Calling it from .NET: two paths, one of them experimental

dotnet add package OpenAI currently installs 2.13.0. It exposes GPT-6 Astra through two different clients, and only one of them is available without opting into an experimental API.

The stable path: Chat Completions

OpenAI.Chat.ChatClient carries no experimental attribute — it's been the production path for a while, and GPT-6 Astra works through it like any other chat model:

using OpenAI.Chat;

ChatClient client = new("gpt-6-astra", Environment.GetEnvironmentVariable("OPENAI_API_KEY"));

ChatCompletion completion = await client.CompleteChatAsync(
    [new UserChatMessage("Refactor the DbContext lifetime across every endpoint in this project.")],
    new ChatCompletionOptions
    {
        ReasoningEffortLevel = ChatReasoningEffortLevel.High,
    });

Console.WriteLine(completion.Content[0].Text);

And through Microsoft.Extensions.AI (a separate package, Microsoft.Extensions.AI.OpenAI), the bridge is just as unremarkable, which is the point if you're already standardized on IChatClient the way I described in my Microsoft.Extensions.AI post:

using OpenAI.Chat;
using Microsoft.Extensions.AI;

IChatClient client = new ChatClient("gpt-6-astra", Environment.GetEnvironmentVariable("OPENAI_API_KEY"))
    .AsIChatClient();

var response = await client.GetResponseAsync(
    "Refactor the DbContext lifetime across every endpoint in this project.");

Console.WriteLine(response);

OpenAIClientExtensions.AsIChatClient(this ChatClient) has no [Experimental] attribute on it either. This is the shape to reach for as long as Astra is just answering questions, not calling any tools.

One packaging gotcha worth knowing before you add both: Microsoft.Extensions.AI.OpenAI 10.9.0 declares a dependency on OpenAI >= 2.12.0 && < 2.13.0. dotnet add package OpenAI on its own resolves to 2.13.0, one patch outside that range — add both packages the naive way and you'll get an NU1608 warning about a version outside the dependency constraint. It still restores and builds, but it's worth pinning the OpenAI version explicitly if you want a clean restore log.

That caveat about not calling tools isn't a small one. OpenAI's own release notes for Astra say it plainly: tool calling requires the Responses API, and if you're already calling tools through Chat Completions against another model, there's a dedicated migration guide for moving that to Responses. For Astra specifically, function calling, web search, file search, code interpreter, computer use, and MCP all live on the client that's still gated behind OPENAI001 — the stable client answers questions, the experimental one is where the agentic behavior actually lives.

The experimental path: Responses API

OpenAI.Responses.ResponsesClient, the whole class, is marked [Experimental("OPENAI001")]. That's not a stray warning on one method; try to construct it and the compiler stops you cold until you suppress the diagnostic:

#pragma warning disable OPENAI001
using OpenAI.Responses;

ResponsesClient client = new(Environment.GetEnvironmentVariable("OPENAI_API_KEY"));

ResponseResult result = await client.CreateResponseAsync(
    "gpt-6-astra",
    "Refactor the DbContext lifetime across every endpoint in this project.",
    previousResponseId: null);

Console.WriteLine(result.GetOutputText());

For anything beyond the three-string convenience overload (tools, reasoning options, structured output), you build a CreateResponseOptions (not ResponseCreationOptions, which is what I'd have guessed from the docs' own prose before checking):

ResponseResult result = await client.CreateResponseAsync(new CreateResponseOptions
{
    Model = "gpt-6-astra",
    InputItems = { ResponseItem.CreateUserMessageItem("Refactor the DbContext lifetime across every endpoint in this project.") },
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.High,
    },
});

The same Microsoft.Extensions.AI.OpenAI package also ships AsIChatClient(this ResponsesClient, string) — and that one is [Experimental("OPENAI001")] too, consistently.

The gap: named reasoning levels stop at `High`

This is the part worth knowing before you plan around it. GPT-6 Astra's documented reasoning.effort values are low, medium, high, xhigh, max — and, worth calling out on its own, Astra explicitly does not accept none. That's a small irony given what's coming next: both convenience enums in the .NET SDK (ChatReasoningEffortLevel for Chat Completions, ResponseReasoningEffortLevel for Responses) expose exactly five static members each in 2.13.0: None, Minimal, Low, Medium, High. The one named value that's fastest to reach for by habit is the one value this model will reject.

Neither xhigh nor max exists as a named member on either type — but that doesn't mean the .NET SDK can't send them, only that it hasn't given them a name yet. Both types are extensible string wrappers rather than real C# enums, each with a public string constructor, and I found direct proof the wrapper is meant to carry exactly this: Microsoft.Extensions.AI's own OpenAI integration already does it internally. Microsoft.Extensions.AI.Abstractions 10.9.0 defines ReasoningEffort as None, Low, Medium, High, ExtraHigh on ChatOptions.Reasoning, and the mapping inside Microsoft.Extensions.AI.OpenAI 10.9.0 sends ExtraHigh as new ChatReasoningEffortLevel("xhigh") — I confirmed the literal UTF-16 string "xhigh" is embedded in the actual 10.9.0 DLL I've got pinned in the companion repo, not just in a newer sample on GitHub's main branch. So this works at the IChatClient layer without writing the raw string yourself:

IChatClient client = new ChatClient("gpt-6-astra", Environment.GetEnvironmentVariable("OPENAI_API_KEY"))
    .AsIChatClient();

var response = await client.GetResponseAsync(
    "Refactor the DbContext lifetime across every endpoint in this project.",
    new ChatOptions { Reasoning = new ReasoningOptions { Effort = ReasoningEffort.ExtraHigh } });

ReasoningEffort stops at ExtraHigh, though — there's no abstraction-level equivalent for max. To reach that one, or to use xhigh/max against the raw SDK types directly, you're back to constructing the string yourself:

ReasoningEffortLevel = new ChatReasoningEffortLevel("max"),

What I haven't done is fire that against a live GPT-6 Astra endpoint to confirm the API accepts max back with a 200 rather than a validation error. Confirming the SDK is willing to send an arbitrary string and confirming Astra is willing to accept it are two different claims, and only the first one is checked here. If you try it before I follow up, I'd genuinely like to know.

What's still open

Everything above (the model's specs, the pricing card, the class names, the [Experimental] attribute, the "xhigh" string embedded in the shipped Microsoft.Extensions.AI.OpenAI DLL) is checked against the live docs and the SDK's actual compiled surface, not the announcement post or someone else's blog snippet. What isn't checked yet: whether GPT-6 Astra's API actually accepts max back with a 200, and a real task run through high versus xhigh through the experimental Responses client to see whether the extra effort is worth the 2x token cost on an actual .NET workload — the same follow-up I still owe from the Fable 5 post. That comparison is next, once GPT-6 Astra is out of phased rollout and reachable without a Daybreak invite.

Distributed Tracing in ASP.NET Core: From HTTP to the Queue with OpenTelemetry

Adrián Bailador — Mon, 24 Aug 2026 16:35:28 +0000

Every health check I've written answers one question well: is this dependency reachable right now. Every Kubernetes probe answers a narrower one: should this pod keep receiving traffic. Neither one answers the question that actually pages someone at 2am: this specific request took 900ms, and which of the four services it touched spent that time doing what?

This post has one goal: follow a single request across an HTTP call between two real services, then find the exact point where that tracking stops working. It isn't the HTTP call. OpenTelemetry gets that right for free, and I'll show it. It's one hop further, the moment the same request hands off work through a queue. That boundary is where most tracing setups go blind in production, and it's the part no getting-started guide covers, because those guides only ever call one service from another over HTTP.

Everything below comes from running it for real: two ASP.NET Core APIs and Jaeger, wired together with docker compose up, no cloud account or agent involved. The repo is linked at the bottom.

What a trace is actually made of

A trace is a tree of spans. Each span is one unit of work (an HTTP request, a database call, a block of business logic), with a start time, a duration, and a parent. The thing that makes it a distributed trace instead of a pile of unrelated logs is the W3C Trace Context standard: a traceparent HTTP header carrying the trace ID and the calling span's ID, attached to every outbound request and read by the receiving server to attach its own spans to the same tree.

You don't write that header by hand. OpenTelemetry.Instrumentation.AspNetCore reads it on the way in, OpenTelemetry.Instrumentation.Http writes it on the way out, and the two packages agree on the format because it's a spec, not a vendor convention. Wire both into two services and the trace crosses the process boundary for free.

The setup: two services, one trace

The demo is deliberately small: OrdersApi receives a request, calls PricingApi over HTTP, saves the result to SQLite via EF Core, and queues a notification. PricingApi does one thing: compute a price, slowly enough that it shows up as a real span. Here's OrdersApi's OpenTelemetry registration in full:

const string ServiceName = "orders-api";
var activitySource = new ActivitySource(ServiceName);

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService(
        serviceName: ServiceName,
        serviceVersion: "1.0.0"))
    .WithTracing(tracing => tracing
        .AddSource(ServiceName)
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddEntityFrameworkCoreInstrumentation()
        .AddOtlpExporter(otlp =>
        {
            otlp.Endpoint = new Uri(builder.Configuration["Otlp:Endpoint"] ?? "http://localhost:4317");
        }));

AddAspNetCoreInstrumentation and AddHttpClientInstrumentation are the pair that makes cross-process propagation automatic, and AddEntityFrameworkCoreInstrumentation (still on a beta version of the package as of this writing) turns SaveChangesAsync into its own span without touching a line of the DbContext. AddOtlpExporter ships everything to Jaeger over gRPC on port 4317, the same OTLP endpoint any other backend (Tempo, Application Insights, Honeycomb) would also accept. Nothing here is Jaeger-specific.

Auto-instrumentation covers "a request happened." It has no idea what your code was actually doing, and that's what ActivitySource is for. The failure mode when you get this wrong is silent, which is exactly why it pays to be careful. new ActivitySource(ServiceName) creates a source your code calls StartActivity on; .AddSource(ServiceName) is what subscribes the OpenTelemetry SDK to that specific source, by name. Get the two strings out of sync, a typo, a copy-paste from a different service, and StartActivity won't throw, won't log anything, it will just return null. ActivitySource.StartActivity in the base class library checks whether any listener is subscribed before creating anything, and if none is, there's nothing to create. Every activity?.SetTag(...) call after that becomes a silent no-op, and the span simply never existed as far as Jaeger is concerned. Using the same ServiceName constant for both calls, like the snippet above does, isn't a style choice. It's the whole fix for that class of bug.

With the source wired up, a manual span looks like this:

using var activity = activitySource.StartActivity("CalculatePrice");
activity?.SetTag("product.id", productId);
activity?.SetTag("order.quantity", quantity);

var delayMs = Random.Shared.Next(80, 260);
await Task.Delay(delayMs);

activity?.SetTag("pricing.total", (double)total);

PricingApi's manual span wraps the actual pricing logic, tagged with the business data that made this particular call take however long it took. OrdersApi does the same around its validation step. SetStatus(ActivityStatusCode.Error, ...) marks a span as failed when validation rejects the request; that status is what makes a bad request visibly red in the trace waterfall instead of just another green box.

Reading the actual trace

docker compose up --build
curl -X POST http://localhost:5080/orders \
  -H "Content-Type: application/json" \
  -d '{"productId": 42, "quantity": 3}'

Open http://localhost:16686, pick orders-api from the service dropdown, and open the POST /orders trace. This is a real capture from that exact request, not a mockup:

As a labeled tree, with the durations Jaeger actually reported:

POST /orders (429.41ms)
├── ValidateOrder (76µs)
├── GET (261.62ms)                          — orders-api, HttpClient instrumentation
│   └── GET /pricing/{productId:int} (236.3ms)  — pricing-api
│       └── CalculatePrice (192.81ms)           — pricing-api
└── main → /app/orders.db (13.13ms)          — orders-api, EF Core SaveChangesAsync

Two things here are easy to get wrong.

The GET span (261.62ms) belongs to orders-api: it's HttpClient's view of the call, timed from just before the request goes out to just after the response comes back. The GET /pricing/{productId:int} span nested inside it (236.3ms) belongs to pricing-api: it's the server's view, timed from request received to response sent. The ~25ms difference between them is the two network hops there and back, and in the waterfall it shows up exactly as that: a small gap before the inner bar starts and another after it ends, not a separately labeled span of its own. W3C Trace Context guarantees the two spans link into one trace; it doesn't guarantee the wire time gets its own box.

The other one is that name, main. Jaeger's peer label spells out why: orders-api → /app/orders.db main. I checked this rather than assumed it: new SqliteConnection("Data Source=orders.db").Database returns the literal string "main", always, regardless of what the file is called. That's SQLite's own name for the primary database attached to a connection, and the EF Core instrumentation package reads that Database property verbatim as the span name. The actual file path lives in the peer annotation next to it. Yours will say main too, on any SQLite database, until the day you ATTACH a second one. Small detail, but exactly the kind that trips people up if they've never checked.

Where it actually breaks

Real systems don't only call one service from another over HTTP; they also hand work off through a queue: publish now, a different process consumes it later. That boundary does not propagate trace context automatically, and the reason is simple: there's no shared execution context between "the request that wrote the message" and "the background loop that reads it," even when both happen to run inside the same process.

I built exactly that boundary into OrdersApi. After saving the order, the handler writes a notification onto an in-memory Channel<T>, and a BackgroundService reads from it separately, a deliberately minimal stand-in for a real message broker, chosen specifically because it makes the failure reproducible without RabbitMQ or Service Bus in the loop:

// in the POST /orders handler
var parentContext = propagateTraceContext ? Activity.Current?.Context : null;
await notifications.Writer.WriteAsync(new OrderNotification(order.Id, parentContext));

// in NotificationBackgroundService
using var activity = activitySource.StartActivity(
    "ProcessOrderNotification",
    ActivityKind.Consumer,
    parentContext: notification.ParentContext ?? default);

OrdersApi__PropagateTraceContext defaults to false in docker-compose.yml. With it off, parentContext is always null, StartActivity receives default(ActivityContext), and OpenTelemetry treats that as "no parent": a brand-new root trace. Same order, two disconnected traces in Jaeger:

WITHOUT PROPAGATION (default)

  POST /orders ─────────────────────────  Trace A
  ├── ValidateOrder
  ├── GET → CalculatePrice
  └── main

  ProcessOrderNotification ──────────────  Trace B — no parent, no link back


WITH PROPAGATION (OrdersApi__PropagateTraceContext=true)

  POST /orders ─────────────────────────  Trace A
  ├── ValidateOrder
  ├── GET → CalculatePrice
  ├── main
  └── ProcessOrderNotification            — same trace, linked

I ran it both ways and confirmed both trees in the Jaeger UI. Flipping the flag doesn't change anything about Channel<T> or the BackgroundService. The only thing that changes is whether Activity.Current?.Context, captured while still inside the request, gets carried across the boundary as data instead of being dropped on the floor.

Capture the ActivityContext before you hand off, carry it alongside the message (a header, in a real broker), and pass it explicitly to StartActivity on the consuming side: that's the honest version of "propagate trace context across a queue." A Service Bus message or a Kafka record needs exactly the same treatment as this in-memory channel, because the underlying problem is identical either way. The consumer's execution context was never connected to the producer's in the first place, and nothing about messaging infrastructure fixes that on its own.

Correlating logs with the trace

Once Activity.Current exists, using it in a log line costs nothing:

logger.LogInformation(
    "Created order {OrderId} for product {ProductId} (traceId={TraceId})",
    order.Id, order.ProductId, Activity.Current?.TraceId);

One field, and you can go from "I found a slow log line" to "here's the exact trace in Jaeger" without a second observability backend. Paste the trace ID into the search box and you're looking at the same request.

What I didn't cover

This is instrumentation and propagation: what a trace actually contains and where it breaks. It isn't sampling strategy for production volume, exemplars linking metrics back to traces, or a real message-broker integration instead of the in-memory stand-in. Those are the next layer once the basic shape is solid, and the ActivityContext-capture pattern above is the same one you'd reach for in each case.

Full working code (both services, the Dockerfiles, docker-compose.yml, and the toggle to flip between the broken and fixed trace) is in the companion repo: opentelemetry-tracing-dotnet.

Upgrading to .NET 10: The Breaking Changes That Don't Show Up at Compile Time

Adrián Bailador — Fri, 14 Aug 2026 20:12:48 +0000

Both .NET 8 and .NET 9 hit end of support on November 10, 2026, which is a slightly odd coincidence given .NET 8 is LTS (36 months from its November 2023 release), and .NET 9 is only STS, even with that window stretched to 24 months instead of the usual 18. After that date, Microsoft stops shipping security patches for either one — the apps don't stop working; they just quietly stop being anyone's problem to fix.

So if you're still on 8 or 9, that's under three months. The upgrade part is nothing: bump TargetFramework to net10.0, dotnet restore, done in thirty seconds. What actually takes work is everything that changes underneath it without a single line of your own code moving: how EF Core translates a .Contains() query, whether one BackgroundService failing at startup takes every other hosted service down with it, how Microsoft.Data.Sqlite parses a DateTimeOffset it's never seen before. I went through Microsoft's breaking-change docs for .NET 10, ASP.NET Core 10, and EF Core 10 and then, instead of just taking the changelog's word for any of it, ran every item myself on both SDKs.

Every SQL statement, DateTimeOffset value, and startup log line below came out of that — the same ASP.NET Core + EF Core project, run once on the .NET 9 SDK and once on .NET 10. The project itself, migrations and all, is a companion repo if you want to poke at it yourself: DotNet10MigrationChecklist.

Most of the wider .NET 10 breaking-change list you can skip. It's either genuinely obscure (Arm64 SVE nonfaulting loads, LDAP DirectoryControl parsing) or a source-incompatible deprecation the compiler points straight at — WebHostBuilder, IWebHost, and WebHost are obsolete now, not that anyone's written Program.cs that way since minimal hosting shipped, and IActionContextAccessor too. If your project builds warning-free on .NET 9 already, most of this simply won't touch you. What follows is the stuff that doesn't announce itself at compile time.

EF Core 10

Start with Contains(). A query like context.Blogs.Where(b => ids.Contains(b.Id)) used to translate, in EF 9, to a single JSON array parameter fed through OPENJSON. In EF 10 it becomes multiple scalar parameters by default:

// EF 9: single JSON parameter
// WHERE [b].[Id] IN (SELECT [value] FROM OPENJSON(@__ids_0))

// EF 10: multiple scalar parameters, same query, no code change
// WHERE [b].[Id] IN (@ids1, @ids2, @ids3)

Functionally identical, but the SQL text isn't, and SQL Server's plan cache is keyed on exact text. That means any cached plan for this query goes stale the moment you deploy and gets recompiled on next use — for most workloads that's a one-off cost, invisible past the first request. If the query runs constantly under load, or the collection sizes vary widely enough that you were counting on the old translation's plan-reuse characteristics, it's worth actually watching for rather than assuming away. Re-test if you were leaning on the old OPENJSON translation for a reason. On SQLite the same change shows up as json_each(@\_\_ids\_0) turning into IN (@ids1, @ids2). I ran the identical LINQ query against the identical SQLite database on both EF Core versions in the companion repo, and EFCORE.md has both outputs pasted straight from the terminal. If a specific query regresses you can pin the old behavior:

optionsBuilder.UseSqlServer(connectionString,
    o => o.UseParameterizedCollectionMode(ParameterTranslationMode.Parameter));

Parameter names changed shape for the same underlying reason. @__city_0 is now just @city. Harmless for the database itself, but it'll break anything that snapshot-tests generated SQL, or an interceptor parsing DbCommand.CommandText for a specific name.

ExecuteUpdateAsync no longer takes an expression tree either. If your code was building the column-setters argument with Expression.Lambda<Func<...>> to make SetProperty calls conditional, that stops compiling now — the parameter's a plain Func<...>, which honestly is easier to write anyway. You don't even need the dynamic-expression case to see the difference. Drop a bare if inside an ExecuteUpdateAsync lambda on EF Core 9 and it fails outright:

error CS1643: Not all code paths return a value in lambda expression of type
'Func<SetPropertyCalls<Blog>, SetPropertyCalls<Blog>>'

The parameter type is an actual expression tree, and C# expression trees can't hold an if statement, full stop. The same code compiles cleanly on EF Core 10, where the parameter's a real delegate instead:

// EF 10 — conditional setters, no expression-tree gymnastics
await context.Blogs.ExecuteUpdateAsync(s =>
{
    s.SetProperty(b => b.Views, 8);
    if (nameChanged)
        s.SetProperty(b => b.Name, "foo");
});

Complex type column names also got safer; another way of saying your next migration might not be empty. EF 10 uniquifies column names for complex types that used to collide, and nested complex-type properties now use the full path in the column name (Complex_NestedComplex_Property rather than just NestedComplex_Property). If you're using owned or complex types, run dotnet ef migrations add after upgrading and actually read the diff before applying it. It might rename columns nobody asked it to.

One more that's easy to miss because it only shows up in the terminal, not in code: dotnet-ef now requires --framework on any project that multi-targets (<TargetFrameworks>, plural, rather than <TargetFramework>). If you're straddling net9.0 and net10.0 during the migration itself — which is exactly when you'd want to keep running migrations — every dotnet ef command needs --framework net10.0 tacked on, or it just refuses with "the project targets multiple frameworks."

The one I'd check first is Microsoft.Data.Sqlite. Microsoft marks it High impact, not Low, and for good reason: GetDateTimeOffset on a timestamp with no offset now assumes UTC instead of the machine's local time zone, writing a DateTimeOffset into a REAL column now converts to UTC before writing, and GetDateTime on a timestamp that does carry an offset now comes back as DateTimeKind.Utc instead of DateTimeKind.Local. Whether that actually bites you depends on how those values got written and where they get read back. A single-server app that's always written and read offset-less timestamps under the same machine's time zone stays internally consistent either way — nothing to reinterpret if the writer and reader always agreed. The real risk is rows written under one assumption and read back under the other: historical data from before the upgrade, or a fleet of machines in different time zones that previously each resolved "local" differently. That's the case worth going and looking for, not assuming.

I didn't want to take that on faith, so I checked it directly. Wrote the same offset-less timestamp string into the same SQLite database file, read it back once on .NET 9 and once on .NET 10 — same row, same file, only the SDK swapped out. On .NET 9 it came back +01:00, my machine's local offset at that exact moment. On .NET 10, +00:00. SQLITE.md has the full walkthrough if you want to reproduce it yourself. While you're auditing what's actually sitting in your database, there's a temporary escape hatch:

AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", isEnabled: true);

ASP.NET Core 10

Same pattern here as EF Core: most of it is a clean deprecation the compiler will tell you about — WithOpenApi, Razor runtime compilation, the Microsoft.Extensions.ApiDescription.Client package — except one thing that changes behavior at runtime with no build-time signal at all. Cookie login redirects are now disabled for known API endpoints. Mix cookie auth with minimal API endpoints in the same app, and ASP.NET Core 9 would redirect an unauthenticated call to a login page, which is almost never what you actually want from something returning JSON. .NET 10 returns 401 instead. Correct behavior, genuinely, but if anything downstream — a frontend, a test — was quietly depending on that redirect, it just shows up as a different status code with nothing throwing to flag it.

BackgroundService and configuration

Two more that fall in the same bucket — nothing to compile, nothing that fails a build, just different behavior at runtime once the app is already live. BackgroundService now runs the whole of ExecuteAsync on a background thread, which it didn't used to. The synchronous portion — everything before the first await — ran on the main thread as part of host startup and blocked every other IHostedService from starting until it returned. Nobody noticed most of the time because that portion is usually two field assignments. But if one service does anything slow, or throws, before its first await, whatever's registered after it just sits there. Or never starts at all.

I checked this one properly: registered two hosted services, made the first throw synchronously before any await. On .NET 9 the second service's ExecuteAsync never runs — the host fails before it gets a turn. Same code on .NET 10, and the second service starts and logs like nothing happened, because the whole method body now runs on a background thread from the start and the synchronous throw in the first one doesn't block it anymore. The host still stops shortly after either way (BackgroundServiceExceptionBehavior.StopHost is still the default), but the other services get a fair shot at starting first now instead of never getting one.

Worth a separate grep: null values are preserved in configuration now. Code checking IConfiguration["Key"] is null to tell "not present" apart from "explicitly set to null" in a JSON file gets a real distinction instead of both cases collapsing into the same thing. Check anything reading appsettings.json if a config key is legitimately nullable.

SDK and CI

A PackageReference without a version now raises NU1015 instead of silently resolving to whatever floats, so a bare <PackageReference Include="SomePackage" /> quietly leaning on central package management you never actually wired up will fail restore outright now rather than picking a version and hoping for the best. NuGet audit sources also stop allowing insecure HTTP by default, so if CI pulls from an internal feed over plain HTTP, dotnet restore fails there specifically — and reads like a flaky network for a while before you realize it's the feed URL.

Migration order

Bump TargetFramework to net10.0 on a branch, restore, and read every warning. Most of the "just works" list turns into a compiler warning pointing exactly at the fix.
Run dotnet ef migrations add CheckNet10 on anything using complex or owned types, and read the diff before applying it — if the project still multi-targets net9.0 and net10.0 while you're mid-migration, add --framework net10.0 or the command just refuses to run.
Grep for Microsoft.Data.Sqlite next to DateTimeOffset or DateTime if you touch SQLite anywhere. It's the one item on this list that can silently move data underneath you.
Deploy to staging and watch how your busiest Contains()-based queries behave under load — that's where the plan-cache recompilation would show up, and for most workloads it's a one-off, not a sustained regression, but "most workloads" isn't "yours" until you've actually looked.
If you mix cookie auth and API endpoints in the same app, hit an unauthenticated API route by hand and confirm you get a 401, not a redirect.

None of it's exotic. It's just the gap between "the app compiles" and "the app behaves the way it did on .NET 9," and three months is plenty of time to close that gap properly — as long as you go looking for it now instead of the week before November 10.

Code

Full runnable project, migrations included, with every SQL statement and log line in this post captured straight from a real dotnet run on both SDKs: DotNet10MigrationChecklist.

Microsoft.Extensions.AI: One IChatClient Interface, Any LLM Provider

Adrián Bailador — Thu, 30 Jul 2026 18:30:23 +0000

I built a semantic search API a while back on top of raw OpenAI embedding calls, and a local-first assistant on top of Ollama a few months after that. Both projects needed the same things — send messages, get a response, sometimes stream it, sometimes let the model call a function. Both projects ended up with completely different code to do it, because OpenAIClient and OllamaApiClient don't share a shape. Swapping the provider later — dev on Ollama, staging on Azure OpenAI, a fallback to Anthropic — meant rewriting the call sites, not changing a config value.

That's the exact problem Microsoft.Extensions.AI (MEAI) exists to close. It's not a new SDK competing with the provider SDKs — it's a thin, provider-agnostic interface that sits in front of them, plus a set of DI-friendly middleware components (caching, logging, telemetry, automatic tool invocation) that work identically regardless of which model answers on the other end.

Code

The examples in this post are runnable end to end in a companion repo: MicrosoftExtensionsAiDotnet — a minimal API against a local Ollama model, no API keys needed, with one endpoint per section below (caching, streaming, keyed clients, tool calling, conversation state).

Two Packages, Three Interfaces

Microsoft.Extensions.AI.Abstractions defines the contracts and nothing else: IChatClient, IEmbeddingGenerator<TInput,TEmbedding>, and the experimental IImageGenerator. Library authors implement against this package — it's what a provider SDK depends on to plug into the ecosystem.

Microsoft.Extensions.AI is the package your application references. It pulls in the abstractions and adds the useful part: the middleware pipeline, DI registration extensions, and the automatic function-calling machinery.

dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.Ollama    # or .OpenAI, or Azure's SDK extension

Every provider that plugs in — OpenAI, Azure OpenAI, Azure AI Inference, Ollama (via OllamaSharp) — exposes an IChatClient and/or IEmbeddingGenerator for the same abstraction. Swap the constructor, keep every call site.

IChatClient: Send Messages, Get a Response

At its simplest, this is the whole surface:

using Microsoft.Extensions.AI;
using OllamaSharp;

IChatClient client = new OllamaApiClient(new Uri("http://localhost:11434/"), "phi3:mini");

Console.WriteLine(await client.GetResponseAsync("What is AI?"));

Real conversations are a list of ChatMessage, and the response comes back with the messages the model generated appended to it — you feed those back in on the next turn:

List<ChatMessage> history = [];
while (true)
{
    Console.Write("Q: ");
    history.Add(new(ChatRole.User, Console.ReadLine()!));

    ChatResponse response = await client.GetResponseAsync(history);
    Console.WriteLine(response);

    history.AddMessages(response); // appends the assistant's reply to history
}

Streaming is the same shape, just an IAsyncEnumerable<ChatResponseUpdate> instead of a single ChatResponse — the natural fit for await foreach that C# has had since IAsyncEnumerable<T> landed:

await foreach (ChatResponseUpdate update in client.GetStreamingResponseAsync("What is AI?"))
{
    Console.Write(update);
}

Nothing here is provider-specific. Point client at OllamaApiClient, AzureOpenAIClient.AsChatClient(...), or an Anthropic wrapper, and every line above is unchanged.

The Actual Value: Middleware You Don't Have to Write

Any real app needs more than "call the model." It needs caching so identical prompts don't re-hit a paid API, telemetry so you can see latency and token counts in your observability stack, and often automatic tool invocation. MEAI ships all three as decorators over IChatClient, composed with a fluent builder:

IChatClient client = new ChatClientBuilder(new OllamaApiClient(new Uri("http://localhost:11434"), "llama3.1"))
    .UseDistributedCache(new MemoryDistributedCache(Options.Create(new MemoryDistributedCacheOptions())))
    .UseFunctionInvocation()
    .UseOpenTelemetry(sourceName: "MyApp.Chat", configure: c => c.EnableSensitiveData = true)
    .Build();

Each Use* call wraps the previous client — DistributedCachingChatClient around FunctionInvokingChatClient around OpenTelemetryChatClient around your actual provider. Order matters: the outermost layer sees the request first. Put caching outside function invocation and a cached response skips re-running any tool calls entirely; put it inside and you'd cache before tools even execute. For most apps, cache outermost, telemetry innermost — you want to see every real call to the model, but you don't want to pay for or wait on ones a cache already answered.

This is precisely the pattern this blog has used for HybridCache and rate limiting — wrap a cross-cutting concern around a call you don't want to reimplement per call site, once, in a pipeline.

Wiring It Into DI

For an ASP.NET Core app, register the pipeline once with AddChatClient and resolve IChatClient anywhere:

builder.Services.AddDistributedMemoryCache();
builder.Services.AddChatClient(new OllamaApiClient(new Uri("http://localhost:11434"), "llama3.1"))
    .UseDistributedCache()
    .UseOpenTelemetry();

// Anywhere else in the app
public class SupportEndpoint(IChatClient chatClient)
{
    public Task<ChatResponse> Handle(string question) => chatClient.GetResponseAsync(question);
}

If you need more than one model in the same app — a cheap fast model for classification, a stronger one for generation — AddKeyedChatClient registers each under a key, resolved with [FromKeyedServices("classifier")] or IServiceProvider.GetRequiredKeyedService<IChatClient>("classifier"), the same keyed-DI pattern .NET 8 introduced everywhere else.

Tool Calling Without Writing the Loop Yourself

Function/tool calling used to mean: describe your function's schema by hand, parse the model's function-call response, invoke the method, serialize the result back into the conversation, repeat until the model stops asking. UseFunctionInvocation() collapses that whole loop:

string GetCurrentWeather() => Random.Shared.NextDouble() > 0.5 ? "It's sunny" : "It's raining";

IChatClient client = new OllamaApiClient(new Uri("http://localhost:11434"), "llama3.1")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

ChatOptions options = new() { Tools = [AIFunctionFactory.Create(GetCurrentWeather)] };

await foreach (var update in client.GetStreamingResponseAsync("Should I wear a rain coat?", options))
{
    Console.Write(update);
}

AIFunctionFactory.Create reflects over the method — name, parameters, doc comments if present — and builds the schema description the model needs. When the model decides to call GetCurrentWeather, FunctionInvokingChatClient invokes it, feeds the result back, and only returns control to you once the model has produced its actual answer. You never see the intermediate function-call message unless you go looking for it.

This is also the entry point for MCP tools inside an IChatClient — an McpClientTool from a Model Context Protocol server implements the same AIFunction contract, so a tool exposed over MCP and a local C# method sit in the exact same Tools list.

A quick note on structured outputs. Tool calling gets the model to invoke your code — structured output gets the model's final answer to come back as your type instead of prose you then have to regex apart. Microsoft.Extensions.AI ships this as GetResponseAsync<T>, an extension method that accepts a record or class and returns a ChatResponse<T>:
record TicketClassification(string Category, string Priority, string Summary);

ChatResponse<TicketClassification> response =
    await chatClient.GetResponseAsync<TicketClassification>(
        $"Classify this support ticket: {ticketBody}");

Console.WriteLine(response.Result.Category); // strongly typed, no manual JSON parsing
Under the hood this builds a JSON schema from T and sets it on ChatOptions.ResponseFormat via ChatResponseFormat.ForJsonSchema, then deserializes the result for you. The optional useJsonSchemaResponseFormat parameter (default true) is what decides whether that schema is handed to the provider's native structured-output mode — the model is constrained to emit valid JSON for your shape — or whether MEAI falls back to asking nicely via the prompt for providers that don't support schema-constrained output. This is the piece that turns "parse the model's text and hope" into a normal typed C# call, and it's what most people reach for Microsoft.Extensions.AI for in production once the chat demo is working.

Writing Your Own Middleware

The Use* methods aren't special-cased into the library — they're the same extensibility point you can use yourself, via DelegatingChatClient:

public sealed class RateLimitingChatClient(IChatClient inner, RateLimiter limiter)
    : DelegatingChatClient(inner)
{
    public override async Task<ChatResponse> GetResponseAsync(
        IEnumerable<ChatMessage> messages, ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        using var lease = await limiter.AcquireAsync(1, cancellationToken);
        if (!lease.IsAcquired)
            throw new InvalidOperationException("Rate limit exceeded.");

        return await base.GetResponseAsync(messages, options, cancellationToken);
    }
}

DelegatingChatClient forwards everything by default; you override only what you need to change. Package it as a Use* extension on ChatClientBuilder and it composes with the built-in middleware exactly the same way UseOpenTelemetry does.

Stateless History vs. Stateful Conversations

Not every provider works the same way underneath, and IChatClient is deliberately built to cover both. Stateless services (most self-hosted models) need the full message history resent every call — that's the history.AddMessages(response) pattern above. Stateful services (some hosted APIs support server-side thread/conversation state) let you pass a ChatOptions.ConversationId instead and skip resending history:

ChatOptions options = new() { ConversationId = "conversation-123" };
var response = await client.GetResponseAsync(new(ChatRole.User, "Continue where we left off"), options);

If you don't know which kind of service you're talking to, check ChatResponse.ConversationId after the first call — if it's set, switch to the ID-based pattern and stop resending history; if it's null, keep accumulating messages yourself.

What This Doesn't Replace

MEAI is an abstraction layer, not an orchestration framework. It doesn't give you agents, planning, or multi-step reasoning graphs — that's Semantic Kernel or the Microsoft Agent Framework, both of which now build on top of IChatClient rather than defining their own client abstraction. If you already have an agent loop like the one in the Uncle Bob pipeline post, MEAI is what you'd put underneath it so the loop doesn't care which model is answering.

It also doesn't stop at chat. IEmbeddingGenerator<string, Embedding<float>> is the same idea applied to the embedding calls from the semantic search post — one interface, swappable between OpenAIClient.AsEmbeddingGenerator("text-embedding-3-small") and a local OllamaEmbeddingGenerator. And chat reduction — trimming or summarizing history once a conversation gets long, via MessageCountingChatReducer or SummarizingChatReducer — is available too, though still marked experimental as of this writing.

Conclusion

The fragmentation problem was never really about missing features — every provider SDK could already do chat, streaming, and tool calling. The problem was that "swap providers" meant "rewrite call sites," which made every experiment expensive and every vendor decision permanent-feeling. Microsoft.Extensions.AI fixes that by doing what Microsoft.Extensions.* has always done for logging, caching, and DI: define the interface once, let the ecosystem implement it, and give you a middleware pipeline so cross-cutting concerns are configured once instead of copy-pasted into every call site. Start a project against IChatClient and Ollama on your laptop; ship it against Azure OpenAI without touching a single method that calls the model.

Passkeys in ASP.NET Core 10: Passwordless Authentication with Identity

Adrián Bailador — Tue, 21 Jul 2026 19:08:19 +0000

Every password reset flow you've ever built is a small admission of defeat. The user forgot a secret they were never supposed to be able to remember in the first place, so now you're emailing them a time-limited link and hoping nobody intercepts it. Multiply that by a database full of hashed passwords sitting there as a permanent breach liability, and it's no surprise "just get rid of passwords" has been the industry's stated goal for close to a decade.

.NET 10 is the first version where ASP.NET Core Identity can actually do it natively. No third-party WebAuthn package, no hand-rolled FIDO2 ceremony — SignInManager and UserManager grew new methods that handle passkey registration and authentication directly. It's scoped, it has sharp edges, and it is absolutely not a general-purpose WebAuthn library. But for the scenario most apps actually have — "let our users sign in with Windows Hello / Face ID / a security key instead of a password" — it's now built in.

Attestation and Assertion, in Plain Terms

WebAuthn has its own vocabulary, and it's worth pinning down before looking at code:

Attestation is registration. The browser asks an authenticator (a platform authenticator like Windows Hello, or a hardware key) to generate a new public/private key pair. The private key never leaves the device. The server gets the public key and stores it.
Assertion is sign-in. The server sends a fresh challenge, the authenticator signs it with the private key it generated during attestation, and the server verifies that signature against the stored public key.

Nothing secret ever crosses the network. There's no password database to breach, because there's no shared secret at all — just public keys that are useless to an attacker without the matching private key locked inside the user's device.

What ASP.NET Core Identity Actually Supports

The docs are explicit about scope: "The passkey implementation in ASP.NET Core Identity is deliberately scoped to authentication scenarios. It isn't intended as a general-purpose WebAuthn library." Concretely, that means three supported scenarios:

Adding a passkey to an existing account — a user with a password-based account registers a passkey as an additional sign-in method.
Passwordless account creation — a new account created with a passkey and no password at all.
Passwordless sign-in — authenticating with only the passkey, no password prompt.

And a few things it deliberately doesn't do:

No attestation statement validation by default (more on this below).
No 2FA integration — a passkey is treated as a primary factor, not a second factor.
Only the Blazor Web App template ships with the UI wired up; MVC/Razor Pages/minimal API projects need to build the client-side flow themselves.

If you need full WebAuthn/FIDO2 compliance — enterprise attestation policies, hardware allowlists, cross-platform ceremony beyond authentication — look at fido2-net-lib. What ships in Identity is meant for the 90% case: replacing or supplementing passwords for a normal web app.

Configuring Passkey Behaviour

Everything is driven by IdentityPasskeyOptions:

builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.ServerDomain = "contoso.com";                 // Relying Party ID
    options.AuthenticatorTimeout = TimeSpan.FromMinutes(3);
    options.ChallengeSize = 64;                            // bytes, default is 32
    options.UserVerificationRequirement = "required";       // force biometric/PIN
    options.ResidentKeyRequirement = "preferred";           // discoverable credential
});

ServerDomain matters more than it looks. If you leave it null, Identity infers the Relying Party ID from the request's Host header — which means your hosting environment (Kestrel, IIS, reverse proxy) must validate that header, or you've opened the door to credential-scoping attacks. Set it explicitly in production rather than trusting the default inference.

A passkey registered on app.contoso.com also works on any *.app.contoso.com subdomain — the browser enforces this, not your code. If you can't guarantee every subdomain under your ServerDomain is trustworthy, you need custom origin validation (see below).

Registration Flow

Registration is a round trip: your server hands the browser a set of creation options, the browser hands those to the authenticator via navigator.credentials.create(), and the signed result comes back for your server to verify and persist.

Server: generate creation options

app.MapPost("/account/passkey-options", async (
    HttpContext context,
    UserManager<ApplicationUser> userManager) =>
{
    var user = await userManager.GetUserAsync(context.User);
    if (user is null)
        return Results.NotFound();

    var userId = await userManager.GetUserIdAsync(user);
    var userName = await userManager.GetUserNameAsync(user) ?? "User";

    var optionsJson = await signInManager.MakePasskeyCreationOptionsAsync(new()
    {
        Id = userId,
        Name = userName,
        DisplayName = userName
    });

    return TypedResults.Content(optionsJson, contentType: "application/json");
});

MakePasskeyCreationOptionsAsync doesn't just build a JSON blob — it stashes temporary state in an authentication cookie so the server can later confirm the browser's response corresponds to this specific challenge, not a replayed one.

That cookie is why this flow assumes a same-origin, server-rendered relationship between the app issuing the challenge and the app completing it. If your frontend is a decoupled SPA (React, Vue, etc.) hosted on its own domain calling this as a separate API — app.contoso.com talking to api.contoso.com, or worse, a completely different domain — that cookie needs SameSite=None; Secure to survive the cross-site request, and your API needs a CORS policy that explicitly allows credentials (AllowCredentials(), no wildcard origin). Without both, the browser silently drops the cookie, PerformPasskeyAttestationAsync can't find the matching challenge state, and attestation fails with an error that has nothing to do with WebAuthn itself.

Client: hand the options to the authenticator

async function createPasskey(headers, signal) {
  const response = await fetch('/account/passkey-options', {
    method: 'POST',
    headers,
    signal,
    credentials: 'include', // required whenever the API lives on a different origin
  });
  const optionsJson = await response.json();
  const options = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJson);

  try {
    // Prompts Windows Hello / Touch ID / a security key — entirely browser-handled
    return await navigator.credentials.create({ publicKey: options, signal });
  } catch (err) {
    // NotAllowedError: user cancelled the OS/biometric prompt, or it timed out
    // InvalidStateError: an authenticator for this account already has a credential registered
    // SecurityError: origin doesn't match the configured ServerDomain / RP ID
    console.error('Passkey creation failed:', err.name, err.message);
    throw err;
  }
}

Server: verify and store

app.MapPost("/account/passkey-register", async (
    HttpContext context,
    UserManager<ApplicationUser> userManager,
    [FromBody] string credentialJson) =>
{
    var user = await userManager.GetUserAsync(context.User);

    var attestationResult = await signInManager.PerformPasskeyAttestationAsync(credentialJson);
    if (!attestationResult.Succeeded)
        return Results.BadRequest(attestationResult.Failure.Message);

    var addResult = await userManager.AddOrUpdatePasskeyAsync(user!, attestationResult.Passkey);
    return addResult.Succeeded ? Results.Ok() : Results.BadRequest("Failed to store passkey");
});

PerformPasskeyAttestationAsync checks the credential type, validates the client data (origin, challenge), inspects the authenticator flags for user presence/verification, and extracts the public key. AddOrUpdatePasskeyAsync is also what you call later if you just want to rename a credential — set passkey.Name and pass it back through the same method.

Under the hood, this lands in a new AspNetUserPasskeys table: credential ID, the owning user, and a JSON blob with the public key material, signature counter, and backup-state flags. A migration against a fresh IdentityDbContext picks this up automatically.

Sign-In Flow

Sign-in mirrors registration, but ends in an authenticated session instead of a stored credential.

app.MapPost("/account/passkey-request-options", async (
    UserManager<ApplicationUser> userManager,
    string? username) =>
{
    var user = string.IsNullOrEmpty(username)
        ? null
        : await userManager.FindByNameAsync(username);

    // Pass null for username-less / conditional UI sign-in
    var optionsJson = await signInManager.MakePasskeyRequestOptionsAsync(user);
    return TypedResults.Content(optionsJson, contentType: "application/json");
});

app.MapPost("/account/passkey-signin", async ([FromBody] string credentialJson) =>
{
    var result = await signInManager.PasskeySignInAsync(credentialJson);
    return result.Succeeded ? Results.Ok() : Results.Unauthorized();
});

async function signInWithPasskey(username, headers, signal) {
  const response = await fetch(`/account/passkey-request-options?username=${username}`, {
    method: 'POST', headers, signal, credentials: 'include'
  });
  const optionsJson = await response.json();
  const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);

  try {
    return await navigator.credentials.get({
      publicKey: options,
      // 'conditional' shows saved passkeys as native autofill suggestions on the
      // username/email <input> instead of popping a dialog immediately — pair it
      // with autocomplete="username webauthn" on that input and call this on page
      // load with no username, before the user has typed anything
      mediation: 'conditional',
      signal,
    });
  } catch (err) {
    // NotAllowedError: user dismissed the prompt, or the request timed out
    // AbortError: the request was cancelled via the AbortSignal (e.g. a newer request superseded it)
    console.error('Passkey sign-in failed:', err.name, err.message);
    throw err;
  }
}

mediation: 'conditional' is specifically for the autofill case — call signInWithPasskey with an empty username as soon as the login page loads. For a regular "Sign in with a passkey" button that the user clicks explicitly, drop mediation (or set it to 'optional', the default) so the browser shows its normal picker dialog immediately instead of waiting for autofill.

PasskeySignInAsync is the one-call convenience method — it validates the signature against the stored public key, checks the challenge matches, updates the replay-protection counter, and signs the user in. If you need to inspect the result before committing to a sign-in (say, to run additional checks first), drop down to PerformPasskeyAssertionAsync directly — just remember to call AddOrUpdatePasskeyAsync afterwards yourself, since the updated signature counter isn't persisted automatically at that lower level.

The Gaps You Need to Know About

No attestation validation by default. Identity accepts whatever attestation statement the authenticator provides without verifying it against a trust store. Fine for consumer scenarios; not fine if you need to say "only allow YubiKey 5 series" in an enterprise environment. You can hook in your own check:

builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.VerifyAttestationStatement = async context =>
    {
        // Inspect context, compare AAGUID against an allowlist, etc.
        return true;
    };
});

Account recovery is on you. If a user's only authentication method is a passkey tied to a phone they lose, they're locked out unless you've planned for it. The Blazor Web App template sidesteps this by requiring a backup method (password or external login) at account creation. If you're building passkey-only auth, budget for recovery codes or an email-based recovery flow up front — don't bolt it on after the first support ticket.

HTTPS is mandatory, not a recommendation. Passkey ceremony state is stored in encrypted, signed cookies, but they're still cookies — over plain HTTP they're interceptable. There's no way to make this work correctly without TLS in production.

When to Reach for Something Else

If your requirements are "let users sign in without a password, using their platform authenticator" — this is now the default answer for a new ASP.NET Core project, no extra dependency required. If your requirements include enterprise attestation policies, hardware model allowlisting, or WebAuthn scenarios that go beyond authenticating into your own app (signing documents, step-up auth for high-value transactions with custom ceremony), the built-in support will run out of road quickly, and fido2-net-lib or a dedicated identity provider is the better starting point.

Conclusion

Passkeys in .NET 10 aren't a bolt-on library — they're SignInManager and UserManager methods sitting right next to the password APIs you already know, backed by a new table in the Identity schema. MakePasskeyCreationOptionsAsync / PerformPasskeyAttestationAsync handle registration, MakePasskeyRequestOptionsAsync / PasskeySignInAsync handle sign-in, and the browser's navigator.credentials API does the actual cryptographic ceremony without either side of the wire ever seeing a shared secret. The scope is intentionally narrow — no attestation validation, no 2FA role, no template support outside Blazor — but for the passwordless-login scenario most apps actually need, that narrow scope is exactly right.

Full source code: github.com/AdrianBailador/PasskeysAspNetCoreIdentityDotnet

Questions or suggestions? Open an issue on GitHub.

C# 15 Preview: Union Types and Closed Hierarchies, Finally

Adrián Bailador — Wed, 08 Jul 2026 18:50:18 +0000

Last year I built a payment gateway integration that needed a result type with three shapes: Approved(string TransactionId), Declined(string Reason), and RequiresReview(string CaseId). None of them share fields. None of them belong in an inheritance hierarchy — a declined payment isn't a kind of approved payment, no matter how hard you squint at the class diagram. What I actually wanted was simple to say and impossible to express: exactly one of these three, and the compiler yells at me if I forget to handle one.

C# didn't have that. So we did what every .NET team does. We argued for twenty minutes, then picked between the two usual workarounds: a PaymentResult base record with three subclasses and a default arm in every switch "just in case", or a dependency on the community OneOf package. We went with the base record. The default arm threw an UnreachableException that, of course, was reached eight months later when someone added a fourth case.

C# 15, shipping in the .NET 11 previews, finally closes this gap. Real union types. Plus closed hierarchies, which solve a closely related but distinct problem, and the first step of a multi-release rethink of what unsafe means. None of it is final — .NET 11 goes GA in November 2026 and the design is still being argued in the open on GitHub — but the shape you learn today is close to what will ship, and it's worth learning now.

Ten Years of Asking

Discriminated unions have been one of the most requested C# features for as long as the language design has happened in public. F# has had them since its first release. Rust and TypeScript treat them as table stakes. C# has spent a decade approximating them with sealed class hierarchies and pattern matching, which works — right up until you need to combine two types that have nothing to do with each other.

// The old workaround: force unrelated shapes into a hierarchy
public abstract record PaymentResult;
public sealed record Approved(string TransactionId) : PaymentResult;
public sealed record Declined(string Reason) : PaymentResult;
public sealed record RequiresReview(string CaseId) : PaymentResult;

This is fine. Genuinely — I've shipped it many times, and it will keep being fine after C# 15 lands. But it has two failure modes that only show up later.

The first is the one that bit my team: someone adds a fourth subclass, possibly in a different assembly, and every "exhaustive" switch in the codebase silently stops being exhaustive. No warning. The compiler has no way of knowing the hierarchy was supposed to be complete, because C# has never had a way to say so.

The second is subtler: the workaround only works when the cases plausibly are a family. The moment you want a value that's either a string or an Exception, or an int or an IEnumerable<T>, inheritance has nothing to offer. You end up with object and runtime type checks, and the type system waves goodbye.

Union Types: The Actual Syntax

A union declares a fixed, closed set of case types with the union keyword. The case types don't need to be related to each other in any way:

public record class Cat(string Name);
public record class Dog(string Name);
public record class Bird(string Name);

public union Pet(Cat, Dog, Bird);

That last line is the whole feature. Pet is not a base class, and Cat doesn't know Pet exists. The union composes existing types into a closed set of alternatives, and the compiler provides implicit conversions from each case type, so assignment reads the way you'd hope:

Pet pet = new Dog("Rex");

The payoff is in the switch. Expressions over a union are checked for exhaustiveness across all case types — no _ discard, no default arm, no silent gap:

string name = pet switch
{
    Dog d => d.Name,
    Cat c => c.Name,
    Bird b => b.Name,
    // Remove any one arm and the compiler flags the switch as non-exhaustive.
};

This is the behavioural difference that matters. With the hierarchy workaround, exhaustiveness was a convention you maintained by hand and hoped nobody broke. With a union, it's structural — the set of cases is part of the type, and the compiler enforces it on every switch, in every file, forever.

The Payment Result, Done Properly

Back to my gateway. With union types, the three-shape result becomes:

public record class Approved(string TransactionId);
public record class Declined(string Reason);
public record class RequiresReview(string CaseId);

public union PaymentResult(Approved, Declined, RequiresReview);

You can attach helper members directly in the union body — useful for logic that belongs with the type rather than being copy-pasted at every call site:

public union PaymentResult(Approved, Declined, RequiresReview)
{
    public bool NeedsHumanAttention => Value switch
    {
        RequiresReview => true,
        _ => false
    };
}

And consuming it looks exactly like the pattern matching you already write, minus the arm you never trusted:

PaymentResult result = ProcessPayment(order);

string message = result switch
{
    Approved a => $"Payment {a.TransactionId} confirmed.",
    Declined d => $"Payment declined: {d.Reason}",
    RequiresReview r => $"Case {r.CaseId} flagged for manual review.",
};

No base class. No shared members forced onto types that don't need them. No default arm quietly swallowing the case nobody wrote a handler for. When the inevitable fourth case arrives — Refunded, it's always Refunded — every switch in the codebase fails to compile until someone handles it. That's not an inconvenience. That's the feature.

The Gotcha: How Unions Actually Store Data

Here's the part the announcement posts tend to bury. In the current preview, a union instance stores its contents as a single object? reference internally, and value types get boxed to fit into it. The .NET Blog's own deep dive is upfront about this. Pet above costs you nothing extra because Cat, Dog, and Bird are already reference types — but a union over int and bool boxes both, on every assignment.

That makes unions a poor fit for the hot paths where you'd reach for a struct specifically to avoid allocation — a tight loop classifying millions of numeric results, say. For request-scoped types like PaymentResult, one allocation per payment is noise and you should not think about it twice. Know which of the two situations you're in before you pick a union as a readonly struct replacement, because it isn't one.

There's also a null-shaped hole to be aware of: the default value of a union has a null Value, which won't match any of your case-type arms. If a union can sit uninitialised in a field or array, add an explicit null arm or guard against it — exhaustiveness checking can't cover a state that isn't one of the declared cases.

Closed Hierarchies: The Other Half of the Answer

Unions are for combining unrelated types. Closed hierarchies solve the opposite case: types that do share a real inheritance relationship, where the missing piece was telling the compiler the family is complete.

public closed record class GateState;
public record class Closed : GateState;
public record class Open(float Percent) : GateState;

The closed modifier means the class can only be derived from within its declaring assembly — the set of direct descendants is fixed at compile time. And once the compiler knows every subclass, it can do for hierarchies what it does for unions:

string Describe(GateState state) => state switch
{
    Closed => "closed",
    Open(var percent) => $"{percent}% open",
    // No warning: every direct descendant of 'GateState' is handled.
};

This is the fix for the exact bug that bit my payment gateway. Had PaymentResult been a closed record, the fourth subclass would have broken the build instead of reaching the unreachable exception in production.

Two details worth knowing before you use it. First, closed is implicitly abstract, and can't be combined with sealed, static, or an explicit abstract modifier — you're declaring the hierarchy closed, not making the base type instantiable. Second, closure isn't transitive: a non-closed subclass of a closed class can still be derived from anywhere. If you want exhaustiveness to hold two levels deep, mark the intermediate classes closed too.

One preview wrinkle: as of Preview 5, the runtime doesn't yet ship ClosedAttribute, so every project using the modifier has to declare the attribute itself:

namespace System.Runtime.CompilerServices;

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public sealed class ClosedAttribute : Attribute { }

That's not a bug you're working around — it's a language preview shipping slightly ahead of its own runtime support. Expect the workaround to disappear in a later preview.

Which One Do You Reach For?

The distinction is about relationship, not preference:

Reach for a union when the case types are unrelated, or you don't control all of them — string | Exception, or three DTOs that already exist for other reasons and shouldn't be bent into a common base class.
Reach for a closed hierarchy when the cases genuinely are a family with shared behaviour, and you'd have written a base class anyway — GateState, an AST node hierarchy, a domain state machine.

My PaymentResult works as either, which turns out to be a useful test: if your would-be union cases keep growing shared members, you're actually modelling a closed hierarchy and should switch. If your closed hierarchy's base class stays empty forever, it wanted to be a union.

The Quiet Third Feature: `unsafe` Gets Redefined

Away from the pattern-matching spotlight, C# 15 also starts a multi-release project to change what unsafe actually gates. Today, merely declaring a pointer type requires an unsafe context, even if you never dereference it. The new model ties the requirement to the operations that actually touch unmanaged memory — because those are where the vulnerabilities live, and those are what a security reviewer needs to find.

Compiling with <LangVersion>preview</LangVersion>, these no longer require unsafe:

Declaring a pointer type and taking an address with &
The fixed statement that pins a variable
Converting a stackalloc expression to a pointer
sizeof on any unmanaged type

int number = 42;
int* pointer = &number;

int[] numbers = [10, 20, 30];
fixed (int* first = numbers)
{
    // Dereferencing the pointer still requires an unsafe context.
}

Dereferencing (*p), member access through a pointer (p->member), indexing (p[i]), and function pointer invocation all remain gated — the point of the redesign is precisely that these stand out while the harmless declarations don't. The full model goes further: unsafe on a member will eventually mean requires-unsafe, pushing the audit obligation onto callers, with a new safe keyword for extern members and explicit-layout fields that are provably fine. Both of those come in a later preview.

If you maintain a library with low-level buffer code, track this even before it's final. It changes where your unsafe blocks start and end in code that currently over-scopes them just to declare a pointer variable.

Should You Touch Any of This Today?

In production? No. This needs the .NET 11 preview SDK or Visual Studio 2026 Insiders, <LangVersion>preview</LangVersion> in the .csproj, and a tolerance for syntax that can still change before GA. The UnionAttribute and IUnion runtime types only landed in Preview 5, the ClosedAttribute workaround is a stopgap by definition, and Microsoft's own docs note that parts of the unions proposal aren't implemented yet.

But if you're designing a result type, an event payload, or a state hierarchy right now, and you're about to write a OneOf<A, B, C> or yet another sealed-class-plus-default-arm — it changes the calculation. Keep the workaround thin. Isolate it behind a type you can swap out. The native answer is months away, not years.

The Fourth Case

That payment gateway is still in production, still running the sealed-record hierarchy, still carrying the default arm that threw the "unreachable" exception the day Refunded was added. It got a proper handler and a post-mortem, and the arm went back to being unreachable — we think.

When .NET 11 goes GA in November, one of the first pull requests I want to open is the one that turns that hierarchy into a union and deletes that arm. Not because the code is broken today, but because I'd rather the compiler tell me about the fifth case than another post-mortem.

Ten years of asking. It was worth the wait.

Modernising Legacy .NET Applications Without a Rewrite

Adrián Bailador — Sun, 21 Jun 2026 10:47:04 +0000

The codebase was twelve years old. It had started as a straightforward .NET Framework 4.5 Web API, grown through four acquisitions, and now powered a logistics platform processing six thousand orders a day. Nobody fully understood it. The team that built it had mostly left. The documentation was a 200-page Word document that described a system that no longer existed.

The business needed three things: a feature the existing architecture couldn't support, performance that was increasingly hard to explain to stakeholders, and developers who were willing to work on it — something that had become genuinely difficult to achieve when .NET Framework 4.x appeared in a job posting.

The answer that kept coming up in the architecture meetings was "rewrite it." Greenfield. Modern stack. Clean slate.

We didn't. And this is why, and what we did instead.

Why Rewrites Fail

A rewrite feels like clarity. You escape the accumulated decisions, the workarounds layered on top of workarounds, the APIs that no longer make sense. You get to do it right.

The problem is that the old system contains twelve years of business logic that nobody fully documented. Edge cases that were discovered in production in 2016 and fixed in ways that aren't obvious from reading the code. Rules that come from contracts with specific customers. Behaviour that exists because a regulator asked for it in 2019 and the ticket was closed when someone committed a one-liner to a method nobody else touched.

A rewrite ships something that looks correct and fails in production in ways that take months to diagnose. The Joel Spolsky argument — that the old code contains bug fixes you don't know about — is not theoretical. It happens on almost every rewrite, and it's almost never budgeted for.

The alternative is incremental modernisation: make the system better without stopping, replacing pieces without rewriting the whole, and measuring progress against real outcomes rather than architectural ideals.

Start with a Diagnosis, Not a Plan

Before you change anything, you need to understand what you actually have. This is the step teams skip because it feels like delay. It's the step that makes everything else work.

Run the following against the solution:

# .NET Upgrade Assistant — assesses upgrade readiness
dotnet tool install -g upgrade-assistant
upgrade-assistant analyze MySolution.sln

# See which projects still target Framework
grep -r "TargetFramework" **/*.csproj

# Find synchronous database calls (rough heuristic)
grep -rn "\.ExecuteNonQuery\(\)\|\.ExecuteReader\(\)\|\.Fill(" --include="*.cs" .

What you're looking for:

Target framework distribution — are all projects on the same version, or is it a mix?
Synchronous I/O — ExecuteNonQuery(), SqlDataReader without async, Thread.Sleep in request paths
Static state — static service locators, static HttpClient instances, global mutable state
Unhandled exception patterns — swallowed exceptions, empty catch blocks, exceptions used for control flow
External dependency calls — HTTP calls, database calls, queue interactions that have no timeout or retry

This diagnosis produces a map. Not every item on that map needs to be fixed. The goal is knowing which ones are blocking the features the business needs, which ones are performance liabilities under load, and which ones are simply technical debt that can be paid down later.

Phase 1: Upgrade the Target Framework

The first concrete step is moving projects from .NET Framework to a current LTS release. This unlocks every modern API, every performance improvement, and every tooling benefit. It's also the step with the highest perceived risk and the most predictable actual risk, because the .NET Upgrade Assistant exists precisely for this.

dotnet tool install -g upgrade-assistant
upgrade-assistant upgrade MySolution.sln --target-tfm net9.0

The assistant runs in interactive mode, shows you what it intends to change, and lets you confirm each step. For most projects it handles:

Updating <TargetFramework> in .csproj files
Migrating packages.config to PackageReference
Updating package versions to .NET-compatible equivalents
Flagging APIs that don't exist in modern .NET for manual review

The flagged items are the real work. Common ones:

// ❌ .NET Framework — no equivalent in .NET 8
ConfigurationManager.AppSettings["key"]

// ✅ Modern .NET
IConfiguration config; // injected
config["key"]

// ❌ HttpContext.Current — ASP.NET Classic
var user = HttpContext.Current.User.Identity.Name;

// ✅ ASP.NET Core
// inject IHttpContextAccessor or receive HttpContext directly in controllers

Run the full test suite after each project upgrade. If you don't have a test suite, the upgrade is the moment to write characterisation tests — tests that capture the existing behaviour, right or wrong, so you know if you've changed it.

Characterisation tests against a legacy system are only trustworthy if they run against a real database, not a mocked one — mocks tend to agree with whatever assumption you already had about the old code, which defeats the point. Testcontainers solves this by spinning up an ephemeral, disposable database in Docker for the duration of the test run:

dotnet add package Testcontainers.MsSql

public class OrderServiceCharacterisationTests : IAsyncLifetime
{
    private readonly MsSqlContainer _sqlContainer = new MsSqlBuilder().Build();

    public async Task InitializeAsync()
    {
        await _sqlContainer.StartAsync();
        // run existing migrations / restore a production-like schema dump here
    }

    public Task DisposeAsync() => _sqlContainer.DisposeAsync().AsTask();

    [Fact]
    public async Task ProcessOrder_AppliesLegacyDiscountRule_ForBulkCustomers()
    {
        using var connection = new SqlConnection(_sqlContainer.GetConnectionString());
        // exercise the legacy code path against a real, disposable SQL Server instance
    }
}

This matters more for legacy .NET than for new code: a twelve-year-old codebase often has business rules implemented as stored procedures, triggers, or computed columns that a mock can't replicate. Testcontainers lets the characterisation suite exercise the actual schema and the actual stored procedures, so a behaviour change in either the C# or the database layer gets caught.

Phase 2: Migrate Off EF6 and EDMX

If the application predates EF Core, it's almost certainly using EF6 with an EDMX — a visual, designer-generated model with a .tt template that generates entity classes, a DbContext, and XML mapping in one tightly coupled bundle. EDMX doesn't exist in EF Core, and this is usually the single biggest bottleneck in the entire modernisation, bigger than the framework upgrade itself.

The honest version of this work has three parts, and skipping any of them is how migrations stall for months:

1 — Inventory what the EDMX actually does. Open it and look specifically for:

Stored procedure mappings for inserts/updates/deletes (EF Core supports calling stored procedures, but the designer-generated mapping syntax doesn't carry over — they have to be re-wired through ModelBuilder)
Complex types and inheritance mapping (TPH/TPT/TPC) — EF Core's support differs from EF6's in ways that change generated SQL
Database-generated computed columns and triggers — these need explicit [DatabaseGenerated] or HasComputedColumnSql configuration in EF Core; EF6's EDMX inferred a lot of this from the designer

# EF Core has a community tool to reverse-engineer an EDMX into Code First
dotnet tool install -g ErikEJ.EFCorePowerTools

2 — Move to Code First, against the existing database, before changing any schema. The goal of this phase is a like-for-like model in EF Core, not an improved one. Resist the urge to "clean up" the schema at the same time — that turns a mechanical migration into a redesign with redesign-sized risk.

// ✅ EF Core Code First, mapped against the unchanged legacy schema
public class AppDbContext : DbContext
{
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>(entity =>
        {
            entity.ToTable("tbl_Orders"); // legacy table name, kept as-is
            entity.Property(o => o.TotalAmount).HasColumnType("decimal(18,2)");
            // stored procedure mapping that EDMX used to generate visually
            entity.InsertUsingStoredProcedure("usp_InsertOrder", sp => sp
                .HasParameter(o => o.CustomerId)
                .HasParameter(o => o.TotalAmount)
                .HasResultColumn(o => o.OrderId));
        });
    }
}

3 — Run the old and new data access side by side against the characterisation tests. Before retiring the EF6 DbContext, run the same Testcontainers-backed test suite against both the EF6 path and the new EF Core path, and diff the results. EF Core's LINQ translation is not identical to EF6's — queries that relied on client-side evaluation in EF6 throw or silently change behaviour in EF Core. This diffing step is what catches that before production does.

Heavy stored-procedure-based EDMX models are the case where "rewrite the data layer cleanly" is tempting and usually wrong for the same reason a full rewrite is wrong: the stored procedures encode business rules nobody documented. Migrate the mapping, not the logic, and modernise the logic later as a separate, deliberate decision.

Phase 3: Replace Static State and Service Locators

Legacy .NET applications are full of static state. It was idiomatic for its time.

// ❌ Common pattern in .NET Framework apps
public class OrderService
{
    public void ProcessOrder(int orderId)
    {
        var logger = LogManager.GetLogger(typeof(OrderService)); // static lookup
        var db = DatabaseFactory.GetConnection();               // static factory
        var emailService = ServiceLocator.Get<IEmailService>(); // service locator

        // business logic
    }
}

The problem isn't aesthetic. Static dependencies are invisible to tests, make behaviour unpredictable under concurrent load, and prevent the DI container from managing lifetimes. Replace them with constructor injection:

// ✅ Constructor injection — testable, explicit, container-managed
public class OrderService
{
    private readonly ILogger<OrderService> _logger;
    private readonly AppDbContext _db;
    private readonly IEmailService _emailService;

    public OrderService(
        ILogger<OrderService> logger,
        AppDbContext db,
        IEmailService emailService)
    {
        _logger = logger;
        _db = db;
        _emailService = emailService;
    }

    public async Task ProcessOrderAsync(int orderId, CancellationToken ct = default)
    {
        // business logic
    }
}

builder.Services.AddScoped<OrderService>();
builder.Services.AddScoped<IEmailService, SmtpEmailService>();
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Default")));

Don't try to convert everything at once. Pick the services in the critical path — the ones the business needs to change — and convert those first. The rest can wait.

Phase 4: Make It Async — Without Breaking It

Synchronous I/O in a web application blocks threads. Under sustained load, a thread pool exhausts and requests queue. This is the performance problem that's hardest to diagnose from the outside (latency climbs steadily; error rate spikes when the queue fills) and easiest to fix from the inside.

The dangerous middle ground is sync-over-async: calling .Result or .Wait() on a Task from synchronous code. It doesn't help — it blocks a thread just as a synchronous call does, and it can deadlock on older synchronisation contexts.

// ❌ Sync-over-async — blocks a thread, can deadlock
public Order GetOrder(int id)
{
    return _db.Orders.FindAsync(id).Result; // never do this
}

// ❌ Still wrong — same problem, different syntax
public Order GetOrder(int id)
{
    return _db.Orders.FindAsync(id).GetAwaiter().GetResult();
}

// ✅ Async all the way down
public async Task<Order?> GetOrderAsync(int id, CancellationToken ct = default)
{
    return await _db.Orders.FindAsync([id], ct);
}

The async conversion has to propagate up the call stack. You cannot make a method async and leave its callers synchronous — that just moves the sync-over-async problem one level up. Start at the I/O boundary (database call, HTTP call, file read) and work upward to the controller action.

Controller actions in ASP.NET Core support async Task<IActionResult> natively:

// ✅ Async controller — ASP.NET Core handles the thread correctly
[HttpGet("{id}")]
public async Task<ActionResult<OrderDto>> GetOrder(int id, CancellationToken ct)
{
    var order = await _orderService.GetOrderAsync(id, ct);
    return order is null ? NotFound() : Ok(order.ToDto());
}

Pass CancellationToken through every async call. When a client disconnects mid-request, ASP.NET Core cancels the token — and every awaited operation that respects it will exit cleanly instead of running to completion for a result nobody is waiting for.

Phase 5: Add Structured Logging

Legacy applications log with Console.WriteLine, Debug.WriteLine, or frameworks like log4net writing to text files. Text logs don't aggregate, don't filter, and don't support queries beyond grep.

Replace them with Microsoft.Extensions.Logging and a structured sink. The built-in logger works from day one; add a provider for wherever you ship logs:

dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.Console
dotnet add package Serilog.Sinks.Seq  # or Elasticsearch, OpenTelemetry, etc.

// Program.cs
builder.Host.UseSerilog((context, config) =>
{
    config
        .ReadFrom.Configuration(context.Configuration)
        .Enrich.FromLogContext()
        .WriteTo.Console(outputTemplate:
            "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}")
        .WriteTo.Seq("http://localhost:5341"); // or your log aggregator
});

The most important shift is from message formatting to property logging:

// ❌ Text log — unsearchable, unstructured
_logger.LogInformation($"Order {orderId} processed in {elapsed}ms for customer {customerId}");

// ✅ Structured log — every property is queryable
_logger.LogInformation(
    "Order {OrderId} processed in {ElapsedMs}ms for customer {CustomerId}",
    orderId, elapsed, customerId);

The string looks the same in a terminal. In a log aggregator, OrderId, ElapsedMs, and CustomerId are indexed fields. You can query "all orders for customer 42 that took more than 500ms" without parsing text.

Phase 6: Add Resilience for External Calls

Every call your application makes to an external system — a database, an HTTP API, a message broker — can fail. Most legacy applications handle this with try/catch and maybe a retry loop written by hand. The problems: the retry logic isn't consistent, the timeouts aren't set, and there's no circuit breaker to stop hammering a dependency that's genuinely down.

Polly v8 solves this with typed resilience pipelines:

dotnet add package Microsoft.Extensions.Http.Resilience

// Program.cs — applies to every HttpClient registered with this name
builder.Services.AddHttpClient<PaymentGatewayClient>(client =>
{
    client.BaseAddress = new Uri(builder.Configuration["PaymentGateway:BaseUrl"]!);
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddStandardResilienceHandler(options =>
{
    // Retry: 3 attempts with exponential backoff + jitter
    options.Retry.MaxRetryAttempts = 3;
    options.Retry.Delay = TimeSpan.FromSeconds(1);
    options.Retry.UseJitter = true;

    // Circuit breaker: open after 5 failures in 30s, try again after 30s
    options.CircuitBreaker.FailureRatio = 0.5;
    options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(30);
    options.CircuitBreaker.BreakDuration = TimeSpan.FromSeconds(30);

    // Timeout per attempt
    options.AttemptTimeout.Timeout = TimeSpan.FromSeconds(10);
});

For database calls and other non-HTTP operations, use the generic ResiliencePipelineBuilder:

var pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        MaxRetryAttempts = 3,
        Delay = TimeSpan.FromMilliseconds(500),
        BackoffType = DelayBackoffType.Exponential,
        ShouldHandle = new PredicateBuilder()
            .Handle<SqlException>(ex => ex.IsTransient)
    })
    .AddTimeout(TimeSpan.FromSeconds(5))
    .Build();

await pipeline.ExecuteAsync(async ct =>
{
    await _db.SaveChangesAsync(ct);
}, cancellationToken);

The key insight: resilience is a cross-cutting concern, not something individual services should implement in ad hoc ways. Define it once at the HttpClient registration or pipeline construction level. The calling code stays clean.

Phase 7: Add Health Checks

A health check endpoint is the minimum observability contract between your service and its infrastructure. Kubernetes uses it for liveness and readiness probes. Load balancers use it to route traffic. Uptime monitors use it to send alerts.

// Program.cs
builder.Services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>("database")
    .AddUrlGroup(new Uri(builder.Configuration["PaymentGateway:BaseUrl"] + "/health"),
        name: "payment-gateway",
        tags: ["external"])
    .AddCheck("memory", () =>
    {
        var allocated = GC.GetTotalMemory(forceFullCollection: false);
        var threshold = 1024L * 1024 * 512; // 512 MB
        return allocated < threshold
            ? HealthCheckResult.Healthy($"{allocated / 1024 / 1024}MB")
            : HealthCheckResult.Degraded($"{allocated / 1024 / 1024}MB — approaching limit");
    });

// Map two endpoints: one for liveness, one for readiness
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false // liveness: just confirm the process is up
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => !check.Tags.Contains("external"), // readiness: internal deps only
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
});

The split between liveness and readiness matters. A liveness probe that checks the database will restart the pod when the database is slow — killing a perfectly healthy process. Liveness should only verify the process is alive and not deadlocked. Readiness verifies that the service can handle traffic.

Phase 8: The Strangler Fig — Replace Incrementally

The strangler fig is the architectural pattern for replacing a legacy system without a rewrite. You build new functionality alongside the old system and gradually route traffic from old to new, strangling the legacy code until nothing depends on it.

In .NET, this typically looks like:

1 — New service, same database (initially)

Build new endpoints alongside old ones. They can share the same database while the migration is in progress — this is a pragmatic compromise, not a permanent state.

/api/v1/orders  → Legacy controller (existing code, unchanged)
/api/v2/orders  → New controller (modern code, DI, async, validated)

2 — Introduce the Anti-Corruption Layer

When the new code needs to consume functionality from the old system (for features that haven't been rebuilt yet), wrap the old code in an ACL. The new system speaks the new model; the ACL translates.

// New domain model
public record OrderSummary(int Id, Money Total, OrderStatus Status);

// ACL — translates from legacy model to new model
public class LegacyOrderAdapter : IOrderRepository
{
    private readonly LegacyOrderService _legacy; // old code

    public async Task<OrderSummary?> GetOrderAsync(int id, CancellationToken ct)
    {
        // Call legacy code, translate result
        var legacyOrder = _legacy.GetOrder(id); // synchronous, returns LegacyOrder
        if (legacyOrder is null) return null;

        return new OrderSummary(
            legacyOrder.OrderId,
            new Money(legacyOrder.TotalAmount, Currency.EUR),
            MapStatus(legacyOrder.StatusCode));
    }

    private static OrderStatus MapStatus(int code) => code switch
    {
        1 => OrderStatus.Pending,
        2 => OrderStatus.Processing,
        3 => OrderStatus.Completed,
        _ => OrderStatus.Unknown
    };
}

3 — Route gradually, measure, retire

Use feature flags or routing rules to send a percentage of traffic to the new implementation. Measure error rates, latency, and correctness against the old system. When confidence is high, route everything to the new code and delete the old.

// Feature flag routing — coarse but effective
app.MapGet("/api/orders/{id}", async (int id, IFeatureManager features, ...) =>
{
    if (await features.IsEnabledAsync("UseNewOrderService"))
        return await newOrderService.GetOrderAsync(id, ct);

    return await legacyOrderAdapter.GetOrderAsync(id, ct);
});

The strangler fig works because it's reversible at every step. If the new code breaks, you route back to the old code. If the old code has a bug you didn't know about, you replicate it in the new code before retiring the old one. At no point are you committed to a rewrite that can't be partially rolled back.

What Not to Modernise

Not everything should be touched. The goal is a system that serves the business better — not a system that satisfies architectural principles.

Leave stable, tested code alone. If a module works correctly, has no performance problems, and doesn't need to change for any upcoming features, the cost of modernising it is pure overhead. The business doesn't benefit from async versions of code that runs once a day on a schedule.

Don't add abstractions for future flexibility. Every abstraction layer you add to "make it easier to change later" has to be maintained by every developer who reads that code. Add it when the flexibility is needed, not before.

Don't retrofit patterns onto code that doesn't need them. CQRS in a service with three endpoints and twenty queries adds complexity without benefit. The patterns that appear throughout this article — structured logging, health checks, resilience pipelines — provide value independent of traffic and team size. Architectural patterns like CQRS, event sourcing, and domain-driven design are valuable when the problem demands them.

Measuring Progress

Modernisation without measurement is renovation without a blueprint. Track these:

P99 latency on endpoints that changed — async conversion and connection pooling produce visible improvements here.
Thread pool starvation events — available in EventCounters or via dotnet-counters monitor. These drop to near-zero after async conversion.
Build time — moving to modern .NET typically cuts build times significantly.
Deployment frequency — if modernisation is working, the team moves faster, not slower.
Error rate in the critical path — resilience pipelines and proper exception handling produce measurable drops here.

A modernisation that doesn't show up in metrics is either not working or fixing the wrong things.

The Twelve-Year Application

We didn't rewrite the logistics platform. Over eighteen months, we moved it to .NET 9, converted the critical path to async, replaced the log files with structured logging in Seq, added Polly pipelines to every external call, split the health check into liveness and readiness, and rebuilt the order processing module using the strangler fig — new code alongside old, gradual traffic shift, old code retired when confidence was established.

The team is faster. The platform handles three times the daily order volume without adding infrastructure. Developers want to work on it now.

The twelve-year application is still running. It's just not the same twelve-year application it was.

Full source code: github.com/AdrianBailador/enterprise-dotnet-modernisation

Questions or suggestions? Open an issue on GitHub.

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.

DEV Community: Adrián Bailador

GPT-6 Astra for .NET: What Changes in the API, and Where the SDK Hasn't Caught Up

Code

What's actually in the model

Pricing, per the live pricing page

Calling it from .NET: two paths, one of them experimental

The stable path: Chat Completions

The experimental path: Responses API

The gap: named reasoning levels stop at High

What's still open

Distributed Tracing in ASP.NET Core: From HTTP to the Queue with OpenTelemetry

What a trace is actually made of

The setup: two services, one trace

Reading the actual trace

Where it actually breaks

Correlating logs with the trace

What I didn't cover

Upgrading to .NET 10: The Breaking Changes That Don't Show Up at Compile Time

EF Core 10

ASP.NET Core 10

BackgroundService and configuration

SDK and CI

Migration order

Code

Microsoft.Extensions.AI: One IChatClient Interface, Any LLM Provider

Code

Two Packages, Three Interfaces

IChatClient: Send Messages, Get a Response

The Actual Value: Middleware You Don't Have to Write

Wiring It Into DI

Tool Calling Without Writing the Loop Yourself

Writing Your Own Middleware

Stateless History vs. Stateful Conversations

What This Doesn't Replace

Conclusion

Passkeys in ASP.NET Core 10: Passwordless Authentication with Identity

Attestation and Assertion, in Plain Terms

What ASP.NET Core Identity Actually Supports

Configuring Passkey Behaviour

Registration Flow

Sign-In Flow

The Gaps You Need to Know About

When to Reach for Something Else

Conclusion

C# 15 Preview: Union Types and Closed Hierarchies, Finally

Ten Years of Asking

Union Types: The Actual Syntax

The Payment Result, Done Properly

The Gotcha: How Unions Actually Store Data

Closed Hierarchies: The Other Half of the Answer

Which One Do You Reach For?

The Quiet Third Feature: unsafe Gets Redefined

Should You Touch Any of This Today?

The Fourth Case

Modernising Legacy .NET Applications Without a Rewrite

Why Rewrites Fail

Start with a Diagnosis, Not a Plan

Phase 1: Upgrade the Target Framework

Phase 2: Migrate Off EF6 and EDMX

Phase 3: Replace Static State and Service Locators

Phase 4: Make It Async — Without Breaking It

Phase 5: Add Structured Logging

Phase 6: Add Resilience for External Calls

Phase 7: Add Health Checks

Phase 8: The Strangler Fig — Replace Incrementally

What Not to Modernise

Measuring Progress

The Twelve-Year Application

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

The Pipeline at a Glance

Stage 1: You Write Informal Specs

Stage 2: Specifier Agent — Informal to Hard Specs

Stage 3: Specifier Agent — Tasks to Gherkin

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

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

Stage 6: Architect Agent — Mutation Testing

Language Mutation

Gherkin Mutation

Full Suite

Human Interaction Across the Pipeline

The gap: named reasoning levels stop at `High`

The Quiet Third Feature: `unsafe` Gets Redefined