DEV Community: Hitesh

Delete the Event Switch: Runtime Dispatch with dynamic in C#

Hitesh — Thu, 13 Aug 2026 04:36:07 +0000

A switch over event types is dynamic dispatch. You just wrote it by hand, took on the maintenance yourself, and skipped the help the runtime was ready to give you.

You've written this method. Every event-driven codebase has one:

public Task HandleAsync(BaseEvent @event) => @event switch
{
    OrderPlaced e       => HandleAsync(e),
    PaymentFailed e     => HandleAsync(e),
    InventoryReserved e => HandleAsync(e),
    _ => throw new NotSupportedException(
        $"No handler for '{@event.GetType().Name}'.")
};

It works. It's also a lookup table you maintain by hand, keyed on runtime type, mapping each type to the method that should run. That's the exact job overload resolution already does for you. The compiler does it for free, at every call site, and it never forgets to add a case.

Let me show you how to hand that job back to the runtime.

The setup

Say we have a small, closed hierarchy of domain events that we own:

public abstract record BaseEvent;

public sealed record OrderPlaced(Guid OrderId, decimal Total)   : BaseEvent;
public sealed record PaymentFailed(Guid OrderId, string Reason) : BaseEvent;
public sealed record InventoryReserved(Guid OrderId, int Qty)   : BaseEvent;

A processor needs to route each event to the right handler. The switch above does it, but the pattern-match arm and the target method are saying the same thing twice: "if it's an OrderPlaced, call the OrderPlaced overload." The type check is the dispatch. We just wrote it out longhand.

Let the runtime dispatch it

Cast to dynamic at a single boundary, and let the C# runtime binder pick the overload based on the argument's actual runtime type:

public sealed class EventProcessor
{
    // The only boundary where the type is late-bound.
    public Task HandleAsync(BaseEvent @event)
    {
        ArgumentNullException.ThrowIfNull(@event);
        return Dispatch((dynamic)@event);
    }

    private Task Dispatch(OrderPlaced e) =>
        // handle the order...
        Task.CompletedTask;

    private Task Dispatch(PaymentFailed e) =>
        // compensate, alert, retry...
        Task.CompletedTask;

    private Task Dispatch(InventoryReserved e) =>
        Task.CompletedTask;

    // Least-specific overload: the intentional fallback (more on this below).
    private Task Dispatch(BaseEvent e) =>
        throw new NotSupportedException(
            $"No handler is registered for '{e.GetType().Name}'.");
}

The switch is gone. Adding a fourth event now means adding its record and one Dispatch overload. Nothing central to edit, nothing to forget.

Why the boundary and the handlers have different names

Small thing, but it matters. The public entry point is HandleAsync and the overload set is Dispatch. That's on purpose. If the boundary were also called Dispatch(BaseEvent), it would clash with the fallback overload, because two methods with the same signature are a compile error, and public versus private doesn't break the tie. Giving the boundary its own name gets you out of that, and it reads better anyway. One method's job is "enter the dispatch" and the other set's job is "handle a specific event."

`dynamic` removes the conditional, not the responsibility

This is the part that makes or breaks the pattern. dynamic deletes your if/switch, but it does not delete the need to handle an event you never wrote a handler for. It only changes how you find out.

With no fallback, an unrecognized type throws a RuntimeBinderException from deep inside the framework. That's a confusing error that doesn't even name your domain. So add the fallback on purpose:

private Task Dispatch(BaseEvent e) =>
    throw new NotSupportedException(
        $"No handler is registered for '{e.GetType().Name}'.");

Here's why it works. Every event is a BaseEvent, so the binder always has at least the fallback overload available, and it picks the most-derived one that fits:

Runtime type is OrderPlaced, so Dispatch(OrderPlaced) is more specific than Dispatch(BaseEvent), and the specific handler wins.
Runtime type has no dedicated overload, so only Dispatch(BaseEvent) fits, and you get your NotSupportedException, thrown from your code, with a message you control.

Same guarantee the _ arm gave you in the switch, now written as an overload.

How this actually behaves at runtime

Two questions people always ask.

"Isn't dynamic slow?" There's a one-time cost the first time a given runtime type flows through the boundary. The DLR builds a call site and works out the overload. That result gets cached per runtime type. After warm-up, dispatching another OrderPlaced is about as fast as a normal virtual call, and you're not paying reflection costs on every event. For most event pipelines this just doesn't matter. For a genuinely hot path chewing through millions of events a second, benchmark it against a Dictionary<Type, Func<…>> or a source generator before you commit.

"Does dynamic leak everywhere?" No, and this is the discipline that keeps it sane. dynamic lives in exactly one expression: (dynamic)@event. Every Dispatch overload is ordinary, statically typed C#. They get full IntelliSense, full type checking, and they're easy to unit-test on their own. The late binding stays in one small, contained spot instead of spreading through the class.

