skip to content

In C# on .NET 8 and later, what do the ConfigureAwaitOptions flags for Task.ConfigureAwait do, and why does SuppressThrowing fail on a Task<TResult>?

level: seniorimportance: nice to knowfreq 20%

answer

  1. a flags enum, not a bool
  2. None means false
  3. wait for it, ignore the failure
  4. always yield, even if done
  5. no result to hand back

basics

~20 s

ConfigureAwaitOptions (.NET 8) replaces the bool: ContinueOnCapturedContext resumes on the captured context, SuppressThrowing completes the await without throwing, ForceYielding suspends even on a finished task. SuppressThrowing on Task<TResult> throws ArgumentOutOfRangeException, since no valid result exists.

solid answer

~40 s

`ConfigureAwaitOptions` is a `[Flags]` enum, added in .NET 8, taken by `Task.ConfigureAwait(ConfigureAwaitOptions)` and `Task<TResult>.ConfigureAwait(ConfigureAwaitOptions)`. `None` behaves like `ConfigureAwait(false)` and `ContinueOnCapturedContext` like `ConfigureAwait(true)`. `SuppressThrowing` lets you await a task only to know it finished: a faulted or cancelled task completes the await without throwing, and its exception is marked handled. `ForceYielding` makes the awaiter report incomplete even for a completed task, so the method always suspends; without `ContinueOnCapturedContext` the continuation goes to the thread pool. `Task<TResult>` rejects `SuppressThrowing` with `ArgumentOutOfRangeException` because a failed task has no valid `TResult` to return; analyzer CA2261 warns at build time, and the fix is to cast to `Task` first. There is no `ValueTask` overload.

code

csharp · 17 lines
csharp
Task cleanup = Task.Run(() => throw new IOException("temp file locked"));
await cleanup.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
Console.WriteLine($"SuppressThrowing on Task: no exception, status = {cleanup.Status}");

Task<int> count = Task.FromResult(42);
try
{
    await count.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);   // CA2261 warns at build time
}
catch (ArgumentOutOfRangeException ex)
{
    Console.WriteLine($"SuppressThrowing on Task<int>: {ex.GetType().Name} for '{ex.ParamName}'");
}
await ((Task)count).ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);   // the documented fix

var forced = Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding).GetAwaiter();
Console.WriteLine($"ForceYielding on a completed task: awaiter.IsCompleted = {forced.IsCompleted}");

go deeper

for a junior

Know that newer .NET lets you pass options to ConfigureAwait instead of true or false, and that None means the same as false.

for a middle

Describe each flag and that they combine, and that SuppressThrowing alone also drops context capture.

for a senior

Explain the Task<TResult> restriction, CA2261 and the cast-to-Task fix, and when ForceYielding is the right tool.

for a principal

Weigh adopting the options in a shared codebase: clearer intent and no try/catch for best-effort waits, against targets older than .NET 8 that lack the overload.

