Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Async and Concurrency

ConfigureAwait()

Reference for Task.ConfigureAwait in C#: how await captures the synchronization context, when false helps, ConfigureAwaitOptions and library guidance.

By default await remembers the SynchronizationContext (or, failing that, the TaskScheduler) that was current when the wait began, and it resumes the rest of the method there. In a UI app this is what brings you back to the UI thread. ConfigureAwait(false) tells the awaiter not to bother: the continuation runs wherever the awaited task completes, usually on a thread-pool thread.

In console programs and ASP.NET Core there is no synchronization context, so the call makes no practical difference there. It matters in library code that might be used from a UI framework, and in code that has to avoid deadlocks.

C#
string text = await File.ReadAllTextAsync(path).ConfigureAwait(false);

Try it

C# Observing context capture

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# ConfigureAwaitOptions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public ConfiguredTaskAwaitable ConfigureAwait(bool continueOnCapturedContext);
public ConfiguredTaskAwaitable ConfigureAwait(ConfigureAwaitOptions options);   // .NET 8+

[Flags]
enum ConfigureAwaitOptions
{
    None = 0,
    ContinueOnCapturedContext = 1,
    SuppressThrowing = 2,
    ForceYielding = 4,
}
Value Description
true The default. Resume on the captured context or scheduler.
false Do not capture; resume on whatever thread completes the task.
SuppressThrowing Do not rethrow exceptions or cancellation (meant for Task, not Task<T>).
ForceYielding Never continue synchronously, even if the task is already complete.
None Equivalent to ConfigureAwait(false).

Returns: an awaitable wrapper; it must be awaited right away. It is not a Task, so it cannot be stored in a Task variable.

Errors: the same as the wrapped task. Using SuppressThrowing with a Task<T> is a mistake the analyzers flag, because the result could be missing.

Usage notes

  • Libraries: use ConfigureAwait(false) on every await in general-purpose library code, so callers on UI or legacy ASP.NET threads cannot deadlock you and you avoid needless thread hops.
  • Application code: in ASP.NET Core and console apps skip it. In UI code you usually want the context back after the await.
  • It affects only the code after that await. Each await in a method needs its own setting; setting it once does not carry over.
  • It does not leave the original thread by itself. If the task is already complete when awaited, the code continues synchronously on the same thread regardless.
  • After ConfigureAwait(false) you cannot touch UI objects or rely on HttpContext.Current in old ASP.NET.
  • Not a deadlock fix: blocking with .Result is still wrong. ConfigureAwait(false) all the way down can hide the problem but not remove it.
  • Analyzers: rule CA2007 can require the call in libraries. Turn it on there and off in apps.
  • Async streams and disposal: await foreach (...).ConfigureAwait(false) and await using var x = y.ConfigureAwait(false) follow the same rules.