Sharp edges worth knowing

A few things that bite if you're not ready for them:

Null. A null dynamic has no runtime type for the binder to work with. That's why the boundary guards with ArgumentNullException.ThrowIfNull before the cast. Skip it and you get a murky runtime error instead of a clear one.
Return type. The expression Dispatch((dynamic)@event) is itself typed dynamic at compile time, so returning it from a Task-returning method adds a runtime conversion to Task. Keep every overload returning Task (or a Task subtype). If a handler ever returns something you can't await, you find out at runtime, not at compile time.
Tooling goes quiet. "Find all references" on Dispatch(OrderPlaced) won't show it being called, because statically it isn't. IDE navigation and some analyzers lose the thread across the dynamic hop. You're trading a bit of compile-time visibility for a lot less churn.

When this is the right tool, and when it isn't

Use it when your event types are a closed, trusted hierarchy that you own: domain events, internal commands, a message set defined in your own assembly. That's the whole premise. The runtime is choosing among a fixed set of methods you wrote, so late binding is safe, and the fallback covers the "someone added a type and forgot a handler" case.

Do not point it at arbitrary deserialized payloads or plugin-provided types without checking them first. Late-binding on untrusted input is a footgun. You'd be handing the overload resolver whatever type an attacker or a buggy producer put on the wire. Validate or whitelist the type, then dispatch.

What about a type-pattern switch?

Fair question. The modern switch expression over type patterns is a perfectly good alternative:

public Task HandleAsync(BaseEvent @event) => @event switch
{
    OrderPlaced e   => Dispatch(e),
    PaymentFailed e => Dispatch(e),
    _               => throw new NotSupportedException(/* ... */)
};

It's explicit, statically visible, and pays no binder cost. But notice it's still a table you keep by hand. Adding an event means editing it, and the _ discard means the compiler won't force you to. It has the same "you have to remember the fallback" property as the dynamic version, just spelled out.

So it comes down to what you want to optimize for:

Reach for dynamic when you want adding an event to need only a new overload, and you're fine trading some static visibility for that.
Reach for the switch when you want the dispatch table sitting in one readable place and fully visible to your tooling.

Both need the deliberate unknown-event branch. Neither is wrong.

Scaling it up: resolving handlers from DI

The version so far keeps the handler bodies inside the processor. In real code, they usually live in their own classes, resolved from the container, so they can take their own dependencies. This is where dynamic really earns its keep, because the awkward part of doing this with DI is the exact thing the cast fixes.

Define the usual generic handler interface:

public interface IEventHandler<in TEvent> where TEvent : BaseEvent
{
    Task HandleAsync(TEvent @event, CancellationToken ct);
}

Now the dispatcher swaps its overload set for a single generic method, and lets dynamic pick the type argument instead of the overload:

public sealed class EventDispatcher(IServiceScopeFactory scopeFactory)
{
    // Same one boundary as before.
    public Task DispatchAsync(BaseEvent @event, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(@event);
        return Handle((dynamic)@event, ct);
    }

    private async Task Handle<TEvent>(TEvent @event, CancellationToken ct)
        where TEvent: BaseEvent
    {
        await using var scope = scopeFactory.CreateAsyncScope();

        var handlers = scope.ServiceProvider
            .GetServices<IEventHandler<TEvent>>()
            .ToList();

        if (handlers.Count == 0)
            throw new NotSupportedException(
                $"No handler registered for '{typeof(TEvent).Name}'.");

        foreach (var handler in handlers)
            await handler.HandleAsync(@event, ct);
    }
}

When @event is runtime-type OrderPlaced, the binder infers TEvent = OrderPlaced on that generic method, and GetServices<IEventHandler<OrderPlaced>>() resolves the correctly typed handlers. That's the whole point. dynamic is bridging runtime type to generic type parameter, the one gap you can't cross from a static BaseEvent reference. Registration is the plain generic story, and with assembly scanning (Scrutor), adding an event touches the dispatcher zero times:

services.Scan(s => s
    .FromAssemblyOf<OrderPlaced>()
    .AddClasses(c => c.AssignableTo(typeof(IEventHandler<>)))
    .AsImplementedInterfaces()
    .WithScopedLifetime());

Two things change once DI is in the picture, and both are worth calling out.

The fallback moves. In the overload version, an unknown event got caught by the most-derived overload that fit, and Dispatch(BaseEvent) threw. Here there's one generic method, so every subtype runs it happily and GetServices just hands back an empty sequence. The "fail loud on an unhandled event" behavior no longer comes for free, so you put it back with the empty-set check above. Same guarantee, different mechanism. It's a count check now, not overload resolution.

