What does ConfigureAwait(false) do, when should you use it, and what are ConfigureAwaitOptions in .NET 8+?

1. Mechanism

task.ConfigureAwait(false) returns a ConfiguredTaskAwaitable whose awaiter registers the continuation with continueOnCapturedContext: false:

awaiter.UnsafeOnCompleted(continuation):
    if continueOnCapturedContext:
        capture SynchronizationContext.Current (if non-default) or TaskScheduler.Current (if non-default)
    else:
        no capture -> continuation runs on the pool or synchronously on the completing thread

2. The already-completed caveat

public async Task SaveAsync()
{
    await _cache.GetAsync().ConfigureAwait(false);   // cache hit: already complete -> still on UI thread
    DoCpuHeavyWork();                                 // runs on the UI thread!
    await _http.PostAsync(...).ConfigureAwait(false); // incomplete -> switches to the pool
}

That's why libraries apply it to every await. If you need to guarantee you've left the context now, use await Task.Yield() (which honours the context, careful) or, in .NET 8+, await someTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding), or offload with Task.Run.

3. SuppressThrowing in practice

// Shutdown: wait for background work to finish, log failures, never throw from here.
await _backgroundTask.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
if (_backgroundTask.IsFaulted)
    _log.LogError(_backgroundTask.Exception, "Background loop failed");

Restrictions: not supported for Task<TResult> (throws ArgumentOutOfRangeException), because there would be no result to return. Cast to Task if you only need completion.

4. Why ASP.NET Core doesn't need it

With no SynchronizationContext and the default scheduler, the "captured" and "not captured" paths behave the same, so ConfigureAwait(false) makes no functional difference in app code there. Teams often omit it in ASP.NET Core apps for readability, while keeping it in shared libraries.

5. Analysers

6. Version notes

7. Try it yourself

1. In WinForms/WPF, set a label after await Task.Delay(100).ConfigureAwait(false) and see the cross-thread exception; remove it and it works.
2. Print SynchronizationContext.Current == null and the thread id before and after awaits with and without ConfigureAwait(false).
3. Await Task.CompletedTask.ConfigureAwait(false) on the UI thread and confirm you're still on the UI thread.
4. Run the code example: SuppressThrowing lets you inspect the faulted task without try/catch.
5. Try SuppressThrowing on a Task<int> and observe the exception.
6. Enable CA2007 in a library project and fix the warnings.

using System.Net.Http;

var client = new WeatherClient(new HttpClient { BaseAddress = new Uri("https://example.com/") });
try
{
    Console.WriteLine(await client.GetForecastAsync("Sydney"));
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Request failed: {ex.Message}");
}

// .NET 8+: wait for a task without throwing, then inspect it.
Task risky = FailLaterAsync();
await risky.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
Console.WriteLine($"Faulted: {risky.IsFaulted}");

static async Task FailLaterAsync()
{
    await Task.Delay(10);
    throw new InvalidOperationException("background failed");
}

// Library code: no dependency on the caller's context.
public sealed class WeatherClient(HttpClient http)
{
    public async Task<string> GetForecastAsync(string city, CancellationToken ct = default)
    {
        using var response = await http.GetAsync($"forecast/{Uri.EscapeDataString(city)}", ct)
            .ConfigureAwait(false);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
    }
}