Quartz.NET 3.x 快速入门指南：从安装到第一个定时任务

前言

Quartz.NET 是一个功能强大且灵活的开源作业调度框架，专为 .NET 平台设计。它可以帮助开发者在应用程序中实现各种定时任务和后台作业。本文将带你快速了解 Quartz.NET 3.x 的基本使用方法，从安装配置到创建第一个定时任务。

环境准备

在开始使用 Quartz.NET 之前，你需要确保已安装以下环境：

• .NET Core 3.1 或更高版本/.NET Framework 4.6.1 或更高版本
• Visual Studio 2019 或更高版本（推荐）

安装 Quartz.NET

Quartz.NET 提供了两种安装方式：

1. 通过 NuGet 安装（推荐）

这是最简单的安装方式，适合大多数开发场景：

1. 在 Visual Studio 中，右键点击项目中的"引用"
2. 选择"管理 NuGet 程序包"
3. 在搜索框中输入"Quartz"
4. 选择 Quartz.NET 并点击安装

或者使用 NuGet 命令行：

Install-Package Quartz

如果需要 JSON 序列化支持，可以额外安装：

Install-Package Quartz.Serialization.Json

2. 通过 ZIP 压缩包安装

这种方式适合需要查看源代码或进行二次开发的场景：

1. 下载 Quartz.NET 的 ZIP 压缩包
2. 解压到本地目录
3. 在项目中引用 bin 目录下的 Quartz.dll

基础配置

Quartz.NET 提供了灵活的配置方式，主要有两种：

1. 使用流畅 API 配置

这种方式适合在代码中直接配置调度器：

var properties = new NameValueCollection();

IScheduler scheduler = await SchedulerBuilder.Create(properties)
    .UseDefaultThreadPool(x => x.MaxConcurrency = 5)
    .UsePersistentStore(x =>
    {
        x.UseProperties = true;
        x.UseClustering();
        x.UseSqlServer("your_connection_string");
        x.UseSystemTextJsonSerializer();
    })
    .BuildScheduler();

2. 使用配置文件

Quartz.NET 支持多种配置文件格式：

• quartz.config 文件
• appsettings.json (仅限 .NET Core/NET5+)
• YourApplication.exe.config (仅限完整 .NET 框架)

一个基本的 quartz.config 配置示例：

quartz.scheduler.instanceName = MyScheduler
quartz.jobStore.type = Quartz.Simpl.RAMJobStore, Quartz
quartz.threadPool.maxConcurrency = 3

创建第一个定时任务

下面我们创建一个简单的控制台应用程序，演示如何使用 Quartz.NET 调度任务。

1. 创建作业类

首先定义一个简单的作业类：

public class HelloJob : IJob
{
    public async Task Execute(IJobExecutionContext context)
    {
        await Console.Out.WriteLineAsync("Hello from Quartz.NET!");
    }
}

2. 配置并启动调度器

using System;
using System.Threading.Tasks;
using Quartz;
using Quartz.Impl;

class Program
{
    static async Task Main(string[] args)
    {
        // 创建调度器工厂
        StdSchedulerFactory factory = new StdSchedulerFactory();
        IScheduler scheduler = await factory.GetScheduler();

        // 启动调度器
        await scheduler.Start();

        // 定义作业
        IJobDetail job = JobBuilder.Create<HelloJob>()
            .WithIdentity("job1", "group1")
            .Build();

        // 定义触发器（每10秒执行一次）
        ITrigger trigger = TriggerBuilder.Create()
            .WithIdentity("trigger1", "group1")
            .StartNow()
            .WithSimpleSchedule(x => x
                .WithIntervalInSeconds(10)
                .RepeatForever())
            .Build();

        // 调度作业
        await scheduler.ScheduleJob(job, trigger);

        // 等待60秒
        await Task.Delay(TimeSpan.FromSeconds(60));

        // 关闭调度器
        await scheduler.Shutdown();
    }
}

3. 添加日志输出

为了更好地了解调度器的运行情况，我们可以添加简单的日志输出：

private class ConsoleLogProvider : ILogProvider
{
    public Logger GetLogger(string name)
    {
        return (level, func, exception, parameters) =>
        {
            if (level >= LogLevel.Info && func != null)
            {
                Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] [{level}] {func()}", parameters);
            }
            return true;
        };
    }
    
    // 其他必要方法实现...
}

// 在Main方法开始处添加
LogProvider.SetCurrentLogProvider(new ConsoleLogProvider());

进阶配置

1. 使用数据库持久化

在生产环境中，建议使用数据库持久化作业信息：

.UsePersistentStore(x =>
{
    x.UseProperties = true;
    x.UseClustering();
    x.UseSqlServer("Server=.;Database=QuartzDB;Trusted_Connection=True;");
    x.UseJsonSerializer();
})

2. 配置集群

Quartz.NET 支持集群部署，确保在配置中启用集群功能：

quartz.jobStore.clustered = true
quartz.scheduler.instanceId = AUTO

常见问题解答

Q: 作业没有按预期执行？ A: 检查调度器是否已启动，触发器配置是否正确，以及是否有足够的线程可用。

Q: 如何确保作业在应用重启后继续执行？ A: 使用数据库持久化存储（如 SQL Server）而不是默认的内存存储。

Q: 如何动态添加或修改作业？ A: 可以通过 IScheduler 接口的 ScheduleJob、RescheduleJob 等方法实现。

总结

通过本文，你已经学会了：

1. 如何安装 Quartz.NET
2. 基本的配置方法
3. 创建并调度简单的作业
4. 添加日志输出
5. 一些进阶配置选项

Quartz.NET 提供了丰富的功能和灵活的配置选项，可以满足各种复杂的调度需求。建议在实际项目中先从简单的配置开始，逐步探索更高级的功能。