DEV Community: Adrián Bailador

CQRS with MediatR, Revisited for .NET 10

Adrián Bailador — Mon, 26 Oct 2026 09:39:39 +0000

Code

Full runnable solution — API, pipeline behaviors, tests, and a side-by-side comparison against a source-generated alternative: cqrs-mediatr-dotnet10.

Rebuilding Instead of Patching

In 2024 I wrote a guide to implementing CQRS with MediatR on .NET 8. It did well — picked up, shared, still shows up when people search for MediatR and CQRS together. People used it to learn the pattern, and some of them are still running the code from it, unmodified, in production.

Two years felt like enough distance that patching the original in place wasn't going to cut it, so I rebuilt it from scratch — new project, new tests, same pattern — on .NET 10 and the current MediatR, rather than diff the old code against new package versions and call it current. The pattern itself didn't need reinventing. What was worth a second look was everything sitting around it: what MediatR's license actually asks of you now, which parts of the original code were weaker than they looked, and what .NET 10 does differently by default.

Setup, and What the License Requires

MediatR changed its license in July 2025 — the last Apache 2.0 release was 12.5.0, and from 13.0 onward it's dual-licensed (RPL-1.5, or commercial) through Lucky Penny Software. For most people this changes nothing you'll actually feel: the Community edition is free under $5,000,000 in gross annual revenue, and you register a key at mediatr.io and set it via MEDIATR_LICENSE_KEY. Skip it and MediatR logs a reminder; it doesn't break anything.

I wrote about building CQRS without MediatR entirely back when the license change was the news — that's the article for "I want this pattern with zero third-party dependency." This one assumes you're staying on MediatR, or close to it, and cares about what else is different.

The registration looks like this, with the key wired to configuration instead of hardcoded:

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssemblyContaining<Program>();
    cfg.AddOpenBehavior(typeof(LoggingBehavior<,>));
    cfg.AddOpenBehavior(typeof(ValidationBehavior<,>));

    var licenseKey = builder.Configuration["MediatR:LicenseKey"];
    if (!string.IsNullOrWhiteSpace(licenseKey))
    {
        cfg.LicenseKey = licenseKey;
    }
});

appsettings.json ships with "MediatR": { "LicenseKey": "" } as a placeholder — the actual key comes from configuration or environment variables in every real deployment, never committed alongside the code.

Building It Again, On .NET 10

Same shape as the original: a CreateProductCommand that writes, a GetProductByIdQuery that reads, both going through MediatR's pipeline instead of calling a service directly. What's different is the surrounding plumbing — minimal API endpoints instead of a controller, Results.Created/Results.NotFound instead of generic IActionResult, and an IExceptionHandler instead of a behavior that catches Exception and does nothing useful with it:

app.MapPost("/products", async (CreateProductCommand command, ISender sender, CancellationToken ct) =>
{
    var id = await sender.Send(command, ct);
    return Results.Created($"/products/{id}", new { id });
});

app.MapGet("/products/{id:int}", async (int id, ISender sender, CancellationToken ct) =>
{
    var product = await sender.Send(new GetProductByIdQuery(id), ct);
    return product is Product found ? Results.Ok(found) : Results.NotFound();
});

Endpoints depend on ISender, not the full IMediator — they only ever send requests, never publish notifications directly, so the narrower interface is what they should ask for.

The Pipeline Behaviors: Validation and Logging

The original guide's ExceptionHandlingBehavior caught Exception, left a // Log and handle the exception comment, and rethrew. It was a placeholder that looked like a feature. This version replaces it with something that actually resolves to an HTTP response:

public sealed class ValidationBehavior<TRequest, TResponse>(IEnumerable<IValidator<TRequest>> validators)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : notnull
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        if (!validators.Any())
        {
            return await next(cancellationToken);
        }

        var context = new ValidationContext<TRequest>(request);
        var failures = (await Task.WhenAll(validators.Select(v => v.ValidateAsync(context, cancellationToken))))
            .SelectMany(result => result.Errors)
            .Where(failure => failure is not null)
            .ToList();

        if (failures.Count > 0)
        {
            throw new ValidationException(failures);
        }

        return await next(cancellationToken);
    }
}

ValidationException gets caught by a registered IExceptionHandler that turns it into a 400 with field-level errors, instead of a generic 500 or a hand-rolled try/catch scattered across every endpoint.

One more thing about the library, stated as a fact rather than a warning: RequestHandlerDelegate<TResponse>'s CancellationToken parameter is optional, so next() compiles without it. Calling it that way isn't the footgun it looks like — MediatR's own pipeline wrapper checks for it explicitly. In the actual source:

Task<TResponse> Handler(CancellationToken t = default) =>
    serviceProvider.GetRequiredService<IRequestHandler<TRequest, TResponse>>()
        .Handle((TRequest) request, t == default ? cancellationToken : t);

Every layer of the pipeline substitutes the original request's token back in whenever it sees default. Calling next(cancellationToken) explicitly, the way this repo does, doesn't fix anything — MediatR already defends against the omitted case. It's just clearer to read, and it's the one way to deliberately pass a different token downstream (a derived timeout token, say) without that substitution quietly overriding it: pass anything other than default, and this fallback doesn't apply. CancellationTokenPipelineTests.Send_IgnoresADeliberateCancellationTokenNone_AndUsesTheOriginalToken proves it end to end, through the real pipeline rather than a hand-built delegate: a behavior that deliberately calls next(CancellationToken.None) still can't stop the original Send() token from reaching the handler.

The LoggingBehavior follows the same explicit style:

public sealed class LoggingBehavior<TRequest, TResponse>(ILogger<LoggingBehavior<TRequest, TResponse>> logger)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : notnull
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        var requestName = typeof(TRequest).Name;
        var stopwatch = Stopwatch.StartNew();

        try
        {
            return await next(cancellationToken);
        }
        finally
        {
            logger.LogInformation(
                "{RequestName} completed in {ElapsedMilliseconds}ms",
                requestName,
                stopwatch.ElapsedMilliseconds);
        }
    }
}

Behaviors run in registration order — logging wraps validation wraps the handler — so a request that fails validation still gets timed and logged instead of vanishing before anything records it happened.

Domain Events, Unchanged in Spirit

The event side of the original guide didn't need rebuilding, just tightening. A command handler that creates a Product publishes a notification afterward; a separate handler reacts to it. Same decoupling as before, now through IPublisher instead of the full IMediator:

public sealed class CreateProductCommandHandler(ApplicationDbContext context, IPublisher publisher)
    : IRequestHandler<CreateProductCommand, int>
{
    public async Task<int> Handle(CreateProductCommand request, CancellationToken cancellationToken)
    {
        var product = new Product { Name = request.Name, Price = request.Price };

        context.Products.Add(product);
        await context.SaveChangesAsync(cancellationToken);

        await publisher.Publish(new ProductCreatedEvent(product.Id), cancellationToken);

        return product.Id;
    }
}

The handler doesn't know or care what reacts to ProductCreatedEvent — logging, a future email, a future integration event onto a bus. That's still the point of the pattern, and it hasn't changed.

Testing Handlers Without Mocking DbContext

The original guide's test mocked ApplicationDbContext directly with Moq and asserted SaveChangesAsync was called once. That pattern is weaker than it looks: DbContext and DbSet<T> aren't designed to be mocked faithfully — Add doesn't behave the way a real change tracker behaves against a mock, and the test ends up checking "did I call a method" rather than "did the right data end up persisted."

The first instinct is EF Core's InMemory provider, and it's a real improvement over mocking — but it's worth being precise about what it actually is: a simplified in-process store that skips relational behavior entirely. It won't catch a constraint violation, and its LINQ translation doesn't go through the same path a real provider's does. For handler tests that only need "did the data end up there," that gap rarely bites. For anything that needs to behave like the database it'll actually run against, it's the wrong tool.

The companion repo uses a real SQLite database instead, kept in memory for the test's lifetime — same relational engine, same constraint and query behavior a production SQLite deployment would see, just not persisted to disk:

internal sealed class SqliteTestContext : IAsyncDisposable
{
    private readonly SqliteConnection _connection;

    public ApplicationDbContext Context { get; }

    private SqliteTestContext(SqliteConnection connection, ApplicationDbContext context)
    {
        _connection = connection;
        Context = context;
    }

    public static async Task<SqliteTestContext> CreateAsync()
    {
        var connection = new SqliteConnection("DataSource=:memory:");
        await connection.OpenAsync();

        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
            .UseSqlite(connection)
            .Options;

        var context = new ApplicationDbContext(options);
        await context.Database.EnsureCreatedAsync();

        return new SqliteTestContext(connection, context);
    }

    public async ValueTask DisposeAsync()
    {
        await Context.DisposeAsync();
        await _connection.DisposeAsync();
    }
}

The connection has to stay open for as long as the context does — SQLite drops an in-memory database the moment its one connection closes, which is why it's wrapped here instead of opened and discarded inside DbContextOptionsBuilder. Each test gets its own connection, so they don't share state:

[Fact]
public async Task Handle_PersistsProduct_AndReturnsItsId()
{
    await using var db = await SqliteTestContext.CreateAsync();
    var context = db.Context;
    var publisher = new RecordingPublisher();
    var handler = new CreateProductCommandHandler(context, publisher);

    var id = await handler.Handle(new CreateProductCommand("Keyboard", 49.99m), CancellationToken.None);

    var stored = await context.Products.FindAsync(id);
    Assert.NotNull(stored);
    Assert.Equal("Keyboard", stored!.Name);
}

RecordingPublisher is a two-method fake implementation of IPublisher that appends to a list — enough to assert ProductCreatedEvent was actually published, with the actual product ID, without pulling in a mocking framework for an interface that's trivial to implement directly.

The Native AOT Limitations of Reflection-Based Handler Discovery

Three separate things are easy to lump together here, so worth pulling apart. MediatR's default registration — RegisterServicesFromAssemblyContaining<T>() — finds handlers by scanning assembly types with reflection (ConnectImplementationsToTypesClosing, walking assembliesToScan in MediatR's own ServiceRegistrar source). That's reflection-based discovery, and it's orthogonal to AOT by itself — plenty of reflection-heavy code runs fine on the normal JIT runtime. The actual conflict is with trimming: a separate publish-time step that removes types and members it can't prove are reachable. A handler type that's only ever referenced dynamically, through that assembly scan, gives the trimmer nothing to anchor on, so it can get stripped from a trimmed build. Native AOT is where this bites in practice because, per Microsoft's own documentation, a Native AOT publish requires trimming — the two aren't independent toggles once PublishAot is set.

None of this is MediatR being careless. Asked directly on GitHub whether MediatR supports AOT, Jimmy Bogard's answer was blunt: "I have no idea... it's not something any of my clients need, none of them need any kind of AOT." It's an honest statement of priorities, not a bug report languishing — and it's exactly why a small ecosystem of source-generator alternatives has grown up around that same issue thread: FastMediatR, ZeroAlloc.Mediator, and the one this article uses for comparison below, all moving handler discovery to compile time instead of leaning on a runtime scan trimming can't see through.

If you're not publishing with PublishAot, none of this touches you — skip it. If you are, better to know now than while debugging a trimmed build that can't find a handler it could find fine in dotnet run.

A Third Option: Mediator, Source-Generated

If hand-rolling the dispatcher yourself — the approach in the "without MediatR" article — is more control than you want, there's a middle ground. martinothamar/Mediator — package name is just Mediator, easy to confuse with the pattern it implements — is a source-generated, MIT-licensed, reflection-free in-process mediator. No license key, no runtime assembly scanning, and no interfaces to design yourself: it exists partly because of MediatR's license change, built to be close enough to MediatR's API that switching isn't a rewrite.

Close enough that the same CreateProductCommand handler barely changes shape:

public sealed record CreateProductCommand(string Name, decimal Price) : IRequest<int>;

public sealed class CreateProductCommandHandler : IRequestHandler<CreateProductCommand, int>
{
    private static int _nextId = 1;

    public ValueTask<int> Handle(CreateProductCommand request, CancellationToken cancellationToken)
    {
        var id = _nextId++;
        return new ValueTask<int>(id);
    }
}

Same IRequest<TResponse>, same IRequestHandler<TRequest, TResponse> names. The difference that matters: Handle returns ValueTask<TResponse> instead of Task<TResponse> — a real signature change, not a cosmetic one, since ValueTask can't be awaited twice the way Task can. Registration is services.AddMediator(), generated by the source generator rather than resolved at startup via assembly scanning. And it's two packages, not one: Mediator.SourceGenerator goes in your outermost executable project, Mediator.Abstractions goes wherever you define messages and handlers.

That example is deliberately thin — a static counter standing in for the write, no persistence, no ProductCreatedEvent equivalent published afterward. It's there to compare the mediator plumbing, not to claim this is a drop-in functional match for the MediatR version, which persists through EF Core and publishes a real notification. Mediator has its own INotification/INotificationHandler<T> for that side of the pattern; wiring it up is more of the same shape-matching shown here, not a different story.

What you give up: a decade-plus of MediatR-specific Stack Overflow answers, blog posts, and third-party extensions that assume MediatR's exact API — some of it won't translate cleanly. For a greenfield service where Native AOT or the license terms are a real constraint, it's a legitimate default. For an existing MediatR codebase, it's a migration with a real cost, not a drop-in swap — don't start one over a licensing preference alone.

When CQRS With a Mediator Still Makes Sense

None of the above changes when this pattern is worth reaching for. It still is, when:

Commands and queries have genuinely different scaling or consistency needs — a read model that's eventually consistent and heavily cached, next to a write path that isn't.
Cross-cutting concerns — validation, logging, authorization — are numerous enough that a pipeline earns its keep over scattering the same checks across services.
The team is large enough, or the domain complex enough, that "every handler does exactly one thing" is worth the extra files it costs.

And it's still not worth it for a CRUD API with five endpoints and one developer. A mediator pipeline adds indirection — tracing a request means following Send into a handler you can't Ctrl+click to in every IDE, through behaviors that run in an order you have to remember. That cost doesn't go away because the library got more interesting; if anything, a licensing decision and an AOT caveat are two more things to weigh against a pattern you might not have needed.

Pitfalls in Production

A missing or expired license key doesn't fail loudly. It logs. If your logging pipeline filters Information-level noise in production, you can run unlicensed for months without anyone noticing — know what MediatR logs before you decide that's acceptable.
Notification handler failures can fail the triggering command. MediatR's default publisher awaits each notification handler in turn; if ProductCreatedEventHandler throws, that exception propagates back through Publish and into the command handler that called it. Decide deliberately whether that's what you want; it usually isn't for truly fire-and-forget side effects.
AddOpenBehavior order is registration order, not alphabetical or declared-type order. Reordering two cfg.AddOpenBehavior calls changes which behavior sees a request first. Treat that order as part of the design, not an implementation detail.
The $5M revenue threshold is gross revenue, not profit, and it's evaluated per company, not per project. A small team inside a large company doesn't get to claim the Community tier because their specific project is small.
If you deliberately want to pass CancellationToken.None downstream, you can't, by accident or on purpose. MediatR's pipeline substitutes the original request token back in whenever it sees default at any layer — convenient for the common case, but it means there's no way to say "this specific sub-call shouldn't observe cancellation" through the token parameter alone.

Best Practices