Lifetimes are the real trap. Resolving handlers from the container here is fine, not a service-locator smell, because the handler type genuinely isn't known until runtime. That's the textbook case for it, and it's how MediatR dispatches internally. But which provider you resolve from matters a lot. Event processors are usually long-lived, like a queue consumer or a BackgroundService, and resolving scoped handlers off the root provider from a long-lived object is the classic captive-dependency bug that shows up later as an ObjectDisposedException. That's why the dispatcher takes IServiceScopeFactory and opens a fresh scope per event instead of hanging onto one provider for its whole life. If your dispatcher already lives inside a scope, say it's resolved per web request, you can inject the scoped IServiceProvider directly and skip the manual scope.

One footnote for the reflection-minded. The pre-dynamic way to do all of this is typeof(IEventHandler<>).MakeGenericType(@event.GetType()) followed by a reflected invoke, usually behind a cached compiled delegate. It's the same idea written out by hand. dynamic just lets the DLR do the MakeGenericType, the resolution, and the per-type call-site caching for you. Same trade as the rest of the post: you give up "find all references" on the handlers in exchange for never editing the dispatcher.

The takeaway

The switch was never wrong. It was redundant. Picking a method based on the runtime type of an argument is the whole definition of overload resolution, and the runtime already knows how to do it, faster and more reliably than a hand-kept list of case labels.

dynamic just asks it to do that job one moment later than usual. Delete the switch, keep the fallback.

Request and Response Migration in .NET

Hitesh — Tue, 11 Aug 2026 17:56:09 +0000

If you've maintained a public API long enough, you've opened a folder that looks like this:

Handlers/
  GetQuoteV1Handler.cs
  GetQuoteV2Handler.cs
  GetQuoteV3Handler.cs   ← the only one anybody has read this year

Three files, one behaviour. V1 and V2 are copies of V3 with a field dropped and a flag hardcoded.

Nobody planned this. We shipped GetQuote, symbol in and price out. A customer wanted the daily change, so v2 grew an IncludeChange flag. We sold into Europe, so v3 grew Currency. Every one of those was the right call on the day. And you can't delete the old ones, because there's a mobile app whose release cycle you don't own and a partner who integrated in 2022 and won't look at it again.

So you keep all three. A pricing fix is three edits. Then one Friday somebody patches two of the three, and from that afternoon v2 quotes a different number than v3. You find out five weeks later from a customer.

Asp.Versioning works out which version a request is. It has nothing to say about the duplication sitting behind that answer.

What we tried first

The instinct is to pull the logic into a shared method with optional parameters:

private async Task<Quote> GetQuoteCore(
    string symbol, bool includeChange = false, string currency = "USD", ...)

But includeChange = false is v1's behaviour written down as a default in a signature that belongs to the current version. Nothing connects it to the version it exists for. Delete v1 in three years and that = false sits there forever, because nobody can prove which caller needs it. And it grows one permanent parameter per version until half the defaults are archaeology.

Branching on a version number inside one handler is worse: the checks interleave, so you can't read one version end to end, and one request type now has to carry the union of every field any version ever had. A base class with virtual hooks looks like real design but is a fragile base class in a costume, because adding v4 means changing the base, and changing the base changes what v1 does.

All three share a shape. Each one puts knowledge of every version in one place, so the thing you edit grows with every version you've shipped, and every edit can touch all of them. What we wanted was the opposite: each version knowing about exactly one neighbour, and old versions being genuinely finished.

The idea, borrowed from Stripe

Stripe has shipped close to a hundred backwards-incompatible changes and retired zero versions. Code written against their API a decade ago still runs. Brandur Leach wrote up how, and it comes down to two things:

One implementation, always at the newest version. Nothing in it has heard of 2017.
A small module per breaking change that knows how to undo it.

A response gets built at the current version, then walked backwards through those modules until the shape matches what the caller is pinned to. A version stops costing you a copy of your business logic and starts costing you a small transform. Nothing about that is HTTP-specific, so we built it for .NET, in a library called Versionary.

Building it

Start with plain records. No base class, no attributes, no library reference. The current one gets no prefix, because it isn't a version, it's the contract.

public static class V1
{
    public sealed record GetQuote(string Symbol) : IRequestContract<Quote>;
    public sealed record Quote(string Symbol, decimal Price);
}

public static class V2
{
    public sealed record GetQuote(string Symbol, bool IncludeChange) : IRequestContract<Quote>;
    public sealed record Quote(string Symbol, decimal Price, decimal Change);
}

// Current.
public sealed record GetQuote(string Symbol, bool IncludeChange, string Currency)
    : IRequestContract<Quote>;
