skip to content

Asynchronous Sequences

IAsyncEnumerable<T> with await foreach consumes results as they arrive, and .NET 10 ships async LINQ in the box. Interviewers ask when streaming beats returning a list.

on this pageshow

explore

questions

6

In C#, when does returning IAsyncEnumerable<T> beat returning Task<List<T>>, and when is the list still the better return type?

level: middleimportance: must knowfreq 55%

answer

  1. first result vs last result
  2. memory grows with the buffer
  3. the caller can stop early
  4. a second loop runs the body again

basics

~20 s

Stream with IAsyncEnumerable<T> when results arrive over time and callers act on each: the first result comes early, memory stays bounded and the caller can stop. Return Task<List<T>> when callers need a complete, countable snapshot they can read twice.

solid answer

~40 s

`Task<List<T>>` completes once, after every page has been fetched and buffered, so the caller waits for the last page and memory grows with the result. An async iterator returning `IAsyncEnumerable<T>` hands each element over as it is yielded: a log viewer shows the first entries after the first page, holds roughly one page at a time, and stops fetching when the consumer `break`s. The list is still better when callers need `Count`, indexing, sorting or a second pass: enumerating an async iterator again **runs its body again** and re-fetches every page. Streaming also keeps the producer's resources open while a slow consumer works, and a failure on page three arrives after pages one and two were already processed, so partial work must be acceptable. Small, bounded results gain little from streaming.

code

csharp · 21 lines
csharp
int pageFetches = 0;
IAsyncEnumerable<string> entries = TailAsync(pages: 2);

int count = 0;
await foreach (string entry in entries) count++;        // first pass

string? last = null;
await foreach (string entry in entries) last = entry;   // second pass

Console.WriteLine($"count={count} last={last} pageFetches={pageFetches}");

async IAsyncEnumerable<string> TailAsync(int pages)
{
    for (int page = 1; page <= pages; page++)
    {
        pageFetches++;                 // stands in for a remote call
        await Task.Delay(50);
        yield return $"page {page} entry A";
        yield return $"page {page} entry B";
    }
}

go deeper

for a junior

Remember the core difference: the list arrives once, complete; the async sequence hands you elements one at a time as they are produced.

for a middle

Explain the trade-offs concretely: time to first result and bounded memory for the stream, against counting, sorting and reading twice for the list.

for a senior

Point out the traps that bite in production: re-enumeration repeating every remote call, resources held open by a slow consumer, and failures that arrive after partial processing.

for a principal

Frame a team guideline: stream for large, open-ended or per-item-useful results, buffer for small or must-be-complete ones, and make the choice visible in the API.

## Two contracts for the same data A method that reads log entries from a paged remote API can expose them in two ways: ```csharp Task<List<LogEntry>> GetEntriesAsync(); // buffered IAsyncEnumerable<LogEntry> TailAsync(); // streamed ``` Both are asynchronous and both return many entries. The difference is **when** the caller gets them and **what** the caller holds. `Task<List<T>>` is a promise of one finished collection. `IAsyncEnumerable<T>` is a recipe for producing elements one at a time; nothing is fetched until someone enumerates it with `await foreach`, and each enumeration produces the elements afresh. ## Where streaming wins - **Time to first result.** With the list, the caller waits for the slowest, last page. With an async iterator, `MoveNextAsync()` completes at the first `yield return`, so a log viewer can show the first entries after the first page. - **Bounded memory.** The list holds every entry at once. The iterator keeps only what its current page needs; the consumer decides whether to keep anything. - **Early exit stops the work.** When the consumer `break`s out of `await foreach`, the loop disposes the enumerator instead of resuming it, so the pages the iterator has not fetched yet are never requested. With a list, every page has already been paid for. - **Unbounded sources.** A tail that keeps reading new entries cannot be a list at all; an async sequence can run as long as the consumer keeps asking. ## Where the list wins 1. **The caller needs the whole set.** `Count`, indexing, sorting by a key, or a total over all entries need everything anyway. Streaming only to collect into a list on the other side adds machinery for nothing. 2. **The caller reads the results twice.** An async iterator does not cache. A second `await foreach` over the same `IAsyncEnumerable<T>` runs the iterator body from the start and **repeats every fetch**: the example below loops twice and counts four page fetches for two pages. A `List<T>` is read twice for free. 3. **The producer holds expensive resources.** While the consumer works on an element, the iterator is suspended at its `yield return` with whatever it opened still open: a network connection, a file handle, a cursor. A slow consumer stretches that lifetime. Buffering and releasing early can be kinder to a shared resource. 4. **Errors must come before any processing.** A list either arrives whole or the task fails. A stream can fail on page three after the consumer has already acted on pages one and two, so the consumer must tolerate partial work. 5. **Small, bounded results.** Ten rows from one call gain nothing from streaming; the simpler contract wins. ## Side by side | Concern | `Task<List<T>>` | `IAsyncEnumerable<T>` | |---|---|---| | First element available | after the last is fetched | after it is yielded | | Memory held by the producer | the whole result | roughly the current batch | | Consumer stops early | all work already done | remaining work is skipped | | Reading twice | free, same data | runs the body again | | `Count`, indexing, sorting | built in | needs a full pass first | | Failure timing | before any processing | possibly mid-stream | | Producer resource lifetime | ends when the list is built | lasts as long as the loop | ## Reading the question in an interview The interviewer usually wants two things: that you know streaming is about **latency and memory**, not raw speed (fetching every page still takes as long), and that you can name the costs. The strongest answers point out that a sequence is not a collection: a method that returns `IAsyncEnumerable<T>` promises a fresh walk per enumeration, and callers who treat it like a list will silently double the calls. When a caller does need everything, buffering is one loop away, and the producer can still stream for the callers who do not. A practical guideline for a team API: stream when results are large, open-ended or useful one at a time; return a list when the result is small, must be complete before use, or will be read more than once. Either way, document which one it is in the method name and return type, and keep the two from drifting into a method that streams but is always buffered by its only caller.

  • Is a stream faster than the list for a consumer that reads every element anyway?
    Not in total time: every page is still fetched, one after another. An async iterator does not fetch page two until the consumer asks for the next element, so fetching and consumer work take turns rather than overlap unless the producer prefetches. What streaming changes is time to first result and peak memory. If the consumer needs everything before it can act, a buffered `Task<List<T>>` is simpler and no slower.
  • A caller needs both a count and the entries from an IAsyncEnumerable<T>; how do you avoid fetching twice?
    Enumerate once and buffer what you need: one `await foreach` that adds each entry to a `List<T>` and counts as it goes, then work on the list. Never loop the sequence once to count and once to process, because each `await foreach` over an async iterator runs its body again and repeats every remote call.
  • Why can a streamed API surface a failure after the consumer already acted on some results?
    The iterator throws from inside a later `MoveNextAsync()`, which `await foreach` rethrows in the middle of the loop. Everything the body did for earlier elements has already happened. A consumer that writes to a database or sends messages per element must be idempotent or track progress, which a caller of `Task<List<T>>` never has to think about.