Set the license key from configuration or environment, never hardcoded. MEDIATR_LICENSE_KEY as an environment variable keeps it out of source control entirely — no placeholder value to accidentally commit.
Inject ISender/IPublisher, not IMediator, at the call site. The narrower interface documents intent: this endpoint sends requests, that handler publishes notifications, and nothing in either needs the other's half of the API.
Call next(cancellationToken) explicitly in a behavior, even though MediatR doesn't strictly require it. It's clearer to read, and it's the only way to intentionally pass a different token downstream without the library's own fallback overriding it.
Test handlers against a real database engine, not a mocked DbContext or EF Core's InMemory provider. SQLite in memory is still fast and still disposable, but it exercises real relational behavior — a mocked DbContext only tells you a method was called, and InMemory skips the constraints and query translation a real provider applies.
Keep validation in the pipeline, not in handlers. A ValidationBehavior that runs before every handler means no handler has to remember to call a validator manually — and none of them can forget to.
Decide once, in writing, whether event handler failures should fail the triggering command. IPublisher.Publish makes that choice for you by default (they do fail it); don't discover that in an incident.
If you're not shipping Native AOT, the reflection-vs-source-generator question isn't yours to solve today. Don't migrate off MediatR pre-emptively for a constraint you don't have.

Conclusion

The pattern in this guide is the same pattern from 2024 — commands and queries, pipeline behaviors for the cross-cutting concerns, notifications for the side effects nobody wants coupled to the write path. None of that needed reinventing, and rebuilding it from scratch confirmed as much. What rebuilding it actually changed was everything sitting around the pattern: a license that now asks something of you it didn't before, an exception-handling placeholder replaced with something that resolves to a real response, a test suite that checks persistence instead of a mocked method call, and a credible source-generated alternative that didn't exist when the original guide did.

If your MediatR setup predates mid-2025 and you haven't looked at any of this yet, that's the gap worth closing. The CQRS was fine the whole time.

Your Database Column Is Encrypted. Your JSON Response Isn't.

Adrián Bailador — Tue, 20 Oct 2026 13:39:28 +0000

Code

Full runnable demo, with tests: stj-property-encryption-dotnet.

The Leak Nobody Flagged in the Security Review

A SOC 2 audit two years ago flagged customer PII sitting in plaintext in the database. The fix was the standard one: an EF Core ValueConverter wrapping Email and Ssn in AES before SaveChangesAsync, decrypting them back out on the way through the DbContext. The audit closed. Everyone moved on.

Last month, a support engineer debugging a billing issue pasted the raw response from GET /api/users/42 into a shared Slack channel to show a teammate what the API was returning. The response had a customer's email and SSN sitting right there in the JSON, in plaintext, for anyone in that channel to read — and for Slack's own servers to store indefinitely.

The database was never the problem. EncryptionHelper and the ValueConverter did exactly what they were built to do: nothing reaches disk unencrypted. But EF Core decrypts those columns back into plain C# strings the moment it hydrates the entity, because the application needs the real values to do anything useful with them. From that point on, Email and Ssn are just string properties on a POCO — and every serializer in the process, System.Text.Json included, treats them exactly like Name or City. The column was encrypted. The object in memory was not. Neither was the response.

(A composite of two scenarios that play out the same way in enough codebases that naming a specific one wouldn't add anything — the audit-then-decrypted-leak pattern is the point, not the particular Slack channel it happened in.)

Where This Actually Lives: the Serialization Boundary, Not the Persistence Layer

Encrypting a column protects data at rest — on disk, in a backup, in a stolen database file. It says nothing about data in transit through your own process: API responses, structured logs, outbound webhook payloads, anything that calls JsonSerializer.Serialize on an object holding that value. Those are two different quality attributes solving two different threats, and treating one as a substitute for the other is how a "we encrypt sensitive data" checkbox survives an audit while a raw response still leaks a social security number into a chat tool.

The obvious fix is a custom JsonConverter<T> — but a converter is attached to a type. Writing one for User means hand-rolling the entire object's read/write logic just to intercept two fields out of several, re-implementing it by hand every time User gains a new property. The alternative is wrapping each sensitive field in its own type (EncryptedString instead of string) so a per-type converter has something narrower to target — and that wrapper leaks into your domain model, your EF Core mappings, and every place that reads user.Email. Neither approach scales to "any property on any type that happens to need this," which is exactly the shape of the actual problem.

System.Text.Json's contract customization API solves the actual problem: a JsonTypeInfo modifier runs once per type, when its serialization contract is built, and can rewrite how any individual property is read or written — without changing its declared type. You mark the property, not the type:

public sealed class User
{
    public required int Id { get; set; }
    public required string Name { get; set; }

    [Encrypted]
    public required string Email { get; set; }

    [Encrypted]
    public required string Ssn { get; set; }

    public required Address Address { get; set; }
}

public sealed class Address
{
    public required string Street { get; set; }
    public required string City { get; set; }

    [Encrypted]
    public required string PostalCode { get; set; }
}

User and Address are plain POCOs. Nothing here says "encrypted" beyond an attribute that's meaningless to EF Core, to a unit test, to anything that isn't specifically looking for it. That's the point — the serializer is the only thing that needs to care.

The Modifier: Rewriting `Get` and `Set` for One Attribute

A JsonTypeInfo exposes its properties as a mutable collection during contract resolution. Each JsonPropertyInfo carries an AttributeProvider — the reflection metadata for the backing member — and two delegates: Get, called when serializing, and Set, called when deserializing. A modifier is just a function that walks that collection and replaces those delegates for the properties it cares about:

public static class EncryptionTypeInfoModifier
{
    public static Action<JsonTypeInfo> Create(IPropertyEncryptor encryptor)
    {
        return typeInfo =>
        {
            if (typeInfo.Kind != JsonTypeInfoKind.Object)
            {
                return;
            }

            foreach (var property in typeInfo.Properties)
            {
                var isEncrypted = property.AttributeProvider
                    ?.GetCustomAttributes(typeof(EncryptedAttribute), inherit: false)
                    .Length > 0;

                if (!isEncrypted)
                {
                    continue;
                }

                if (property.PropertyType != typeof(string))
                {
                    throw new InvalidOperationException(
                        $"[Encrypted] on '{typeInfo.Type.Name}.{property.Name}' requires a string property, " +
                        $"but '{property.Name}' is '{property.PropertyType.Name}'.");
                }

                var originalGet = property.Get;
                var originalSet = property.Set;

                if (originalGet is not null)
                {
                    property.Get = instance =>
                    {
                        var plaintext = (string?)originalGet(instance);
                        return plaintext is null ? null : encryptor.Encrypt(plaintext);
                    };
                }

                if (originalSet is not null)
                {
                    var propertyName = property.Name;
                    var declaringTypeName = typeInfo.Type.Name;

                    property.Set = (instance, value) =>
                    {
                        var ciphertext = (string?)value;
                        if (ciphertext is null)
                        {
                            originalSet(instance, null);
                            return;
                        }

                        string plaintext;
                        try
                        {
                            plaintext = encryptor.Decrypt(ciphertext);
                        }
                        catch (Exception ex) when (ex is FormatException or CryptographicException)
                        {
                            throw new JsonException(
                                $"'{declaringTypeName}.{propertyName}' is marked [Encrypted], but the incoming " +
                                "value isn't valid ciphertext for the configured key.", ex);
                        }

                        originalSet(instance, plaintext);
                    };
                }
            }
        };
    }
}

Three details earn their keep here. First, the typeInfo.Kind guard at the top — Get/Set rewriting is only meaningful for Object contracts; a List<T> or Dictionary<TKey,TValue> contract doesn't expose properties the same way, and the Microsoft documentation for JsonTypeInfo.Properties is explicit that this mutation path applies to object contracts. Skipping early is cheap and keeps the modifier correct if it ever runs against a contract kind it wasn't written for. Second, the type check isn't optional — [Encrypted] on an int or a DateTime fails the moment the contract is built, with a message naming the exact type and property, instead of an InvalidCastException three call frames deep inside System.Text.Json the first time something tries to serialize it. Third, Set catches only FormatException and CryptographicException — the two exceptions a real decryption failure can actually throw — and rethrows as JsonException; anything else propagates unchanged, because a bug in IPropertyEncryptor itself shouldn't get relabeled as "bad input."

Wiring it in is one line on JsonSerializerOptions:

var encryptedOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web)
{
    TypeInfoResolver = new DefaultJsonTypeInfoResolver()
        .WithAddedModifier(EncryptionTypeInfoModifier.Create(encryptor))
};

