.NET Creating Async Streams with IAsyncEnumerable

In modern .NET applications, asynchronous programming is crucial for handling large-scale operations efficiently. One powerful feature introduced in C# 8.0 is IAsyncEnumerable<T>, which allows streaming of asynchronous data efficiently using async/await patterns. Unlike traditional IEnumerable<T>, which loads all data at once, IAsyncEnumerable<T> enables lazy evaluation, reducing memory overhead and improving performance.

In this article, we will explore how to create and consume async streams using IAsyncEnumerable<T>, understand its use cases, and see real-world applications.

What is IAsyncEnumerable<T>?

IAsyncEnumerable<T> is an asynchronous version of IEnumerable<T>, allowing elements to be iterated over asynchronously using await foreach. This is particularly useful when dealing with data sources that involve I/O operations, such as databases, web APIs, or large datasets.

Key Benefits of IAsyncEnumerable<T>

• Improved Performance: Streams data as it arrives rather than loading everything at once.
• Memory Efficient: Reduces memory footprint by processing elements lazily.
• Better Responsiveness: Avoids UI freezing in front-end applications.

Creating Async Streams with IAsyncEnumerable<T>

Basic Example of IAsyncEnumerable<T>

Here’s how to create an async stream that generates numbers with a delay:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async IAsyncEnumerable<int> GenerateNumbersAsync()
    {
        for (int i = 1; i <= 5; i++)
        {
            await Task.Delay(1000); // Simulate async work
            yield return i;
        }
    }

    static async Task Main()
    {
        await foreach (var number in GenerateNumbersAsync())
        {
            Console.WriteLine(number);
        }
    }
}

Explanation

• The method GenerateNumbersAsync is an asynchronous iterator that uses yield return to return elements lazily.
• await Task.Delay(1000) simulates an asynchronous operation.
• The await foreach loop consumes the stream without blocking.

Consuming Async Streams from APIs

In a real-world scenario, APIs often return paginated results. Instead of waiting for all results, IAsyncEnumerable<T> enables streaming responses efficiently.

Here’s an example using HttpClient to consume an async API:

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

public class GitHubRepo
{
    public string Name { get; set; }
}

class Program
{
    static async IAsyncEnumerable<GitHubRepo> GetRepositoriesAsync()
    {
        using HttpClient client = new();
        var responseStream = await client.GetStreamAsync("https://api.github.com/users/dotnet/repos");
        var repos = JsonSerializer.DeserializeAsyncEnumerable<GitHubRepo>(responseStream);
        await foreach (var repo in repos)
        {
            yield return repo;
        }
    }

    static async Task Main()
    {
        await foreach (var repo in GetRepositoriesAsync())
        {
            Console.WriteLine(repo.Name);
        }
    }
}

Real-World Use Cases

• Database Streaming: Fetching records lazily from a database.
• File Processing: Reading large files asynchronously.
• API Pagination: Processing paginated API responses.

Handling Errors in Async Streams

Error handling in async streams follows standard exception handling patterns:

static async IAsyncEnumerable<int> GenerateNumbersWithErrorAsync()
{
    for (int i = 1; i <= 5; i++)
    {
        if (i == 3) throw new Exception("An error occurred at 3");
        yield return i;
        await Task.Delay(1000);
    }
}

static async Task Main()
{
    try
    {
        await foreach (var number in GenerateNumbersWithErrorAsync())
        {
            Console.WriteLine(number);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error: {ex.Message}");
    }
}

Best Practices

1. Use await foreach properly: Always consume async streams using await foreach.

2. Error Handling: Wrap await foreach in try-catch blocks.

3. Avoid Blocking Calls: Do not mix Task.Run with IAsyncEnumerable<T>.

4. Use CancellationToken for Graceful Cancellation:

   static async IAsyncEnumerable<int> GenerateNumbersAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
   {
       for (int i = 1; i <= 10; i++)
       {
           if (cancellationToken.IsCancellationRequested)
               yield break;
   
           yield return i;
           await Task.Delay(1000, cancellationToken);
       }
   }
   

Conclusion

IAsyncEnumerable<T> provides a powerful way to handle asynchronous streaming in .NET applications. By leveraging async streams, developers can build more responsive and scalable applications, especially when dealing with databases, file I/O, and API calls.

Frequently Asked Questions (FAQs)

1. What is IAsyncEnumerable<T> used for?

IAsyncEnumerable<T> is used for asynchronously streaming data, reducing memory consumption and improving performance.

2. How does IAsyncEnumerable<T> differ from IEnumerable<T>?

Unlike IEnumerable<T>, IAsyncEnumerable<T> supports asynchronous iteration using await foreach, making it ideal for I/O-bound operations.

3. Can I use IAsyncEnumerable<T> in ASP.NET Core?

Yes, it can be used in ASP.NET Core controllers for streaming large datasets to clients efficiently.

4. How do I handle exceptions in async streams?

Wrap await foreach inside a try-catch block to gracefully handle errors.

5. Can IAsyncEnumerable<T> be used with LINQ?

Yes, methods like ToListAsync() and FirstOrDefaultAsync() from Entity Framework Core work with IAsyncEnumerable<T>.

---

Did you find this guide helpful? follow this blog for more .NET tips!