C# Async Academy
from await to the hardware

📦 Task = a promise for later

A Task (System.Threading.Tasks.Task) is an object representing an operation that may not be finished yet. Task<T> also carries a result of type T. A Task is not a thread — it's a status board.

• Running / waiting — not finished (states like WaitingForActivation)
• RanToCompletion — finished; Result is ready
• Faulted — an exception was stored inside
• Canceled — stopped via a CancellationToken

Try it

Drive a Task through its lifecycle.

Awaiting this task now would pause the caller until it finishes.

⏸️ await = "pause me, free the thread"

async on a method lets you use await inside it (and makes the compiler wrap the result in a Task). await checks: is the awaited Task finished? If yes, keep going. If not, register the rest of the method as a callback, return an incomplete Task to the caller, and give the thread back.

Async is contagious ("async all the way"): callers usually await too, up to the framework entry point (a controller action, an event handler, async Task Main).

Try it

Watch which thread runs each line (simulated thread IDs).

⚡ Already done? No pause at all

If the awaited operation has already completed (a cache hit, data already buffered), await doesn't suspend. The method keeps running on the same thread with no callback registration and, often, no allocation. This "synchronous fast path" is why async code can be nearly as cheap as sync code.

Try it

🔗 Continuation = "the rest of the method"

A continuation is the code after an await, packaged as a callback. Where does it run?

• UI apps (WPF, WinForms, MAUI): back on the UI thread, via the captured SynchronizationContext.
• ASP.NET Core & console apps: on any thread-pool thread — there is no SynchronizationContext.
• With ConfigureAwait(false): on the thread pool, ignoring any context.

The old way was task.ContinueWith(...). Prefer await: it's easier to read, flows exceptions naturally and respects the context.

Try it

💥 Exceptions travel inside the Task

