C#使用Quartz.NET详细讲解

Quartz.NET是一个开源的作业调度框架，是OpenSymphony 的 Quartz API的.NET移植，它用C#写成，可用于winform和asp.net应用中。它提供了巨大的灵活性而不牺牲简单性。你能够用它来为执行一个作业而创建简单的或复杂的调度。它有很多特征，如：数据库支持，集群，插件，支持cron-like表达式等等。

你曾经需要应用执行一个任务吗？这个任务每天或每周星期二晚上11：30，或许仅仅每个月的最后一天执行。一个自动执行而无须干预的任务在执行过程中如果发生一个严重错误，应用能够知到其执行失败并尝试重新执行吗？你和你的团队是用.NET编程吗？如果这些问题中任何一个你回答是，那么你应该使用Quartz.NET调度器。 Quartz.NET允许开发人员根据时间间隔（或天）来调度作业。它实现了作业和触发器的多对多关系，还能把多个作业与不同的触发器关联。整合了 Quartz.NET的应用程序可以重用来自不同事件的作业，还可以为一个事件组合多个作业.

Quartz.NET入门

要开始使用 Quartz.NET，需要用 Quartz.NET API 对项目进行配置。步骤如下：

1. 到http://quartznet.sourceforge.net/download.html下载 Quartz.NET API，最新版本是0.6

2. 解压缩Quartz.NET-0.6.zip 到目录，根据你的项目情况用Visual Studio 2003或者Visual Studio 2005打开相应工程，编译。你可以将它放进自己的应用中。Quartz.NET框架只需要少数的第三方库，并且这些三方库是必需的，你很可能已经在使用这些库了。

3. 在Quartz.NET有一个叫做quartz.properties的配置文件，它允许你修改框架运行时环境。缺省是使用Quartz.dll里面的quartz.properties文件。当然你可以在应用程序配置文件中做相应的配置，下面是一个配置文件示例：

?xml version="1.0" encoding="utf-8" ?>

<configuration>

<configSections>

<section name="quartz" type="System.Configuration.NameValueSectionHandler, System, Version=1.0.5000.0,Culture=neutral, PublicKeyToken=b77a5c561934e089"/>

</configSections>

<quartz>

<add key="quartz.scheduler.instanceName" value="ExampleDefaultQuartzScheduler"/>

<add key="quartz.threadPool.type" value="Quartz.Simpl.SimpleThreadPool, Quartz"/>

<add key="quartz.threadPool.threadCount" value="10"/>

<add key="quartz.threadPool.threadPriority" value="2"/>

<add key="quartz.jobStore.misfireThreshold" value="60000"/>

<add key="quartz.jobStore.type" value="Quartz.Simpl.RAMJobStore, Quartz"/>

</quartz>

</configuration>

为了方便读者，我们使用Quartz.NET的例子代码来解释，现在来看一下 Quartz API 的主要组件。

调度器和作业

Quartz.NET框架的核心是调度器。调度器负责管理Quartz.NET应用运行时环境。调度器不是靠自己做所有的工作，而是依赖框架内一些非常重要的部件。Quartz不仅仅是线程和线程管理。为确保可伸缩性，Quartz.NET采用了基于多线程的架构。 启动时，框架初始化一套worker线程，这套线程被调度器用来执行预定的作业。这就是Quartz.NET怎样能并发运行多个作业的原理。Quartz.NET依赖一套松耦合的线程池管理部件来管理线程环境。作业是一个执行任务的简单.NET类。任务可以是任何C#\VB.NET代码。只需你实现Quartz.IJob接口并且在出现严重错误情况下抛出JobExecutionException异常即可。

IJob接口包含唯一的一个方法Execute()，作业从这里开始执行。一旦实现了IJob接口和Execute ()方法，当Quartz.NET确定该是作业运行的时候，它将调用你的作业。Execute()方法内就完全是你要做的事情。

通过实现 Quartz.IJob接口，可以使 .NET 类变成可执行的。清单 1 提供了 Quartz.IJob作业的一个示例。这个类用一条非常简单的输出语句覆盖了 Execute(JobExecutionContext context) 方法。这个方法可以包含我们想要执行的任何代码（所有的代码示例都基于 Quartz.NET 0.6 ，它是编写这篇文章时的稳定发行版）。

