C#怎么使用TaskCompletionSource_C#手动控制Task完成教程【高级】

TaskCompletionSource：异步世界的桥梁，而非手动开关

先明确一个核心认知：TaskCompletionSource 的定位，并非一个让你随心所欲“手动完成”Task的工具。它的真正使命，是充当一座桥梁，将那些老旧的、非awaitable的异步模式（比如回调、事件、甚至是原生的Win32 API）无缝接入现代async/await的生态系统。很多开发者从“手动完成”这个角度入手，第一步就走错了。

为什么“new完就SetResult”是危险的起点？

一个常见的误解是：创建一个TaskCompletionSource，立刻设置结果，然后把它的Task返回去。这听起来很直接，对吧？但问题恰恰出在这里。这样做会导致Task瞬间进入“已完成但未被观察”的状态。想象一下，调用方还没来得及对这个Task进行await或.Wait()，它就已经悄悄完成了。

这种“无人认领”的Task一旦在后续抛出异常（即使是通过SetException设置的），就会触发UnobservedTaskException事件。在.NET 6及更高版本中，这个异常的默认行为相当严厉——直接终止进程。代价不可谓不大。

来看看典型的错误写法：

var tcs = new TaskCompletionSource();
tcs.SetResult(42); // 危险！Task瞬间完成，但调用链路可能还没准备好观察它
return tcs.Task; // 返回的这个Task，状态已经尘埃落定

正确的思路是什么？关键在于控制权交接。你必须确保Task的生命周期由它的使用者（即调用方）来主导。SetResult或SetException的调用时机，应当发生在调用方已经开始等待（即执行了await）之后，或者至少能有绝对的把握保证这个完成状态会被观察到。

典型场景剖析：将事件转换为异步方法（以按钮点击为例）

这是TaskCompletionSource最常用，也最容易踩坑的场景。比如，你想把WPF或WinForms中按钮的Click事件变成一个可以await的方法。技术实现本身不难，真正的难点在于管理背后的复杂性：谁负责取消？如何设置超时？事件重复触发怎么办？

• 取消支持并非自动：TaskCompletionSource本身不感知CancellationToken。你必须手动监听Token的取消请求，并在回调中调用tcs.TrySetCanceled()。
• 谨防事件轰炸：用户可能连续快速点击按钮。虽然TrySetResult()方法在首次成功后，后续调用会返回false，但事件处理器仍然会被执行。因此，通常需要在成功设置结果后，立即注销事件处理器，避免不必要的逻辑运行。
• 同步上下文的陷阱：在UI线程中使用时，Task的延续（continuation）默认可能会被派发回UI线程执行，如果处理不当可能引发死锁。一个重要的技巧是：在构造TaskCompletionSource时传入TaskCreationOptions.RunContinuationsAsynchronously参数，这可以强制后续延续在线程池线程执行，有效避免在WinForms/WPF等环境中陷入死锁。

来看一个相对完整的WPF示例：

public static Task WaitForClickAsync(this Button button, CancellationToken ct = default)
{
    // 关键：指定异步延续选项
    var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);

    RoutedEventHandler handler = null;
    handler = (s, e) =>
    {
        // 只有第一次点击会成功设置结果
        if (tcs.TrySetResult(true))
            button.Click -= handler; // 成功后立即解绑，防止重复处理
    };

    // 注册取消令牌的回调
    void CancelHandler(object _, EventArgs __) => tcs.TrySetCanceled(ct);
    ct.Register(CancelHandler);

    button.Click += handler;
    return tcs.Task;
}

SetException的学问：异常类型必须严格匹配

TaskCompletionSource.SetException()方法接受一个或一组Exception对象。这里有个隐蔽的坑：如果你传入的是一个AggregateException，那么它在内部又会被包装一层。最终，调用方在await时捕获到的异常，会是AggregateException.InnerException，而不是你最初抛出的那个异常实例。

• 直接传递原始异常：tcs.SetException(new InvalidOperationException("xxx"))。这样最清晰。
• 避免不必要的包装：不要传入new AggregateException(ex)，除非你确实希望调用方看到外层的AggregateException包装。
• 处理多个异常：如果确实需要传递多个异常（这种情况较少），应使用new Exception[] { ex1, ex2 }作为参数，而不是一个AggregateException。

否则，调用方精心编写的异常捕获逻辑可能会失效：try { await MyMethod(); } catch (InvalidOperationException e) { ... } 可能根本抓不到预期的异常。

别忘了状态检查：TrySetXXX的返回值至关重要

SetResult、SetException、SetCanceled这些方法是“强制设置”，如果Task已经处于完成状态，再次调用它们会直接抛出InvalidOperationException。而它们的“Try”版本（TrySetResult, TrySetException, TrySetCanceled）则不同，它们返回一个bool值，指示此次设置是否成功——这是实现线程安全操作的关键。

• 跨线程场景必用Try版本：所有涉及跨线程、事件驱动、回调的场景，一律使用TrySetXXX系列方法。不要假设“此刻Task肯定还没完成”。
• 正确处理竞争：如果TrySetXXX返回false，意味着Task已经被其他执行路径完成了（例如触发了超时或取消）。此时，你不应该再执行任何原本计划在“设置完成”后进行的副作用操作（比如释放资源、注销事件）。这些清理逻辑，应该放在Task完成后的延续（continuation）中，或者使用Task.ContinueWith(..., TaskContinuationOptions.OnlyOnRanToCompletion)来条件执行。
• 以返回值驱动逻辑：不要在调用TrySetXXX后就直接执行业务逻辑，除非你检查了它的返回值并确认是true。

说到底，使用TaskCompletionSource的高级挑战，从来不是“如何让一个Task完成”这个动作本身。真正的难点在于：谁拥有这个Task的“所有权”？完成时机是否与并发的超时、取消路径存在竞争？最终暴露给调用方的异常语义是否清晰、可预测？理清这些所有权和生命周期的边界，才是避开深坑的关键所在。