In previous versions of SharePoint (or other platforms), if you had some task you wanted to perform on a scheduled basis, you'd have to either create a console EXE and schedule it to run via Windows Task Scheduler (ala AT.EXE) or create a Windows Service that went to sleep for a period of time. In order to install (and maintain) these tasks, you had to have console access to your production SharePoint (or other app) servers… something IT or admins wouldn't easily hand out.
Addressing this issue, Microsoft has added something called timer jobs to Microsoft Office SharePoint Server (MOSS) 2007. Microsoft uses timer jobs to do things like dead web cleanup (purging unused sites from site collections) among others. To see what other timer jobs are out there, from Central Administration, click Operations and then Timer Job Definitions. Not only does Microsoft use timer jobs in MOSS, but you can create your own custom timer jobs to do your own scheduled tasks. What's nice about this is once your timer job has been installed (something you can easily do with a solution & a feature), you can view it's status through Central Administration and even disable/enable it… all without console access to your production servers! Another cool thing is that when your job runs, MOSS passes it the GUID of the content database for the site the job is registered with. You can use this GUID to obtain a reference to a content database, then a site collection, and finally a site within the collection (SPWeb).
How do you build one? Well, unfortunately the documentation is lacking here… there isn't a single article in the SDK talking about creating custom timer jobs and the necessary objects aren't well documented either.
Everything surrounds the
Microsoft.SharePoint.Administration.SPJobDefinition object. Create a new class that inherits from SPJobDefinition, implement a few constructors and a single method:
Execute(Guid). I created a simple timer job that (assuming it's associated with a WSS site created using the Team Site template and there's a Tasks list in the root of the site) creates a new task every 5 minutes when the job is enabled. Here's what the constructors look like:
Now, after you build the assembly containing your custom timer job and add it to the GAC (a requirement), you need to associate it with a specific site, site collection, web application, or farm and specify a schedule for when it should run. Ideally I'd like to do this with STSADM.EXE, but no such command exists (custom command opportunity out there!). Another way is to do this through the object model. Because I want to minimize any console access requirements, I'll do this in a feature by implementing the FeatureActivated event. To do this, you create an instance of your job, set the schedule, and call update like so:
That's it! Course you should take this a step further by packaging all this up in a solution that will deploy the assembly to the GAC and install a feature. Then, upon activating the feature, it will associate the web with the timer job. Conversely, upon deactivating the feature, it removes the timer job. Very slick!
Updated: February 1, 2007 @10:00 PM (ET)Due to the great number of comments and questions triggered by this post, I took the time to write a new article explaining in more detail, with sample code, how to create a custom timer job. Please review that article before asking any questions: Creating custom SharePoint Timer Jobs. I'm closing the comments on this post… please post all new comments ot the article linked here.
Updated: July 2, 2007 @11:00 PM (ET)Make sure you don't use visible Features when deploying your custom timer jobs as explained here in this post.
Updated: April 8, 2008 @12:00 AM (ET)A Visual How-To I created on the subject of creating custom timer jobs was recently posted on MSDN. You can get more info here.
Updated: May 1, 2008 @7:30 AM (ET)There is now an in-depth article on MSDN about creating custom timer jobs. If you have trouble please check this out as there is a ton of additional info here. Post: More Help on Creating Custom Timer Jobs
Page update history / changelogThis page has been updated since it was originally published. The following list details each change and when it occurred.
- Thursday, January 11, 2007 - 12:00 PM
Added a default empty constructor to the first code listing.