清单 1：作业

using System;

using System.Collections.Generic;

using System.Text;

using Common.Logging;

using Quartz;

namespace QuartzBeginnerExample

{

publicclass SimpleQuartzJob : IJob

{

privatestatic ILog _log = LogManager.GetLogger(typeof(SimpleQuartzJob));

///<summary>

/// Called by the <see cref="IScheduler" /> when a

///<see cref="Trigger" /> fires that is associated with

/// the <see cref="IJob" />.

///</summary>

publicvirtualvoid Execute(JobExecutionContext context)

{

try { // This job simply prints out its job name and the // date and time that it is running string jobName = context.JobDetail.FullName;

_log.Info("Executing job: "+ jobName +" executing at "+ DateTime.Now.ToString("r"));

}

catch (Exception e)

{

_log.Info("--- Error in job!");

JobExecutionException e2 =new JobExecutionException(e); // this job will refire immediately e2.RefireImmediately =true; throw e2;

}

}

}

}

请注意，Execute 方法接受一个 JobExecutionContext 对象作为参数。这个对象提供了作业实例的运行时上下文。特别地，它提供了对调度器和触发器的访问，这两者协作来启动作业以及作业的 JobDetail 对象的执行。Quartz.NET 通过把作业的状态放在 JobDetail 对象中并让 JobDetail 构造函数启动一个作业的实例，分离了作业的执行和作业周围的状态。JobDetail 对象储存作业的侦听器、群组、数据映射、描述以及作业的其他属性。

作业和触发器:

Quartz.NET设计者做了一个设计选择来从调度分离开作业。Quartz.NET中的触发器用来告诉调度程序作业什么时候触发。框架提供了一把触发器类型，但两个最常用的是SimpleTrigger和CronTrigger。SimpleTrigger为需要简单打火调度而设计。

典型地，如果你需要在给定的时间和重复次数或者两次打火之间等待的秒数打火一个作业，那么SimpleTrigger适合你。另一方面，如果你有许多复杂的作业调度，那么或许需要CronTrigger。

CronTrigger是基于Calendar-like调度的。当你需要在除星期六和星期天外的每天上午10点半执行作业时，那么应该使用CronTrigger。正如它的名字所暗示的那样，CronTrigger是基于Unix克隆表达式的。

Cron表达式被用来配置CronTrigger实例。Cron表达式是一个由7个子表达式组成的字符串。每个子表达式都描述了一个单独的日程细节。这些子表达式用空格分隔，分别表示：

1. Seconds 秒

2. Minutes 分钟

3. Hours 小时

4. Day-of-Month 月中的天

5. Month 月

6. Day-of-Week 周中的天

7. Year (optional field) 年（可选的域）

一个cron表达式的例子字符串为"0 0 12 ? * WED",这表示“每周三的中午12：00”。

单个子表达式可以包含范围或者列表。例如：前面例子中的周中的天这个域（这里是"WED"）可以被替换为"MON-FRI", "MON, WED, FRI"或者甚至"MON-WED,SAT"。

通配符（'*'）可以被用来表示域中“每个”可能的值。因此在"Month"域中的*表示每个月，而在Day-Of-Week域中的*则表示“周中的每一天”。

所有的域中的值都有特定的合法范围，这些值的合法范围相当明显，例如：秒和分域的合法值为0到59，小时的合法范围是0到23，Day-of-Month中值得合法凡范围是0到31，但是需要注意不同的月份中的天数不同。月份的合法值是0到11。或者用字符串JAN,FEB MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV 及DEC来表示。Days-of-Week可以用1到7来表示（1=星期日）或者用字符串SUN, MON, TUE, WED, THU, FRI 和SAT来表示.

'/'字符用来表示值的增量，例如, 如果分钟域中放入'0/15'，它表示“每隔15分钟，从0开始”，如果在份中域中使用'3/20'，则表示“小时中每隔20分钟，从第3分钟开始”或者另外相同的形式就是'3,23,43'。

'?'字符可以用在day-of-month及day-of-week域中，它用来表示“没有指定值”。这对于需要指定一个或者两个域的值而不需要对其他域进行设置来说相当有用。