public sealed record Quote(string Symbol, decimal Price, decimal Change, string Currency);

Then one handler, written for the current shape. This is the only copy of the behaviour, and it has never heard of v1.

public sealed class GetQuoteHandler(IPriceFeed feed) : IVersionaryHandler<GetQuote, Quote>
{
    public async ValueTask<Quote> HandleAsync(GetQuote request, CancellationToken ct)
    {
        var price = await feed.PriceAsync(request.Symbol, ct);
        var change = request.IncludeChange ? decimal.Round(price * 0.015m, 2) : 0m;
        return new Quote(request.Symbol, price, change, request.Currency);
    }
}

And the piece that replaces the two deleted handlers, one migrator per hop:

public sealed class V1QuoteMigrator :
    IMigrator<V1.GetQuote, V2.GetQuote>,   // forward:  the request goes up
    IMigrator<V2.Quote, V1.Quote>          // backward: the response comes down
{
    public ValueTask<V2.GetQuote> MigrateAsync(V1.GetQuote input, CancellationToken ct)
        => new(new V2.GetQuote(input.Symbol, IncludeChange: false));

    public ValueTask<V1.Quote> MigrateAsync(V2.Quote input, CancellationToken ct)
        => new(new V1.Quote(input.Symbol, input.Price));
}

IncludeChange: false is the whole point. That one literal is the entire v1 behaviour, in one line you can put in front of a reviewer. It used to be an emergent property of a 200-line handler nobody had opened since 2023. Both directions live in one class on purpose, because the request transform and the response transform are two halves of the same decision, and split across files someone updates one and forgets the other.

Each migrator only speaks to its immediate neighbour. V1's knows v2 and nothing else, even after v3 ships. The chain does the rest.

builder.Services.AddVersionary(cfg => cfg.RegisterFromAssemblyContaining<GetQuoteHandler>());

app.MapGet("/v1/quotes/{symbol}", async (string symbol, IVersionarySender sender, CancellationToken ct) =>
    TypedResults.Ok(await sender.SendAsync(new V1.GetQuote(symbol), ct)));

That endpoint mentions no migration and no response type. The contract declares what it returns, so asking a v1 request for a v2 response won't compile. What actually happens:

V1.GetQuote ──► V2.GetQuote ──► GetQuote ──► [ the one handler ]
                                                     │
V1.Quote    ◄─── V2.Quote    ◄─── Quote    ◄─────────┘

Two hops up, run, two hops back. The client gets bytes identical to 2022.

The harder direction

Stripe mostly walks responses backwards. Migrating a request forward is harder, because you have to invent data the caller never sent. A v2 client couldn't tell us the currency, so somebody has to decide it, and sometimes that means a lookup:

public async ValueTask<GetQuote> MigrateAsync(V2.GetQuote input, CancellationToken ct)
{
    var currency = await feed.CurrencyAsync(input.Symbol, ct);
    return new GetQuote(input.Symbol, input.IncludeChange, currency);
}

That's why migrations are async and migrators come out of DI. Pure reshaping allocates nothing, but a migration that needs a database round trip shouldn't have to fight the API to make one.

"So where do I configure the current version?"

This stalled the first design review. The tempting answer is a setting: cfg.CurrentVersion = "v3". Don't. It's a second source of truth that has to agree with your handler, it goes stale silently when you add v4 and forget to bump it, and it forces one versioning scheme on an API, an internal service, and a queue consumer that don't share one.

There's no setting, because the rule is:

A contract is current when nothing migrates away from it.

The forward walk is deliberately dumb: take the request's type, look for an outgoing hop, run it, repeat. When the lookup comes back empty, you've arrived, and that's where the handler is. The version map is derived from the code, not declared next to it and left to rot. Pinning a version that changed behaviour rather than shape then costs nothing: give it a handler and no outgoing migrator, and its requests arrive untouched.

The payoff

Add a version tomorrow, and here's what moves:

	Changes?
The v1 endpoint	No
The v2 endpoint	No
A migrator for the new hop	Added
Your handler, now on the new contract	Changed

Two files, neither an endpoint. A v1 endpoint names v1 types and only v1 types, and those can never change.

The one way to get burned is to add the migrator and forget to move the handler forward, so it strands on an old contract and can never run. That's a startup failure, not a 3am one:

Error VER005: A handler is registered for 'Api.V3.GetQuote', but that contract still
              migrates onward to 'Api.GetQuote', so the handler can never run.

Cycles, duplicate hops, stranded handlers, ambiguous paths- all checked while AddVersionary runs and reported together. There's a Graph.Validate() for a unit test too, and a Graph.Explain() that prints the version map from the graph itself, so your docs can't drift.

