Async streams with IAsyncEnumerable

A report reads 3 pages of orders from an API that needs 100 ms per page. Collected into a list first, the first order reaches the report after all 3 pages, 300 ms; read as an async stream, it arrives after the first page, 100 ms, and only one page is in memory at a time.

You will write async streams with yield return, read them with await foreach, see how far a stream runs when its reader stops early, and query streams with the LINQ operators that .NET 10 ships.

An async iterator hands over each item as soon as it has it

pages.cs reads 3 pages of 2 orders each, first as a stream, then collected into a list:

// An async stream: an async method that returns IAsyncEnumerable<T> and uses yield return. Each order is handed to
// the loop as soon as its page has arrived, while the next page is still to be fetched.
await foreach (Order order in OrdersAsync())
{
    Console.WriteLine($"  the loop got order {order.Id} ({order.Amount})");
}

// The same orders collected into a list first: nothing reaches the caller before the last page has arrived.
List<Order> all = await AllOrdersAsync();
Console.WriteLine($"the list arrived with {all.Count} orders, after {Api.PagesFetched} pages");

static async IAsyncEnumerable<Order> OrdersAsync()
{
    for (int page = 1; page <= 3; page++)
    {
        Order[] orders = await Api.GetPageAsync(page);
        foreach (Order order in orders)
        {
            yield return order;
        }
    }
}

static async Task<List<Order>> AllOrdersAsync()
{
    Api.PagesFetched = 0;
    var all = new List<Order>();
    for (int page = 1; page <= 3; page++)
    {
        all.AddRange(await Api.GetPageAsync(page, quiet: true));
    }

    return all;
}

static class Api
{
    public static int PagesFetched;

    // A paginated API: page n holds orders n01 to n02, and every page takes 100 ms to arrive.
    public static async Task<Order[]> GetPageAsync(int page, bool quiet = false)
    {
        if (!quiet)
        {
            Console.WriteLine($"fetching page {page}");
        }

        await Task.Delay(100);
        PagesFetched++;
        return [new(page * 100 + 1, 250 * page), new(page * 100 + 2, 120 * page)];
    }
}

record Order(int Id, int Amount);

fetching page 1
  the loop got order 101 (250)
  the loop got order 102 (120)
fetching page 2
  the loop got order 201 (500)
  the loop got order 202 (240)
fetching page 3
  the loop got order 301 (750)
  the loop got order 302 (360)
the list arrived with 6 orders, after 3 pages

OrdersAsync is an async iteratorasync iterator: An async method that returns IAsyncEnumerable<T> and uses yield return. Its body runs only as its reader asks for items, each time up to the next yield return.: an async method that returns IAsyncEnumerable<Order> and uses yield return. Its result is an async streamasync stream: A sequence whose items arrive asynchronously, typed IAsyncEnumerable<T>. An async iterator produces it with yield return, and await foreach reads it one item at a time., and await foreach reads it. The run interleaved the two: the loop printed orders 101 and 102 before page 2 was even fetched, while the list version handed over nothing until the last page had arrived. Step through the first orders:

The interfaces mirror the ones a foreach uses: IAsyncEnumerable<T> hands out an IAsyncEnumerator<T>, whose MoveNextAsync returns a ValueTask<bool> that the loop awaits, and the enumerator is disposed asynchronously when the loop ends. Async streams came with C# 8 and .NET Core 3.0.

await foreach pulls one item at a time, so the reader sets the pace

early.cs reads a stream of 5 pages and stops after 3 orders:

// await foreach asks for one item at a time, so the producer runs only as far as the consumer reads. Breaking out
// of the loop disposes the stream: the iterator's finally block runs, and the pages after it are never fetched.
int pagesFetched = 0;
int seen = 0;
await foreach (int id in OrderIdsAsync())
{
    Console.WriteLine($"  the loop got order {id}");
    if (++seen == 3)
    {
        Console.WriteLine("the loop breaks after 3 orders");
        break;
    }
}

Console.WriteLine($"pages fetched: {pagesFetched} of 5");

async IAsyncEnumerable<int> OrderIdsAsync()
{
    try
    {
        for (int page = 1; page <= 5; page++)
        {
            Console.WriteLine($"fetching page {page}");
            await Task.Delay(100);
            pagesFetched++;
            yield return page * 100 + 1;
            yield return page * 100 + 2;
        }
    }
    finally
    {
        Console.WriteLine("the iterator's finally block runs: connection closed");
    }
}

fetching page 1
  the loop got order 101
  the loop got order 102
fetching page 2
  the loop got order 201
