Running Work Concurrently

You have seen that starting work and collecting its result are separate acts. Task.WhenAll makes that separation easy to express: start several operations, then wait for all of them.

The decision that matters is not how to write it. It is whether the operations are independent. Two calls that do not need each other's results can overlap. A call that needs the answer from the previous one cannot, no matter how it is written.

Getting this wrong in either direction costs you. Awaiting independent calls one at a time makes a page slower than it needs to be. Firing off hundreds of dependent or heavy calls at once can take down the thing you are calling.

public async Task<OrderPage> BuildPageAsync(int orderId, CancellationToken ct)
{
    // Dependent. Everything below needs the order, so this one is on its own.
    Order? order = await _orders.FindAsync(orderId, ct);

    if (order is null)
    {
        throw new OrderNotFoundException(orderId);
    }

    // Independent. None of these three needs a result from the others.
    Task<Customer> customerTask = _customers.GetAsync(order.CustomerId, ct);
    Task<List<Shipment>> shipmentsTask = _shipments.ForOrderAsync(order.Id, ct);
    Task<decimal> rateTask = _rates.GetAsync(order.Currency, ct);

    await Task.WhenAll(customerTask, shipmentsTask, rateTask);

    // Every task has finished, so reading Result here cannot block.
    return new OrderPage(
        order,
        customerTask.Result,
        shipmentsTask.Result,
        rateTask.Result);
}

• The first await stands alone because it has to. The customer id, the order id and the currency all come out of the order, so nothing else can start until it has arrived.
• The next three lines start three operations without awaiting them. All three are in flight by the time the fourth line runs.
• Task.WhenAll returns a task that completes when all three have. If the three calls take 120, 300 and 90 milliseconds, this step takes about 300 rather than 510.
• Reading .Result after Task.WhenAll is safe, because every task has already completed. This is the one place .Result does not block. If you find it uncomfortable, await each task individually after the WhenAll instead — those awaits cost nothing since the work is done.
• There is an overload of Task.WhenAll for tasks of the same type that returns an array of results, which is neater when you have a list of identical calls. Here the three types differ, so separate variables are clearer.
• The cancellation token goes into all four calls. Concurrency does not change that, and a cancelled page should stop all three outstanding requests, not just the next one.

public async Task<int> RevalueOrdersAsync(
    IReadOnlyList<int> orderIds,
    CancellationToken ct)
{
    int updated = 0;

    // Four at a time is enough to hide the latency without flooding the API.
    ParallelOptions options = new()
    {
        MaxDegreeOfParallelism = 4,
        CancellationToken = ct,
    };

    await Parallel.ForEachAsync(orderIds, options, async (orderId, token) =>
    {
        // A context per operation, because DbContext is not thread-safe.
        await using AppDbContext db = await _dbFactory.CreateDbContextAsync(token);

        Order? order = await db.Orders.FindAsync(new object?[] { orderId }, token);

        if (order is null)
        {
            return;
        }

        decimal rate = await _rates.GetAsync(order.Currency, token);

        order.SetLocalTotal(order.Total * rate);
        await db.SaveChangesAsync(token);

        Interlocked.Increment(ref updated);
    });

    return updated;
}

• Parallel.ForEachAsync runs an asynchronous body over a collection with a ceiling on how many are in flight. It is the readable way to say "concurrent, but not unlimited".
• MaxDegreeOfParallelism is the ceiling. Four is a starting guess, not a rule; the right number comes from the limits of whatever you are calling and from measurement.
• CreateDbContextAsync gives each iteration its own context. This is the part that is not optional — sharing one context across concurrent iterations is a bug even when it appears to work in testing.
• await using disposes each context when its iteration finishes, returning its connection to the pool. Without this, four concurrent iterations over 10,000 orders would hold on to 10,000 contexts.
• Interlocked.Increment is needed because several iterations may update the counter at the same moment. updated++ is not atomic: it reads, adds and writes, and two iterations can read the same value.
• The body receives its own token rather than closing over ct. They are the same cancellation here, but using the supplied one keeps the body honest if the options change.
• If you do not have a DbContext factory available, SemaphoreSlim with WaitAsync and Release achieves the same throttling by hand. Parallel.ForEachAsync is less code and harder to get wrong.