One Resolver, Two Directions

Get runs on the way out, Set runs on the way in — the same JsonSerializerOptions handles both, which is convenient right up until it isn't. If an endpoint accepts a request body and you bind it with encryptedOptions, every [Encrypted] property on that payload is assumed to already be ciphertext this encryptor produced. A client sending a plain "jane.doe@example.com" for Email on a signup request isn't sending malformed JSON — it's sending exactly what the field name says. Without the try/catch in Set, that call falls straight into Convert.FromBase64String or AesGcm.Decrypt and surfaces whatever exception they happen to throw, several layers away from anything that explains what actually went wrong.

The fix isn't cleverer code, it's a clearer boundary: decide per endpoint whether the body you're reading is plaintext input from a client or ciphertext round-tripped from one of your own previous responses, and don't use encryptedOptions for the former. This demo's two endpoints are both reads, so the question never comes up — but the moment you add a PUT that accepts a new email address, that handler needs plainOptions for binding, encrypting the value explicitly before it's persisted, not the resolver that assumes every incoming value is already encrypted. The JsonException in Set exists for the case this still slips through: it names the exact property and says plainly that the value wasn't valid ciphertext, instead of leaving you to decode a FormatException or an AuthenticationTagMismatchException thrown from inside a third-party serializer.

This also means /secure/users/{id} is only a useful response for a caller that can decrypt it. In this demo that's deliberately left open — the point is to show the mechanism — but in a real system, whoever calls that endpoint needs the key, or the endpoint needs to exist for a different consumer than the one calling /users/{id}: another backend service, a batch job, something that's supposed to see the real value and holds the key to prove it. Encrypting the response doesn't change who can ultimately read the data, only who can read it as it crosses this one boundary. A caller holding the key can decrypt, log, or forward the plaintext exactly as freely as if it had never been encrypted at all.

The Encryptor Behind `IPropertyEncryptor`

The modifier doesn't know or care how encryption happens — it depends on an interface:

public interface IPropertyEncryptor
{
    string Encrypt(string plaintext);
    string Decrypt(string payload);
}

The implementation uses AES-GCM, which is authenticated encryption — it detects tampering, not just hides content — with a fresh random nonce per call, so encrypting the same value twice never produces the same ciphertext twice:

public string Encrypt(string plaintext)
{
    var plaintextBytes = Encoding.UTF8.GetBytes(plaintext);
    var nonce = RandomNumberGenerator.GetBytes(NonceSize);
    var ciphertext = new byte[plaintextBytes.Length];
    var tag = new byte[TagSize];

    using (var aesGcm = new AesGcm(_key, TagSize))
    {
        aesGcm.Encrypt(nonce, plaintextBytes, ciphertext, tag);
    }

    var payload = new byte[NonceSize + TagSize + ciphertext.Length];
    Buffer.BlockCopy(nonce, 0, payload, 0, NonceSize);
    Buffer.BlockCopy(tag, 0, payload, NonceSize, TagSize);
    Buffer.BlockCopy(ciphertext, 0, payload, NonceSize + TagSize, ciphertext.Length);

    return Convert.ToBase64String(payload);
}

The nonce and the authentication tag travel with the ciphertext in the same base64 string, so Decrypt doesn't need anywhere else to look them up. This is also why the "same plaintext in, different ciphertext out" property matters for a demo claiming to be production-shaped: a field that always encrypts to the same value is a fingerprint, not a secret — anyone who can see two responses can tell whether two users share an email without ever decrypting either one.

Decrypt checks the payload is at least NonceSize + TagSize bytes before it tries to slice a nonce and a tag out of it — a short string that happens to be valid base64 (user input landing in the wrong place, for instance) would otherwise fail a byte-array slice with an unrelated-looking exception instead of a message that says what's actually wrong.

Before / After

Before ❌

app.MapGet("/users/{id:int}", (int id) =>
    users.TryGetValue(id, out var user)
        ? Results.Text(JsonSerializer.Serialize(user, plainOptions), "application/json")
        : Results.NotFound());

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "ssn": "078-05-1120",
  "address": { "street": "1 Market St", "city": "Dublin", "postalCode": "D02 AF30" }
}

plainOptions is a default JsonSerializerOptions. The database column was encrypted. This response isn't — and it's the response, not the column, that ends up in a browser dev tools tab, a support ticket attachment, or a Slack message.

After ✅

app.MapGet("/secure/users/{id:int}", (int id) =>
    users.TryGetValue(id, out var user)
        ? Results.Text(JsonSerializer.Serialize(user, encryptedOptions), "application/json")
        : Results.NotFound());

{
  "id": 42,
  "name": "Jane Doe",
  "email": "RiWPxVsYwFpr9y7O/ObDdAGoW31inngQR3LslYlfm12AKw/PdyGj2C2lAJXTXlUh",
  "ssn": "nKvWH5Ylan1hNIPt10yvsiuHI4ONS8u0Z0mZsYiS2dUaJwFkKTEB",
  "address": {
    "street": "1 Market St",
    "city": "Dublin",
    "postalCode": "se4eSO+KdhIvlWCdMwdSqlbj4Ws3IyOdU7rEZB7yTMBi3+jU"
  }
}

Same User, same Address, same handler — encryptedOptions is the only difference. Name, Street, and City stay readable because nothing marked them [Encrypted]; Email, Ssn, and the nested Address.PostalCode don't, including inside the nested object, without a separate converter for Address.

Impact: every marked property's value is encrypted when it's serialized through this specific JsonSerializerOptions — the HTTP response here, or anywhere else that explicitly reuses the same options. It says nothing about direct in-memory access to user.Email, a different serializer in the same process, or a structured logger with its own JSON formatter — those are separate paths that need their own control, not an assumption that this one already covers them. The domain model, the EF Core mapping, and the database schema don't change at all.

Encryption Is Not Redaction

Before reaching for this pattern, check a simpler question first: does the caller need this field at all? An endpoint that lists users for an internal admin dashboard might have no business returning Ssn in any form, encrypted or not. The right fix there is a DTO that omits the field entirely — a property that faithfully returns its ciphertext is still answering a question nobody should have asked. Encrypting a value you shouldn't be sending still sends it; the data has left the process either way, just unreadable to whoever shouldn't have it and to anyone else who intercepts it along the way. If the honest answer is "this response shouldn't carry that field," the fix is projection, not cryptography.

That's the general shape of the decision: each of these threats has a control shaped for it, and they're not interchangeable.

Need	Reach for
Protecting stored data	At-rest / column-level encryption
Protecting data on the wire between client and server	TLS
Not returning fields a caller doesn't need	A purpose-built DTO, not the full entity
Keeping sensitive values out of logs	Redaction or property filtering in the logging pipeline
Deliberately encrypting specific fields of a JSON payload	A `JsonTypeInfo` modifier
Stopping one caller from reading another caller's data	Authorization, not encryption

A JsonTypeInfo modifier answers exactly the fifth row. It's not a substitute for the other five, and using it as one just moves where a problem lives without closing it.

Pitfalls in Production