the loop breaks after 3 orders
the iterator's finally block runs: connection closed
pages fetched: 2 of 5

The iterator fetched page 2 only when the loop asked for a third order, and when the loop broke out, the iterator’s finally block ran, printing “connection closed”, because leaving await foreach disposes the enumerator. Pages 3, 4 and 5 were never fetched: 2 pages of 5. A stream runs exactly as far as its reader asks, so a fast producer cannot bury a slow consumer under items. This built-in back-pressureback-pressure: A consumer setting the pace of its producer. An async stream has it built in: the producer runs only when the consumer asks for the next item, so items never pile up between them. is the difference from a buffer: when the producer should run ahead of its reader, as when messages arrive whether or not anyone reads them, a channel holds them in between, a tool of the concurrency module.

.NET 10 has LINQ for async streams built in

linq.cs filters, maps and totals a stream with the System.Linq.AsyncEnumerable class:

// .NET 10 has LINQ for async streams in the shared framework: System.Linq.AsyncEnumerable. Its operators
// read an IAsyncEnumerable<T> and return one, and the ...Async methods (ToListAsync, SumAsync) end the query.
IAsyncEnumerable<int> squares = AsyncEnumerable.Range(1, 10)
    .Where(n => n % 2 == 0)
    .Select(n => n * n);

List<int> list = await squares.ToListAsync();
Console.WriteLine($"even squares: {string.Join(",", list)}");
Console.WriteLine($"their sum: {await squares.SumAsync()}");
Console.WriteLine($"AsyncEnumerable is in the assembly {typeof(AsyncEnumerable).Assembly.GetName().Name}");

// The operators also take async lambdas, which get the stream's cancellation token.
IAsyncEnumerable<string> labels = AsyncEnumerable.Range(1, 3)
    .Select(async (int n, CancellationToken cancellationToken) =>
    {
        await Task.Delay(10, cancellationToken); // a lookup per item
        return $"order {n}";
    });
Console.WriteLine($"labels: {string.Join("; ", await labels.ToListAsync())}");

even squares: 4,16,36,64,100
their sum: 220
AsyncEnumerable is in the assembly System.Linq.AsyncEnumerable
labels: order 1; order 2; order 3

Where and Select return new streams, and nothing runs until ToListAsync or SumAsync reads them: the even squares 4, 16, 36, 64 and 100, with the sum 220. The operators also take async lambdas, which receive the stream’s cancellation token. AsyncEnumerable came from the assembly System.Linq.AsyncEnumerable, which is part of .NET 10.

Two more tools complete the set. [EnumeratorCancellation] marks the iterator parameter that receives the token of WithCancellation. It goes on the iterator’s CancellationToken parameter, written last with default as its value, as in Microsoft’s tutorial. JsonSerializer.DeserializeAsyncEnumerable reads a JSON array, or one JSON value per line, as an async stream.

Cancelling an async stream: [EnumeratorCancellation] and WithCancellation Pro: opens with a Pro, Premium or Ultimate pass

Streaming JSON without loading it: DeserializeAsyncEnumerable, measured Pro: opens with a Pro, Premium or Ultimate pass

A lab: read NDJSON orders lazily, skip bad lines and total them Pro: opens with a Pro, Premium or Ultimate pass

Practise

The self-check covers the first three sections: when an async iterator runs, how far it runs for a reader that stops early, and what the AsyncEnumerable operators return. Your weakest topic gets the first question, and each choice comes with its reason:

Interview questions

Fresher · What is the difference between IEnumerable<T> and IAsyncEnumerable<T>?

Both are sequences read one item at a time, and both can be written as iterators with yield return. With IEnumerable<T>, MoveNext returns a bool at once, so getting an item that needs I/O would block the thread. With IAsyncEnumerable<T>, MoveNextAsync returns a ValueTask<bool> that the reader awaits, so the producer can await a page, a row or a message between items without holding a thread. You read it with await foreach, which also disposes the enumerator asynchronously when the loop ends or breaks. Choose IAsyncEnumerable<T> when items arrive over time from I/O, and IEnumerable<T> when they are computed or already in memory.

Key takeaways

• An async iterator, an async method that returns IAsyncEnumerable<T> with yield return, hands over each item as soon as it has it, and await foreach reads it.
• The iterator runs only as far as its reader asks, and leaving the loop early disposes it, which runs its finally blocks; that is back-pressure without a buffer.
• .NET 10 ships LINQ for async streams in System.Linq.AsyncEnumerable, whose operators run only when a method such as ToListAsync reads the result.