Quartz.NET 3.x 迁移指南：从旧版本平滑升级的关键要点-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00428/article/details/148465507

Quartz.NET 3.x 迁移指南：从旧版本平滑升级的关键要点

quartznet Quartz Enterprise Scheduler .NET 项目地址: https://gitcode.com/gh_mirrors/qu/quartznet

前言

Quartz.NET 作为.NET平台最强大的任务调度框架之一，在3.0版本进行了重大架构调整。本文将从技术架构演进的角度，系统性地讲解从2.x升级到3.x版本需要注意的关键变化点，帮助开发者顺利完成迁移工作。

核心架构变化概述

Quartz.NET 3.x最大的变革是全面拥抱异步编程模型和.NET Core支持：

异步化改造：所有API接口都基于Task异步模型重构
跨平台支持：新增对.NET Core的完整支持
模块化拆分：核心功能被拆分为更细粒度的NuGet包

包结构调整详解

3.x版本对原先单一的Quartz包进行了模块化拆分：

核心调度功能：仍保留在主包中
常用作业类型：迁移到Quartz.Jobs包
- 目录扫描作业(DirectoryScanJob)
- 文件扫描作业(FileScanJob)
- 原生作业(NativeJob)
- 邮件发送作业(SendMailJob)
插件功能：迁移到Quartz.Plugins包
- XML调度配置插件(XMLSchedulingDataProcessorPlugin)

迁移建议：检查项目中是否使用了这些功能，并添加对应的NuGet包引用。

数据库兼容性说明

数据库模式

2.6版本的数据库模式完全兼容3.0版本
无需执行额外的数据库迁移脚本

特殊日历处理

如果使用了HolidayCalendar并以二进制格式存储在数据库中：

需要先用2.4+版本加载这些日历
然后重新存储它们
这将转换为不依赖C5库的新序列化格式

线程模型重大变更

3.x版本重构了线程池实现：

SimpleThreadPool移除：现在统一使用DefaultThreadPool
基于CLR线程池：作业执行现在使用.NET自带的线程池
线程数限制保留：ThreadCount参数仍然有效，但实际是控制CLR线程池的队列大小
线程优先级移除：不再支持设置线程优先级

异步API适配指南

调度器接口变更

所有调度器操作现在都是异步的：

// 旧版同步代码
scheduler.ScheduleJob(job, trigger);
scheduler.Start();
scheduler.Shutdown(true);

// 新版异步代码
await scheduler.ScheduleJob(job, trigger);
await scheduler.Start();
await scheduler.Shutdown(waitForJobsToComplete: true);

作业接口变更

作业执行方法现在返回Task：

public class MyJob : IJob
{
    // 旧版同步Execute
    public void Execute(IJobExecutionContext context) { /*...*/ }
    
    // 新版异步Execute
    public async Task Execute(IJobExecutionContext context)
    {
        await SomeAsyncOperation();
    }
}

无异步代码的处理：如果作业中没有异步操作，可以直接返回已完成的任务：

public Task Execute(IJobExecutionContext context)
{
    DoSyncWork();
    return Task.CompletedTask; // .NET 4.6+
}

已移除的接口

IInterruptableJob：改用CancellationToken机制

public async Task Execute(IJobExecutionContext context)
{
    while(!context.CancellationToken.IsCancellationRequested)
    {
        // 工作逻辑
    }
}

IStatefulJob：改用特性标注方式

[DisallowConcurrentExecution]
[PersistJobDataAfterExecution]
public class StatefulJob : IJob { /*...*/ }

作业存储序列化配置

3.x版本要求显式指定序列化方式：

| 序列化类型 | 适用场景 | 配置值 | 需要添加的NuGet包 | |------------|----------|--------|-------------------| | 二进制 | 兼容旧系统 | "binary" | 无 | | JSON(推荐) | 新项目 | "newtonsoft" | Quartz.Serialization.Json |

配置示例：

var props = new NameValueCollection
{
    ["quartz.jobStore.type"] = "Quartz.Impl.AdoJobStore.JobStoreTX, Quartz",
    ["quartz.serializer.type"] = "newtonsoft" // 或 "binary"
};