The same resolver that encrypts a response will try to decrypt a request. If an endpoint binds a request body with encryptedOptions and the client sends a plain value for an [Encrypted] property, that's not malformed input from the resolver's point of view — it's a value that fails to decrypt. Decide per endpoint whether you're reading your own ciphertext back or a client's plaintext input, and don't default to the encrypting resolver for the latter.
This protects the serializer you wire it into — and reusing it for logs isn't the fix either. A logging call like logger.LogInformation("{@User}", user) through a structured logger generally serializes with its own formatter, one that's never heard of EncryptionTypeInfoModifier, and writes the plaintext object straight into your log sink. But even wiring the same encryptedOptions into that logger doesn't make the result right — a log line full of ciphertext is still capturing a value it had no business holding. Redact or drop sensitive fields in the logging pipeline directly; reserve this resolver for serialization paths where encrypted output is the actual desired output, like the HTTP response itself.
Build JsonSerializerOptions once and reuse it. A modifier runs when a type's JsonTypeInfo is first resolved, and System.Text.Json caches that per JsonSerializerOptions instance. Constructing a fresh JsonSerializerOptions with the resolver chain on every request throws that cache away and rebuilds the whole contract, property by property, on every single call.
A property with no Set delegate doesn't just skip decryption — it can hand you back the wrong value entirely. The modifier guards on if (originalSet is not null) for a reason: a get-only property backed by a constructor parameter (no parameterless constructor, no settable backing field) never gets a reflection setter, so System.Text.Json populates it straight from the raw constructor argument instead, bypassing Set altogether. Serialization still encrypts it correctly on the way out. Deserialization, with no setter to intercept, lets the ciphertext go straight into the constructor — the resulting object's property holds ciphertext, not the original value, with no exception to flag it. Treat every type you mark as needing its own tested deserialization path, including types built through a parameterized constructor, not just a shared "does it look encrypted" assertion.
Nonce reuse is the one mistake that breaks AES-GCM's security guarantee outright — and there's no single safe number of operations to cite. This demo generates a fresh random 96-bit nonce per call via RandomNumberGenerator, which is the right default for a property-level encryptor. How much volume that tolerates under one key depends on message size, how many messages share that key, and the security margin your threat model actually needs — not a fixed operation count. A high-throughput system needs an explicit answer for nonce tracking, and a separate one for key rotation: when you retire a key, something still has to decrypt the payloads encrypted under the old one, which means versioning which key encrypted which value.
This is a confidentiality control, not a storage strategy. Ciphertext isn't queryable, sortable, or indexable by the database that eventually stores it. If the field is both persisted and serialized, you need the persistence-layer answer too — a ValueConverter, column-level encryption, or whatever your data layer uses — and the two don't have to use the same key or even the same algorithm.
A compile-time attribute isn't a compile-time guarantee here. [Encrypted] on the wrong property type fails at startup, the first time that type's contract is built — not at compile time, because this is a reflection-based resolver reading attributes at runtime. If you need the stronger guarantee, the equivalent check in a Roslyn source generator would catch it before the build even finishes.

Best Practices

Match the control to the actual threat instead of reaching for the most impressive one. If the real fix is "stop returning this field," a DTO solves it in one line and leaves nothing to decrypt. Save encryption for the case where the caller genuinely needs the value and the only question is how it travels.
Treat serialization-boundary encryption and at-rest encryption as two separate controls. Each protects a different threat (a leaked API response vs. a stolen database file). Don't let one satisfy an audit requirement meant for the other.
Fail loudly on misconfiguration, in both directions. InvalidOperationException for the wrong property type and JsonException for non-ciphertext input both turn a silent data-handling bug into something that fails the first smoke test instead of surfacing in a postmortem months later.

   if (property.PropertyType != typeof(string))
   {
       throw new InvalidOperationException(
           $"[Encrypted] on '{typeInfo.Type.Name}.{property.Name}' requires a string property...");
   }

Use authenticated encryption with a per-value random nonce, never a fixed one. AES-GCM with RandomNumberGenerator.GetBytes per call means identical plaintexts never produce identical ciphertexts — a deterministic scheme leaks equality even without ever decrypting anything.
Keep the key out of the repository you're reading this from — and plan its lifecycle, not just its storage. This demo loads a base64 key from appsettings.json for clarity; a real deployment pulls it from a key vault or secret manager, not a config file checked into source control. Storing it safely doesn't by itself answer what happens when the key rotates: something still needs to know which key encrypted which value, so a real deployment versions its keys and decides that up front, not when the first rotation breaks decryption for old data.
Test both directions explicitly, including the failure modes. A modifier that only gets exercised by a "the response looks encrypted" assertion can still be silently broken on the deserialize path. Round-trip every annotated type, including nested and collection properties, and assert that plaintext input and wrong-key ciphertext both fail clearly instead of corrupting data or throwing something unreadable.
Apply explicit redaction in the logging pipeline — don't assume this resolver reaches it. A modifier scoped to one JsonSerializerOptions instance protects exactly that instance's call sites, and a structured logger almost never shares it. Reuse the encrypting options for other serialization paths that deliberately need the same ciphertext a client would see — a background job, an outbound webhook built from the same model — but handle logs as their own control.
Reach for a modifier before reaching for a converter-per-type. A converter changes a type's entire serialization behavior; a modifier changes specific properties across every type that has them, including ones you haven't written yet. For a cross-cutting concern like "which fields are sensitive," that's the better default.

Conclusion

Encrypting a database column answers "what happens if someone steals the disk." It says nothing about "what happens the first time that value is serialized back out of the process that just decrypted it" — and most sensitive data spends far more of its lifetime in memory, in a response body, or in a log line than it ever spends sitting in a backup. A JsonTypeInfo modifier closes that specific gap: it's a serialization-time control, scoped to the properties that actually need it, that never touches the domain model, the EF Core mapping, or anything that isn't System.Text.Json itself.

Reach for this when the thing you're protecting is "what crosses this specific serializer's boundary," and the caller genuinely needs the value — not when the simpler fix is a DTO that doesn't return the field at all, not as a substitute for at-rest encryption, TLS, or authorization, and not as a stand-in for redacting what your logger captures, each of which answers a different question. And once you're comfortable rewriting Get/Set for one attribute, the same WithAddedModifier chain is how you'd implement field-level redaction for a lower trust level, audit logging on read, or masking in non-production environments — encryption is one instance of a much more general technique: changing what a property means at the serialization boundary without changing what it means anywhere else.

BOLA in ASP.NET Core: Why Authenticated Users Can Still Read Someone Else's Data

Adrián Bailador — Sun, 11 Oct 2026 07:29:39 +0000

A pentest report came back with a finding rated "high": change the invoiceId in GET /api/invoices/{invoiceId}, and a logged-in user from Tenant A could read a PDF belonging to Tenant B. No token theft, no SQL injection, no exotic exploit — just a sequential integer in a URL and a valid, perfectly legitimate session cookie. The endpoint had [Authorize] on it. It had role checks. It had passed every authentication test anyone had written. Nobody had written a test for "user A requests an object that belongs to user B," because on paper, authentication was the thing that made the endpoint secure.

This is Broken Object Level Authorization — BOLA, also known by its older name, IDOR (Insecure Direct Object Reference). It's been the #1 entry on the OWASP API Security Top 10 since the list existed, and it keeps that spot because it doesn't look like a vulnerability in code review. The code compiles, the happy path works, the demo looks fine. The bug is an absence: nobody checked whether this caller should see this object.

Code

The vulnerable endpoint, the fix, and the batch-endpoint pitfall below are all runnable in a companion repo: bola-aspnetcore-dotnet. All 5 tests pass, including the cross-tenant request that reproduces the bug and the regression test for the batch endpoint's .IgnoreQueryFilters() call. .NET 10.

Why `[Authorize]` Doesn't Help Here

[Authorize] and policy-based authorization in ASP.NET Core answer one question: is this already-authenticated principal allowed to call this endpoint at all? Authentication establishes who the caller is; endpoint authorization decides whether that principal can access the endpoint — "is this user logged in," "does this user have the Billing.Read claim." Neither of those questions mentions the specific invoice, document, or order the request is asking for. BOLA lives in the gap between "can call this endpoint" and "can touch this specific object," and that gap is invisible to anything that only inspects the token.

// Controller — passes every auth check ASP.NET Core ships with, out of the box
[Authorize(Policy = "Billing.Read")]
[HttpGet("api/invoices/{invoiceId:int}")]
public async Task<ActionResult<InvoiceDto>> GetInvoice(int invoiceId, CancellationToken ct)
{
    var invoice = await _invoiceRepository.GetByIdAsync(invoiceId, ct);
    if (invoice is null)
        return NotFound();

    return Ok(invoice.ToDto()); // whoever asked for invoiceId 4821 gets invoice 4821
}