'L'字符可以在day-of-month及day-of-week中使用，这个字符是"last"的简写，但是在两个域中的意义不同。例如，在day-of-month域中的"L"表示这个月的最后一天，即，一月的31日，非闰年的二月的28日。如果它用在day-of-week中，则表示"7"或者"SAT"。但是如果在day-of-week域中，这个字符跟在别的值后面，则表示"当月的最后的周XXX"。例如："6L" 或者 "FRIL"都表示本月的最后一个周五。当使用'L'选项时，最重要的是不要指定列表或者值范围，否则会导致混乱。

'W' 字符用来指定距离给定日最接近的周几（在day-of-week域中指定）。例如：如果你为day-of-month域指定为"15W",则表示“距离月中15号最近的周几”。

'#'表示表示月中的第几个周几。例如：day-of-week域中的"6#3" 或者 "FRI#3"表示“月中第三个周五”。

作为一个例子，下面的Quartz.NET克隆表达式将在星期一到星期五的每天上午10点15分执行一个作业。

0 15 10 ? * MON-FRI

下面的表达式

0 15 10 ? * 6L 2007-2010

将在2007年到2010年的每个月的最后一个星期五上午10点15分执行作业。你不可能用SimpleTrigger来做这些事情。你可以用两者之中的任何一个，但哪个跟合适则取决于你的调度需要。

清单 2 中的 SimpleTrigger 展示了触发器的基础：

清单2 SimpleTriggerRunner.cs

using System;

using System.Collections.Generic;

using System.Text;

using Common.Logging;

using Quartz;

using Quartz.Impl;

namespace QuartzBeginnerExample

{

publicclass SimpleTriggerRunner

{

publicvirtualvoid Run()

{

ILog log = LogManager.GetLogger(typeof(SimpleTriggerExample));

log.Info("------- Initializing -------------------");

// First we must get a reference to a scheduler

ISchedulerFactory sf =new StdSchedulerFactory();

IScheduler sched = sf.GetScheduler();

log.Info("------- Initialization Complete --------");

log.Info("------- Scheduling Jobs ----------------");

// jobs can be scheduled before sched.start() has been called // get a "nice round" time a few seconds in the future...

);

// job1 will only fire once at date/time "ts"

JobDetail job =new JobDetail("job1", "group1", typeof(SimpleJob));

SimpleTrigger trigger =new SimpleTrigger("trigger1", "group1");

// set its start up time

trigger.StartTime = ts;

// set the interval, how often the job should run (10 seconds here)

;

// set the number of execution of this job, set to 10 times. // It will run 10 time and exhaust.

;

// schedule it to run!

DateTime ft = sched.ScheduleJob(job, trigger);

)));

log.Info("------- Starting Scheduler ----------------");

// All of the jobs have been added to the scheduler, but none of the jobs // will run until the scheduler has been started

sched.Start();

log.Info("------- Started Scheduler -----------------");

log.Info("------- Waiting 30 seconds... --------------");

try {

// wait 30 seconds to show jobs

);

// executing...

}

catch (ThreadInterruptedException) { }

log.Info("------- Shutting Down ---------------------");

sched.Shutdown(true);

log.Info("------- Shutdown Complete -----------------");

// display some stats about the schedule that just ran

SchedulerMetaData metaData = sched.GetMetaData();

log.Info(string.Format("Executed {0} jobs.", metaData.NumJobsExecuted));

} } }

清单 2 开始时实例化一个 SchedulerFactory，获得此调度器。就像前面讨论过的，创建 JobDetail 对象时，它的构造函数要接受一个 Job 作为参数。顾名思义，SimpleTrigger 实例相当原始。在创建对象之后，设置几个基本属性以立即调度任务，然后每 10 秒重复一次，直到作业被执行 100 次。

还有其他许多方式可以操纵 SimpleTrigger。除了指定重复次数和重复间隔，还可以指定作业在特定日历时间执行，只需给定执行的最长时间或者优先级（稍后讨论）。执行的最长时间可以覆盖指定的重复次数，从而确保作业的运行不会超过最长时间。

清单 3 显示了 CronTrigger 的一个示例。请注意 SchedulerFactory、Scheduler 和 JobDetail 的实例化，与 SimpleTrigger 示例中的实例化是相同的。在这个示例中，只是修改了触发器。这里指定的 cron 表达式（“0/5 * * * * ?”）安排任务每 5 秒执行一次。

