Adding a Windows Phone Background Agent to an XNA Game

Article
09/29/2011

Note

This topic does not describe programming background agents in detail. For more detailed information, see Scheduled Actions Overview for Windows Phone in the Windows Phone Silverlight documentation. This topic is concerned primarily with details about how to add such background agents to an XNA Framework game.

Background agents, implemented by the Windows Phone BackgroundAgent class, can be used to perform background actions for XNA Framework games by adding a background agent to your existing Windows Phone game project.

Background agents are only available for games that target Windows Phone OS 7.1. For more information about creating a project that targets Windows Phone OS 7.1, see Creating a Windows Phone Game or Library Project.

Creating a New Background Agent

Before you can use a background agent in your game, you need to create one. This can be done by adding a new Task Scheduler Agent to your game's solution in Microsoft Visual Studio.

To add a new background agent to your game

In Solution Explorer, right-click the game solution, click Add, and then click New Project.
In the Add New Project dialog box, click Silverlight for Windows Phone.

A list of project types, including Windows Phone Task Scheduler Agent, is displayed.
Click Windows Phone Task Scheduler Agent, type the name of your project, and then click OK.

This adds a new task scheduler agent project and class to your solution.

Note

While this example uses the Task Scheduler Agent, any of the other background agent project types can also be used.

Adding Necessary References to Your Game Project

Next you need to add references to the newly created background agent and to the Microsoft.Phone assembly in your game project.

To add a reference to the background agent project

In your game project, right-click the References node, and then click Add Reference. The Add Reference dialog box opens.
On the Projects tab, click the Task Scheduler Agent you created in your solution, and then click OK to add it to your game.

Note

Alternatively, you can add a pre-built background agent assembly to your game by using the Browse tab to search for it. This topic assumes, however, that you've created a new background agent project specifically for your game.

To add a reference to the Microsoft.Phone assembly

In your game project, right-click the References node and click Add Reference. This opens the Add Reference dialog box.
On the .NET tab, click Microsoft.Phone in the list of components, and then click OK to add the reference to your game project.

Updating WMAppManifest.xml with Extended Task Information

Next you need to add extended task information to the WMAppManifest.xml file.

To add extended task information to WMAppManifest.xml

In your game project open the Properties node and double-click on the WMAppManifest.xml file.

Locate the Tasks element and create an ExtendedTask child node like this, replacing instances of SchedulerAgent1 with the name of your new agent.

<Tasks>
   <DefaultTask Name="_default"/>
   <ExtendedTask Name="BackgroundTask">
      <BackgroundServiceAgent Specifier="ScheduledTaskAgent" Name="SchedulerAgent1" Source="SchedulerAgent1" Type="SchedulerAgent1.TaskScheduler" />
   </ExtendedTask>
</Tasks>

Scheduling the Background Agent in Your Game Code

Once the background agent is added to your game, you must add it to your game code so it can be scheduled.

To use the background agent in your game code

In the source file you'll be using to schedule the background agent, add a using statement for Microsoft.Phone.Scheduler before your class or namespace declaration.
```
using Microsoft.Phone.Scheduler;
```

Use ScheduledActionService.Add to schedule the task for execution at a predefined interval or based on phone events such as idling. For example:

ScheduledActionService.Add(new PeriodicTask("Periodic") { Description = "UXDescription" });
ScheduledActionService.Add(new ResourceIntensiveTask("Idle"));