Scheduling custom tasks

The process of scheduling a custom task includes two steps:

1. Writing the code that performs the required actions
2. Creating a new scheduled task in the Kentico administration interface

Writing the task code

You need to define each scheduled task as a class that implements the CMS.Scheduler.ITask interface. To integrate this type of class into the application, you can:

• Create a new assembly (Class library) in your web project and include the task class there. In this case, you must add the appropriate references to both the assembly and the main Kentico project.
• Define the scheduled task in App_Code and load the class via the API. This ensures that the system automatically compiles the task and you do not need to use a separate assembly. The following example uses the App_Code approach.

Defining a custom App_Code class task

1. Open your web project in Visual Studio.

2. Add a new class into the App_Code folder (or CMSApp_AppCode -> Old_App_Code if the project is installed as a web application). For example, name the class CustomTask.cs.

3. Edit the class and add the following references:

   Copy

   
   
   
    using CMS.Scheduler;
    using CMS.EventLog;
   
   
   
    

4. (Optional) Wrap the class into the Custom namespace.

   Copy

   
   
   
    namespace Custom
    {
         /// <summary>
         /// Custom task class.
         /// </summary>
         public class CustomTask
         {
   
         }
    }
   
   
    

5. Make the class implement the ITask interface.

   Copy

   
   
   
    public class CustomTask: ITask
   
   
    

6. Define the Execute method in the class:

   Copy

   
   
   
    /// <summary>
    /// Executes the task.
    /// </summary>
    /// <param name="ti">Info object representing the scheduled task</param>
    public string Execute(TaskInfo ti)
    {
        string detail = "Executed from '~/App_Code/CustomTask.cs'. Task data:" + ti.TaskData;
   
        // Logs the execution of the task in the event log.
        EventLogProvider.LogInformation("CustomTask", "Execute", detail);
   
        return null;
    }
   
   
    

You must always include the Execute method when writing scheduled tasks. The system calls this method whenever the given task is executed, so it needs to contain all code implementing the required functionality.

In this example, the task only creates a record in the application’s event log so that you can confirm it is being executed:

• The TaskInfo parameter of the method allows you to access the data fields of the corresponding scheduled task object. The sample code adds the content of the TaskData field into the details of the event log entry.
• The string returned by the method is displayed in the administration interface as the result of the task’s most recent execution. You can leave it as null in this case.

Loading the App_Code class for the task

For tasks defined in the App_Code folder, you need to ensure that the system loads the appropriate class when executing the scheduled task. You can find additional information related to this topic in Loading custom classes from App_Code.

1. Add a reference to the CMS namespace to your scheduled task file:

   Copy

   
   
   
    using CMS;
   
   
    

2. Add the RegisterCustomClass assembly attribute above the class declaration (outside of the Custom namespace).

   Copy

   
   
   
    [assembly: RegisterCustomClass("Custom.CustomTask", typeof(Custom.CustomTask))]
   
   
    

This attribute registers custom classes and makes them available in the system. The attribute accepts two parameters:

• The first parameter is a string identifier representing the name of the class. The name must match the value of the Task provider - Class field specified for the given scheduled task (Custom.CustomTask in this example).
• The second parameter specifies the type of the class as a System.Type object. When the system executes the scheduled task, the attribute ensures that an instance of the given class is provided.

Creating new scheduled tasks

1. Log in to the Kentico administration interface and open the Scheduled tasks application.

2. Select the Site for which you wish to schedule the task ((global) if you want the task to run for all sites or affect global objects).

3. Click New task and fill in the properties of the task.

   

4. Click Save.

The system now executes the task regularly according to the specified interval.

Result

To check the result of this sample custom task, open the Event log application and look for entries with CustomTask as the Source.