为什么需要 [EnumeratorCancellation]？
在使用 C# 编写异步迭代器时，您可能会遇到如下警告：
warning CS8425: 异步迭代器“TestConversationService.ChatStreamed(IReadOnlyList<ChatMessage>, ChatCompletionOptions, CancellationToken)”具有一个或多个类型为 "CancellationToken" 的参数，但它们都未用 "EnumeratorCancellation" 属性修饰，因此将不使用所生成的 "IAsyncEnumerable<>.GetAsyncEnumerator" 中的取消令牌参数。
看到这样的警告，您可能会困惑：究竟需要在异步迭代器的方法参数上添加 [EnumeratorCancellation] 属性吗？如果不添加，会有什么区别？ 让我们深入探讨一下这个问题，揭示其背后的真相。
正常调用时，[EnumeratorCancellation] 的影响
如果您只是简单地在异步迭代器方法中传递一个普通的 CancellationToken，无论是否使用 [EnumeratorCancellation]，方法的行为似乎并没有显著区别。例如：
public async IAsyncEnumerable<int> GenerateNumbersAsync(CancellationToken cancellationToken = default)
{for (int i = 0; i < 10; i++){cancellationToken.ThrowIfCancellationRequested();yield return i;await Task.Delay(1000, cancellationToken);}
}public async Task ConsumeNumbersAsync()
{CancellationTokenSource cts = new CancellationTokenSource();Task cancelTask = Task.Run(async () =>{await Task.Delay(3000);cts.Cancel();});try{await foreach (var number in GenerateNumbersAsync(cts.Token)){Console.WriteLine(number);}}catch (OperationCanceledException){Console.WriteLine("枚举已被取消");}await cancelTask;
}
输出如下：
0
1
2
枚举已被取消
在上述代码中，即使没有使用 [EnumeratorCancellation]，取消令牌 cts.Token 依然会生效，导致迭代过程被取消。这可能会让开发者误以为 [EnumeratorCancellation] 没有实际作用，进而引发更多的困惑。
揭开真相：生产者与消费者的职责分离
实际上，[EnumeratorCancellation] 的核心作用在于 实现生产者与消费者的职责分离。具体来说：
-
生产者（即提供数据的异步迭代方法）专注于数据的生成和响应取消请求，不关心取消请求的来源或何时取消。
-
消费者（即使用数据的部分）负责控制取消逻辑，独立地决定何时取消整个迭代过程。
通过这种设计，生产者不需要知道取消请求是由谁或何时发起的，简化了生产者的设计，同时赋予消费者更大的控制权。这不仅提高了代码的可维护性和可复用性，还避免了取消逻辑的混乱。
示例说明
下面通过一个示例，直观地展示 [EnumeratorCancellation] 如何实现职责分离。
1. 定义异步迭代器方法
using System;
using System.Collections.Generic;
using System.Runtime.CompilerServices;
using System.Threading;
using System.Threading.Tasks;public class DataProducer
{public async IAsyncEnumerable<int> ProduceData([EnumeratorCancellation] CancellationToken cancellationToken = default){int i = 0;while (true){cancellationToken.ThrowIfCancellationRequested();Console.WriteLine($"[Iterator] 生成数字: {i}");yield return i++;await Task.Delay(1000, cancellationToken); // 模拟数据生成延迟}}
}
在这个 DataProducer 类中，ProduceData 方法使用 [EnumeratorCancellation] 标注了 cancellationToken 参数。这意味着，当消费者通过 WithCancellation 传递取消令牌时，编译器会自动将该取消令牌传递给 ProduceData 方法的 cancellationToken 参数。
2. 定义消费者方法
using System;
using System.Threading;
using System.Threading.Tasks;public class DataConsumer
{public async Task ConsumeDataAsync(IAsyncEnumerable<int> producer){using CancellationTokenSource cts = new CancellationTokenSource();// 在5秒后发出取消请求_ = Task.Run(async () =>{await Task.Delay(5000);cts.Cancel();Console.WriteLine("[Trigger] 已发出取消请求");});try{// 通过 WithCancellation 传递取消令牌await foreach (var data in producer.WithCancellation(cts.Token)){Console.WriteLine($"[Consumer] 接收到数据: {data}");}}catch (OperationCanceledException){Console.WriteLine("[Consumer] 数据接收已被取消");}}
}
在 DataConsumer 类中，ConsumeDataAsync 方法创建了一个 CancellationTokenSource，并在5秒后取消它。通过 WithCancellation 方法，将取消令牌传递给 ProduceData 方法。这样，消费者完全控制了取消逻辑，而生产者只需响应取消请求。
3. 执行示例
public class Program
{public static async Task Main(string[] args){var producer = new DataProducer();var consumer = new DataConsumer();await consumer.ConsumeDataAsync(producer.ProduceData());}
}
预期输出：
[Iterator] 生成数字: 0
[Consumer] 接收到数据: 0
[Iterator] 生成数字: 1
[Consumer] 接收到数据: 1
[Iterator] 生成数字: 2
[Consumer] 接收到数据: 2
[Iterator] 生成数字: 3
[Consumer] 接收到数据: 3
[Iterator] 生成数字: 4
[Consumer] 接收到数据: 4
[Trigger] 已发出取消请求
[Consumer] 数据接收已被取消
在5秒后，取消请求被触发，迭代器检测到取消并抛出 OperationCanceledException，导致迭代过程被中断。请注意DataConsumer在接收生产出来的数据 IAsyncEnumerable<int> 时，已经错过了在生产函数中传入 cancellationToken 的机会，但作为消费者，仍然可以通过 .WithCancellation 方法进行优雅取消。
这展示了生产者与消费者如何通过 WithCancellation 和 [EnumeratorCancellation] 实现职责分离，消费者能够独立地控制取消逻辑，而生产者只需响应取消请求。
CancellationToken 与 WithCancellation 同时作用时的行为
那么，如果在异步迭代器方法中同时传递了 CancellationToken 参数，并通过 WithCancellation 指定了不同的取消令牌，取消操作会听哪个的？还是都会监听？
结论是：两者都会生效，只要其中任意一个取消令牌被触发，迭代器都会检测到取消请求并中断迭代过程。这取决于方法内部如何处理多个取消令牌。
示例演示
以下是一个详细的示例，展示当同时传递 CancellationToken 参数和使用不同的 WithCancellation 时的行为。
1. 定义异步迭代器方法
using System;
using System.Collections.Generic;
using System.Runtime.CompilerServices;
using System.Threading;
using System.Threading.Tasks;public class EnumeratorCancellationDemo
{// 异步迭代器方法，接受两个 CancellationTokenpublic async IAsyncEnumerable<int> GenerateNumbersAsync([EnumeratorCancellation] CancellationToken cancellationToken,CancellationToken externalCancellationToken = default){int i = 0;try{while (true){// 检查两个取消令牌cancellationToken.ThrowIfCancellationRequested();externalCancellationToken.ThrowIfCancellationRequested();Console.WriteLine($"[Iterator] 生成数字: {i}");yield return i++;// 模拟异步操作await Task.Delay(1000, cancellationToken);}}finally{Console.WriteLine("[Iterator] 迭代器已退出。");}}
}
2. 定义消费者方法
public class Program
{static async Task Main(string[] args){Console.WriteLine("启动枚举取消示例...\n");var demo = new EnumeratorCancellationDemo();// 测试1: 先取消方法参数Console.WriteLine("=== 测试1: 先取消方法参数 ===\n");await TestCancellation(demo, cancelParamFirst: true);// 测试2: 先取消 WithCancellationConsole.WriteLine("\n=== 测试2: 先取消 WithCancellation ===\n");await TestCancellation(demo, cancelParamFirst: false);Console.WriteLine("\n演示结束。");Console.ReadLine();}static async Task TestCancellation(EnumeratorCancellationDemo demo, bool cancelParamFirst){using CancellationTokenSource ctsParam = new CancellationTokenSource();using CancellationTokenSource ctsWith = new CancellationTokenSource();if (cancelParamFirst){// 第一个取消任务：3秒后取消 ctsParam_ = Task.Run(async () =>{await Task.Delay(3000);ctsParam.Cancel();Console.WriteLine("[Trigger] 已取消 ctsParam (方法参数)");});// 第二个取消任务：5秒后取消 ctsWith_ = Task.Run(async () =>{await Task.Delay(5000);ctsWith.Cancel();Console.WriteLine("[Trigger] 已取消 ctsWith (WithCancellation)");});}else{// 第一个取消任务：3秒后取消 ctsWith_ = Task.Run(async () =>{await Task.Delay(3000);ctsWith.Cancel();Console.WriteLine("[Trigger] 已取消 ctsWith (WithCancellation)");});// 第二个取消任务：5秒后取消 ctsParam_ = Task.Run(async () =>{await Task.Delay(5000);ctsParam.Cancel();Console.WriteLine("[Trigger] 已取消 ctsParam (方法参数)");});}try{// 传递 ctsWith.Token 作为方法参数，并通过 WithCancellation 传递 ctsWith.Tokenawait foreach (var number in demo.GenerateNumbersAsync(ctsWith.Token, ctsParam.Token).WithCancellation(ctsWith.Token)){Console.WriteLine($"[Consumer] 接收到数字: {number}");}}catch (OperationCanceledException ex){string reason = ex.CancellationToken == ctsWith.Token ? "WithCancellation" : "方法参数";Console.WriteLine($"[Iterator] 迭代器检测到取消。原因: {reason}");Console.WriteLine("[Consumer] 枚举已被取消。");}}
}
3. 运行示例并观察结果
启动程序后，控制台输出可能如下所示：
启动枚举取消示例...=== 测试1: 先取消方法参数 ===[Iterator] 生成数字: 0
[Consumer] 接收到数字: 0
[Iterator] 生成数字: 1
[Consumer] 接收到数字: 1
[Iterator] 生成数字: 2
[Consumer] 接收到数字: 2
[Trigger] 已取消 ctsParam (方法参数)
[Iterator] 迭代器已退出。
[Iterator] 迭代器检测到取消。原因: 方法参数
[Consumer] 枚举已被取消。=== 测试2: 先取消 WithCancellation ===[Iterator] 生成数字: 0
[Consumer] 接收到数字: 0
[Iterator] 生成数字: 1
[Consumer] 接收到数字: 1
[Trigger] 已取消 ctsWith (WithCancellation)
[Iterator] 生成数字: 2
[Consumer] 接收到数字: 2
[Trigger] 已取消 ctsWith (WithCancellation)
[Iterator] 迭代器已退出。
[Iterator] 迭代器检测到取消。原因: WithCancellation
[Consumer] 枚举已被取消。演示结束。
解释：
-
测试1：先取消方法参数 (
ctsParam)- 在第3秒时，
ctsParam被取消。 - 迭代器检测到
externalCancellationToken被取消，抛出OperationCanceledException。 - 终止迭代过程，即使
ctsWith还未被取消。
- 在第3秒时，
-
测试2：先取消
WithCancellation(ctsWith)- 在第3秒时，
ctsWith被取消。 - 迭代器检测到
cancellationToken被取消，抛出OperationCanceledException。 - 终止迭代过程，即使
ctsParam还未被取消。
- 在第3秒时，
关键点：
-
独立生效：无论是通过方法参数传递的
CancellationToken还是通过WithCancellation传递的CancellationToken，只要其中一个被取消，迭代器就会响应取消请求并终止迭代。 -
取消顺序无关紧要：不论先取消哪一个取消令牌，迭代器都会正确响应取消请求。取消操作的顺序不会影响最终的效果。
总结
通过上述示例，我们深入了解了 [EnumeratorCancellation] 的必要性及其在异步迭代器中的核心作用。简要回顾：
-
消除警告：使用
[EnumeratorCancellation]可以消除 Visual Studio 提示的警告，确保取消请求能够正确传递给异步迭代器方法。 -
职责分离：它实现了生产者与消费者的职责分离，使生产者专注于数据生成，消费者控制取消逻辑，从而提升代码的可维护性和可复用性。
-
灵活的取消机制：即使同时传递多个取消令牌，只要任意一个被取消，迭代器就会终止，提供了灵活而强大的取消控制能力。
.NET 的这些强大功能为开发者提供了极大的便利和灵活性，使得编写高效、可维护的异步代码变得更加轻松与自信。让我们为 .NET 的强大功能自豪，并在实际开发中善加利用这些工具，构建出更优秀的软件解决方案！
