Asynchronous Sequences#

Asynchronous sequences combine two concepts: iterators (yield statement) with asynchronous methods (async/await). They allow writing iterating methods that return subsequent elements asynchronously. This is particularly useful when each element of the sequence needs to be awaited. (If the entire sequence needs to be awaited, but not individual elements, it is better to consider using Task<IEnumerable<T>>).

public interface IAsyncEnumerable<out T>
{
    IAsyncEnumerator<T> GetAsyncEnumerator(CancellationToken cancellationToken = default);
}

public interface IAsyncEnumerator<out T> : IAsyncDisposable
{
    T Current { get; }
    ValueTask<bool> MoveNextAsync();
}

The Current property returns the current element. Access to this property is only allowed after MoveNextAsync() completes with a true result.

ValueTask<T> is a struct, analogous to the Task<T> class, which allows for more efficient execution by limiting the number of memory allocations, which can be quite numerous in the case of sequences.

IAsyncDisposable is the asynchronous version of the IDisposable interface with a single method ValueTask DisposeAsync().

The language syntax provides a special await foreach statement, which allows iterating over subsequent elements of a sequence with asynchronous waiting for subsequent elements.

IAsyncEnumerable<int> asyncSequence = RangeAsync(from: 0, to: 100, delay: 50);
await foreach(var item in asyncSequence)
{
    Console.WriteLine(item);
}

To pass a CancellationToken to a sequence, you can use the WithCancellation(CancellationToken token) extension method, e.g.: await foreach(var item in asyncSequence.WithCancellation(token)).

Similar to foreach, await foreach is syntactic sugar. The compiler expands this statement as follows:

IAsyncEnumerable<int> asyncSequence = RangeAsync(from: 0, to: 100, delay: 50);
IAsyncEnumerator<int> asyncEnumerator = asyncSequence.GetAsyncEnumerator();
try
{
    while(await asyncEnumerator.MoveNextAsync())
    {
        var item = asyncEnumerator.Current;
        Console.WriteLine(item);
    }
}
finally
{
    if (asyncEnumerator != null)
    {
        await asyncEnumerator.DisposeAsync();
    }
}

Asynchronous Iterator Methods#

Similar to iterator methods, the return type must be IAsyncEnumerable<T> or IAsyncEnumerator<T>. Similar to asynchronous methods, it must be marked async. In such a method, we can use both the yield and await statements.

public class Program
{
    public static async Task Main()
    {
        await foreach (int i in RangeAsync(0, 100, 50))
        {
            Console.WriteLine(i);
        }
    }
    
    private static async IAsyncEnumerable<int> RangeAsync(int from, int to, int delay)
    {
        for (int i = from; i < to; i++)
        {
            await Task.Delay(delay);
            yield return i;
        }
    }
}

The compiler will similarly generate a state machine corresponding to the asynchronous iterator method.

Cancellation#

Asynchronous iterator methods can support cancellation. You should add a CancellationToken parameter to such a method and decorate it with the EnumeratorCancellation attribute (from the System.Runtime.CompilerServices namespace). This allows the compiler to know which parameter to pass the token to when using the WithCancellation method.

using System.Runtime.CompilerServices;

public class Program
{
    public static async Task Main()
    {
        CancellationTokenSource cts = new CancellationTokenSource(2500);
        try
        {
            await foreach (int i in RangeAsync(0, 100, 50).WithCancellation(cts.Token))
            {
                Console.WriteLine(i);
            }
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("Enumeration cancelled");
        }
    }

    private static async IAsyncEnumerable<int> RangeAsync(int from, int to, int delay,
        [EnumeratorCancellation] CancellationToken token = default)
    {
        for (int i = from; i < to; i++)
        {
            await Task.Delay(delay, token);
            yield return i;
        }
    }
}

LINQ#

Since .NET 10, LINQ operators for asynchronous sequences are part of the base class library: the System.Linq.AsyncEnumerable class in the System.Linq namespace. In earlier versions of .NET, they were provided by the community-maintained System.Linq.Async NuGet package (in .NET 10, remove this package reference or upgrade it to version 7, otherwise ambiguous call errors may occur).

IAsyncEnumerable<int> asyncSequence = RangeAsync(from: 0, to: 100, delay: 50)
    .Where(x => x % 2 == 0)
    .Select(x => x * x);
    
await foreach(var item in asyncSequence)
{
    Console.WriteLine(item);
}

Operators that return a single value or a collection (e.g., ToListAsync, CountAsync, FirstAsync) are asynchronous and have to be awaited. Many operators also have overloads that accept an asynchronous delegate, which takes a CancellationToken and returns a ValueTask<T>:

List<int> squares = await RangeAsync(from: 0, to: 10, delay: 50)
    .Where(x => x % 2 == 0)
    .Select(async (x, token) =>
    {
        await Task.Delay(10, token);
        return x * x;
    })
    .ToListAsync();

Console.WriteLine(string.Join(", ", squares)); // 0, 4, 16, 36, 64