🔧 The Await Foreach That Was Never Actually Streaming
An async-enumerable sequence is supposed to stream results one at a time, pulling and awaiting only what the consumer actually asks for – that is the entire reason to reach for it over a regular collection. Add a single call that materializes the whole sequence into a list anywhere before the real consumer gets to it, and every row loads into memory upfront instead, which defeats the one benefit the streaming method was written for in the first place. The code still compiles, still works on a small development dataset, and the regression only shows up as excess memory use or a timeout once it meets a production-sized result.
🔎 The Problem
public async IAsyncEnumerable<Order> GetOrdersAsync(
[EnumeratorCancellation] CancellationToken ct = default)
{
using var reader = await _db.ExecuteReaderAsync(ct);
while (await reader.ReadAsync(ct))
{
yield return MapOrder(reader);
}
}
// The caller only wants a count, and reaches for the obvious-looking API:
public async Task<int> CountOrdersAsync()
{
var orders = await GetOrdersAsync().ToListAsync();
return orders.Count;
}
// Every single row now sits in memory as a materialized list before
// CountOrdersAsync even looks at the count - the streaming method
// never gets a chance to do what it was written for, because the
// list-building call drains it completely before returning control.
✅ Fix: Match the Call to What You Actually Need
- Prefer the method that matches what you actually need – a counting method, an existence check, or a plain await-foreach with an incrementing counter – instead of reaching for a list-building call out of habit when all you need is a single derived value, not the whole collection.
- Audit call sites that accept an async-enumerable parameter or return value for any list- or array-building call applied immediately afterward – that combination means the method signature promises streaming but the actual code path never streams at all.
- When a method truly needs the entire collection in memory, say so directly in its own return type instead of accepting a streaming sequence and materializing it internally – that keeps the real cost visible at the call site rather than hidden one layer down.
⚠️ Why This Is Easy to Miss
- A list-building call reads as the natural next step once a plain await-foreach does not fit cleanly into a chained, LINQ-style expression, so it looks like an idiomatic choice rather than a deliberate decision to give up on streaming.
- A small development or staging dataset loads into memory in milliseconds either way, so the real difference between streaming and loading everything upfront only becomes visible once the sequence reaches production scale.
An async-enumerable sequence is a promise to go row by row – one eager list-building call anywhere in the chain cashes that promise in for the full balance, all at once.
