SPSchedule and Derived Classes

When you schedule a Timer Job in SharePoint 2010, you usually create a new instance from a class derived from the SPSchedule base class and link it through the SPJobDefinition.Schedule property. SPSchedule is an abstract non-extensible base class for different schedule types used in job definitions. For most derived classes, the timer service will pick a random time between the begin and end property values and start the job at that time. Set the begin property value equal to end to start the timer job at a precise time. You have also one SPMonthlyByDaySchedule class to start and run the job monthly in one specific week and day of that week, and one SPOneTimeSchedule class to run the related job once only.

SPSchedule Class Hierarchy

• SPMinuteSchedule – starts job randomly between Begin/EndSecond and repeat at every Interval minutes (default = 5).
• SPHourlySchedule – starts job hourly between Begin/EndMinute.
• SPOneTimeSchedule – starts and runs job once only, at Time begin=end specific time.
• SPMonthlyByDaySchedule – starts job monthly in a specific WeekOfMonth BeginWeek week and DayOfWeek BeginDay day of that week, at BeginHour/Minute/Second.
• SPDailySchedule – starts job daily between Begin/EndHour/Minute/Second.
• SPWeeklySchedule – starts job weekly between Begin/End…/DayOfWeek.
• SPMonthlySchedule – starts job monthly between Begin/End…/Day.
• SPYearlySchedule – starts job yearly between Begin/End…/Month.

Structure of SPSchedule-based Classes

Any scheduler has a Description and a NextOccurance(DateTime) method, which returns a random time in the period between the begin and end times specified by the schedule that occurs after the specified time. A schedule object can be created through the static FromString(recurrenceValue) method from the specified recurrence string. All these members belong to the abstract base class SPSchedule.

All Use Case Scenarios

The following sequence uses a SPMinuteSchedule instance to start the related job within the next 30 seconds and re-run every 5 minutes:

SPMinuteSchedule scheduler = new SPMinuteSchedule();
scheduler.BeginSecond = 0;
scheduler.EndSecond = 29;
scheduler.Interval = 5;

In SharePoint there may be many timer jobs running at the same time and it is a good idea to provide a range of a few seconds for the random starting time selected by the system, to avoid putting a heavy load on server. However, if you want your timer to start precisely at some moment in time, give BeginSecond and EndSecond properties the same value. The job with this slightly modified scheduler will start immediately after the next 10 seconds:

SPMinuteSchedule scheduler = new SPMinuteSchedule();
scheduler.BeginSecond = scheduler.EndSecond = 9;
scheduler.Interval = 5;

When you want your timer job to run every hour, use a SPHourlySchedule object. An Interval property is no longer necessary, because it is always of 60 minutes (one hour). The timer with this scheduler starts in the next 5 minutes and repeats every hour:

SPHourlySchedule scheduler = new SPHourlySchedule();
scheduler.BeginMinute = 0;
scheduler.EndMinute = 5;

Daily schedulers use the SPDailySchedule class and the begin/end time to start the job specified by hour, minute and second. This scheduler will start the job every day sometime between 2:00 am and 2:10 am:

SPDailySchedule scheduler = new SPDailySchedule();
scheduler.BeginHour = 2;
scheduler.BeginMinute = 0;
scheduler.BeginSecond = 0;
scheduler.EndHour = 2;
scheduler.EndMinute = 10;
scheduler.EndSecond = 0;

Schedulers supposed to start a job once a week can use the SPWeeklySchedule class. This scheduler will start the job every Monday between 2:00 am and 2:10 am:

SPWeeklySchedule scheduler = new SPWeeklySchedule();
scheduler.BeginDayOfWeek = DayOfWeek.Monday;
scheduler.BeginHour = 2;
scheduler.BeginMinute = 0;
scheduler.EndDayOfWeek = DayOfWeek.Monday;
scheduler.EndHour = 2;
scheduler.EndMinute = 10;

Schedulers supposed to start a job once a month can use the SPMonthlySchedule class. This scheduler will start the job every 5th of the month between 2:00 am and 2:10 am:

SPMonthlySchedule scheduler = new SPMonthlySchedule();
scheduler.BeginDay = 5;
scheduler.BeginHour = 2;
scheduler.BeginMinute = 0;
scheduler.EndDay = 5;
scheduler.EndHour = 2;
scheduler.EndMinute = 10;

With SPMonthlyByDaySchedule class, the job starts and runs repeatedly one specific day (DayOfWeek enum: Monday, Tuesday etc) of one specific week (WeekOfMonth enum: First, Second, Third, Fourth or Last) of the month. Remark there are no End time properties for this class. This scheduler will start the job every second Monday of a month at 2:00 am:

SPMonthlyByDaySchedule scheduler = new SPMonthlyByDaySchedule();
scheduler.BeginWeek = WeekOfMonth.Second;
scheduler.BeginDay = DayOfWeek.Monday;
scheduler.BeginHour = 2;
scheduler.BeginMinute = 0;
scheduler.BeginSecond = 0;

Schedulers supposed to start a job just once a year can use the SPYearlySchedule class. This scheduler will start the job every 5th of the month of February between 2:00 am and 2:10 am:

SPYearlySchedule scheduler = new SPYearlySchedule();
scheduler.BeginMonth = 2;
scheduler.BeginDay = 5;
scheduler.BeginHour = 2;
scheduler.BeginMinute = 0;
scheduler.BeginSecond = 0;
scheduler.EndMonth = 2;
scheduler.EndDay = 5;
scheduler.EndHour = 2;
scheduler.EndMinute = 10;
scheduler.EndSecond = 0;

When you don’t want to run your job repeatedly, use SPOneTimeSchedule class and specify just the starting time, in its contructor or the Time property. The begin time is equal in this case with the end time. Assuming you already have a timerJob instance derived from SPJobDefinition, this sequence will update it to start the job immediately:

timerJob.Schedule = new SPOneTimeSchedule(DateTime.Now);
timerJob.Update();