The repository call fetches by primary key with no notion of whose key it is. Swap _invoiceRepository.GetByIdAsync for a query scoped to CurrentUser.TenantId, and the vulnerability disappears — but that fix has to live somewhere deliberate, not as a habit every developer remembers to repeat on every endpoint that takes an ID. Object-level authorization is a cross-cutting concern, and like every cross-cutting concern, it rots the moment it's implemented as a convention instead of a mechanism the framework enforces for you.

In Clean Architecture terms, this check belongs at the boundary between the API/Application layer and the data it hands back — after authentication has established who, before the handler returns what. It optimizes one quality attribute specifically: data confidentiality under multi-tenancy or multi-user ownership. It's overkill for genuinely public resources (a published blog post, a product catalog entry) and mandatory for anything scoped to an account, tenant, or user — invoices, documents, orders, support tickets, anything with an owner.

Resource-Based Authorization, Not an `if` Statement

ASP.NET Core already ships the mechanism for this: resource-based authorization via IAuthorizationService, which evaluates a policy against both the current user and the specific object, not just the user.

// Domain-adjacent resource
public sealed record Invoice(int Id, Guid TenantId, Guid OwnerId, decimal Amount, InvoiceStatus Status);

// Requirement — a marker, not logic
public sealed class SameTenantRequirement : IAuthorizationRequirement;

// Handler — the actual object-level check, written once
public sealed class SameTenantAuthorizationHandler : AuthorizationHandler<SameTenantRequirement, Invoice>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        SameTenantRequirement requirement,
        Invoice resource)
    {
        var tenantClaim = context.User.FindFirst("tenant_id")?.Value;

        if (Guid.TryParse(tenantClaim, out var tenantId) && tenantId == resource.TenantId)
            context.Succeed(requirement);

        return Task.CompletedTask;
    }
}

// Program.cs
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("SameTenant", policy => policy.Requirements.Add(new SameTenantRequirement()));

builder.Services.AddSingleton<IAuthorizationHandler, SameTenantAuthorizationHandler>();

// Controller — the object-level check is now explicit, reusable, and independently testable
[Authorize(Policy = "Billing.Read")]
[HttpGet("api/invoices/{invoiceId:int}")]
public async Task<ActionResult<InvoiceDto>> GetInvoice(
    int invoiceId,
    IAuthorizationService authorizationService,
    CancellationToken ct)
{
    var invoice = await _invoiceRepository.GetByIdAsync(invoiceId, ct);
    if (invoice is null)
        return NotFound();

    var authResult = await authorizationService.AuthorizeAsync(User, invoice, "SameTenant");
    if (!authResult.Succeeded)
        return Forbid(); // 403 here — this repository isn't tenant-scoped yet; that changes below

    return Ok(invoice.ToDto());
}

The handler is unit-testable in isolation, independent of HTTP, EF Core, or any controller — it takes a user principal and a plain record, and returns a decision. That's the point: object-level authorization becomes a named, reusable policy instead of a tenantId == invoice.TenantId check that one developer remembers to write and the next one forgets.

Defense in Depth: Scope the Query, Not Just the Response

Resource-based authorization catches the bug after the data is already loaded from the database. That's fine for a single invoice fetched by primary key, but it doesn't help with list endpoints, joins, or any query that could leak rows in bulk before a per-object check ever runs. The second layer is scoping the query itself, so cross-tenant rows are unreachable through normal queries against that DbSet — EF Core's global query filters are built for exactly this.

public sealed class AppDbContext(DbContextOptions<AppDbContext> options, ICurrentTenantProvider tenantProvider)
    : DbContext(options)
{
    public DbSet<Invoice> Invoices => Set<Invoice>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Invoice>()
            .HasQueryFilter(i => i.TenantId == tenantProvider.TenantId);
    }
}

Now _dbContext.Invoices.Where(i => i.Status == InvoiceStatus.Overdue) can never return another tenant's rows, regardless of whether the handler that wrote the query remembered to add a tenant check. That has a direct consequence for the HTTP response: with the filter enabled, a cross-tenant lookup for GetInvoice above resolves to no resource at all. invoice is null, the method returns 404, and AuthorizeAsync never runs — there's nothing left to pass it. Nothing's wrong there; the filter is doing exactly its job as a tenant boundary. What it means for the resource-based check is that its real value sits elsewhere: ownership or permission decisions within the tenant the filter already scoped the query to, and any code path that deliberately bypasses the filter, like the batch endpoint below. One answers "which tenant can this query see at all"; the other answers "can this specific caller touch this specific object" — and only the second one is still watching once the first gets turned off.

Before/After

Before ❌

[Authorize]
[HttpGet("api/documents/{documentId:guid}")]
public async Task<ActionResult<DocumentDto>> GetDocument(Guid documentId, CancellationToken ct)
{
    // Authenticated, but "authenticated" says nothing about ownership of THIS document.
    // Any logged-in user who guesses or enumerates a GUID gets the file.
    var document = await _documentRepository.GetByIdAsync(documentId, ct);
    return document is null ? NotFound() : Ok(document.ToDto());
}

After ✅

[Authorize]
[HttpGet("api/documents/{documentId:guid}")]
public async Task<ActionResult<DocumentDto>> GetDocument(
    Guid documentId,
    IAuthorizationService authorizationService,
    CancellationToken ct)
{
    // Query filter already scopes this to the caller's tenant (defense layer 1).
    var document = await _documentRepository.GetByIdAsync(documentId, ct);
    if (document is null)
        return NotFound();

    // Resource-based check covers ownership within the tenant (defense layer 2).
    var authResult = await authorizationService.AuthorizeAsync(User, document, "DocumentOwner");
    if (!authResult.Succeeded)
        return Forbid();

    return Ok(document.ToDto());
}

Impact line: In the audit that prompted this fix, 11 of 34 endpoints taking a resource ID had no object-level check — all 11 were exploitable with nothing more than a valid session and a predictable or enumerable ID. After adding query scoping and resource-based authorization as complementary controls enforced in code review for every multi-tenant resource, the same 34 endpoints produced zero cross-tenant findings on re-test.

Where the Check Sits in the Request Pipeline

Authentication and policy-based authorization answer "who, and can they call this endpoint." The query filter and the resource-based handler are the two object-level gates, and they sit on either side of the fetch — one preventing the wrong rows from ever being queryable, the other making the ownership decision explicit and testable for the single object that was fetched.

Pitfalls in Production

403 vs. 404 isn't a universal rule — it's a per-resource decision. Use 403 for "exists, but not yours" when the resource's existence isn't itself sensitive and you want "unauthorized" distinguishable from "not found," which helps debugging and legitimate support tooling. Use a uniform 404 when you specifically don't want a caller able to infer whether an ID exists at all — some account and billing APIs choose this deliberately. What causes real problems isn't picking one; it's leaving the choice to whichever status code a repository's null-check happened to return, mixing both inconsistently across endpoints.
Bulk and export endpoints are the ones everyone forgets. GET /api/invoices/export?ids=4821,4822,4823 is a classic blind spot: the single-object handler got the resource-based check, the batch endpoint reusing the same repository didn't, because "it's basically the same code."
.IgnoreQueryFilters() is a silent bypass of layer one. It's legitimately needed for admin tooling and background jobs, but every call site needs the resource-based check back in, explicitly — a global filter disabled for one legitimate reason disables it for the whole query, not just the reason you disabled it for.
GraphQL and OData make this worse, not better. $filter=tenantId eq 'other-tenant-guid' or a GraphQL query reaching through a relation the resolver didn't expect to be traversable both route around a check written for one specific REST shape. Query filters at the DbContext level are the control that survives an unexpected traversal path; a check written only in a specific controller action is not.
Soft-delete and restore paths skip the checks their "live" counterparts have. POST /api/invoices/{id}/restore is new code, written later, and routinely missing the same authorization the GET endpoint already has.
Nested resources need the parent checked too. Authorizing access to a comment by its own OwnerId isn't enough if the comment's parent document should also gate visibility — check the resource you're returning and the resource it belongs to.

Best Practices

