
## Table of Contents

1. [Why Task Combinators Matter](#why-task-combinators-matter)
2. [Task.WhenAll](#taskwhenall)
3. [Start First, Await One-by-One](#start-first-await-one-by-one)
4. [Task.WhenAny](#taskwhenany)
5. [Task.WhenEach (.NET 9)](#taskwheneach-net-9)
6. [Parallel.ForEachAsync](#parallelforeachasync)
7. [Exception Handling by Combinator](#exception-handling-by-combinator)
8. [Concurrent Scenario: Prefer task1, Fallback to task2](#concurrent-scenario-prefer-task1-fallback-to-task2)
9. [Decision Guide](#decision-guide)

---

## Why Task Combinators Matter

When an application performs multiple async operations, the hard part is usually not writing the operations themselves. The hard part is orchestration:

- Do you need all results before continuing?
- Do you only need the fastest result?
- Do you want to process results as they complete?
- Do you need bounded parallelism to protect CPU, I/O, or downstream services?

Task combinators solve these orchestration problems with expressive, reliable APIs.

---

## Task.WhenAll

**C# 5.0 / .NET 4.5**

Purpose: Runs multiple tasks concurrently and completes when all of them finish.

- Returns an array of results for `Task<T>` overloads.

```csharp
Task<string> t1 = FetchAsync("url1");
Task<string> t2 = FetchAsync("url2");
Task<string> t3 = FetchAsync("url3");

string[] results = await Task.WhenAll(t1, t2, t3);
```

- [OK] Use for fan-out / scatter-gather patterns.
- [!] If one or more tasks fail, `await Task.WhenAll(...)` throws. Inspect individual tasks if you need full error details.

---

## Start First, Await One-by-One

Another common pattern is to start multiple tasks first, then await them one-by-one:

```csharp
Task task1 = DoTask1();
Task task2 = DoTask2();
Task task3 = DoTask3();

await task1;
await task2;
await task3;
```

This is concurrent in the success path because all tasks are created before the first `await`.

How it differs from `Task.WhenAll`:

- Success case: often similar total time.
- Failure case: stops at the first failed `await`, so later tasks might not be observed in that method.
- `Task.WhenAll`: gives a single coordination point and naturally fits "wait for everything" intent.

If you need all tasks to complete and want consistent exception handling, prefer `Task.WhenAll`:

```csharp
Task task1 = DoTask1();
Task task2 = DoTask2();
Task task3 = DoTask3();

try
{
    await Task.WhenAll(task1, task2, task3);
}
catch
{
    // Inspect all faults if needed.
    var failures = new[] { task1, task2, task3 }
        .Where(t => t.IsFaulted)
        .SelectMany(t => t.Exception!.Flatten().InnerExceptions)
        .ToList();

    throw failures.Count == 1
        ? failures[0]
        : new AggregateException(failures);
}
```

---

## Task.WhenAny

**C# 5.0 / .NET 4.5**

Purpose: Completes when any of the supplied tasks finishes.

- Returns the first completed task.

```csharp
Task<string> fastest = await Task.WhenAny(
    FetchAsync("primary"),
    FetchAsync("fallback"));

string result = await fastest;
```

- [OK] Use for racing, timeouts, or first-response-wins patterns.
- [!] The other tasks keep running unless you cancel them.

---

## Task.WhenEach (.NET 9)

**.NET 9.0 / C# 13.0**

Purpose: Returns an `IAsyncEnumerable<Task<T>>` that yields tasks in completion order.

```csharp
Task<int>[] tasks = [ComputeAsync(1), ComputeAsync(2), ComputeAsync(3)];

await foreach (Task<int> completed in Task.WhenEach(tasks))
{
    int result = await completed;
    Console.WriteLine(result);
}
```

- [OK] Process results as soon as each task finishes, without manual bookkeeping.

---

## Parallel.ForEachAsync

**.NET 6.0**

Purpose: Processes items in parallel with async/await and built-in degree-of-parallelism control.

```csharp
var urls = new[] { "url1", "url2", "url3" };

await Parallel.ForEachAsync(urls,
    new ParallelOptions { MaxDegreeOfParallelism = 3 },
    async (url, ct) =>
    {
        string html = await httpClient.GetStringAsync(url, ct);
        Process(html);
    });
```

- [OK] Preferred over manual `Task.WhenAll` + `Select` when you need bounded parallelism.

---

## Exception Handling by Combinator

Different combinators surface exceptions differently. Use the pattern that matches your intent.

### Task.WhenAll: collect all failures

`await Task.WhenAll(...)` throws if any task fails. To inspect all faults, catch once, then inspect each task.

```csharp
Task<string> t1 = FetchAsync("url1");
Task<string> t2 = FetchAsync("url2");
Task<string> t3 = FetchAsync("url3");

try
{
    string[] results = await Task.WhenAll(t1, t2, t3);
    return results;
}
catch
{
    var failures = new[] { t1, t2, t3 }
        .Where(t => t.IsFaulted)
        .SelectMany(t => t.Exception!.Flatten().InnerExceptions)
        .ToList();

    if (failures.Count == 1)
    {
        throw failures[0];
    }

    throw new AggregateException(failures);
}
```

### Task.WhenAny: winner first, handle loser tasks explicitly

`WhenAny` only tells you which task completed first. The winner can still be faulted/canceled, and losers can fault later.

```csharp
using var cts = new CancellationTokenSource();

Task<string> primary = FetchAsync("primary", cts.Token);
Task<string> fallback = FetchAsync("fallback", cts.Token);

Task<string> winner = await Task.WhenAny(primary, fallback);
Task<string> loser = winner == primary ? fallback : primary;

try
{
    string result = await winner; // May throw if winner faulted/canceled
    cts.Cancel();                 // Stop loser if possible
    return result;
}
catch (Exception winnerEx)
{
    // Winner failed: optionally try loser before failing the request.
    try
    {
        return await loser;
    }
    catch (Exception loserEx)
    {
        throw new AggregateException("Winner and loser both failed.", winnerEx, loserEx);
    }
}
finally
{
    // Observe loser completion to avoid hidden/unobserved failures.
    _ = loser.ContinueWith(_ => { }, TaskScheduler.Default);
}
```

### Task.WhenEach: isolate per-item failures

`WhenEach` is best when each result is independent. Handle each completed task separately so one fault does not stop all processing.

```csharp
Task<int>[] tasks = [ComputeAsync(1), ComputeAsync(2), ComputeAsync(3)];
var failures = new List<Exception>();

await foreach (Task<int> completed in Task.WhenEach(tasks))
{
    try
    {
        int value = await completed;
        Console.WriteLine($"Success: {value}");
    }
    catch (Exception ex)
    {
        failures.Add(ex);
        Console.WriteLine($"Failed: {ex.Message}");
    }
}

if (failures.Count > 0)
{
    throw new AggregateException("One or more computations failed.", failures);
}
```

### Parallel.ForEachAsync: fail-fast by default, aggregate when needed

By default, an unhandled exception in one iteration stops the whole operation. Catch inside the loop if you want best-effort behavior.

```csharp
var urls = new[] { "url1", "url2", "url3" };
var failures = new ConcurrentBag<Exception>();

await Parallel.ForEachAsync(urls,
    new ParallelOptions { MaxDegreeOfParallelism = 3 },
    async (url, ct) =>
    {
        try
        {
            string html = await httpClient.GetStringAsync(url, ct);
            Process(html);
        }
        catch (Exception ex)
        {
            failures.Add(new Exception($"{url} failed", ex));
        }
    });

if (!failures.IsEmpty)
{
    throw new AggregateException(failures);
}
```

---

## Concurrent Scenario: Prefer task1, Fallback to task2

Requirement:

- `task1` and `task2` must start in parallel.
- If `task1` completes with a non-null result, use it.
- If `task1` returns null, use `task2`.

### Simple version

```csharp
Task<string?> task1 = GetPrimaryAsync();
Task<string?> task2 = GetFallbackAsync();

// Both tasks are already running concurrently.
string? primary = await task1;

if (primary is not null)
{
    return primary;
}

return await task2;
```

### Try/Catch Best Practices for This Scenario

- Catch `OperationCanceledException` separately and rethrow with `throw;` when caller cancellation is requested.
- If you catch broad `Exception`, do it only at the orchestration boundary, then inspect task states and rethrow meaningful exceptions.
- Do not use `throw ex;` because it resets the original stack trace.
- Prefer one boundary log entry in the catch block plus final structured failure details when mapping task outcomes.
- Always observe both tasks (for example with `Task.WhenAll`) to avoid hidden or unobserved exceptions.
- Keep business decision logic after the catch section: first choose successful result path, then map fault/cancel outcomes deterministically.

Use this variant when you need deterministic behavior across all outcomes and explicit exception semantics.

---

## Decision Guide

- Use `Task.WhenAll` when all operations are required.
- Use `Task.WhenAny` when the first completed operation is enough.
- Use `Task.WhenEach` when you want streaming completion-order processing.
- Use `Parallel.ForEachAsync` when processing many inputs with bounded concurrency.
- Use the primary/fallback pattern when business logic prefers one source but can accept another.

Task combinators are not just about speed. They are about expressing concurrency intent clearly, which makes code easier to reason about, test, and operate in production.


Learn when to use Task.WhenAll, Task.WhenAny, Task.WhenEach, and Parallel.ForEachAsync, including practical patterns for primary/fallback concurrency in real apps.

C# Task Combinators: Task.WhenAll, Task.WhenAny, Task.WhenEach, and Parallel.ForEachAsync


## Table of Contents

1. [Quick Answer](#quick-answer)
2. [What ConfigureAwait(false) Actually Changes](#what-configureawaitfalse-actually-changes)
3. [Why Deadlocks Happen with .Result and .Wait()](#why-deadlocks-happen-with-result-and-wait)
4. [3-Tier ASP.NET Core API Example](#3-tier-aspnet-core-api-example)
5. [Why ASP.NET Core Usually Does Not Need ConfigureAwait(false)](#why-aspnet-core-usually-does-not-need-configureawaitfalse)
6. [Where ConfigureAwait(false) Still Matters](#where-configureawaitfalse-still-matters)
7. [When NOT to Use ConfigureAwait(false)](#when-not-to-use-configureawaitfalse)
8. [.NET 8: ConfigureAwaitOptions](#net-8-configureawaitoptions)
9. [Blocking vs await: Complete Comparison](#blocking-vs-await-complete-comparison)
10. [Practical Rules You Can Apply Today](#practical-rules-you-can-apply-today)

---

## Quick Answer

- `ConfigureAwait(false)` tells `await` to not capture the current `SynchronizationContext`.
- Continuations resume on any available thread pool thread.
- In ASP.NET Core, there is no request `SynchronizationContext`, so `ConfigureAwait(false)` is usually a functional no-op in app code.
- In reusable library code, still use it consistently because callers might be WPF, WinForms, or older ASP.NET Framework.

---

## What ConfigureAwait(false) Actually Changes

Default `await` behavior is equivalent to `ConfigureAwait(true)`.

```csharp
async Task<string> GetDataAsync(string url)
{
    using var client = new HttpClient();

    // Do not capture caller context
    string data = await client.GetStringAsync(url).ConfigureAwait(false);
    return data;
}
```

Without `ConfigureAwait(false)`:

1. Capture current `SynchronizationContext` (if one exists).
2. Suspend method and return thread to caller.
3. When task finishes, continuation posts back to captured context.

With `ConfigureAwait(false)`:

1. Do not capture `SynchronizationContext`.
2. Suspend method and return thread to caller.
3. Continuation runs on whatever thread is available.

---

## Why Deadlocks Happen with .Result and .Wait()

Classic deadlock pattern in UI apps:

```csharp
// Library method without ConfigureAwait(false)
public async Task<string> FetchAsync(string url)
{
    using var client = new HttpClient();
    return await client.GetStringAsync(url);
}

// UI thread caller (WPF/WinForms)
public string LoadSynchronously()
{
    // Blocks UI thread
    return FetchAsync("https://example.com").Result;
}
```

What goes wrong:

- `.Result` blocks the UI thread.
- `await` continuation tries to return to UI context.
- UI thread is blocked and cannot run continuation.
- Both sides wait forever.

Adding `ConfigureAwait(false)` inside the async method can break that cycle because continuation no longer depends on UI context.

```csharp
public async Task<string> FetchAsync(string url)
{
    using var client = new HttpClient();
    return await client.GetStringAsync(url).ConfigureAwait(false);
}
```

Important: this does not make `.Result` a good pattern. The right fix is still to use `await` end-to-end.

---

## 3-Tier ASP.NET Core API Example

Let us use a simple API with Controller -> Service -> Repository.

### Repository

```csharp
public interface IWeatherRepository
{
    Task<string> GetRawForecastAsync(CancellationToken ct);
}

public sealed class WeatherRepository : IWeatherRepository
{
    private readonly HttpClient _http;

    public WeatherRepository(HttpClient http)
    {
        _http = http;
    }

    public async Task<string> GetRawForecastAsync(CancellationToken ct)
    {
        // In ASP.NET Core app code, ConfigureAwait(false) is optional.
        return await _http.GetStringAsync("https://example.com/forecast", ct);
    }
}
```

### Service

```csharp
public interface IWeatherService
{
    Task<WeatherDto> GetForecastAsync(CancellationToken ct);
}

public sealed class WeatherService : IWeatherService
{
    private readonly IWeatherRepository _repo;

    public WeatherService(IWeatherRepository repo)
    {
        _repo = repo;
    }

    public async Task<WeatherDto> GetForecastAsync(CancellationToken ct)
    {
        string raw = await _repo.GetRawForecastAsync(ct);
        return new WeatherDto
        {
            Summary = raw,
            RetrievedAtUtc = DateTime.UtcNow
        };
    }
}

public sealed class WeatherDto
{
    public string Summary { get; set; } = string.Empty;
    public DateTime RetrievedAtUtc { get; set; }
}
```

### Controller

```csharp
[ApiController]
[Route("api/weather")]
public sealed class WeatherController : ControllerBase
{
    private readonly IWeatherService _service;

    public WeatherController(IWeatherService service)
    {
        _service = service;
    }

    [HttpGet]
    public async Task<ActionResult<WeatherDto>> Get(CancellationToken ct)
    {
        WeatherDto dto = await _service.GetForecastAsync(ct);
        return Ok(dto);
    }
}
```

### Registration (Program.cs)

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddHttpClient<IWeatherRepository, WeatherRepository>();
builder.Services.AddScoped<IWeatherService, WeatherService>();

var app = builder.Build();
app.MapControllers();
app.Run();
```

This works perfectly without `ConfigureAwait(false)` in app layers because ASP.NET Core does not install a request `SynchronizationContext`.

---

## Why ASP.NET Core Usually Does Not Need ConfigureAwait(false)

ASP.NET Core behavior:

- `SynchronizationContext.Current` is usually `null`.
- `await` continuations already run on thread pool threads.
- There is no old request-thread affinity like ASP.NET Framework.

So in Controller/Service/Repository inside ASP.NET Core app code, adding `ConfigureAwait(false)` usually does not change runtime behavior.

Still, teams sometimes keep it in app code for consistency with shared libraries. That is a style choice, not a requirement.

---

## Where ConfigureAwait(false) Still Matters

It matters most in reusable libraries.

```csharp
public sealed class ExternalApiClient
{
    private readonly HttpClient _http;

    public ExternalApiClient(HttpClient http)
    {
        _http = http;
    }

    // Library code: always avoid capturing caller context
    public async Task<string> FetchDataAsync(string url, CancellationToken ct)
    {
        using var response = await _http.GetAsync(url, ct).ConfigureAwait(false);
        response.EnsureSuccessStatusCode();

        string content = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
        return content;
    }
}
```

Why this is safer:

- Library cannot assume caller environment.
- Caller may be WPF, WinForms, Xamarin, or legacy ASP.NET Framework.
- Avoids context capture overhead and reduces deadlock risk for bad sync callers.

---

## When NOT to Use ConfigureAwait(false)

Do not use it when continuation must run on a context-bound thread.

Examples:

1. WPF/WinForms event handlers that update UI controls after `await`.
2. Code paths that depend on context-specific state in older frameworks.

```csharp
// WPF/WinForms example
private async void BtnLoad_Click(object sender, EventArgs e)
{
    string text = await _client.FetchDataAsync("https://example.com", CancellationToken.None);
    // Resume on UI context so control access is safe.
    txtOutput.Text = text;
}
```

If you write UI app code, default `await` is typically the correct behavior in event handlers.

---

## .NET 8: ConfigureAwaitOptions

In .NET 8+, you can use flags-based options.

```csharp
// Equivalent intent to ConfigureAwait(false)
await task.ConfigureAwait(ConfigureAwaitOptions.None);

// Guarantee asynchronous continuation
await task.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
```

Common options:

- `None`: do not capture context.
- `ContinueOnCapturedContext`: capture and resume on context.
- `ForceYielding`: force asynchronous continuation.
- `SuppressThrowing`: advanced scenario, avoid automatic exception rethrow.

For most code, simple `ConfigureAwait(false)` remains easy to read and widely understood.

---

## Blocking vs await: Complete Comparison

| Approach                        | Blocks Thread? | Deadlock Risk with SyncContext? | Scales Under Load? | Recommendation                    |
| ------------------------------- | -------------- | ------------------------------- | ------------------ | --------------------------------- |
| `await task`                    | No             | No                              | Yes                | Always prefer                     |
| `task.Result`                   | Yes            | Yes                             | No                 | Avoid                             |
| `task.Wait()`                   | Yes            | Yes                             | No                 | Avoid                             |
| `task.GetAwaiter().GetResult()` | Yes            | Yes                             | No                 | Only last-resort bootstrap/legacy |

Even in ASP.NET Core where deadlock risk is lower, blocking still burns worker threads and hurts throughput.

---

## Practical Rules You Can Apply Today

1. Prefer async all the way: avoid sync-over-async wrappers.
2. In ASP.NET Core app layers, `ConfigureAwait(false)` is optional.
3. In reusable library/NuGet code, apply `ConfigureAwait(false)` on every await.
4. In UI event handlers, do not use `ConfigureAwait(false)` if you must update controls after await.
5. If legacy code must block, use `.GetAwaiter().GetResult()` rather than `.Result`, and keep that boundary as small as possible.

If you remember one line: use `await` everywhere you can, and use `ConfigureAwait(false)` where your code should not care about the caller's context.


Learn exactly what ConfigureAwait(false) does, when it prevents deadlocks, why ASP.NET Core usually does not need it, and how to apply it correctly in reusable library code.

ConfigureAwait(false) in C# and ASP.NET Core: Deadlocks, 3-Tier API, and Library Rules

Master SynchronizationContext, understand how .Result and .Wait() cause deadlocks in WPF/WinForms/ASP.NET Framework, and why ASP.NET Core eliminated this problem entirely.

async

C# Task Combinators: Task.WhenAll, Task.WhenAny, Task.WhenEach, and Parallel.ForEachAsync

ConfigureAwait(false) in C# and ASP.NET Core: Deadlocks, 3-Tier API, and Library Rules

C# Deadlocks and SynchronizationContext — Why ASP.NET Core Doesn't Have It

Subscribe for Updates