XYS.Worker 3.0.0

XYS.Worker

后台任务服务组件：基于 BlockingCollection 的生产者-消费者线程池，提供入队接口 Handler、抽象消费方法 Handle、异常兜底钩子 OnError 与优雅停机 Stop。

• 目标框架：net8.0 / net462 / netcoreapp3.1 / netstandard2.0 / netstandard2.1
• 依赖：XYS（同解决方案项目引用）

快速使用

1. 定义工作数据

复用内置的 WorkData（键值参数字典，默认已初始化），或实现 IWorkData 自定义结构：

using XYS.Worker;

// 方式 A：直接用 WorkData
var data = new WorkData();
data.KeyParams["patientId"] = "P00001";
data.KeyParams["reportId"]  = 123L;

// 方式 B：自定义
public class LabPrintWorkData : IWorkData
{
    public string ReportId { get; set; }
    public int    Copies   { get; set; }
}

2. 继承 BaseWorker 实现消费者

using System;
using XYS.Worker;

public sealed class LabPrintWorker : BaseWorker
{
    public LabPrintWorker(int workerCount)
    {
        WorkerCount = workerCount;                // 消费线程数
        LoggerName  = "LabPrintWorker";           // 用于线程名与 Trace 前缀
        ActualType  = typeof(LabPrintWorker);     // 可选：供反射/日志使用
        InitWorker();                             // 启动线程池
    }

    protected override void Handle(IWorkData data)
    {
        var wd = (WorkData)data;
        string reportId = (string)wd.KeyParams["reportId"];
        // ... 打印逻辑
    }

    // 可选：接入项目日志系统（默认走 System.Diagnostics.Trace）
    protected override void OnError(IWorkData data, Exception ex)
    {
        // 例如：LogManager.GetLogger(LoggerName).Error(ex);
        base.OnError(data, ex);
    }
}

3. 生产者入队

_worker.Handler(data);   // data 为 null 或 Worker 已停止时静默丢弃

4. 优雅停机

宿主进程停止时（Windows Service OnStop / Topshelf WhenStopped / IIS 应用退出 / ASP.NET Core IHostApplicationLifetime.ApplicationStopping）显式调用：

_worker.Stop();                            // 默认最多等待 5 秒
_worker.Stop(TimeSpan.FromSeconds(30));    // 自定义超时

Stop 语义：停止入队 → 消费完队列剩余项 → 超时后取消。重复调用无副作用。

关键契约

3.0.0 变更说明

• 目标框架增 net8.0，移除已 EOL 的 netcoreapp2.0
• 依赖从 NuGet 包 XYS 2.1.0.9 改为同解决方案的 ProjectReference，避免版本漂移
• 消费循环由 ConcurrentQueue + Thread.Sleep(1000) 轮询改为 BlockingCollection.GetConsumingEnumerable：空闲无 1 秒延迟，无线程空转
• Handle 异常不再杀消费者线程：单条数据的业务异常走 OnError，其他数据继续处理
• 新增 Stop(TimeSpan?) 支持优雅停机
• 构造函数初始化内部字段，消除子类忘记初始化导致的 NRE
• InitWorker / Stop 幂等，重复调用安全
• 破坏性变更：移除 protected ConcurrentQueue<IWorkData> RequestQueue 与 protected List<Thread> ThreadPool 属性（封装为 private）。若外部子类曾直接读写这两个成员，需改用 Handler 入队、Handle 消费的官方入口

建议

• WorkerCount 按业务量设置：I/O 密集型（打印、HTTP、数据库）可设 CPU 核数的 2~4 倍；CPU 密集型接近核数即可
• OnError 尽量接入项目日志：默认 Trace 在生产环境很少被采集
• Handle 内部尽量短平快：长耗时任务应拆分或换成异步 IO，避免单条数据长时间占用消费者线程