C#如何使用IAsyncEnumerable C#异步流使用详解

来源：这里教程网时间：2026-02-21 17:34:50 作者：

IAsyncEnumerable 是 C# 8.0 引入的核心异步流类型，用于高效、自然地处理“按需异步生成的多个数据项”，比如分页查询、实时日志、流式 API 响应、大数据集逐块读取等场景。它不是一次性加载全部结果，而是支持

await foreach

消费，每个元素可独立 await，内存友好且响应及时。

什么时候该用 IAsyncEnumerable？

当你需要以下任意一种能力时，IAsyncEnumerable 是比 List 或 IEnumerable 更合适的选择：

数据源本身是异步的（如数据库分页查询、HTTP 流式响应、文件分块读取） 不想阻塞线程，也不愿把全部结果缓存在内存里（尤其数据量大或生成耗时） 消费者希望边接收边处理，而不是等所有数据就绪才开始（降低端到端延迟） 需要在迭代中途取消（配合 CancellationToken）

如何定义和返回 IAsyncEnumerable？

最常用方式是使用 async yield return 语法（需方法返回 IAsyncEnumerable，且标记为 async）：

示例：模拟异步分页获取用户

public async IAsyncEnumerable<User> GetUsersAsync(int pageSize = 10, [EnumeratorCancellation] CancellationToken ct = default)
{
    int page = 0;
    while (true)
    {
        var users = await _apiClient.GetPageAsync(page++, pageSize, ct).ConfigureAwait(false);
        if (users.Length == 0) break;
<pre class="brush:php;toolbar:false;">    foreach (var user in users)
    {
        // 每次 yield return 都可被 await foreach 暂停等待
        yield return user;
    }
}

}

注意：
– 方法签名必须是

async IAsyncEnumerable<t></t>

，不能是

Task<iasyncenumerable>></iasyncenumerable>

；
–

[EnumeratorCancellation]

是可选但推荐的特性，让调用方传入的 CancellationToken 能自动注入到 yield return 的执行上下文中；
– 不要在 yield return 外部 await 长时间操作（否则会阻塞整个流），应在每次 yield 前完成必要 await。

如何安全消费 IAsyncEnumerable？

使用

await foreach

（C# 8+），它会自动处理异步枚举器的创建、移动、释放和异常传播：

await foreach (var user in GetUsersAsync(20, cancellationToken))
{
    Process(user); // 同步处理
    await SaveToDbAsync(user); // 也可 await 异步操作
}

关键点：
– 必须在 async 方法内使用，且外层方法需标记为 async；
– 支持直接传入 CancellationToken（会被传递到底层 yield 方法）；
– 若在循环中抛出异常，会自动调用 DisposeAsync() 清理资源（前提是底层实现了 IAsyncDisposable）；
– 不支持 LINQ 查询语法（如 .Where()、.Select()），但可使用 System.Linq.Async（需 NuGet 包

Microsoft.Bcl.AsyncInterfaces

或

System.Linq.Async

）。

常见误区与建议

别包装成 Task：返回 Task 就失去了流式优势，消费者必须 await 完才拿到枚举器 避免在 yield return 中做 CPU 密集型工作：这会阻塞异步流线程，考虑用 Task.Run 分离，但要权衡调度开销 谨慎共享状态：多个 await foreach 并发消费同一 IAsyncEnumerable 实例时，行为未定义（多数实现不支持重入），应确保每个消费方获得独立流实例 注意取消时机：CancellationToken 在每次 MoveNextAsync() 时检查，若某次 yield 返回后立刻取消，后续不会执行 —— 但当前正在 await 的操作仍可能继续运行，需在内部主动检查 ct.IsCancellationRequested

基本上就这些。IAsyncEnumerable 不复杂但容易忽略其“流式”本质——它不是异步版的 List，而是一条可暂停、可取消、低内存占用的数据流水线。