清单3 CronTriggerRunner.cs

); // executing... } catch (ThreadInterruptedException) { } log.Info("------- Shutting Down ---------------------"); sched.Shutdown(true); log.Info("------- Shutdown Complete -----------------"); SchedulerMetaData metaData = sched.GetMetaData(); log.Info(string.Format("Executed {0} jobs.", metaData.NumJobsExecuted)); } } }

如上所示，只用作业和触发器，就能访问大量的功能。但是，Quartz 是个丰富而灵活的调度包，对于愿意研究它的人来说，它还提供了更多功能。下一节讨论 Quartz 的一些高级特性。

作业管理和存储

作业一旦被调度，调度器需要记住并且跟踪作业和它们的执行次数。如果你的作业是30分钟后或每30秒调用，这不是很有用。事实上，作业执行需要非常准确和即时调用在被调度作业上的Execute()方法。Quartz通过一个称之为作业存储（JobStore）的概念来做作业存储和管理。

有效作业存储

Quartz提供两种基本作业存储类型。第一种类型叫做RAMJobStore，它利用通常的内存来持久化调度程序信息。这种作业存储类型最容易配置、构造和运行。Quartz.net缺省使用的就是RAMJobStore。对许多应用来说，这种作业存储已经足够了。

然而，因为调度程序信息是存储在被分配在内存里面，所以，当应用程序停止运行时，所有调度信息将被丢失。如果你需要在重新启动之间持久化调度信息，则将需要第二种类型的作业存储。为了修正这个问题，Quartz.NET 提供了 AdoJobStore。顾名思义，作业仓库通过 ADO.NET把所有数据放在数据库中。数据持久性的代价就是性能降低和复杂性的提高。它将所有的数据通过ADO.NET保存到数据库可中。它的配置要比RAMJobStore稍微复杂，同时速度也没有那么快。但是性能的缺陷不是非常差，尤其是如果你在数据库表的主键上建立索引。

设置AdoJobStore

AdoJobStore几乎可以在任何数据库上工作，它广泛地使用Oracle, MySQL, MS SQLServer2000, HSQLDB, PostreSQL 以及 DB2。要使用AdoJobStore，首先必须创建一套Quartz使用的数据库表，可以在Quartz 的database\tables找到创建库表的SQL脚本。如果没有找到你的数据库类型的脚本，那么找到一个已有的，修改成为你数据库所需要的。需要注意的一件事情就是所有Quartz库表名都以QRTZ_作为前缀（例如：表"QRTZ_TRIGGERS",及"QRTZ_JOB_DETAIL"）。实际上，可以你可以将前缀设置为任何你想要的前缀，只要你告诉AdoJobStore那个前缀是什么即可（在你的Quartz属性文件中配置）。对于一个数据库中使用多个scheduler实例，那么配置不同的前缀可以创建多套库表，十分有用。

一旦数据库表已经创建，在配置和启动AdoJobStore之前，就需要作出一个更加重要的决策。你要决定在你的应用中需要什么类型的事务。如果不想将scheduling命令绑到其他的事务上，那么你可以通过对JobStore使用JobStoreTX来让Quartz帮你管理事务（这是最普遍的选择）。

最后的疑问就是如何建立获得数据库联接的数据源（DataSource）。Quartz属性中定义数据源是通过提供所有联接数据库的信息，让Quartz自己创建和管理数据源。

要使用AdoJobStore（假定使用StdSchedulerFactory），首先需要设置Quartz配置中的quartz.jobStore.type属性为Quartz.Impl.AdoJobStore.JobStoreTX, Quartz。

配置 Quartz使用 JobStoreTx

quartz.threadPool.type = Quartz.Simpl.SimpleThreadPool, Quartz

下一步，需要为JobStore 选择一个DriverDelegate ， DriverDelegate负责做指定数据库的所有ADO.NET工作。StdADO.NETDelegate是一个使用vanilla" ADO.NET代码（以及SQL语句）来完成工作的代理。如果数据库没有其他指定的代理，那么就试用这个代理。只有当使用StdADO.NETDelegate发生问题时，我们才会使用数据库特定的代理（这看起来非常乐观。其他的代理可以在Quartz.Impl.AdoJobStor命名空间找到。）。其他的代理包括PostgreSQLDelegate ( 专为PostgreSQL 7.x)。

