c# backgroundworker 用法

BackgroundWorker 是 WinForms 专用的 UI 安全异步协调器，DoWork 中不可访问 UI 控件，须通过 ReportProgress 触发 ProgressChanged 更新界面；取消需手动检查 CancellationPending 并设 e.Cancel = true；ProgressChanged 和 RunWorkerCompleted 自动在 UI 线程执行。

BackgroundWorker 不是“后台线程封装”，而是 WinForms 专用的 UI 安全异步协调器——它只在 Windows Forms 里真正好用，且必须配合事件驱动模式。

DoWork 里不能碰任何 UI 控件

这是最常踩的坑：你在 backgroundWorker1_DoWork 里写 label1.Text = "正在计算..."，程序不报错但会抛 InvalidOperationException: 跨线程操作无效。因为 DoWork 运行在独立工作线程，而 WinForms 控件只能由创建它的 UI 线程访问。

• ✅ 正确做法：用 ReportProgress(int percentage, object userState) 发消息，让 ProgressChanged 事件在 UI 线程中更新控件
• ❌ 错误写法：textBox1.Text = "done" 或 progressBar1.Value++ 出现在 DoWork 中
• ⚠️ 注意：e.Argument 是唯一安全传参入口，类型为 object，需手动强转（如 (int)e.Argument）

取消操作不是“立刻停止”，而是协作式退出

CancelAsync() 只是设个标记，真正中断逻辑靠你手写检查 bw.CancellationPending 并主动退出循环或 return。

• ✅ 必须在耗时操作内部定期检查：if (bw.CancellationPending) { e.Cancel = true; return; }
• ✅ e.Cancel = true 是给 RunWorkerCompleted 事件用的判断依据，不设它就无法区分“完成”和“取消”
• ❌ 不检查 CancellationPending → 点取消按钮毫无反应，直到任务自然结束
• ⚠️ Sleep、IO、数据库查询等阻塞调用中，CancellationPending 不会自动生效，需改用支持取消的 API（如 HttpClient.GetAsync(..., cancellationToken)）

ProgressChanged 和 RunWorkerCompleted 是 UI 线程安全的

这两个事件由 BackgroundWorker 自动封送到 UI 线程，你可以放心操作所有控件。

• ✅ 在 ProgressChanged 中直接更新：progressBar1.Value = e.ProgressPercentage、label1.Text = (string)e.UserState
• ✅ 在 RunWorkerCompleted 中统一收尾：if (e.Cancelled) {...}、if (e.Error != null) {...}、resultLabel.Text = e.Result?.ToString()
• ⚠️ e.Result 是你在 DoWork 中赋值的 e.Result = "OK"，类型为 object，记得判空和转型
• ⚠️ 如果 DoWork 抛异常，不会崩掉 UI，但会进 RunWorkerCompleted 的 e.Error 分支，不处理就会静默失败

private void backgroundWorker1_DoWork(object sender, DoWorkEventArgs e)
{
    var bw = sender as BackgroundWorker;
    int max = (int)e.Argument;
    for (int i = 0; i <= max; i++)
    {
        if (bw.CancellationPending)
        {
            e.Cancel = true;
            return;
        }
        bw.ReportProgress(i * 100 / max, $"第 {i} 步");
        Thread.Sleep(50); // 模拟耗时
    }
    e.Result = $"总计 {max} 次";
}
private void backgroundWorker1_ProgressChanged(object sender, ProgressChangedEventArgs e)
{
progressBar1.Value = e.ProgressPercentage;
statusLabel.Text = e.UserState?.ToString();
}
private void backgroundWorker1_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e)
{
if (e.Cancelled)
statusLabel.Text = "已取消";
else if (e.Error != null)
statusLabel.Text = "出错了：" + e.Error.Message;
else
statusLabel.Text = "结果：" + e.Result?.ToString();
}

真正难的不是写这几行代码，而是理解它背后的设计契约：BackgroundWorker 不帮你管理线程生命周期，也不替你处理并发，它只保证三件事——DoWork 在后台跑、Progress/Completed 回 UI 线程、Cancellation 是合作而非强制。一旦离开 WinForms（比如用在 WPF 或控制台），这套机制就失效了，该换 Task + async/await 了。