Scheduling Jobs Programmatically in Quartz.Net 1.0

This post is one of those back to basics posts and is inspired by a comment left by Jan on one of the Getting Started posts. Today we’ll take a look at how to schedule a job programmatically in Quartz.Net 1.0. I’ll follow up with a post on how to schedule a job programmatically in Quartz.Net 2.0 as well.

Scheduling Jobs in Quartz.Net

There are two ways you can schedule a job to run on Quartz.Net. The first way is to schedule it using the plugin that reads an xml file containing the job and scheduling information. If you want more information on how to schedule jobs using the xml plugin, take a look at this post.
You can also schedule jobs by interacting directly with the scheduler API. The Quartz.Net scheduler supports remote access via the .Net remoting facility, so this method of scheduling jobs is available to you regardless of whether the scheduler is running as a standalone windows service or whether it is embedded in your application. The remote scheduler does have some limitations, but we will not run into them while scheduling jobs. Let’s take a look at how we can schedule jobs using the scheduler API.

Scheduling Jobs via the Scheduler API

In a nutshell, these are the steps you would follow to schedule a job using the API:
  1. Get a reference to the scheduler object. How you do this will depend on whether you are running a standalone or embedded scheduler.
  2. Create a JobDetail object and set all the necessary properties. At a minimum you must set the Name, the Group and JobType. Please note that because the type of JobType is Type, the dll containing the JobType MUST be available to the code that is scheduling the job AS WELL as to the scheduler.
  3. Create a Trigger object (Trigger itself is an abstract class, so you will actually be creating one of these concrete types: SimpleTrigger, CronTrigger or NthIncludedDayTrigger) and set all the necessary properties. At a minimum you must set the Name, and the Group. The JobGroup and the JobName are also necessary as they are what links the JobDetail you created in the previous step with the Trigger you are creating now. However, you do not need to set these properties right now. Read on to step 4 to understand why.
  4. Call the ScheduleJob method on your scheduler object passing in your Trigger and your Job. If you call this overload of the ScheduleJob method, then the scheduler will link your trigger and your job, so there is no need for you to set the link explicitly.

Code Example

I’d like to close out this post with a code sample that implements the steps outlined above. 
public void ScheduleOneTimeJob(Type jobType, JobDataMap dataMap)
{
  string name = DateTime.Now.ToString("yyyyMMddHHmmss"));
  string group = "OneTimeJobs";
  // create job
  JobDetail jobDetail = new JobDetail(name, group, jobType);
  jobDetail.Description = "One time job.";
  jobDetail.JobDataMap = dataMap;
  
  // create trigger
  SimpleTrigger trigger = new SimpleTrigger();
  trigger.Name = name;
  trigger.Group = group;
  trigger.StartTimeUtc = DateTime.UtcNow;
  trigger.RepeatCount = 0;
  trigger.RepeatInterval = TimeSpan.Zero;
 
  // get reference to scheduler (remote or local) and schedule job
  GetScheduler().ScheduleJob(jobDetail, trigger);
}


This sample code demonstrates one way of creating and scheduling a job that runs once, immediately.


In Quartz.Net 2.0 the scheduler API has changed significantly, so we will cover that topic in another post.

            Continue Reading
          

        

        
        
        

        
        
        

          
          

            
How Does Quartz.Net Configuration Work?

            
            
In this post we will explain in great detail how the Quartz.Net scheduler loads its configuration upon startup. Since the scheduler configuration did not change between versions 1.0 and 2.0, the information here is applicable to both Quartz.Net versions.
In Quartz.Net, the StdSchedulerFactory is responsible for configuring the scheduler. When the Quartz.Net scheduler is started, the factory will try to automatically configure a scheduler by looking for configuration information in different places:
  • the hosting application’s configuration file 
  • a file specified in an environment variable 
  • the quartz.config file 
  • the embedded configuration file 
