Windows Phone 8 : Scheduled Tasks - Using Scheduled Tasks

Using scheduled tasks in your app involves creating an agent class and adding an XML fragment to your WMAppManifest.xml file. This process can be done manually or by using the Windows Phone Scheduled Task Agent project template that resides beneath the Windows Phone node of the Add New Project dialog (see Figure 1).

FIGURE 1 Adding a new Windows Phone Scheduled Task Agent project.

The benefit of using the project template to create a scheduled task agent is seen when you reference that project from your primary phone project; a required XML fragment is automatically placed in the WMAppManifest.xml file.

A secondary benefit that can arise from using a separate project for your agent is that it can help to minimize the size of the assembly that is loaded by the CLR when your agent is invoked, which may marginally improve the load time of your agent. The larger an assembly is, the longer it takes the CLR to load it.

The XML fragment placed in the WMAppManifest.xml file informs the OS of the agent class type so that it can be resolved and invoked. The XML fragment resembles the following:

<Tasks>
    <DefaultTask  Name ="_default" NavigationPage="MainPage.xaml"/>
    <ExtendedTask Name="BackgroundTask">
        <BackgroundServiceAgent Specifier="ScheduledTaskAgent"
                                Name="[An identifier]"
                                Source="[Assembly Name]"
                                Type="[Class Name]" />
    </ExtendedTask>
</Tasks>

Table 1 provides descriptions of the attributes of the BackgroundServiceAgent element.

TABLE 1. BackgroundServiceAgent Attributes

public class ScheduledAgent : ScheduledTaskAgent
{
    protected override void OnInvoke(ScheduledTask task)
    {
        //TODO: Add code to perform your task in background

        NotifyComplete();
    }
}

Your agent’s OnInvoke method is called by the OS. In this method, your app can determine the type of ScheduledTask that triggered the invocation of the agent and perform actions accordingly. The task passed to the OnInvoke method is either a PeriodicTask or a ResourceIntensiveTask. To branch according to the type of task, something like the following can be used:

if (task is PeriodicTask)
{
    ProcessPeriodicTask();
}
else
{
    ProcessResourceIntensiveTask();
}

The NotifyComplete method of the base class informs the background task system that your task has finished its activities and signals that it is okay for the process to be terminated.

If your agent is unable to perform its work because of an unavailable resource—a cloud service, for example—call the Abort method instead of the NotifyComplete method. Abort has the same effect on task termination, but causes the task’s IsScheduled property to be set to false, which can then be detected and dealt with appropriately by your foreground app. If IsScheduled is false, you know that Abort was called.

The following shows how to create a new PeriodicTask:

string taskName = "a unique name";
PeriodicTask periodicTask = new PeriodicTask(taskName)
    {
        /* Description is required. */
        Description = "A description for the task"
    };

All ScheduledAction objects added to the ScheduledActionService must be named uniquely. Therefore, you should test whether the task has already been added to the scheduled action service. The task may then be added to the service as shown:

if (ScheduledActionService.Find(taskName) != null)
{
    ScheduledActionService.Remove(taskName);
}
/* This can only be called when the application
 * is running in the foreground. */
ScheduledActionService.Add(periodicTask);