Monday, May 25, 2009

Creating a Custom Job in Quartz.Net

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.

If you use Quartz.Net and you want to do anything other than run  a batch file, then chances are you’ll want to create a custom job. Fortunately, creating it is not hard at all. Let’s get started.
Here’s a quick rundown of what you need to do. First, you’ll need to add a reference to Quartz.dll in your project, Second, create a class that implements IJob. Third, put the code you want to run inside the Execute method. That’s it! That’s all you really need to create a custom job.
However, in order to get this job to execute, there are a couple more steps to follow and a few more things to be aware of, including some not-so-evident gotchas.
I’m going to assume that at this point, you have created your MyJob class and that it implements the IJob interface. Let’s talk  about what you need to do in addition to implementing the logic that you want your job to execute.
Handle Exceptions
You should wrap the code in the Execute method and handle any exceptions that you can. For exceptions that you cannot handle but that can be solved by running the job again, you should wrap your exception inside a JobExecutionException.
If you want the scheduler to try running the job again, then set the RefireImmediately property to true. Otherwise, set it to false. You also have other options, such as un-scheduling triggers, so take a look at the documentation for JobExecutionException.
If your job doesn’t know how to handle the exception that was thrown, then don’t catch it and let the scheduler handle it.
Deploy Your Custom Job
Deploying the custom job is as simple as copying the dll to the same folder where the Quartz.dll is. You can also deploy your dll in any manner that allows the runtime to locate the dll per the normal rules for dll resolution.
Beware of ConfigurationManager
Finally, I’d like to give you a heads up about using the ConfigurationManager to provide your job with configuration information. Don’t do it! It is best to include all the information that your job needs to execute in the job’s JobDataMap. The reason for this is simple. If you use ConfigurationManager and you are running Quartz.Net as a windows service, then the ConfigurationManager will try to look for configuration information in the Quartz.Net config file. If you are running Quartz.Net embedded inside your application, then this might not be an issue for you, but then again… it might.
Let’s wrap up this post by summarizing the steps needed to create a custom Quartz.Net job.
  1. Add a reference to Quartz.dll in your project.
  2. Create a class that implements IJob
  3. Implement the Execute method of the IJob interface.
  4. Catch exceptions and throw a JobExecutionException as needed.
  5. Copy the CustomJob dll to the same folder as Quartz.dll or somewhere that the runtime can locate it.
If you need more information, please let me know in the comments or read over documentation for IJob and for JobExcecutionException.