A kitchen that sends each dish out as it is plated, versus one that holds every plate until the whole table's order is ready. Diners start eating sooner with the first, but asking for the same meal again means cooking it again; only the held-back tray can be served twice.

  • IAsyncEnumerable<T> always finishes sooner in total than returning Task<List<T>>.
  • An IAsyncEnumerable<T> caches its elements, so a second await foreach is free.
  • Streaming means the producer's connection closes before the consumer sees an element.
  • A streamed method fails before any element is processed, just like the list does.
  • Return IAsyncEnumerable<T> everywhere; Task<List<T>> is an outdated pattern.
open as a page

In C#, how do you write a method that produces items asynchronously one at a time, and how does a caller loop over them?

level: juniorimportance: should knowfreq 55%

basics

~20 s

Mark the method async, return IAsyncEnumerable<T>, and use await and yield return in its body. The caller consumes it with await foreach, which awaits each element and runs the loop body as soon as that element is yielded.

open as a page

In .NET 10, what does System.Linq.AsyncEnumerable add for IAsyncEnumerable<T>, and what changes for code built on the System.Linq.Async package?

level: middleimportance: should knowfreq 30%

basics

~20 s

.NET 10 ships System.Linq.AsyncEnumerable: Where, Select, Take and the rest for IAsyncEnumerable<T>, plus terminal operators like ToListAsync that return ValueTask. It replaces the community System.Linq.Async package, which can cause ambiguity errors until removed or upgraded.

open as a page

In a C# async iterator, when does the method body start running, and what runs when the consumer breaks out of await foreach early?

level: middleimportance: should knowfreq 40%

basics

~20 s

Calling an async iterator runs none of its body; it starts at the first MoveNextAsync. When await foreach exits early by break or exception, it awaits DisposeAsync, which runs only the iterator's pending finally blocks and using disposals.

open as a page

In C#, why can a token passed with WithCancellation fail to reach an async iterator, and what does [EnumeratorCancellation] change?

level: seniorimportance: should knowfreq 45%

basics

~20 s

WithCancellation passes its token to GetAsyncEnumerator, and an async iterator ignores that token unless one CancellationToken parameter carries [EnumeratorCancellation]. With the attribute, the body sees that token, combined with any token passed as an argument.

open as a page

In C# library code, what does ConfigureAwait(false) on an await foreach loop configure, and why can the loop body still run on the captured context?

level: seniorimportance: nice to knowfreq 25%

basics

~20 s

source.ConfigureAwait(false) configures only the awaits that await foreach generates on MoveNextAsync and DisposeAsync. Awaits inside the async iterator are configured by the iterator's own code; if they capture the context, the loop body can still run there.

open as a page