An exception thrown in an async method doesn't crash the caller immediately — it's stored in the Task (status Faulted). await rethrows the original exception with its stack trace. Blocking with .Wait() or .Result wraps it in an AggregateException instead (.GetAwaiter().GetResult() doesn't wrap, but still blocks).

With Task.WhenAll, await rethrows the first exception; all of them remain in task.Exception.InnerExceptions.

Try it

⚠️ async void: fire, forget, crash

async void methods return nothing to await, so the caller can't know when they finish or catch their errors. An unhandled exception is raised on the SynchronizationContext (or thread pool) and usually terminates the process.

Only use async void for event handlers (button.Click += async (s, e) => …) and wrap the body in try/catch. Everything else should return Task.

Try it

🫥 "There is no thread"

A famous line by Stephen Cleary: during a truly asynchronous I/O operation no thread is waiting for it. The request sits in the OS and the device; a thread is only borrowed briefly at the end to run your continuation.

Exceptions: Task.Run work (uses a thread by design), and some "async" APIs that internally do blocking work on the pool — for example regular-file reads on Linux, which epoll can't wait on.

Try it

Start 1,000 simultaneous downloads and count threads that are waiting.

ValueTask<T>

A struct that holds either a ready result or a real Task (or a pooled IValueTaskSource). When a method usually completes synchronously, returning ValueTask<T> avoids allocating a Task each call.

• ✅ Use for hot paths that mostly finish synchronously (caches, buffered readers).
• ❌ Await it only once; never call .Result before it completes; never await concurrently.
• Need WhenAll or multiple awaits? Call .AsTask() once.
• Microsoft's guidance: default to Task; switch only when profiling shows it matters. Analyzer CA2012 flags misuse.

ConfigureAwait

ConfigureAwait(false) says: "I don't need to resume on the captured SynchronizationContext/TaskScheduler." It doesn't change results or exceptions.

• Library code (NuGet packages, shared layers): use ConfigureAwait(false) on every await — you don't know who calls you.
• UI code: don't, if the code after await touches controls.
• ASP.NET Core app code: unnecessary (no context). The ASP.NET Core team itself dropped it.
• .NET 8+ ConfigureAwaitOptions: SuppressThrowing (wait without throwing), ForceYielding (always yield, even if completed), ContinueOnCapturedContext.

SynchronizationContext & TaskScheduler

When you await, the awaiter captures SynchronizationContext.Current (or, if none, a non-default TaskScheduler.Current) and posts the continuation there.

ExecutionContext & AsyncLocal<T>

ExecutionContext is ambient data that always flows across awaits (unlike SynchronizationContext, which you can opt out of). It carries culture, security principal and AsyncLocal<T> values — the mechanism behind logging scopes, Activity.Current tracing and IHttpContextAccessor.

• Values flow down into awaited/child calls, not back up to the caller.
• Keep AsyncLocal values small and immutable; each change copies the context.
• ExecutionContext.SuppressFlow() exists for rare low-level cases.

IAsyncEnumerable<T> & await foreach

An async stream: each MoveNextAsync() may wait. Perfect for paging through an API, reading lines from a socket, EF Core AsAsyncEnumerable() or streaming JSON responses in ASP.NET Core.

• Write one with async IAsyncEnumerable<T> + yield return.
• Pass cancellation with [EnumeratorCancellation] and .WithCancellation(ct).
• LINQ over async streams: System.Linq.AsyncEnumerable is in-box from .NET 10.

System.Threading.Channels

A fast, async-friendly producer/consumer queue. Producers await writer.WriteAsync(); consumers await foreach (var x in reader.ReadAllAsync()).

• Bounded channels apply back-pressure: writers wait when full (or drop, per BoundedChannelFullMode).
• Unbounded channels never block writers — watch memory.
• Ideal for background work queues in ASP.NET Core (BackgroundService).

TaskCompletionSource<T>

Creates a Task you complete manually — the bridge from callbacks, events or legacy APIs into the await world.

• Always pass TaskCreationOptions.RunContinuationsAsynchronously, otherwise awaiting code may run inline inside your SetResult call and cause surprising re-entrancy or deadlocks.
• Use TrySetResult/TrySetException/TrySetCanceled when several paths may race.
• Non-generic TaskCompletionSource exists since .NET 5.

Locks and await

You can't await inside a lock block (compiler error CS1996): the continuation might run on a different thread than the one holding the monitor. For mutual exclusion around awaits use SemaphoreSlim(1, 1) with WaitAsync.

• .NET 9's System.Threading.Lock is a faster synchronous lock — still no awaits inside.
• Always release in finally.
• SemaphoreSlim(n) also throttles concurrency (e.g. max 10 outgoing calls).

IAsyncDisposable & await using

Some resources need async cleanup — flushing a stream, closing a network connection. await using calls DisposeAsync() at the end of the scope.

• Use for DbContext, FileStream, Utf8JsonWriter, SignalR connections, etc.
• Implement both IDisposable and IAsyncDisposable in libraries when possible.
• Careful with "eliding" async: returning a Task from inside a using without awaiting disposes the resource too early.

The awaitable pattern

await is pattern-based: anything with a GetAwaiter() method (even an extension method) whose result has IsCompleted, OnCompleted (via INotifyCompletion) and GetResult() can be awaited. That's how Task.Yield(), ConfigureAwait and ValueTask work.

For return types, [AsyncMethodBuilder] lets you build custom task-like types; .NET 6+ also allows per-method builders such as PoolingAsyncValueTaskMethodBuilder.

Task.Yield, Task.Run, StartNew

• await Task.Yield() forces the method to suspend and resume later — useful to let a UI repaint or to make sure a caller gets control back. It is not a "low priority" switch.
• Task.Run(func) queues work to the thread pool. Right for offloading CPU work from a UI thread.
• Task.Factory.StartNew is low-level: with an async lambda it returns Task<Task> (you'd need .Unwrap()), and it uses TaskScheduler.Current. Prefer Task.Run.
• TaskCreationOptions.LongRunning hints for a dedicated thread — only for synchronous, long blocking loops.

Timers without threads

• Task.Delay registers with the runtime's timer queue — no thread sleeps. Never use Thread.Sleep in async code.
• PeriodicTimer (.NET 6+) gives a clean await timer.WaitForNextTickAsync(ct) loop, without overlapping ticks.
• TimeProvider (.NET 8+) abstracts time so tests can fast-forward delays and timeouts (FakeTimeProvider).
• task.WaitAsync(timeout, ct) (.NET 6+) stops waiting after a timeout — it doesn't cancel the underlying work.

ref locals and Span<T> in async (C# 13+)

Before C# 13, async methods couldn't declare ref locals or ref struct locals such as Span<T>. Now they can — as long as the variable isn't used across an await (it can't be stored in the heap-allocated state machine).

Pattern: do the span-based parsing in a block between awaits, or move it into a small synchronous helper.

Runtime async (.NET 11)

For 14 years the C# compiler did all the async work (Chapter 6). Runtime async moves suspension and resumption into the CLR: the compiler emits much simpler IL for methods marked MethodImplOptions.Async, and the runtime captures and restores the stack frames itself.

• Reported benefits: readable stack traces, accurate breakpoints, fewer allocations along deep await chains.
• .NET 10: experimental, enabled via config switches.
• .NET 11: CoreCLR support on by default; System.* libraries ship compiled with it; your projects opt in with a project feature flag.
• Semantics (contexts, exceptions, ConfigureAwait) are intended to stay the same.