## From a bool to a flags enum Before .NET 8, `Task.ConfigureAwait` took one `bool continueOnCapturedContext`. .NET 8 added an overload on `Task` and on `Task<TResult>` that takes `ConfigureAwaitOptions`, a `[Flags]` enum in `System.Threading.Tasks`: | Member | Value | Meaning | |---|---|---| | `None` | 0 | do not capture; identical to `ConfigureAwait(false)` | | `ContinueOnCapturedContext` | 1 | resume on the captured `SynchronizationContext` or `TaskScheduler`; identical to `ConfigureAwait(true)` | | `SuppressThrowing` | 2 | do not throw when the task ends faulted or cancelled | | `ForceYielding` | 4 | suspend even if the task is already complete | The flags combine, for example `ConfigureAwaitOptions.ContinueOnCapturedContext | ConfigureAwaitOptions.ForceYielding`. Any bit outside these three makes `ConfigureAwait` throw `ArgumentOutOfRangeException`. Note the trap in the zero value: writing `ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing)` alone also **drops** context capture, because `ContinueOnCapturedContext` is not set. Code on a UI thread that needs to come back has to include it. ## SuppressThrowing Sometimes you await a task only to know it has finished: shutting down a background loop, waiting for a best-effort cleanup, draining an operation you cancelled yourself. Before .NET 8 that took a `try { await t; } catch { }`, which throws and catches an exception for nothing. With `await cleanup.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing)` the await completes normally whatever the task's final state; you can then inspect `cleanup.Status` or `cleanup.IsFaulted`. The runtime also marks the task's exceptions as handled, so they are not later reported as unobserved. ### Why Task<TResult> refuses it An await on `Task<TResult>` must produce a `TResult`. If the task faulted, there is no valid value to return, and handing back `default` would be a silent wrong answer. So `Task<TResult>.ConfigureAwait(ConfigureAwaitOptions)` accepts only `ContinueOnCapturedContext` and `ForceYielding` and throws `ArgumentOutOfRangeException` (parameter `options`) for `SuppressThrowing`. Three layers report it: 1. **Build time:** analyzer **CA2261**, "Do not use `ConfigureAwaitOptions.SuppressThrowing` with `Task<TResult>`", enabled as a warning by default in .NET 10. 2. **Run time:** the `ConfigureAwait` call itself throws, before any awaiting happens. 3. **Fix:** cast to the base type, `await ((Task)task).ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing)`, and read `Result` only after checking the status. ## ForceYielding An await on a completed task does not suspend; the method continues synchronously. Usually that is what you want, but sometimes you need a guaranteed yield, for example to make sure a long method returns its `Task` to the caller before doing heavy synchronous work. `ForceYielding` makes the configured awaiter's `IsCompleted` return `false`, so the method always suspends: - With `ForceYielding` alone, the continuation is queued to the thread pool. - With `ContinueOnCapturedContext | ForceYielding`, it is posted to the captured context, which is how `await Task.Yield()` behaves. So `await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding)` is a way to say "get off this thread and onto the pool", which `Task.Yield()` cannot do because `YieldAwaitable` has no `ConfigureAwait` method. ## A worked example: stopping a background loop A desktop app runs a polling loop as `Task _poller = PollAsync(_cts.Token);`. On shutdown it cancels and waits for the loop to finish before disposing the resources the loop uses: 1. Call `_cts.Cancel()` to signal the loop. 2. `await _poller.ConfigureAwait(ConfigureAwaitOptions.ContinueOnCapturedContext | ConfigureAwaitOptions.SuppressThrowing);` waits for the loop to end. A loop that stops by throwing `OperationCanceledException` leaves the task cancelled, and a loop that crashed leaves it faulted; neither throws here. 3. Check `_poller.IsFaulted` and log `_poller.Exception` if the loop crashed for a reason other than the cancellation. 4. Dispose the resources, back on the UI thread because `ContinueOnCapturedContext` was included. Before .NET 8 the same step was a `try`/`catch` that existed only to discard the expected exception. The options version states the intent directly and avoids throwing at all. ## What it does not cover - **`ValueTask` and `ValueTask<TResult>`** only have `ConfigureAwait(bool)`. Convert with `AsTask()` if you need the options, at the cost of a possible allocation. - **`await foreach` and `await using`** keep their `bool` `ConfigureAwait` methods. - **ExecutionContext** still flows; no option changes that. ## When it comes up Interviews rarely open with it, but it shows whether a candidate knows the newer API and reads analyzer warnings. A good answer gives the three flags, the equivalence with the old bool, the `Task<TResult>` restriction with its reason, and the zero-value trap.

  • On a C# UI thread, does await task.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing) come back to the UI thread?
    No. Without `ContinueOnCapturedContext` the options mean 'do not capture', just like `ConfigureAwait(false)`. To swallow the failure and still resume on the UI thread, write `ConfigureAwaitOptions.ContinueOnCapturedContext | ConfigureAwaitOptions.SuppressThrowing`.
  • How is ConfigureAwaitOptions.ForceYielding different from await Task.Yield() in C#?
    `await Task.Yield()` always suspends and resumes on the current `SynchronizationContext` or non-default `TaskScheduler` if there is one, so on a UI thread it comes back to the UI thread. `ForceYielding` without `ContinueOnCapturedContext` suspends and resumes on the thread pool, which `Task.Yield()` cannot express.

  • SuppressThrowing works on Task<TResult> and returns default on failure.
  • ConfigureAwaitOptions.None keeps the default context capture.
  • SuppressThrowing alone still resumes on the captured context.
  • ValueTask has the same ConfigureAwaitOptions overload as Task.
  • ForceYielding only matters for tasks that are still running.

Assumes .NET 10; ConfigureAwaitOptions and the Task.ConfigureAwait(ConfigureAwaitOptions) overloads arrived in .NET 8, and older targets only have ConfigureAwait(bool).