"Isn't this just mapping?"

Someone asked me this in review, and for two versions they're right: write MapV1ToCurrent and MapCurrentToV1 and skip this whole article.

The difference shows up at three, and it's structural. Hand-rolled mappers all point at the current contract:

V1 ───┐
V2 ──┐│
V3 ─┐││
    ▼▼▼
  current

So when current changes, which is the only reason you're adding a version, every mapper is wrong at once, and the compiler only catches the fields that disappeared. Add a field with a default, and they all still build while quietly doing the wrong thing.

Chained hops point at their neighbour:

V1 ──► V2 ──► V3 ──► current

V1QuoteMigrator names v1 and v2 and nothing else. Both types are frozen, so it compiled in 2022 and will compile after v7. Adding a version appends one hop and touches nothing behind it. That's O(n) edits per version versus one. (The same trap catches "each endpoint just calls one service directly": every endpoint names the current service signature, so they all break together, and the version semantics end up scattered across your routing table.)

So yes, it's mapping. The library is a chain, a lookup, and a validator wrapped around it. The value is entirely in the chain being adjacent rather than radial.

On MediatR (optional)

The core has no idea MediatR exists. But if you already dispatch through ISender, you keep your handlers and behaviours and add one line:

builder.Services
    .AddVersionary(cfg => cfg.RegisterFromAssemblyContaining<Program>())
    .AddMediatRPipeline();

The one thing worth knowing: when a v1 request climbs two hops, which validators fire? SinglePass (the default) validates the arriving and the current contract. Reentrant re-dispatches each hop, so a validator written for the intermediate V2.GetOrder also fires, catching a bad migration where it happened rather than three hops later. Reentrant re-runs everything, though, so register idempotent behaviours (validation, logging) outermost and once-only ones (transactions, audit, outbox) inside the pipeline. Details are in the repo.

When this is the wrong tool

Changes come in three kinds. Additive (a new optional field) usually needs no migrator. Shape (renamed, split, merged, nested) is exactly what this exists for. Behavioural is the trap: the shape is identical, and the meaning moved underneath it. Cancelling used to refund immediately and now queues it. No transform can express that, because the data was never what changed.

One question settles it:

Can you write a function from the old shape to the new one that loses nothing a caller relied on?

Yes, write the migrator. No, pin the version to its own handler and take the second copy. Pinning is the right answer there, not a failure, but be honest: on that endpoint you've saved nothing. Two of ours are pinned.

A couple of sharp edges: every hop boxes (messages move as object), and assembly scanning isn't AOT-safe, though there are inline registration forms that are.

Once the chain exists, it fits things that aren't API calls. Event upcasting is the same forward walk with no handler on the end, because an event stored three years ago just needs bringing up to the current shape. That works because the graph has no idea what a version is, only that one type can become another. Working out which version a message belongs to stays your transport's job.

Was it worth it?

Two handlers became two migrators, so the file count didn't move. But there's now exactly one copy of the behaviour. A pricing fix is one edit. The Friday bug where v2 and v3 silently disagree can't happen, because there's nothing left to disagree. And IncludeChange: false is a better spec for v1 than the v1 handler ever was.

The asterisk: this reshapes data, not behaviour. If a version differs in what it does, you pin it, and this bought you nothing. If you've got two versions and no duplication yet, none of this is worth your afternoon. Come back when it starts to hurt. It will.

Try it

hiteshk97 / versionary

Versionary

Serve every version of your API from one handler.

How you got here

You shipped CreateOrder. It was clean.

Then finance wanted tax broken out on the response, so you added a flag. That's v2. Europe happened and orders needed a currency, so that's v3. Payments asked for an idempotency key and you shipped v4.

Every one of those was the right call on the day you made it. That's what makes this so annoying.

You can't turn the old versions off. There's a mobile app whose release cycle you don't own. There's a partner who integrated in 2022 and has no budget to look at it again. There are terminals sitting in venues that get updated when somebody drives out there with a laptop.

So all four are live:

CreateOrderV1Handler  ─┐
CreateOrderV2Handler  ─┤   four handlers
CreateOrderV3Handler  ─┤   one actual behaviour
CreateOrderV4Handler  ─┘

Three of them are copies…

View on GitHub

📦 Install

dotnet add package Versionary

MIT · net8.0 / net10.0

Issues and PRs are welcome. I'd especially like to hear from anyone who made the pin-versus-migrate call on a real behavioural change and regretted which way they went. 👇

Ambient Context in .NET

Hitesh — Sun, 02 Aug 2026 13:33:59 +0000

If you’ve worked in .NET long enough, you’ve probably seen a method signature that looks exactly like this:

Task<Order> UpdateOrderAsync(int orderId, UpdateOrderRequest request, int currentUserId);

