为什么需要[EnumeratorCancellation]？

为什么需要 [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
{
    // 异步迭代器方法，接受两个 CancellationToken
    public 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: 先取消 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("[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.Token
			await 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. 测试1：先取消方法参数 (ctsParam)

   • 在第3秒时，ctsParam 被取消。
   • 迭代器检测到 externalCancellationToken 被取消，抛出 OperationCanceledException。
   • 终止迭代过程，即使 ctsWith 还未被取消。

2. 测试2：先取消 WithCancellation (ctsWith)

   • 在第3秒时，ctsWith 被取消。
   • 迭代器检测到 cancellationToken 被取消，抛出 OperationCanceledException。
   • 终止迭代过程，即使 ctsParam 还未被取消。

关键点：

• 独立生效：无论是通过方法参数传递的 CancellationToken 还是通过 WithCancellation 传递的 CancellationToken，只要其中一个被取消，迭代器就会响应取消请求并终止迭代。

• 取消顺序无关紧要：不论先取消哪一个取消令牌，迭代器都会正确响应取消请求。取消操作的顺序不会影响最终的效果。

总结

通过上述示例，我们深入了解了 [EnumeratorCancellation] 的必要性及其在异步迭代器中的核心作用。简要回顾：

• 消除警告：使用 [EnumeratorCancellation] 可以消除 Visual Studio 提示的警告，确保取消请求能够正确传递给异步迭代器方法。

• 职责分离：它实现了生产者与消费者的职责分离，使生产者专注于数据生成，消费者控制取消逻辑，从而提升代码的可维护性和可复用性。

• 灵活的取消机制：即使同时传递多个取消令牌，只要任意一个被取消，迭代器就会终止，提供了灵活而强大的取消控制能力。

.NET 的这些强大功能为开发者提供了极大的便利和灵活性，使得编写高效、可维护的异步代码变得更加轻松与自信。让我们为 .NET 的强大功能自豪，并在实际开发中善加利用这些工具，构建出更优秀的软件解决方案！