Configuring From the Hosting Application’s Configuration File
First, the factory will try to load the scheduler configuration from the <quartz> section of your application’s config file. If you are running Quartz.Net as a windows service, then the service’s configuration file will be used. This file (Quartz.Server.exe.config) can be found in the same folder as the server executable. If you are hosting the Quartz.Net scheduler in your web application, then the web.config file will be checked.
Configuring From A File Specified in an Environment Variable
If the factory was not able to load the quartz configuration section, then the second place it will check is the environment variables of the process. Specifically, the factory will check to see if the quartz.config environment variable has been defined. If such a variable exists and is not empty, the factory will try to load the configuration from whatever file is specified as the value of the variable. For example, let’s say that your configuration file is called myconfig.config. If you set the quartz.config environment variable equal to myconfig.config, then the scheduler will load the configuration information from the file named myconfig.config.
Configuring From the Quartz.config File
Let’s assume that so far, the factory has not been able to load the scheduler’s configuration. The next step that the factory will take is to try to load a file called quartz.config from the same directory where the hosting application’s assembly was loaded. In fact, this is the file that an out-of-the-box Quartz.Net server/service installation uses to configure itself. 
Configuring From the Embedded Configuration File
If all of the previous configuration options fail, then the factory falls back on loading the configuration file that is embedded in the quartz assembly. In case you’re curious, here are the configuration properties that are embedded in the assembly:
       Property        Value     
       quartz.scheduler.instanceName        DefaultQuartzScheduler     
       quartz.threadPool.type         Quartz.Simpl.SimpleThreadPool, Quartz     
       quartz.threadPool.threadCount         10     
       quartz.threadPool.threadPriority         Normal     
       quartz.jobStore.type         Quartz.Simpl.RAMJobStore, Quartz     
       quartz.jobStore.misfireThreshold         60000     
If after checking all of the above locations for configuration information, the factory was not able to configure the scheduler, then an exception is thrown. As you can probably gather from the previous paragraph, unless you actually change the quartz assembly, this configuration exception will not be raised, because a configuration file is already embedded in the quartz assembly by default.
One Final Step
You’d think that by now, the whole configuration process is finished and the scheduler has been configured successfully. Well, the default scheduler factory takes one last step before giving you the configured scheduler. 
Here’s what happens just after your configuration is loaded: if any of the configuration properties that you set in a configuration are also present in the environment variables, then the factory will overwrite them with the environment value. This the expected behavior. However, due to a bug, this does not work in Quartz.Net 1.0, but is fixed in Quartz.Net 2.0.

            Continue Reading
          

        

        
        
        

        
        
        

          
          

            
New in Quartz.Net 2.0-No More IStatefulJob

            
            
Welcome to the the third post of my New in Quartz.Net 2.0 series. 
Goodbye IStatefulJob
Yes, it’s true. In Quartz.Net 2.0 the IStatefulJob has been marked as obsolete. To be sure, it’s still available to use, but if you are using IStatefulJobs you should think about migrating them to use the new Quartz.Net 2.0 features. 
The Disallow Concurrent Execution Attribute
So how do I implement an IStatefulJob in Quartz.Net 2.0? Fortunately, it’s not very hard to do. You just need to mark your IJob with the new DisallowConcurrentExecutionAttribute. Any jobs that have this attribute set are only allowed to run one instance of the job at a time. Keep in mind that an instance is defined by a JobKey (job name and group combination), which means that if you have the same job type scheduled with a different job name or a different job group, you may get more than one instance of that type of job running at the same time.
The Persist Job Data After Execution Attribute
Seems simple enough so far? Well, it is! There is only one other thing to consider. If you want the scheduler to persist the job’s state between executions, you must also add the PersistJobDataAfterExecutionAttribute to the class. This attribute tells the scheduler that you would like for it store the job’s JobDataMap once it is finished executing. 
One Last Thing
While you can use each of these attributes separately, if you are going to use the PersistJobDataAfterExecutionAttribute to persist your job’s state, you should always use the DisallowConcurrentExecutionAttribute, because if you don’t, you might find that your job state is corrupted due to race conditions.

            Continue Reading
          

        

        
        
        

        
        
        

          
          

            
New in Quartz.Net 2.0–Directory Scan Job

            
            
