Job Scheduler (任务调度器)

约 601 字大约 2 分钟

2026-05-20

概述 (Overview)

JobScheduler 是 UniCon 任务调度系统的核心管理器。它基于 Quartz.NET 进行了高级封装，旨在为南向驱动点位交互、北向 HTTP 接口联动及系统后台自愈提供高可靠、精细化的定时任务执行管理能力。

它解决了以下问题：

提供完整的定时任务生命周期管理 (CRUD)。
支持任务的秒级高精度 CRON 触发。
统计当前处于活动执行状态的任务数量，以便系统性能监控。
全面支持 ASP.NET Core 的依赖注入 (DI) 和最小 Web API。

使用方法 (Usage)

通过 IServiceCollection 的一键扩展方法 AddUniConJobs() 完成容器注入，随后可以通过构造函数注入 JobScheduler 进行调用。

// 1. 在 Program.cs 中注入
builder.Services.AddUniConJobs();

// 2. 构造函数注入调用
public class MyService
{
    private readonly JobScheduler _scheduler;
    public MyService(JobScheduler scheduler)
    {
        _scheduler = scheduler;
    }
}

参数说明 (Parameters)

`ScheduleJobAsync<T>` 参数

参数名	类型	说明	是否必填	默认值
jobId	`string`	任务的唯一标识 ID	是	-
cronExpression	`string`	标准 Quartz CRON 触发表达式	是	-
data	`JobDataMap`	伴随任务运行的外部参数映射	否	`null`

UpdateJobAsync 参数

参数名	类型	说明	是否必填	默认值
jobId	`string`	任务的唯一标识 ID	是	-
cronExpression	`string`	新的标准 Quartz CRON 触发表达式	是	-
data	`JobDataMap`	新的外部参数映射，如果不为 null 则更新	否	`null`

返回值 (Returns)

GetExecutingJobsCountAsync 返回值

类型	说明
`Task<int>`	返回当前处于运行状态的任务总数。

GetJobsAsync 返回值

类型	说明
`Task<List<JobInfo>>`	返回所有已调度任务元数据及其运行状态的列表。

UpdateJobAsync / DeleteJobAsync 返回值

类型	说明
`Task<bool>`	表示该操作是否成功执行（如果找不到指定的 Job，则返回 `false`）。

使用示例 (Examples)

示例1：动态注册并安排一个 HttpJob 任务

var jobData = new JobDataMap
{
    [JobDataKeys.HttpUrl] = "https://api.unicontroller.com/heartbeat",
    [JobDataKeys.HttpMethod] = "GET"
};

await jobScheduler.ScheduleJobAsync<HttpJob>(
    jobId: "ControllerHeartbeat",
    cronExpression: "0 0/5 * * * ?", // 每 5 分钟执行一次
    data: jobData
);

示例2：查询所有任务并在控制台打印

var jobs = await jobScheduler.GetJobsAsync();
foreach (var job in jobs)
{
    Console.WriteLine($"Job: {job.JobId}, Type: {job.JobType}, Status: {job.Status}");
}

示例3：更新已有任务的触发时间与参数

var newJobData = new JobDataMap
{
    [JobDataKeys.HttpUrl] = "https://api.unicontroller.com/v2/heartbeat",
    [JobDataKeys.HttpMethod] = "POST"
};

bool isUpdated = await jobScheduler.UpdateJobAsync(
    jobId: "ControllerHeartbeat",
    cronExpression: "0/30 * * * * ?", // 缩短为每 30 秒执行一次
    data: newJobData
);