C# IAsyncEnumerable WithCancellation 使用教程

WithCancellation 是 IAsyncEnumerable 的扩展方法，仅挂载 CancellationToken 而不主动触发取消，是否生效取决于底层实现是否响应该 token。

WithCancellation 是什么，它真能取消 IAsyncEnumerable 的迭代吗？

WithCancellation 是 IAsyncEnumerable 的一个扩展方法，定义在 System.Linq.Async（.NET 5+ 内置，无需额外包），但它**不主动触发取消**，只是把 CancellationToken “挂载”到后续的异步枚举操作上。真正是否响应取消，取决于底层实现——比如 yield return 中是否检查 token，或底层数据源（如 EF Core 查询、HttpClient 流式响应）是否支持取消。

什么时候必须用 WithCancellation？常见误用场景

你不需要在每次遍历前都加 WithCancellation。只有当以下情况之一成立时才需要：

• 你调用的是第三方 IAsyncEnumerable 方法，且它内部未绑定 token（例如某些自定义 yield 实现漏了 await Task.Delay(..., token)）
• 你在组合多个异步 LINQ 操作（如 Where、Select、Take）后，想确保整个链路可被统一取消
• 你显式调用 GetAsyncEnumerator() 并手动控制枚举器生命周期（此时必须传 token 给构造器，WithCancellation 是更简洁的替代）

常见误用：在 await foreach 前无脑加 .WithCancellation(token)，但底层根本没做 token 检查——结果是取消信号被静默忽略，超时后仍卡住。

如何验证 WithCancellation 是否生效？关键检查点

不能只看代码有没有写 WithCancellation，要确认三点：

• 底层 yield return 或 await 调用是否传入了该 token（例如 await stream.ReadAsync(buffer, token)，不是 ReadAsync(buffer)）
• 如果用了 EF Core，确保查询是异步的（AsAsyncEnumerable()），且数据库驱动支持取消（SQL Server 支持，SQLite 部分版本不支持）
• 避免在 yield return 块中做同步阻塞操作（如 Thread.Sleep），这会绕过 token 检查

简单验证示例：

await foreach (var item in GetItemsAsync().WithCancellation(cancellationToken))
{
    // 如果 GetItemsAsync 内部用了 await Task.Delay(1000, cancellationToken)
    // 则 cancellation 可中断等待；否则不会
}

替代方案：不用 WithCancellation 也能安全取消

多数现代框架已默认集成 token 传递，直接传参比后期挂载更可靠：

• EF Core 查询：用 ToListAsync(cancellationToken) 或 AsAsyncEnumerable() + 手动 await foreach，token 由上下文自动传播
• 自定义生成器：在 async IAsyncEnumerable 方法签名中直接接收 CancellationToken，并在每个 await 后显式检查（token.ThrowIfCancellationRequested()）
• HttpClient 流式响应：用 GetStreamAsync(uri, cancellationToken) 获取流，再用 Stream.ReadAsync 传同一 token

真正容易被忽略的是：即使用了 WithCancellation，如果枚举器已经进入下一个 MoveNextAsync 调用但尚未 await，取消信号可能要等到下一次 await 才生效——这不是 bug，而是异步状态机的固有延迟。