The five questions a request has to clear, and where each one is answered:

Layer	Question	Example
Authentication	Who are you?	JWT / cookie
Endpoint authorization	Can you call this endpoint?	`[Authorize(Policy = "Billing.Read")]`
Query scoping	Which objects can the query even see?	EF Core `TenantId` query filter
Resource authorization	Can you access this object?	`IAuthorizationService.AuthorizeAsync`
Tests	Can a different user access it?	Cross-tenant test case

BOLA is what happens when authentication and endpoint authorization pass, but object-level isolation isn't enforced and tested.

For multi-tenant resources, treat query scoping and object-level authorization as complementary controls, not substitutes. A global query filter scoping storage, plus a resource-based policy scoping the single-object response — one without the other leaves either bulk queries or IgnoreQueryFilters() call sites exposed.
Write the handler once per resource type. An AuthorizationHandler<TRequirement, TResource> is reusable across every action that touches that resource — a GET, a PATCH, a DELETE, and the export endpoint all call the same policy.
Test the negative case explicitly: "user A, object owned by user B." Every endpoint accepting a resource ID needs this as its own test, separate from the happy-path "user A, object owned by user A" — a passing authentication test suite proves nothing about object-level isolation.
Pick 403 or 404 once per resource type, before the first endpoint for it ships. The trade-off is in the Pitfalls section above — the goal is a conscious choice, made once, rather than whatever a null-check happens to return.
Scope at the data layer for every entity with an owner or tenant. A global query filter keyed on TenantId or OwnerId protects every query written against that DbSet, including the ones nobody's written yet — it's the control that still helps after someone copy-pastes a repository method into a new feature six months from now.
Put .IgnoreQueryFilters() call sites in front of security review. They tend to get flagged in performance review instead, if at all — but each one is a deliberate disabling of layer one, and the question that matters is "does this call site still have layer two," not "does this still work."
Include object-ID endpoints in automated scanning, not just manual pentest cycles. A script that authenticates as two different test users and cross-requests every known object ID for the other user catches BOLA regressions the same week they're introduced, instead of the next time an external pentest is scheduled.

Conclusion

BOLA survives in production codebases because authentication and object-level authorization look like the same concern from inside a controller action — both involve [Authorize], both involve a user principal, both pass or fail with a status code. They're not the same concern. Authentication confirms identity once, at the edge; object-level authorization has to be re-evaluated for every object a request names, and it has to be a mechanism the architecture enforces, not a line of defensive code an individual developer remembers to write on a Tuesday.

The fix isn't exotic — IAuthorizationService and EF Core query filters have shipped in ASP.NET Core and EF Core for years. What's missing in most codebases that get burned by this isn't the tooling, it's the habit of treating "does this endpoint check the caller" and "does this endpoint check the caller against this specific object" as two separate questions that both need an explicit, testable answer. Apply the pair — query filter plus resource-based handler — to every entity with an owner, and the next pentest report has one less finding rated "high."

Polly v8 Rewrote Itself From Scratch. Here's What Actually Changed

Adrián Bailador — Sat, 03 Oct 2026 11:11:48 +0000

Polly showed up briefly in an earlier post on modernising a legacy enterprise codebase on this blog, wiring resilience into a set of external calls that used to fail with nothing but a bare try/catch. It deserved more room than a section of a bigger post, because v8 wasn't an incremental update to v7. It didn't just add features to the fluent Policy API: it introduced a different resilience model, built around one pipeline of composable strategies instead of one policy object per concern.

If you learned Polly on Policy.Handle<SomeException>().WaitAndRetryAsync(...), returning an IAsyncPolicy you awaited directly, none of that exists in current Polly. Every strategy (retry, circuit breaker, timeout, fallback, hedging, rate limiting) now composes through a single ResiliencePipelineBuilder, producing one ResiliencePipeline you execute once. This post covers what changed, the strategies you get, and how to test the two trickiest ones (retry and circuit breaker) without a test suite that waits out real delays.

Code

Three pipelines, each with its own tests, are runnable in a companion repo: polly-v8-dotnet. All 6 tests pass; run five times in a row while writing this post, the suite finished in 206-210ms every time. Pinned to Polly.Core 8.8.0.

What actually changed

Polly v7's model built a policy object through a fluent chain rooted in a static Policy factory, and that object was the thing you executed:

// v7 - no longer how current Polly works
IAsyncPolicy policy = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(attempt));

var result = await policy.ExecuteAsync(() => CallServiceAsync());

v8 replaces the policy object with a pipeline built from named strategies, each configured through its own options type:

ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        MaxRetryAttempts = 3,
        Delay = TimeSpan.FromSeconds(1),
        BackoffType = DelayBackoffType.Exponential,
    })
    .Build();

var result = await pipeline.ExecuteAsync(ct => CallServiceAsync(ct));

The difference is more than syntax. A ResiliencePipeline is built once and reused; strategies compose by adding them to the same builder instead of nesting policy-wrap calls; and every strategy shares the same ExecuteAsync shape instead of each policy type having its own execution quirks. The vocabulary maps over, but not one-to-one: Policy becomes ResiliencePipelineBuilder, IAsyncPolicy becomes ResiliencePipeline, and Policy.Handle<T>() becomes a ShouldHandle predicate (built with new PredicateBuilder().Handle<T>()) set on each strategy's own options. Code written against the v7 Policy API won't compile unchanged against the v8 Polly.Core API; the pipeline has to be rebuilt around strategies, not just renamed.

The six strategies

Per Polly's own strategy reference, the six built-in strategies split into two groups. Reactive strategies respond to a failure that already happened: Retry re-runs the operation after a delay, Circuit Breaker stops calling a dependency for a period once failures cross a threshold, Fallback returns an alternative value or runs an alternative action on failure, and Hedging runs parallel attempts and takes whichever finishes first. Proactive strategies prevent a failure from taking too long or too much: Timeout guarantees the caller doesn't wait past a limit, and Rate Limiter caps how many executions run at once. Rate Limiter is the odd one out in the list: its RateLimiterStrategyOptions (namespace Polly.RateLimiting) is a thin wrapper over the separate System.Threading.RateLimiting package rather than a Polly-native implementation.

Any number of these compose into one pipeline via repeated .Add*() calls on the same builder.

Retry, tested without waiting

The pipeline builder lets you provide a TimeProvider, which Polly's time-based strategies (retry delays, circuit breaker durations, timeouts) read instead of the real clock. Strategies that don't deal in time ignore it entirely.

public sealed class RetryDemo
{
    private readonly ResiliencePipeline _pipeline;

    public RetryDemo(TimeProvider timeProvider)
    {
        _pipeline = new ResiliencePipelineBuilder
        {
            TimeProvider = timeProvider,
        }
        .AddRetry(new RetryStrategyOptions
        {
            MaxRetryAttempts = 2,
            Delay = TimeSpan.FromSeconds(1),
            BackoffType = DelayBackoffType.Constant,
        })
        .Build();
    }

    public Task<string> CallAsync(Func<CancellationToken, ValueTask<string>> operation, CancellationToken cancellationToken = default) =>
        _pipeline.ExecuteAsync(operation, cancellationToken).AsTask();
}

Coming from v7's Policy.Handle<HttpRequestException>(), the obvious question is where the equivalent goes here. RetryStrategyOptions has a ShouldHandle predicate for exactly that, and RetryDemo above doesn't set it on purpose: left unset, it defaults to handling any exception except OperationCanceledException. Narrowing it to specific exception types is a ShouldHandle = new PredicateBuilder().Handle<HttpRequestException>() away, the same predicate shape used for the circuit breaker below.

In tests, that TimeProvider is a FakeTimeProvider from Microsoft.Extensions.TimeProvider.Testing:

var timeProvider = new FakeTimeProvider();
var demo = new RetryDemo(timeProvider);
var attempts = 0;

var callTask = demo.CallAsync(_ =>
{
    attempts++;
    if (attempts < 3) throw new InvalidOperationException("flaky");
    return ValueTask.FromResult("ok");
});

