This article is Day #25 in a series called 31 Days of Mango, and was written by guest author Gary Johnson. Gary can be reached on Twitter at @GaryGJohnson.
Today we’re going to take a look at one of the multitasking capabilities new to Windows Phone 7.5. The complete multitasking picture is comprised of several new features:
- Background Agents
- Background File Transfer
- Background Audio Playback
- Scheduled Notifications
- Fast Application Switching
Here we will focus on Background Agents. While the file transfer and audio playback tasks cover specific scenarios, they do not allow for custom code to be executed. That is where Background Agents come in.
There are two types of Background Agents: Periodic and Resource Intensive. Resource Intensive agents are meant for tasks that will consume a large amount of system resources and come with several limitations for when they can be run. Periodic agents run more frequently and with less restriction, but are meant for tasks that are light on resource consumption. To fully understand the different limitations and benefits of each, refer to the MSDN page.
A periodic task might do something short and simple, such as refresh an RSS feed or update your live tile. A resource intensive task might do something that requires a lot of time and bandwidth, such as syncing or caching large amounts of data from a cloud service.
We are going to make a Periodic Agent that will update your application live tile with the last time the custom task was run.
Getting Started
Launch Visual Studio and create a new project. Under Silverlight for Windows Phone, select Windows Phone Application. Name it “MyAgentApp”.
You’ve now created the main application. It will be responsible for two things:
1) Having a live tile that the Background Agent can update with information
2) Starting and stopping the Background Agent
The Background Agent itself must live in its own special project. Add a new project to your solution, selecting Windows Phone Scheduled Task Agent. Name it MyAgent. This project will contain your custom code that will run in the background and update the live tile.
Finally, and this is important, go to the MyAgentApp project and add a project reference to MyAgent. This will allow you to register your agent from within the application. Also, notice the entry this automatically created in WMAppManifest.xml:
<DefaultTask Name="_default" NavigationPage="MainPage.xaml" />
<ExtendedTask Name="BackgroundTask">
<BackgroundServiceAgent Specifier="ScheduledTaskAgent" Name="MyAgent" Source="MyAgent" Type="MyAgent.ScheduledAgent" />
</ExtendedTask>
</Tasks>
Creating the Application
Now it’s time to actually wire everything up. Open MainPage.xaml and add two buttons, one for starting the agent, and the other for stopping the agent:
<Button Content="Start Background Agent"
Click="StartButton_Click"/>
<Button Content="Stop Background Agent"
Click="StopButton_Click"/>
</StackPanel>
In MainPage.xaml.cs, wire up the buttons to start and stop the agent:
private void StartButton_Click(object sender, RoutedEventArgs e)
{
StartAgent();
}
private void StopButton_Click(object sender, RoutedEventArgs e)
{
StopAgentIfStarted();
}
private void StartAgent()
{
StopAgentIfStarted();
PeriodicTask task = new PeriodicTask(TASK_NAME);
task.Description = "This is our custom agent for Day 25 – Background Agents";
ScheduledActionService.Add(task);
#if DEBUG
// If we’re debugging, attempt to start the task immediately
ScheduledActionService.LaunchForTest(TASK_NAME, new TimeSpan(0, 0, 1));
#endif
}
private void StopAgentIfStarted()
{
if (ScheduledActionService.Find(TASK_NAME) != null)
{
ScheduledActionService.Remove(TASK_NAME);
}
}
Notice that to create our custom agent, we are creating a new PeriodicTask. We then use the name as an identifier when finding and stopping the agent. Notice also that we specified PeriodicTask.Description – this is a required field and will appear in Settings | Background Tasks under the name of our application.
Create the Background Agent
In the MyAgent project, open ScheduledAgent.cs and add the following code:
{
UpdateAppTile(GetLastUpdatedTimeMessage());
}
private string GetLastUpdatedTimeMessage()
{
return string.Format("Last Updated: {0}", DateTime.Now);
}
private void UpdateAppTile(string message)
{
ShellTile appTile = ShellTile.ActiveTiles.First();
if (appTile != null)
{
StandardTileData tileData = new StandardTileData
{
BackContent = message
};
appTile.Update(tileData);
}
}
ScheduledAgent has one important method to override – OnInvoke. This is where your agent will execute its background task. If your task is complete and you no longer need your agent to run, you can call NotifyComplete() to signal that the task completed successfully or Abort() to signal that you are cancelling your task. To keep the task running at an interval, simply do not call either, which is what we are doing here.
Running the Application
Now that our application is ready to go, deploy it to the device emulator or Windows Phone and run the application. Click the button to start the background agent. Leave the application and find it in your list of applications. Tap and hold on the application and choose “pin to start”. When you view the tile on your start page you should eventually see the application tile flip around, revealing the last time it was updated.
Summary
So, today we created our own custom Background Agent that updates a live tile. When making Background Agents of your own, keep in mind what we covered:
- Background Agents allow you to execute custom code while your application is not running
- There are two types of Background Agents – Periodic and Resource Intensive
- Periodic tasks are for tasks that have low resource consumption, and as a result have fewer restrictions than Resource Intensive tasks
- Background Agents need their own project, which should be added as a project reference to the application that will start the agent
- In your agent you need to override OnInvoke()
- When your task is completed you need to call NotifyComplete() or Abort()
To download a complete Windows Phone project that uses all of the code and concepts from above, click the Download Code button below:
Tomorrow we are going to look at another multitasking feature called Background File Transfer that will allow us to download or upload files while our application is not running. See you then!
JEFF BLANKENBURG 
Leave a Reply