Notice that currentUserId at the end? That’s the culprit.

Nobody chooses which user they are when updating an order. That information is ambient. It’s just a fact about the current request. But because there’s no obvious place to store it, we end up manually passing it down a bucket brigade: from the controller, to the business service, to another helper service, and finally down to the database just to write an audit log.

Eventually, someone gets tired of the plumbing and decides to get clever. They inject IHttpContextAccessor directly into the domain service. Suddenly, your core business logic is tied to Microsoft.AspNetCore.Http. Everything seems fine, right up until a nightly background job tries to reuse that same service, hits a null HttpContext, and crashes.

We escaped this trap by stealing the concept behind IHttpContextAccessor without actually using it. It takes about 80 lines of code. Here is exactly how we did it, including answers to the two questions that always come up in code review: "Why is this registered as a Singleton?" and "How does this work when there is no HTTP request?"

The Magic Behind `IHttpContextAccessor`

Before we write our own, let’s look at how Microsoft does it. The trick is actually much simpler than people assume. Here is the real implementation of IHttpContextAccessor, almost word for word:

public class HttpContextAccessor : IHttpContextAccessor
{
    private static readonly AsyncLocal<HttpContextHolder> _httpContextCurrent = new();

    public HttpContext? HttpContext
    {
        get => _httpContextCurrent.Value?.Context;
        set
        {
            var holder = _httpContextCurrent.Value;
            if (holder != null)
            {
                // Clear the trapped HttpContext. It's done.
                holder.Context = null;
            }

            if (value != null)
            {
                _httpContextCurrent.Value = new HttpContextHolder { Context = value };
            }
        }
    }

    private sealed class HttpContextHolder
    {
        public HttpContext? Context;
    }
}

Two things here do all the heavy lifting:

AsyncLocal<T>: Think of this as a backpack for your thread. It understands await. Whatever you put in it flows down through the entire async call chain, even if the work hops between different background threads.
The HttpContextHolder extra layer: This looks like pointless extra code, but it earns its keep. When a new execution context splits off (like a fire-and-forget Task.Run or a timer), it captures a snapshot of the current AsyncLocal value, not a live link back to you. So if we stored the context directly, cleaning up later with _httpContextCurrent.Value = null only affects our own flow. It can’t reach into the snapshot that stray task already grabbed. A long-lived capture (a static event handler, a persistent timer, a background loop) can then pin the whole request in memory for as long as it stays alive. By storing a box we can change later (the holder), we get around that. Every snapshot points at the same holder instance, so setting holder.Context = null at the end of the request empties the box for all of them at once, and the garbage collector can reclaim the request.

Notice something important: there is nothing HTTP-specific about either of those tricks. So, we just built our own version to hold what we actually cared about: the current user.

Building Our Own

We need four simple types. First, let’s define what a user looks like in our system:

public interface ICurrentUser
{
    bool IsAuthenticated { get; }
    int UserId { get; }
    string ExternalUserId { get; }
    string UserName { get; }
    string Email { get; }
    IReadOnlyList<string> Roles { get; }
}

public sealed class CurrentUser : ICurrentUser
{
    public static readonly ICurrentUser Anonymous = new CurrentUser();

    public bool IsAuthenticated { get; init; }
    public int UserId { get; init; }
    public string ExternalUserId { get; init; }
    public string UserName { get; init; }
    public string Email { get; init; }
    public IReadOnlyList<string> Roles { get; init; } = [];
}

Notice how everything uses init. The current user is a fact about the current call, not a variable to be tweaked. If a service wants to change it, it has to replace the whole object. No silent changes allowed.

Next, we build our ambient store, stealing Microsoft’s "holder box" design:

public static class CurrentUserHolder
{
    private static readonly AsyncLocal<Holder> Current = new();

    // Notice: This never returns null! Unauthenticated calls get CurrentUser.Anonymous.
    public static ICurrentUser User => Current.Value?.Value ?? CurrentUser.Anonymous;

    public static void Set(ICurrentUser user)
    {
        ArgumentNullException.ThrowIfNull(user);

        // Empty the box the previous execution contexts are holding...
        var existing = Current.Value;
        if (existing is not null)
        {
            existing.Value = null;
        }

        // ...then hand this flow a fresh one.
        Current.Value = new Holder { Value = user };
    }

    public static void Clear()
    {
        var existing = Current.Value;
        if (existing is not null)
        {
            existing.Value = null;
        }
    }

    private sealed class Holder
    {
        public ICurrentUser Value;
    }
}

