Tuesday, March 15, 2011

New in Quartz.Net 2.0–New Job File Format

NOTE: I'm now blogging at http://jayvilalta.com/blog and not updating this blog anymore. For information on the latest version of Quartz.Net, visit me there.

The xml format for the quartz_jobs.xml file has changed in Quartz.Net 2.0. This is a breaking change, so you won’t be able to use your existing jobs file with the new version of Quartz.Net without updating it to the 2.0 format. If you’re interested in the details of what can be configured in this file, I would recommend looking at the xsd file that defines the schema for the file. The xsd file that defines the new file format can be downloaded directly from the source code repository, here.
Today I’m going to provide a sample quartz_jobs.xml file in the new format and walk you through the creation of the file. Alternatively, you can take a look at the default file (that will be) provided with the Quartz.Net 2.0 distribution, here.
The new file format starts off with the following root element:
<job-scheduling-data xmlns="http://quartznet.sourceforge.net/JobSchedulingData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0">

Right after the root node, our configuration file has two elements, which we will describe in detail below:
  1. The <processing-directives> element

  2. The <schedule> element

The <processing-directives> Element

The processing directives element contains two elements. The first element, <pre-processing-commands> is used to run commands prior to adding jobs and triggers to the scheduler. I’m not going to spend much time going over these in detail, but here is a list of the commands available to you:

  • delete the jobs in a group
  • delete the triggers in a group
  • delete a job
  • delete a trigger
If you find yourself in need of help with these elements, leave a comment and I will write a follow-up post.

The second element, <processing-directives>, lets you specify how the xml file is to be processed. Here you will find a familiar configuration setting (from Quartz.net 1.0), the <overwrite-existing-data> element. Setting this element’s value to true will replace any jobs currently scheduled with the new schedule given in the xml file (true is the default setting!). The <ignore-duplicates> element is the other element allowed under the <processing-directives> element.

The <schedule> Element

The <schedule> element is where we describe the jobs and triggers that we want to schedule. This section has also changed its format. Now, instead of grouping jobs and triggers under an element, jobs and triggers are all specified at the same level, and are not grouped under the job element, as was the case in version 1.0.

Under the <schedule> element, we can have <job> and <trigger> elements, which are the building blocks that we use to put together our schedule. Let’s take a look at these elements now.

The <job> Element

The <job> element is used to describe the IJob that we want the scheduler to execute. Job details are specified by using the following elements:
  • <name>
  • <group>
  • <description>
  • <job-type>
  • <durable>
  • <recover>
  • <job-data-map>
All of these elements serve the same purpose as they did in version 1 and, except for the job-data-map, they’re all simple types, so I’m not going to go into great detail here either. If you need a little more help with these, leave a comment and I’ll expand on the explanation as needed.

The job-data-map, being a complex element, supports an <entry> element inside. The <entry> element has <key> and <value> elements inside, which describe the job property to be added to the job map.

The <trigger> Element
The <trigger> element is used to describe the trigger that we want to attach to a given job. The xml file loader plugin supports 3 types of triggers:
  • simpleTriggerType
  • cronTriggerType
  • calendarIntervalTriggerType
These three trigger types are based on the abstractTriggerType, which has the following common elements:
  • <name>
  • <group>
  • <description>
  • <job-name>
  • <job-group>
  • <priority>
  • <calendar-name>
  • <job-data-map>
In addition to the elements listed above, each trigger type supports some additional elements. These additional elements are used to set parameters that are not common across all of the trigger types. The table below summarizes each of the trigger types and the elements they support.

Trigger Type Additional Elements
SimpleTrigger <misfire-instruction>,<repeat-count>,<repeat-interval>
CronTrigger <misfire-instruction>,<cron-expression>,<time-zone>
CalendarIntervalTrigger <misfire-instruction>,<repeat-interval>,<repeat-interval-unit>

I’m not going to go into detail here either. This is already a pretty long post, so if anybody needs more information leave me a comment and I will write a follow-up post.

Putting It All Together

At this point we’ve described all of the elements that are necessary to describe a job in the new Quartz.Net 2.0 xml format. To put it all together, here are the contents of a sample quartz_jobs.xml file that you can use as a guide:

<?xml version="1.0" encoding="UTF-8"?>

<!-- This file contains job definitions in schema version 2.0 format -->

<job-scheduling-data xmlns="http://quartznet.sourceforge.net/JobSchedulingData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0">
      <description>Sample job for Quartz Server</description>
      <job-type>Quartz.Job.NativeJob, Quartz</job-type>
        <description>Simple trigger example</description>

This is a working example of a quartz_jobs.xml file that schedules a NativeJob using a SimpleTrigger. This example also shows how to configure the <job-data-map> to pass configuration information to the job.

I hope this post helps you in building a job configuration file for Quartz.Net 2.0.


Javafun said...

Hi J

I recently found this open source project, but I don't quite understand what's different between window service to Quartz?

J said...

This is a C# port of the Java Quartz scheduler. A windows service is just a way of running the scheduler as a standalone service.

gsogol said...

Playing around with the 2.0 version. Excellent work! Having trouble configuring the jobs.xml. I need a sample of the configuration file that contains a simple job that needs to run once a night, persisted with SQL Server store and recoverable. Any help is appreciated.

Nikunj Panchal said...
This comment has been removed by the author.
Nikunj Panchal said...

Hi J

I want to know about that How can we define the prerocessing commands in an xml file. I define such as following, but that job still executing. please let me know


Nikunj Panchal said...

Execute the preprocessing commands still execute the job


Nikunj Panchal said...
This comment has been removed by the author.
hfrmobile said...

Both URLs provided in the original post: 404 ...

Btw, why does the "Quartz.NET-2.0.1.zip" package not contain a new version of the config file?

J said...

Thanks for letting me know about the broken links. I've updated them. I can't really explain why the distribution might not include an example file since it's not my project. When I wrote the article there was no official package yet, but I believe the latest release does include a very slim job configuration file, with a sample job in it. It's in Quartz.Server project though, not in the Quartz.dll package.

Anonymous said...

Hi! I´m learning to use quartz .net and i have a very important doubt. When i develop a job in visual studio 2010, with the triggers and the definition of the scheduler, how can i translate the code to xml to put it on quartz_jobs if i want to build a windows service? Thank a lot!!!

Shreya said...

Hi, when i run this code i am having problem in running this. It is not working at all when i set it with Quartz.net scheduler .Socan you please give a detailed explanation such that the jb runs