How does thread-local storage work in .NET? Compare [ThreadStatic], ThreadLocal of T and AsyncLocal of T.

1. [ThreadStatic] internals and the initialiser trap

[ThreadStatic] private static int s_count = 5;   // runs ONCE, on the thread that runs the static ctor
[ThreadStatic] private static StringBuilder? s_sb; // correct: lazy per thread

static StringBuilder Get() => s_sb ??= new StringBuilder(256);

The runtime keeps a per-thread block of thread-static storage for each type. Access is a few instructions (the JIT has fast paths for thread statics in recent versions). Because the inline initialiser is part of the type's static constructor, only one thread ever gets it.

2. ThreadLocal<T> specifics

using var perThread = new ThreadLocal<long>(() => 0, trackAllValues: true);

Parallel.For(0, 1_000_000, i => perThread.Value += i % 7);
long total = perThread.Values.Sum();   // aggregate without locking in the hot loop

• trackAllValues (available since .NET Framework 4.5) keeps a list of every thread's value.
• Each ThreadLocal<T> instance has an ID; creating many short-lived instances churns IDs and per-thread arrays, so keep them static or long-lived and dispose them.
• Value on a disposed instance throws ObjectDisposedException.

3. ExecutionContext and AsyncLocal<T> internals

ExecutionContext is an immutable map of AsyncLocal keys to values.

set a.Value = 1   -> current EC: {a:1}
await X           -> EC {a:1} captured with the continuation
   child sets a=7 -> child's EC becomes {a:7} (new object); caller's EC still {a:1}
continuation runs -> runtime restores captured EC {a:1}

• Setting a value allocates a new context (copy-on-write). Frequent sets in hot paths have a cost.
• When an async method returns, the runtime restores the caller's context, which is why child changes don't flow up.
• AsyncLocal<T> has a constructor overload with a value-changed callback (AsyncLocalValueChangedArgs<T>) that fires when the value changes because of context switches; it's used by framework code, rarely by apps.

4. Suppressing flow

using (ExecutionContext.SuppressFlow())
{
    _timer = new Timer(OnTick, null, 1000, 1000);   // timer callbacks won't carry this request's AsyncLocals
}

Useful when a request starts long-lived background work (timers, caches, connection pools): otherwise the background work holds the request's context (activity, scopes, HttpContext holder) for its whole lifetime. ThreadPool.UnsafeQueueUserWorkItem and Thread.UnsafeStart do the same.

5. How frameworks use AsyncLocal

6. Version notes

7. Try it yourself

1. Run the code example and note which values survive the thread hop.
2. Remove ConfigureAwait(false) and run it in a console app; observe it still may switch threads (no SynchronizationContext).
3. Store a List<int> in an AsyncLocal, add to it in a child method, and observe the caller sees the mutation.
4. Set an AsyncLocal in a "request", start a Timer without SuppressFlow, and print the value from the timer callback minutes later.
5. Benchmark setting an AsyncLocal<int> in a loop with [MemoryDiagnoser] to see allocations per set.
6. Use ThreadLocal<long> with trackAllValues in Parallel.For and compare with Interlocked.Add on a shared counter.

using System.Threading;

await Demo.RunAsync();

static class Demo
{
    [ThreadStatic] private static int s_threadStatic;
    private static readonly ThreadLocal<int> s_threadLocal = new(() => -1, trackAllValues: true);
    private static readonly AsyncLocal<int> s_asyncLocal = new();

    public static async Task RunAsync()
    {
        s_threadStatic = 42;
        s_threadLocal.Value = 42;
        s_asyncLocal.Value = 42;
        Console.WriteLine($"Before await on thread {Environment.CurrentManagedThreadId}");

        await Task.Delay(50).ConfigureAwait(false);

        Console.WriteLine($"After await on thread {Environment.CurrentManagedThreadId}");
        Console.WriteLine($"ThreadStatic = {s_threadStatic}");   // 0 if the thread changed
        Console.WriteLine($"ThreadLocal  = {s_threadLocal.Value}"); // -1 if the thread changed
        Console.WriteLine($"AsyncLocal   = {s_asyncLocal.Value}");  // 42

        await ChildAsync();
        Console.WriteLine($"After child, AsyncLocal = {s_asyncLocal.Value}"); // still 42
    }

    private static async Task ChildAsync()
    {
        s_asyncLocal.Value = 7; // visible here and below, not to the caller
        await Task.Yield();
    }
}