We made one deliberate change from Microsoft’s design: our accessor never returns null. Dealing with nullable contexts means writing ?. everywhere. In our system, an unauthenticated call isn’t an "absent" user; it’s an "anonymous" one. This means CurrentUser.Anonymous is the floor, and calling accessor.CurrentUser.UserId is always safe.

Finally, we create the clean, injectable window for our application code to use:

public interface ICurrentUserAccessor
{
    ICurrentUser CurrentUser { get; }
}

public sealed class CurrentUserAccessor : ICurrentUserAccessor
{
    public ICurrentUser CurrentUser => CurrentUserHolder.User;
}

This is get-only. We don’t want random services overriding the current user. Writing to the store goes through CurrentUserHolder.Set, which should only ever be called by the entry points of your app.

We register it once in our DI container:

services.AddSingleton<ICurrentUserAccessor, CurrentUserAccessor>();

And this is where code reviews usually grind to a halt. "Wait, why is this a Singleton?"

The Singleton Controversy

The temptation is to register the user as a scoped service. I’ve written this exact code myself:

// The tempting version. Don't do this.
services.AddScoped<ICurrentUser>(sp =>
{
    var http = sp.GetRequiredService<IHttpContextAccessor>();
    return MapFromPrincipal(http.HttpContext?.User);
});

It looks gorgeous. You can just inject ICurrentUser into your constructor without dealing with accessors. But it will break your app in four distinct ways:

Singletons can’t use it: If you have a singleton service (like an EF Core Interceptor, a cache, or a background worker) that needs to know the current user, it will crash. The DI container will yell at you about a "captive dependency": you’ve trapped a short-lived scoped object inside a long-lived singleton.
It freezes in time: A scoped instance is created once per scope and cached. If it gets resolved before your authentication middleware has figured out who the user is, every other service in that request will receive an "Anonymous" user. Silently.
Scopes aren’t always what you think: We treat "Scoped" and "Per HTTP Request" as the same thing because ASP.NET Core does that for us. But in a background worker, there might only be one DI scope for the entire lifetime of the process!

The "Window" Analogy

Look at how ASP.NET Core registers its own accessor:

services.TryAddSingleton<IHttpContextAccessor, HttpContextAccessor>();

It’s a singleton! This isn’t a mistake. The key is separating the data from the object that hands you the data.

Think of ICurrentUserAccessor as a window. The window itself never changes (it’s a Singleton). It has no state, no fields, and holds no memory. But the scenery outside the window (AsyncLocal) changes depending on exactly when you look through it.

By injecting a singleton window, you get hold of a value provider. You ask it for the answer at the exact moment you need it, ensuring you always get the right user, no matter which DI scope you happen to be sitting in.

Setting the User

The current user is only ever written at entry points. Everywhere else just reads it.

In an HTTP API, that entry point is a middleware registered right after authentication:

public class CurrentUserMiddleware
{
    private readonly RequestDelegate _next;

    public CurrentUserMiddleware(RequestDelegate next) => _next = next;

    public async Task InvokeAsync(HttpContext httpContext, IUserService userService)
    {
        CurrentUserHolder.Set(await ResolveAsync(httpContext.User, userService));

        try
        {
            await _next(httpContext);
        }
        finally
        {
            CurrentUserHolder.Clear(); // Empty the box!
        }
    }

    // (ResolveAsync left out to keep this short. It just maps ClaimsPrincipal to our CurrentUser)
}

What about Background Jobs?

This is where the pattern really shines. What if a background queue consumer needs to process a job on behalf of a user?

The publisher simply stamps the user’s ID onto the message envelope before sending it. When the consumer picks it up, it sets up the ambient context:

public sealed class CurrentUserConsumeFilter<T> : IConsumeFilter<T>
{
    public async Task OnConsumeAsync(MessageEnvelope<T> envelope, ConsumeDelegate next)
    {
        // For automated background tasks, we use a dedicated system account
        CurrentUserHolder.Set(SystemPrincipals.BackgroundWorker);

        try
        {
            await next();
        }
        finally
        {
            CurrentUserHolder.Clear();
        }
    }
}

From this point on, the message handler (and every service it calls) sees the exact same ICurrentUserAccessor it would see in a web request. Your business logic never has to know if it was triggered by an HTTP call or a RabbitMQ message.

The Massive Payoff: Automatic Audit Columns

If this sounds like a lot of theory, here is the feature that will make you fall in love with it.

Let’s say your database tables have standard audit columns (CreatedBy, ModifiedBy). We can use an EF Core Interceptor to fill these in automatically, globally, without ever writing it in a service again.

public sealed class AuditInterceptor : SaveChangesInterceptor
{
    private readonly ICurrentUserAccessor _accessor;   // Safely capture the singleton!

    public AuditInterceptor(ICurrentUserAccessor accessor) => _accessor = accessor;

