Background Agent Best Practices for Windows Phone

The following should be considered when debugging background agents.

• Use LaunchForTest(String, TimeSpan) to launch background agents when debugging. Periodic agents are not launched by the system when the debugger is attached. This method can be called from the foreground application or from the background agent.

• Memory and execution time policies are not enforced while the debugger is attached. It is important that you test your agent while not debugging to verify that your agent does not exceed the memory cap or run longer than the allotted time period for the agent type.

• Use ApplicationMemoryUsageLimit to query the memory limit for both foreground applications and background agents.

In Windows Phone OS 7.1, users have the ability to disable background agents for each installed application in the phone’s Settings application. If agents have been disabled for your application, attempts to register an agent using the Add(ScheduledAction) method of the ScheduledActionService will throw an InvalidOperationException, so place calls to Add in a try block. If an exception is thrown and the message associated with the exception is “BNS Error: The action is disabled”, then agents have been disabled for your application. The following code illustrates the proper way to handle this case.

bool agentsAreEnabled = true;
PeriodicTask periodicTask = new PeriodicTask("MyPeriodicTask");
periodicTask.Description = "This demonstrates a periodic task.";

// Place the call to Add in a try block in case the user has disabled agents.
try
{
  ScheduledActionService.Add(periodicTask);
}
catch (InvalidOperationException exception)
{
  if (exception.Message.Contains("BNS Error: The action is disabled"))
  {
    MessageBox.Show("Background agents for this application have been disabled by the user.");
    agentsAreEnabled = false;
  }
  if (exception.Message.Contains("BNS Error: The maximum number of ScheduledActions of this type have already been added."))
  {
    // No user action required. The system prompts the user when the hard limit of periodic tasks has been reached.
  }
}
catch (SchedulerServiceException)
{
  // No user action required.
}

}

An InvalidOperationException will also be thrown when the number of periodic background agents has reached the limit for the device. The number of agents allowed varies depending on the hardware capabilities of the device, but it is a small number and therefore it is common for this limit to be reached. For this reason, it is very important that you catch this exception whenever you attempt to add a periodic task. A SchedulerServiceException can also be thrown when adding a task, for example, if the device has just booted and the Scheduled Action Service hasn’t started yet. You should catch this exception whenever you add a scheduled task.

Tip:

When an application’s periodic background agent runs, it consumes a small amount of the device’s battery power. Users can disable background agents for one or more applications in the Settings application in order to extend battery life. However, to make it easier for users to balance functionality and battery life, you may want to add functionality to your foreground application that allows the user to opt-in to enabling background agents.

Passing information between the foreground application and background agents can be challenging because it is not possible to predict if the agent and the application will run simultaneously. The following are recommended patterns for this.

1. For Periodic and Resource-intensive Agents: Use LINQ 2 SQL or a file in isolated storage that is guarded with a Mutex. For one-direction communication where the foreground application writes and the agent only reads, we recommend using an isolated storage file with a Mutex. We recommend that you do not use IsolatedStorageSettings to communicate between processes because it is possible for the data to become corrupt.

2. For Audio Agents: Store custom data in the Tag property of the AudioTrack class. For notifications from the audio agent to the foreground application, read the Tag property in the PlayStateChanged event handler. To pass data from the foreground application to the audio agent, read the Tag property of the current track in the implementation of the OnPlayStateChanged(BackgroundAudioPlayer, AudioTrack, PlayState) method.

Windows Phone SDK 7.1 includes a project template for background agents called Windows Phone Scheduled Task Agent. When implementing a background agent, you should add a project to your solution using this template. In the project for your foreground application, add a reference to the output of the background agent project by selecting Project->Add Reference… and then selecting your background agent project. You should not create a class that implements ScheduledTaskAgent within the project for your existing application. Background agents will not be run if they are in the same assembly as the foreground application.

If you rename the background agent class or namespace, you will need to manually update the application manifest file for your foreground application. For information about the structure of this file, see the TASKS Element section of Application Manifest File for Windows Phone.