一旦选择好了代理，就将它的名字设置给AdoJobStore。

配置AdoJobStore 使用DriverDelegate

quartz.threadPool.type = Quartz.Simpl.SimpleThreadPool, Quartz

接下来，需要为JobStore指定所使用的数据库表前缀（前面讨论过）。

配置AdoJobStore的数据库表前缀

quartz.jobStore.tablePrefix = QRTZ

然后需要设置JobStore所使用的数据源。必须在Quartz属性中定义已命名的数据源，比如，我们指定Quartz使用名为"default"的数据源（在配置文件的其他地方定义）。

配置 AdoJobStore使用数据源源的名字

properties["quartz.jobStore.dataSource"] = "default"

最后，需要配置数据源的使用的Ado.net数据提供者和数据库连接串，数据库连接串是标准的Ado.net 数据库连接的连接串。数据库提供者是关系数据库同Quartz.net之间保持低耦合的数据库的连接提供者.

配置AdoJobStore使用数据源源的数据库连接串和数据库提供者

quartz.dataSource.default.connectionString = Server=(local);Database=quartz;Trusted_Connection=True;

quartz.dataSource.default.provider= SqlServer-11

目前Quartz.net支持的以下数据库的数据提供者：

l SqlServer-11 - SQL Server driver for .NET Framework 1.1

l SqlServer-20 - SQL Server driver for .NET Framework 2.0

l OracleClient-20 - Microsoft's Oracle Driver (comes bundled with .NET Framework)

l OracleODP-20 - Oracle's Oracle Driver

l MySql-10 - MySQL Connector/.NET v. 1.0.7

l MySql-109 - MySQL Connector/.NET v. 1.0.9

l MySql-50 - MySQL Connector/.NET v. 5.0 (.NET 2.0)

l MySql-51 - MySQL Connector/:NET v. 5.1 (.NET 2.0)

l SQLite1044 - SQLite ADO.NET 2.0 Provider v. 1.0.44 (.NET 2.0)

如果Scheduler非常忙（比如，执行的任务数量差不多和线程池的数量相同，那么你需要正确地配置DataSource的连接数量为线程池数量。为了指示AdoJobStore所有的JobDataMaps中的值都是字符串，并且能以“名字-值”对的方式存储而不是以复杂对象的序列化形式存储在BLOB字段中，应设置 quartz.jobStore.usePropertiess配置参数的值为"true"(这是缺省的方式)。这样做，从长远来看非常安全，这样避免了对存储在BLOB中的非字符串的序列化对象的类型转换问题。

清单 4 展示了 AdoJobStore提供的数据持久性。就像在前面的示例中一样，先从初始化 SchedulerFactory 和 Scheduler 开始。然后，不再需要初始化作业和触发器，而是要获取触发器群组名称列表，之后对于每个群组名称，获取触发器名称列表。请注意，每个现有的作业都应当用 Scheduler. RescheduleJob () 方法重新调度。仅仅重新初始化在先前的应用程序运行时终止的作业，不会正确地装载触发器的属性。

清单4 AdoJobStoreRunner.cs

)); _log.Info("------- Shutting Down --------------------"); sched.Shutdown(); _log.Info("------- Shutdown Complete ----------------"); } publicvoid Run() { bool clearJobs =true; bool scheduleJobs =true; AdoJobStoreRunner example =new AdoJobStoreRunner(); example.Run(clearJobs, scheduleJobs); } }

结束语

Quartz.net 作业调度框架所提供的 API 在两方面都表现极佳：既全面强大，又易于使用。Quartz 可以用于简单的作业触发，也可以用于复杂的 Ado.net持久的作业存储和执行。

示例下载 ：www.cnblogs.com/Files/shanyou/QuartzBeginnerExample.zip  基于 Quartz.net 的示例 （C#代码 ）   QuartzBeginnerExample.zip    324KB

获取Quartz.net ：quartznet.sourceforge.net/download.html：.NET应用程序的开放源码作业调度解决方案