IAsyncEnumerable是C# 8.0引入的异步流类型，适用于按需异步生成多个数据项的场景，支持await foreach消费、内存友好、可取消且响应及时。
IAsyncEnumerableawait foreach 消费，每个元素可独立 await，内存友好且响应及时。
什么时候该用 IAsyncEnumerable？
当你需要以下任意一种能力时，IAsyncEnumerable 是比 List
- 数据源本身是异步的（如数据库分页查询、HTTP 流式响应、文件分块读取）
- 不想阻塞线程，也不愿把全部结果缓存在内存里（尤其数据量大或生成耗时）
- 消费者希望边接收边处理，而不是等所有数据就绪才开始（降低端到端延迟）
- 需要在迭代中途取消（配合 CancellationToken）
如何定义和返回 IAsyncEnumerable？
最常用方式是使用 async yield return 语法（需方法返回 IAsyncEnumerable
示例：模拟异步分页获取用户
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，而是一条可暂停、可取消、低内存占用的数据流水线。
