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>?
answer
- a flags enum, not a bool
- None means false
- wait for it, ignore the failure
- always yield, even if done
- no result to hand back
basics
~20 sConfigureAwaitOptions (.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 linesTask 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
Know that newer .NET lets you pass options to ConfigureAwait instead of true or false, and that None means the same as false.
Describe each flag and that they combine, and that SuppressThrowing alone also drops context capture.
Explain the Task<TResult> restriction, CA2261 and the cast-to-Task fix, and when ForceYielding is the right tool.
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).