for (var i = 0; i < 2; i++)
{
    await Task.Delay(10); // let the pipeline's continuation register its delay timer
    timeProvider.Advance(TimeSpan.FromSeconds(1));
}

var result = await callTask;

Two full one-second delays, compressed into a test that runs in 63ms. The Task.Delay(10) is a real, small wait: the retry continuation needs an actual turn of the async scheduler to register its delay timer before Advance() has anything to fast-forward past. Skip it and the advance can race ahead of the pipeline and do nothing. The 10ms itself isn't the point, and isn't a number to copy verbatim into every test; what matters is yielding long enough for the pipeline to schedule its timer before advancing past it, and the smallest reliable yield can differ by scenario.

Circuit breaker, asserted by state instead of by exception

A circuit breaker over an unreliable dependency, with its state provider exposed directly rather than inferred from catching the right exception:

public sealed class CircuitBreakerDemo
{
    private readonly ResiliencePipeline _pipeline;

    public CircuitBreakerStateProvider StateProvider { get; } = new();

    public CircuitBreakerDemo(TimeProvider timeProvider)
    {
        _pipeline = new ResiliencePipelineBuilder
        {
            TimeProvider = timeProvider,
        }
        .AddCircuitBreaker(new CircuitBreakerStrategyOptions
        {
            FailureRatio = 0.5,
            MinimumThroughput = 4,
            SamplingDuration = TimeSpan.FromSeconds(10),
            BreakDuration = TimeSpan.FromSeconds(5),
            ShouldHandle = new PredicateBuilder().Handle<InvalidOperationException>(),
            StateProvider = StateProvider,
        })
        .Build();
    }

    public Task<string> CallAsync(Func<CancellationToken, ValueTask<string>> operation, CancellationToken cancellationToken = default) =>
        _pipeline.ExecuteAsync(operation, cancellationToken).AsTask();
}

The test sends enough failures to cross MinimumThroughput at a 100% failure rate, confirms the circuit opened, confirms an open circuit refuses to even invoke the delegate, then fast-forwards straight past BreakDuration to confirm recovery:

for (var i = 0; i < 4; i++)
{
    await Assert.ThrowsAsync<InvalidOperationException>(() =>
        demo.CallAsync(_ => throw new InvalidOperationException("down")));
}

Assert.Equal(CircuitState.Open, demo.StateProvider.CircuitState);

timeProvider.Advance(TimeSpan.FromSeconds(5)); // BreakDuration, no real waiting

var result = await demo.CallAsync(_ => ValueTask.FromResult("ok"));
Assert.Equal(CircuitState.Closed, demo.StateProvider.CircuitState);

Five simulated seconds of recovery, asserted by reading CircuitState.Closed directly, in 20ms.

Where FakeTimeProvider stops being practical

Not every timing interaction is worth faking. A Timeout strategy races an in-flight operation against a timer built from the same TimeProvider; to test that race deterministically, the operation itself would also need to be driven by the fake clock, which means the exact interleaving the test controls stops looking anything like the code under test.

The companion repo's ordering demo tests this honestly instead: small real delays, tens of milliseconds, rather than a fake clock. It's the one place in the repo where FakeTimeProvider isn't used, and the reason is worth stating plainly rather than glossing over: some timing interactions are genuinely harder to fake than to just run fast for real.

That demo exists to prove a specific, verified point about strategy order. Building the same two strategies, Retry and Timeout, in opposite order produces different behavior:

// Retry outside, Timeout inside: each attempt gets its own budget
new ResiliencePipelineBuilder { TimeProvider = timeProvider }
    .AddRetry(retryOptions)
    .AddTimeout(perAttemptTimeout)
    .Build();

// Timeout outside, Retry inside: one deadline covers every attempt and delay combined
new ResiliencePipelineBuilder { TimeProvider = timeProvider }
    .AddTimeout(overallTimeout)
    .AddRetry(retryOptions)
    .Build();

Pipeline	Timeout applies to	Result
Retry outside, Timeout inside	Each attempt individually	Every retry gets a fresh timeout window
Timeout outside, Retry inside	The whole pipeline	One deadline covers every attempt and delay combined

Per Polly's pipeline documentation, the first shape gives each retry attempt its own timeout window; if an attempt times out, the retry strategy catches it and the next attempt starts with a fresh clock. The second shape puts one overarching deadline across the whole sequence; if that deadline elapses mid-retry, the entire pipeline is cancelled, even if the retry strategy still had attempts left. The companion repo's tests prove both directions with real numbers: an inner 30ms timeout lets all 3 attempts run to individual completion (215ms total, including two real delays), while an outer 70ms deadline cuts a 5-retry sequence off after 2-3 attempts instead of the roughly 150ms it would take to exhaust naturally.

This is the same lesson Microsoft.Extensions.AI's middleware ordering already taught on this blog, applied to a different pipeline: what you compose matters less than the order you compose it in.

The version most people actually use

Most .NET code doesn't hand-build a ResiliencePipeline for every HttpClient call. Microsoft.Extensions.Http.Resilience's AddStandardResilienceHandler() wires a pre-composed pipeline (rate limiter, an overall timeout, retry, circuit breaker, and a per-attempt timeout) directly onto IHttpClientBuilder:

services.AddHttpClient("my-client")
    .AddStandardResilienceHandler();

Five of the six strategies from this post, combined into one line. The naming alone, a "total" timeout alongside a separate "attempt" timeout, is the same outer/inner distinction the ordering demo above proves with real numbers.

Conclusion

The fluent Policy API most Polly tutorials still show isn't how current Polly works: code written against the v7 Policy API won't compile unchanged against the v8 Polly.Core API, because the pipeline it builds is a different shape, not just a renamed one. What that shape buys you: six composable strategies with one execution shape, a TimeProvider hook that turns retry and circuit breaker tests from multi-second waits into single-digit or low double-digit milliseconds, and a pipeline model precise enough that changing two lines of ordering is the entire difference between a per-attempt timeout and a deadline over your whole retry sequence.

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.

DEV Community: Adrián Bailador

CQRS with MediatR, Revisited for .NET 10

Code

Rebuilding Instead of Patching

Setup, and What the License Requires

Building It Again, On .NET 10

The Pipeline Behaviors: Validation and Logging

Domain Events, Unchanged in Spirit

Testing Handlers Without Mocking DbContext

The Native AOT Limitations of Reflection-Based Handler Discovery

A Third Option: Mediator, Source-Generated

When CQRS With a Mediator Still Makes Sense

Pitfalls in Production

Best Practices

Conclusion

Your Database Column Is Encrypted. Your JSON Response Isn't.

Code

The Leak Nobody Flagged in the Security Review

Where This Actually Lives: the Serialization Boundary, Not the Persistence Layer

The Modifier: Rewriting Get and Set for One Attribute

One Resolver, Two Directions

The Encryptor Behind IPropertyEncryptor

Before / After

Before ❌

After ✅

Encryption Is Not Redaction

Pitfalls in Production

Best Practices

Conclusion

BOLA in ASP.NET Core: Why Authenticated Users Can Still Read Someone Else's Data

Code

Why [Authorize] Doesn't Help Here

Resource-Based Authorization, Not an if Statement

Defense in Depth: Scope the Query, Not Just the Response

Before/After

Before ❌

After ✅

Where the Check Sits in the Request Pipeline

Pitfalls in Production

Best Practices

Conclusion

Polly v8 Rewrote Itself From Scratch. Here's What Actually Changed

Code

What actually changed

The six strategies

Retry, tested without waiting

Circuit breaker, asserted by state instead of by exception

Where FakeTimeProvider stops being practical

The version most people actually use

Conclusion

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

The Modifier: Rewriting `Get` and `Set` for One Attribute

The Encryptor Behind `IPropertyEncryptor`

Why `[Authorize]` Doesn't Help Here

Resource-Based Authorization, Not an `if` Statement

The gap: named reasoning levels stop at `High`

The Quiet Third Feature: `unsafe` Gets Redefined