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