    private void Stamp(DbContext context)
    {
        if (context is null) return;

        // Because this runs right when SaveChanges is called, it always gets the correct, current user.
        var userId = _accessor.CurrentUser.UserId;
        var now = DateTime.UtcNow;

        foreach (var entry in context.ChangeTracker.Entries<IAuditable>())
        {
            if (entry.State == EntityState.Added)
            {
                entry.Entity.CreatedBy = userId;
                entry.Entity.CreatedOnUtc = now;
            }
            if (entry.State == EntityState.Added || entry.State == EntityState.Modified)
            {
                entry.Entity.ModifiedBy = userId;
                entry.Entity.ModifiedOnUtc = now;
            }
        }
    }

    // (Wire this up to SavingChanges and SavingChangesAsync)
}

Because our ICurrentUserAccessor is a Singleton and works across HTTP threads and background workers, this interceptor functions perfectly everywhere. No developer ever has to remember to set ModifiedBy = currentUserId again, which means no developer can forget.

(Bonus: You can use this exact same pattern to auto-tag your Serilog logs via custom Enrichers, so every single log is automatically stamped with the active user’s ID!)

A Few Real-World Gotchas

If you’re going to use this, keep these sharp edges in mind:

AsyncLocal flows down, not up: If you set the user deep inside a child method, the parent method won’t see it. Always call Set() at the absolute highest point of your operation (middleware, top of the cron loop, etc.).
Always Clear() in a finally block: This is what prevents memory leaks in long-lived applications. Don’t skip it.
Don’t treat it like a junk drawer: This pattern is for ambient data (like the user). Don’t start stuffing CurrentOrderId or IsUserHavingAGoodDay in there. If you need a new ambient scope (like a Tenant ID), build a separate, dedicated accessor for it.

One Pattern, Many Uses

Once this is in your toolbox, you start spotting places for it everywhere. The user is just the first example. Anything that is a fact about the current operation, rather than a real input to your methods, is a good fit.

The one I reach for most is the correlation ID. When a request kicks off, you generate a short ID and drop it in an ambient holder. Every log line inside that request can pick it up on its own, so you can trace one user’s journey through a noisy log file without threading an ID through every method.

The real win is that it survives process boundaries. Your publisher stamps the correlation ID onto the message envelope (exactly like we did with the user), the consumer reads it back on the other side and sets its own ambient holder, and suddenly one ID ties together the HTTP call, the queue message, and the three services that handled it downstream. Debugging a distributed system stops feeling like guesswork.

A few other things that fit the same mold:

Tenant ID in a multi-tenant app, so every query is scoped to the right customer without passing it through every layer.
Request culture or locale, so formatting and translations just work wherever you are in the call chain.
Feature flag context, so a deep-down service can check "is this experiment on for this user?" without being handed the whole context.

The recipe is always the same: a get-only accessor (the window), an AsyncLocal holder behind it (the scenery), and a Set() / Clear() pair at your entry points. Build a separate, dedicated accessor for each kind of data, resist the urge to cram them all into one, and you get the same clean, leak-free behavior every time.

Was it worth it?

Absolutely. By adding four simple classes and one DI registration, we entirely deleted int currentUserId from hundreds of method signatures. Audit logs went from a manual chore that was constantly forgotten, to an automated guarantee that works flawlessly in both web apps and background workers.

Sometimes framework abstractions like IHttpContextAccessor are 80% of what you need, but the missing 20% makes them unusable. But if you peek underneath the hood and steal the pattern instead of the class, you can solve massive architectural headaches in less than a hundred lines of code.

DEV Community: Hitesh

Delete the Event Switch: Runtime Dispatch with dynamic in C#

The setup

Let the runtime dispatch it

Why the boundary and the handlers have different names

dynamic removes the conditional, not the responsibility

How this actually behaves at runtime

Sharp edges worth knowing

When this is the right tool, and when it isn't

What about a type-pattern switch?

Scaling it up: resolving handlers from DI

The takeaway

Request and Response Migration in .NET

What we tried first

The idea, borrowed from Stripe

Building it

The harder direction

"So where do I configure the current version?"

The payoff

"Isn't this just mapping?"

On MediatR (optional)

When this is the wrong tool

Was it worth it?

Try it

hiteshk97 / versionary

Versionary

How you got here

Ambient Context in .NET

The Magic Behind IHttpContextAccessor

Building Our Own

The Singleton Controversy

The "Window" Analogy

Setting the User

What about Background Jobs?

The Massive Payoff: Automatic Audit Columns

A Few Real-World Gotchas

One Pattern, Many Uses

Was it worth it?

`dynamic` removes the conditional, not the responsibility

The Magic Behind `IHttpContextAccessor`