This is the second post of the New in Quartz.Net 2.0 series. Today we will look at the DirectoryScanJob, which is a new job in Quartz.Net 2.0. 
The DirectoryScanJob is very similar to the FileScanJob, which is available in Quartz.Net 1.0. As you can probably tell from the names, the main difference between the two jobs is that the DirectoryScanJob scans for changes in… you quessed it… a directory , whereas the FileScanJob scans for changes in… yes, you guessed it again… a file. If you’re not familiar with the FileScanJob, don’t worry, we will look at the DirectoryScanJob in detail.
Introducing the DirectoryScanJob
First, let’s take a look at what the documentation says about this new job:
“Inspects a directory and compares whether any files' "last modified dates" have changed since the last time it was inspected.  If one or more files have been updated (or created), the job invokes a "call-back" method on an identified DirectoryScanListener that can be found in the SchedulerContext.”
That seems pretty self explanatory, no? Basically, you tell the job that it needs to check a certain directory to see if new files have been added or if existing files have been modified. When the job is executed it checks the files and stores the file information in its JobDataMap. The next time the job runs, it compares the information stored in the job’s JobDataMap, with the files in the directory. If any changes are found, the job calls the FilesUpdatedOrAdded method of the IDirectoryScanListener that was configured for that job, passing in an arrary of FileInfo objects.
Configuring the DirectoryScanJob
To configure and use a DirectoryScanJob, you will need to set the following keys in the JobDataMap:
  1. DIRECTORY_NAME: this is the path to the directory that you want to monitor. 
  2. DIRECTORY_SCAN_LISTENER_NAME: this is the name of the DirectoryScanListener that should called if changes are detected 
  3. MINIMUM_UPDATE_AGE: this is an optional parameter which lets you specify how many milliseconds must have passed since the file’s last modified time in order to consider the file modified. If this parameter is not specified, it defaults to 5000 milliseconds. 
Possible Uses for the DirectoryScanJob
There are many uses for the DirectoryScanJob, so let’s list a few here:
  • You could replace any FileWatcher type services that you might have implemented 
  • Scan files uploaded by users for viruses 
  • Schedule other jobs to process files that have been copied to the directory for processing 
The next post in the series will cover a change to the IStatefulJob interface: it has been marked as obsolete and is replaced by a class attribute!

            Continue Reading
          

        

        
        
        

        
        
        

          
          

            
New in Quartz.Net 2.0–The Calendar Interval Trigger

            
            
This is the first post of what will become a series of posts highlighting the new features that will be available in Quartz.Net 2.0.
To kick off the series, we will take a look at the CalendarIntervalTrigger. This trigger is used to fire jobs based on a recurring calendar time interval. The following time intervals are available:
       IntervalUnit     
       Minute     
       Hour     
       Day     
       Week     
       Month     
       Year     
This trigger has a RepeatInterval property, which can be used to indicate that the trigger should fire every N intervals. For example, if you set the RepeatIntervalUnit to Week and the RepeatInterval to 2, your trigger will fire every two weeks.
Here is what the source code documentation says about this trigger:
A concrete ITrigger that is used to fire a IJobDetail based upon repeating calendar time intervals. 
The trigger will fire every N (see RepeatInterval) units of calendar time (see RepeatIntervalUnit) as specified in the trigger's definition.  This trigger can achieve schedules that are not possible with ISimpleTrigger (e.g because months are not a fixed number of seconds) or ICronTrigger (e.g. because "every 5 months" is not an even divisor of 12).
If you use an interval unit of IntervalUnit.Month then care should be taken when setting the startTime value that is on a day near the end of the month.  For example, if you choose a start time that occurs on January 31st, and have a trigger with unit IntervalUnit.Month and interval 1, then the next fire time will be February 28th, and the next time after that will be March 28th - and essentially each subsequent firing will occur on the 28th of the month, even if a 31st day exists.  If you want a trigger that always fires on the last day of the month - regardless of the number of days in the month, you should use ICronTrigger.
That’s it for today’s “New in Quartz.Net 2.0” post. Stay tuned for more, coming soon!

            Continue Reading