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

IAsyncEnumerable 是 C# 8.0 引入的异步流类型，适用于按需异步生成多个数据项的场景，支持 await foreach 消费、内存友好、可取消且响应及时。

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，而是一条可暂停、可取消、低 内存占用 的数据流水线。