Agent Limitations

A Windows Phone app can reference only one Scheduled Task Agent project; however, you can register both the periodic and resource-intensive tasks for an application. If your app registers both types of tasks for your background agent, the tasks will run on different schedules and are limited to 11MB of memory usage at any time. If either agent type experiences two unhandled exceptions, it will be removed from the schedule automatically.

Both periodic and resource-intensive tasks have a limited lifetime and are set to expire two weeks from the time they are first registered by the application. So, it is good practice to reregister your agent before the expiration time is met to ensure the agent is not removed from the schedule. There are some cases where an automatic renewal may occur. Most notably, if the app tile is pinned to the phone start screen or is selected to display notifications on the lock screen and the agent makes a call to the Update method on the ShellTile class, which in turn will update the application’s tile or lock screen status, then its expiration time will be extended by two weeks.

When designing your app and its associated agent, keep in mind that there are large set of API calls that you simply cannot make from your background agent. Many of these included APIs access components that run in the foreground, such as accessing the camera, the clipboard, and the web browser, to name few. To view the complete list of unsupported API calls from within a scheduled agent, review the article “Unsupported APIs for background agents for Windows Phone” on the MSDN web site at http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh202962(v=vs.105).aspx.

If you’ve taken a quick peek at that article, you will notice that the list also includes the background audio player as an unsupported API for scheduled agents. You are probably thinking to yourself, “Why wouldn’t a background audio player be supported in a background agent? Isn’t that the purpose?”

Although that seems like a valid point, this action is not appropriate within a Scheduled Task Agent. The purpose of this agent is to execute an action at timed intervals. Playing audio in the background just doesn’t fit in here, since the playback is initiated by the user rather than launched as a timed-based action. There is a separate type of agent you will create so that your app can play audio even while your app is not running in the foreground; however, that is beyond the scope of this chapter. We will discuss this topic in Chapter 7.

Using a Scheduled Task Agent

Now that we have discussed what you can’t do within a Scheduled Task Agent, let’s go over what you are able to do!

• HttpWebRequest: You can make web requests using the HttpWebRequest class, which will come in handy if your app needs to use web services to manage data, such as uploading or downloading data.
• Mutex: If your background agent needs to access files in isolated storage that are also used by the foreground app, then you will need to use a Mutex class to synchronize access to those files. This holds true for any other resources that are shared between the app and the background agent.
• GeoCoordinateWatcherAPI: You can use a background agent to retrieve the device’s geographic coordinates using the GeoCoordinateWatcher API. Note that the location is a cached value, which is updated every 15 minutes, so the user’s location may not always be 100 percent accurate. Keep this in mind when designing agents that depend on tracking the user’s location.
• ShellTile and ShellToast: As was hinted at during the introduction to this chapter, you can use a background agent to update your app tiles or raise a toast notification.

Since this recipe alludes to updating tiles from the agent, let’s walk through a simple example on how this can be accomplished.

Open the solution named InspireMe, located within the Chapter 5InspireMeStart directory. This application simply displays a list of quotes when launched. It also provides the user with the ability to pin and unpin a live tile to the device’s start screen. For now, when the tile is pinned to the start screen, the wide tile content is set to a random quote. Once this quote is set, it does not change.

We will enhance the application so that the application’s wide tile content will update periodically with a random quote from the list when the tile is pinned to the start screen. We will need to create a Scheduled Task Agent project and make use of the PeriodicTask to accomplish this goal.

Building a Scheduled Task Agent

Add a new project to the solution. In the Add New Project dialog, select Windows Phone Scheduled Task Agent, as depicted in Figure 5-1. Name the project InspireMe.Agent.

When the Scheduled Task Agent project loads, you will notice a single class is included in the file called ScheduledAgent, which derives from the ScheduledTaskAgent class. Open this file and take a look at the generated code that is provided by default. The method that we will be adding code within is the OnInvoke method. However, this will require some modifications to the InspireMe Windows Phone project, which we will get to shortly.

The first thing we will need to do is add a reference within our Scheduled Task Agent to the InspireMe.DataProvider project. The reason we have the Quotes list separated into a data provider class library is so we can access the Quotes list data from both the main app and the background agent. It is extremely important to note that this simplistic approach is being used because we are not modifying the list of quotes at any time.

If the application allowed the user to either add or remove quotes within the foreground app, it would be best to store the Quotes XML file within isolated storage, using the IsolatedStorageFile class. In addition to that, when accessing files from isolated storage from either the foreground app or the background agent, you must use a mutex to secure exclusive access to the file on only one thread. In this way, if one thread acquires a mutex, the second thread is suspended until the first thread releases the mutex. The benefit to this approach is to prevent data corruption in the event the Quotes XML file is being modified by the foreground app at a time when the background agent is also trying to access it. Isolated storage is out of the scope of this chapter, so we will keep our recipe focused on using a background agent with a static collection. We will be discussing IsolatedStorage in more detail in Chapter 11.

Within the InspireMe project, be sure to add a reference to the newly created InspireMe.Agent project. As well, we should ensure that an ExtendedTask element has been added to the application manifest for the background agent, within the Tasks collection. Open the file in Code View, and be sure that the ExtendedTask element is added to the Tasks collection, as shown in Listing 5-1.

Listing 5-1. ExtendedTask Element for the InspireMe.Agent

<Tasks>
   <DefaultTask Name="_default" NavigationPage="MainPage.xaml" />
   <ExtendedTask Name="InspireMeTask">
     <BackgroundServiceAgent Specifier="ScheduledTaskAgent" Name="InspireMeTask" Source="InspireMe.Agent" Type="InspireMe.Agent.ScheduledAgent" />
   </ExtendedTask>
</Tasks>

Registering the Agent

It is now time to add the code in the foreground app to register our background agent. We will need to use a couple of classes from the Microsoft.Phone.Scheduler namespace to accomplish this action: PeriodicTask and ScheduledActionService.

In the MainPage code-behind file, add a using directive to include the Microsoft.Phone.Scheduler namespace. Next, add a new private method called RegisterAgent. In this method, we will do the following:

1. Create a PeriodicTask object, setting a name and description for the agent.
2. Check to determine whether the PeriodicTask has already been registered with the ScheduledActionService by calling the Find method on the ScheduledActionService class and passing in the task name.
3. If the scheduled action is already registered, we will remove it by calling the Remove method on the ScheduledActionService class, passing in the task name.
4. We will then register the PeriodicTask with the operating system by calling the Add method on the ScheduledActionService class and passing in the PeriodicTask object.

If you are wondering why we are going through the effort to remove the task only to add it back into the schedule, recall the point in the beginning of this section when we talked about how background agents have an expiration date set to two weeks from the date when it was first registered. The action of removing this task and then adding it back in ensures that we push out the expiration date when the user runs the application. You are probably thinking “We update the application’s tile. Doesn’t that automatically renew the agent?”

It does, but only in the case when the user has pinned the app’s tile to the device’s start screen. This isn’t a guarantee, so the only way we can be sure to extend the life of our agent is to force a new registration of it whenever the user launches the application.

Finally, we will need to call the RegisterAgent method when the MainPage is loaded. For completeness, we should include exception handling. For this demonstration, we will simply display errors in a MessageBox, as depicted in Listing 5-2. Ideally, if you are publishing your app, you will want to fine-tune your error handling to log errors, notify the user, or provide the user the option to e-mail the exception details to your support e-mail address.

Listing 5-2. RegisterAgent Method in the MainPage Code-Behind

private void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    RegisterAgent();
}
 
private void RegisterAgent()
{
    string taskName = "InspireMeTask";
    try
    {
 
        if (ScheduledActionService.Find(taskName) != null)
        {
            //if the agent exists, remove and then add it to ensure
            //the agent's schedule is updated to avoid expiration
            ScheduledActionService.Remove(taskName);
        }
 
        PeriodicTask periodicTask = new PeriodicTask(taskName);
        periodicTask.Description = "InspireMe task updates the tile with a new quote";
        ScheduledActionService.Add(periodicTask);
    }
    catch (InvalidOperationException exception)
    {
        MessageBox.Show(exception.Message);
    }
    catch (SchedulerServiceException schedulerException)
    {
        MessageBox.Show(schedulerException.Message);
    }
}

At this point, you can run the app in the emulator, but for testing purposes, it’s not efficient to wait for 30 minutes to see whether your agent runs as expected. For this reason, there is a method available on the ScheduledActionService class, called LaunchForTest, which you can use when debugging your scheduled agent. This is to be used only when in debug mode and should be removed before publishing the app. The LaunchForTest method accepts a task name and a TimeSpan value. The TimeSpan value indicates the amount of time that should pass between task executions. For testing purposes, a 30-second delay time works well; however, you can set it to any value you think suits your testing purposes best. Include the code shown in Listing 5-3, after the scheduled task is registered through the ScheduledActionService, in the RegisterAgent method in the MainPage code-behind.

Listing 5-3. Use the LaunchForTest Method When Debugging Scheduled Agents

//only use LaunchForTest when debugging
                //be sure to remove this code section before publishing your app
#if DEBUG
                ScheduledActionService.LaunchForTest(taskName, TimeSpan.FromSeconds(30));
#endif

Note that if we wanted to also register a resource-intensive agent, all we would need to do is create a ResourceIntensiveTask object and register the scheduled action with the operating system, in the same manner we created and registered the PeriodicTask.

ResourceIntensiveTask resourceIntensiveTask =
            new ResourceIntensiveTask("InspireMe RI Agent");
resourceIntensiveTask.Description = "Resource intensive agent for InspireMe";
ScheduledActionService.Add(resourceIntensiveTask);

Since we are simply updating a tile, a resource-intensive agent doesn’t make sense in this recipe. Just note that its implementation is similar to the periodic agent.

Updating the Tile

With everything in place in the foreground app, we need to revisit the Scheduled Task Agent project and include the necessary code to actually update the application’s tile with a random quote.

Within the ScheduledAgent class, add the using directive for the InspireMe.DataProvider namespace. Now it’s time to add code to the OnInvoke method. Notice how there is already a call to the NotifyComplete method. It is important to leave this code intact, because this is what notifies the operating system that the agent has completed the execution of the task’s actions on the current run.

Before the call to the NotifyComplete method, we will include a check to determine whether the current task that is being executed is in fact a PeriodicTask, and we will code the desired actions for the task. The scheduled task that is being invoked could be different in the scenario where the foreground app uses both a PeriodicTask and a ResourceIntensiveTask. In this instance, it’s not necessary to include this check here because we registered only one scheduled task, but it is something worth mentioning while we’re here.

Next, we will want to instantiate a new instance of the QuoteDataProvider class, which will load the quotes from the XML file into the QuoteList collection, making the quotes available within our agent. We will then use the Random class to generate a random number, which will represent the ID of the quote we will then add to the back of the app’s wide tile. We will pull the random quote from the collection using the magic of LINQ! This means we must add the using directive for the System.Linq namespace in this class.

Once we obtain the random quote from the collection, we will update the app’s tile by creating a new FlipTileData object and setting the WideBackContent property to the new quote. For good measure, we will also update the BackTitle property to display the date and time the tile was last updated. Our code should now look similar to Listing 5-4.

Listing 5-4. Include the Desired Code in the OnInvoke Method in the ScheduledTaskAgent Class

protected override void OnInvoke(ScheduledTask task)
{
    if (task is PeriodicTask)
    {
        QuoteDataProvider quoteProvider = new QuoteDataProvider();
 
        if (quoteProvider.QuoteList.Count() > 0)
        {
            FlipTileData newTileData = new FlipTileData()
            {
                //load a random quote from the quote data provider
                WideBackContent = quoteProvider.GetRandomQuote(),
                BackTitle = string.Format("Last Updated: {0}", DateTime.Now.ToString("MMM dd, yyyy h:mm tt"))
            };
 
            ShellTile appTile = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains(mainPageUri));
            if (appTile != null)
            {
                appTile.Update(newTileData);
            }
        }
    }
 
    NotifyComplete();
}

We have all the code in place that is required to load quotes into a list in the main application and display random quotes on the backside of the app’s wide tile. One thing that is important to note here is that if you are developing an application for which you plan to support wide tiles, you will need to explicitly enable this setting in the application manifest, as shown in Figure 5-2. By default, the “Support for large tiles” option in the manifest is turned off.

Another thing that is worthwhile to mention here is that although the Windows Phone project generates default tiles for you to use for each of the possible tile templates, it is good practice to get in the habit of creating your own tile images that are representative of the app’s purpose. Syncfusion provides a free tool for developers, called MetroStudio, which you can use to create your custom tile images. You can download this tool from www.syncfusion.com/downloads/metrostudio. This was the tool used to create the InspireMe tiles.

Testing the Agent in the Emulator

Now it is time to take the application for a test run. Launch the app in the emulator and notice the Quotes list displayed in the app’s main page. Tap the Pin application bar icon. If the tile was pinned successfully, you will automatically be taken to the start screen to view the newly pinned tile.

By default, the medium size tile is pinned to the start screen. Tap and hold the InspireMe tile to change sizes. The first size change will switch to the small tile size. The next size change will expand to the large, wide tile size, as shown in Figure 5-3.

With the app launched and the tile pinned to the start screen, wait for the tile to flip to the backside, as illustrated in Figure 5-4. Notice the random quote that is displayed, along with the last updated date and time. Continue to monitor the start screen to watch the tile as it flips from back to front, and the quotes continue to change on a regular interval.

Congratulations on creating your first scheduled agent for Windows Phone 8! We have packaged the complete solution, which includes the scheduled agent for this recipe, within the Chapter 5InspireMeFinished folder.

There was a lot of content to digest in this recipe, so take some time to sit back, relax, and enjoy this accomplishment. Although it is simple to create a scheduled agent for your app, there is a lot of thought and consideration that must be given to the design of the app, such as the purpose of the background agent, which background agents you will include, and the limitations of each agent.

Let’s Make a Toast!

Now that you are familiar with the concepts of a toast notification for Windows Phone, let’s develop an agent so we can put it into action. Launch Visual Studio 2012, and open the WeatherAlerts solution in the Chapter 5WeatherAlerts folder. Add a new Windows Phone Scheduled Task Agent project to this solution called WeatherAlerts.Agent.

Similar to Recipe 5-1, we will need to add a reference to the application’s related data provider, which, in this case, is the WeatherAlerts.DataProvider project. As we discussed earlier, this approach is taken to enable code reuse between the main Windows Phone application and the scheduled agent. Before we make any modifications, open the AlertsDataProvider class to determine the method call that needs to be included in the background agent.

Notice that there is a public method called LoadData, which uses the OpenReadAsync method on the System.Net.WebClient class to retrieve the data from a URL that points to a weather site’s XML feed. This is the method that we will need to call from within the agent’s OnInvoke method.

Also notice that the OpenReadCompleted event, which receives the result of the data feed, raises another event, AlertsDownloaded. In this way, we can register this event handler within the Scheduled Task Agent so that the agent receives a notification from the data provider when the data has been downloaded from the XML data feed.

Creating the Toast Notification

Within the AlertsDownloaded event, we will create our toast notification by creating an instance of the ShellToast class and setting the Title, Content, and NavigationUri properties. To ensure the notification is displayed, we need to call the ShellToast.Show method. From here, we can also remove the event handler registration. Finally, we will move the NotifyComplete method call from the OnInvoke method to the AlertsDownloaded event. Refer to Listing 5-5 for the code that was added to the ScheduledAgent class.

Listing 5-5. Scheduled Task Agent for the WeatherAlerts App

AlertsDataProvider dataProvider = new AlertsDataProvider();
protected override void OnInvoke(ScheduledTask task)
{
    if (task is PeriodicTask)
    {
        dataProvider.LoadData();
    }
}
 
private void dataProvider_AlertsDownloaded(object sender, System.EventArgs e)
{
    if (dataProvider.WeatherAlerts.Count() > 0)
    {
        ShellToast toast = new ShellToast();
        toast.Title = "Weather Alert";
        toast.Content = dataProvider.WeatherAlerts.Count().ToString() + " active alert(s)";
        toast.NavigationUri = new System.Uri("/MainPage.xaml", System.UriKind.RelativeOrAbsolute);
        toast.Show();
    }
 
    dataProvider.AlertsDownloaded -= new AlertsDataProvider.EventHandler(dataProvider_AlertsDownloaded);
 
    NotifyComplete();
}

Next, we will need to return to the WeatherAlerts application and add a reference to the InspireMe.Agent project. We will also need to modify the MainPage code-behind file to register the agent when the page loads. Refer to Listing 5-2 in Recipe 5-1 to view an example of how to implement this in your MainPage code-behind.

Last but not least, we need to include the ExtendedTask definition in the application manifest. Refer to Listing 5-1 within Recipe 5-1 as the example to follow. Once that is in place, we can launch our app in the emulator to test it. Note that if there no active weather alerts from the feed provided at the time you run this app, you can alternatively replace it with a weather feed that suits your testing needs or just provide some fake data to force a toast notification to occur. You can make this change within the AlertsDataProvider class in the WeatherAlerts.DataProvider project.

Testing Toast Notifications in the Emulator

In launching the app in the emulator, the first thing you want to do is back out of the app and return to the start screen. At this point, it’s just a matter of waiting for the agent to run for the first time. If there are alerts that are active, you should see the toast notification depicted in Figure 5-5.

When the toast notification displays onscreen, click it with your mouse to launch the WeatherAlerts app and view the full details of any active alerts, as shown in Figure 5-6.

That is all it takes to create local toast notifications in your app!

To view the source code for the complete solution, load the WeatherAlerts solution located within the Chapter 5WeatherAlertsFinished folder.

Designing the Background Transfer Service

To understand how background transfer requests work, we will create an application that will allow the user to queue up a list of videos for download. Launch Visual Studio 2012, and create a new Windows Phone Databound App project, named DownloadMe. Since we have chosen a databound app template, we have the basic shell of our ViewModels already created for us, along with some basic data binding already wired up for us in the MainPage. We will be making quite a few modifications, but this is a good starting point.

The purpose of this app is to allow the user to do the following:

• Select videos to download from a static media list of our choosing
• Ensure the download completes even if the user exits the app
• Track the video download progress
• Enable the user to play the video once it is downloaded

The MainPage will be modified slightly to display more information about the media items available for download. As well, we will include a download button and a check box next to each media item to allow the user to selectively download one or more items. Furthermore, when the download completes, we want the user to be able to view any of the video files that downloaded.

In the LongListSelector control, we will modify the DataTemplate to include the check box for each item in the list and some additional TextBlock controls. The TextBlock controls will be used to display the download location of the file and a progress message only while the item is being downloaded. We will also display a button to allow the user to play the file once it has been downloaded. The markup for the LongListSelector should now be similar to the markup in Listing 5-8.

Listing 5-8. LongListSelector Markup Modifications in the MainPage.xaml File

    <phone:LongListSelector.ItemTemplate>
        <DataTemplate>
            <Grid>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto" />
                    <ColumnDefinition Width="*" />
                </Grid.ColumnDefinitions>
                <Grid.RowDefinitions>
                    <RowDefinition />
                    <RowDefinition />
                    <RowDefinition />
                </Grid.RowDefinitions>
               <CheckBox IsChecked="{Binding ItemSelected, Mode=TwoWay}"
                         Grid.RowSpan="2" />
                <Button Content="Play"
                        Height="80"
                        Grid.RowSpan="2" />
               <TextBlock Grid.Column="1" Grid.Row="0"
                          Text="{Binding Title}" TextWrapping="Wrap"
                          Style="{StaticResource PhoneTextLargeStyle}"/>
              <TextBlock Grid.Column="1" Grid.Row="1"
                         Text="{Binding Speaker}" TextWrapping="Wrap"
                         Style="{StaticResource PhoneTextSubtleStyle}"/>
                <TextBlock Grid.Column="1" Grid.Row="2"
                         Text="{Binding LocalUri}" TextWrapping="Wrap"
                         Style="{StaticResource PhoneTextSubtleStyle}"/>
                <TextBlock Grid.Column="1" Grid.Row="2"
                         Text="{Binding DownloadProgress}" TextWrapping="Wrap"
                         Style="{StaticResource PhoneTextSubtleStyle}"/>
            </Grid>
        </DataTemplate>
    </phone:LongListSelector.ItemTemplate>
</phone:LongListSelector>

Enhancing the User Interface

You may have noticed that we have both the check box and button elements in the same grid row and column location. We plan on showing the check box only when a file has not been selected for download yet. Once the file has been downloaded, we will hide this element and display the button instead. To control the visibility of these elements, we need to use a Converter class.

Add a new class to the project, and name it VisibilityConverter. Modify the class to implement the IValueConverter interface. The Converter value that will be passed in will be the ItemDownloaded property for a single media item. If true, the button should be visible, and the check box will be hidden.

public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
{
    bool visibility = (bool)value;
    if (parameter.Equals("checkbox"))
    {
        visibility = !visibility;
    }
 
    return visibility ? Visibility.Visible : Visibility.Collapsed;
}
      

We will need to add the newly created converter as a resource in the MainPage markup.

 
        xmlns:local="clr-namespace:DownloadMe"
    ....
        <Grid.Resources>
            <local:VisibilityConverter x:Key="buttonVisibilityConverter" />        </Grid.Resources>

With that in place, we can now modify our elements to use the new converter to determine which element is displayed based on whether the media item was downloaded. As well, we will include the DownloadUrl and LocalUri values of the item in the Tag properties of the Checkbox and Button, respectively. We will be using these values later to determine the download location of each selected item and to indicate which file to launch when the play button is tapped. On that note, we should also wire up the Tap event handler for the button, because we will be coding for it shortly.

<CheckBox IsChecked="{Binding ItemSelected, Mode=TwoWay}"
          Tag="{Binding DownloadUrl}" Grid.RowSpan="2"
          Visibility="{Binding ItemDownloaded, Converter={StaticResource buttonVisibilityConverter}, ConverterParameter=checkbox}"/>
<Button Content="Play"
        Height="80"
        Tap="PlayButton_Tap_1"
        Tag="{Binding LocalUri}"
        Grid.RowSpan="2"
        Visibility="{Binding ItemDownloaded, Converter={StaticResource buttonVisibilityConverter}, ConverterParameter=button}"/>

Finally, we will add a button in the ContentPanel to appear below the LongListSelector, which will be used to launch the download of any selected media items.

<Button Content="download selected videos" Grid.Row="1" Tap="Button_Tap_1" />

Now, we can move along to the MainViewModel class. In the LoadData method, we will include a set list of Channel9 videos to download.

public void LoadData()
{
    this.Items.Add(new ItemViewModel()
        {
            ID = "1",
            Title = "Building Windows Phone Apps",
            Speaker = "Lori Lalonde",
            DownloadUrl = "http://media.ch9.ms/ch9/a2ec/8673d554-4992-48d4-80e7-b9acdda4a2ec/DEVC3.wmv"
        });
 
    //add a few more items here
        ...
     
    this.IsDataLoaded = true;
}

The complete list of items that is used for this recipe is available in the MainViewModel class within the project that is packaged with this book, in the Chapter 5DownloadMe folder.

Handling Background Transfer Requests

The next method that needs to be added to the MainViewModel class is important, because this will be the method that creates the background transfer requests based on the media items that are selected by the user. We will create a method called DownloadSelectedItems. The method will iterate through the list of selected media items to create a background transfer request for each item and add the request to the Background Transfer Service. We will also register the TransferProgressChanged and TransferStatusChanged events on each request so that we can display the download progress in the UI and so we can monitor the status of each download request.

There is an additional method called ReinitTransferRequests that should be called when the application is reactivated or relaunched after download requests for one or more media files have been started. The purpose of this method is to rewire both transfer events on each active request so that the download progress and status are received by the application when it is relaunched. Refer to Listing 5-9 to see the resulting code.

Listing 5-9. Register Each Download Request and Monitor Its Download Progress and Status

public void DownloadSelectedItems()
{
    List<ItemViewModel> selectedItems = this.Items.Where(i => i.ItemSelected).ToList();
 
    _downloadsInProgress = selectedItems.Count;
 
    //register a background request for each media item separately
    foreach (ItemViewModel item in selectedItems)
    {
        Uri videoUri = new Uri(item.DownloadUrl, UriKind.Absolute);
        Uri downloadLocationUri = new Uri("shared/transfers/" + videoUri.Segments.Last(), UriKind.RelativeOrAbsolute);
 
        //add the request for the selected item to the service if it has not already been added
        if (BackgroundTransferService.Requests.Where(r => r.RequestUri == videoUri).FirstOrDefault() == null)
        {
            BackgroundTransferRequest request = new BackgroundTransferRequest(videoUri, downloadLocationUri);
            request.TransferPreferences = TransferPreferences.AllowCellularAndBattery;
 
            //register the background request with the operating system
            BackgroundTransferService.Add(request);
 
            item.LocalUri = "";
            item.DownloadProgress = "downloading video...";
 
            //register events for each request to monitor download progress and status
            request.TransferProgressChanged += new EventHandler<BackgroundTransferEventArgs>(request_TransferProgressChanged);
            request.TransferStatusChanged += new EventHandler<BackgroundTransferEventArgs>(request_TransferStatusChanged);
        }
    }
 
    SaveToIsolatedStorage();
}
 
void request_TransferProgressChanged(object sender, BackgroundTransferEventArgs e)
{
    //calculate the progress percentage so that we can display it in the UI
    double progress = (e.Request.BytesReceived * 100) / e.Request.TotalBytesToReceive;
 
    //get the current item from the collection that is being downloaded by this request
    //this can be determined by matching the item's DownloadUrl to the RequestUri
    ItemViewModel currentItem = this.Items.Where(i => i.DownloadUrl == e.Request.RequestUri.AbsoluteUri).FirstOrDefault();
    if (currentItem != null)
    {
        //update the DownloadProgress property so that it is reflected in the control that it is bound to in the UI
        currentItem.DownloadProgress = string.Format("download progress: {0}%", progress.ToString());
    }
}
 
void request_TransferStatusChanged(object sender, BackgroundTransferEventArgs e)
{
    BackgroundTransferRequest currentRequest = e.Request;
    if (currentRequest.TransferStatus == TransferStatus.Completed)
    {
        TransferCompleted(currentRequest);
    }
}
 
private void TransferCompleted(BackgroundTransferRequest currentRequest)
{
    //get the current item from the collection that is being downloaded by this request
    //this can be determined by matching the item's DownloadUrl to the RequestUri
    ItemViewModel currentItem = this.Items.Where(i => i.DownloadUrl == currentRequest.RequestUri.AbsoluteUri).FirstOrDefault();
 
    if (currentItem != null)
    {
        if (currentRequest.TransferError != null)
        {
            //update the DownloadProgress to indicate the download failed and include
            //the error message received in the TransferError object on the request
            currentItem.DownloadProgress = "download failed: " + currentRequest.TransferError.Message;
        }
        else
        {
            currentItem.DownloadProgress = "";
            currentItem.ItemDownloaded = true;
 
            //format the download location Uri to use forward slashes such that when
            //the user attempts to play the media files in the UI, the file system location is recognized
            string[] downloadUri = currentRequest.DownloadLocation.OriginalString.Split(new char[] { '' }, StringSplitOptions.RemoveEmptyEntries);
            currentItem.LocalUri = string.Join("/", downloadUri);
            currentItem.ItemSelected = false;
        }
    }
 
    //unregister the events from the request
    currentRequest.TransferProgressChanged -= request_TransferProgressChanged;
    currentRequest.TransferStatusChanged -= request_TransferStatusChanged;
 
    //remove the request from the BackgroundTransferService
    BackgroundTransferService.Remove(currentRequest);
    _downloadsInProgress -= 1;
 
    //if all downloads have completed, updated the current state of the Items collection in IsolatedStorage
    if (_downloadsInProgress == 0)
    {
        SaveToIsolatedStorage();
    }
}
 
public void SaveToIsolatedStorage()
{
    if (IsolatedStorageSettings.ApplicationSettings.Contains("Items"))
    {
        IsolatedStorageSettings.ApplicationSettings.Remove("Items");
    }
 
    IsolatedStorageSettings.ApplicationSettings.Add("Items", this.Items);
    IsolatedStorageSettings.ApplicationSettings.Save();
}
 
public void ReinitTransferRequests()
{
    foreach (BackgroundTransferRequest request in BackgroundTransferService.Requests)
    {
        if (request.TransferStatus == TransferStatus.Completed)
        {
            //if a queued up request has completed when the app was not running
            //be sure to reflect the completed state for the item in the collection
            TransferCompleted(request);
        }
        else
        {
            //if we have active requests in the BackgroundTransferService, rewire the events
            request.TransferProgressChanged += new EventHandler<BackgroundTransferEventArgs>(request_TransferProgressChanged);
            request.TransferStatusChanged += new EventHandler<BackgroundTransferEventArgs>(request_TransferStatusChanged);
        }
 
    }
}

Adding the Finishing Touches

Last but not least, we need to include the code for the button Tap events for both the download and play buttons. As you can see in Listing 5-10, the code required in the MainPage is minimal.

Listing 5-10. Button Event Handlers to Handle Download and Playback of Media Items

private void Button_Tap_1(object sender, System.Windows.Input.GestureEventArgs e)
{
    App.ViewModel.DownloadSelectedItems();
}
 
private void PlayButton_Tap_1(object sender, System.Windows.Input.GestureEventArgs e)
{
    Button btn = (Button)sender;
 
    //the file location is stored in the Tag of list item's play button
    if (btn.Tag != null && btn.Tag.ToString() != "")
    {
        string fileLocation = btn.Tag.ToString();
        //use IsolatedStorageFile to check the file location to be sure the file exists
        //before attempting to launch the video
        IsolatedStorageFile isoFile = IsolatedStorageFile.GetUserStoreForApplication();
        if (isoFile.FileExists(fileLocation))
        {
            Uri videoUri = new Uri(fileLocation, UriKind.RelativeOrAbsolute);
 
            try
            {
                MediaPlayerLauncher mediaPlayerLauncher = new MediaPlayerLauncher()
                {
                    Media = videoUri,
                    Location = MediaLocationType.Data,
                    Orientation =  MediaPlayerOrientation.Landscape,
                    Controls = MediaPlaybackControls.All
                };
 
                mediaPlayerLauncher.Show();
            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.Message);
            }
         }
      }
   }

Finally, modify the LoadData method in the MainViewModel to include a check for any saved data in IsolatedStorage. If the Items collection is found in the ApplicationSettings collection, then load the saved collection. Otherwise, create a new collection using our set media item list.

if (IsolatedStorageSettings.ApplicationSettings.Contains("Items"))
{
    this.Items = IsolatedStorageSettings.ApplicationSettings["Items"] as ObservableCollection<ItemViewModel>;
 
    ReinitTransferRequests();
}
else
{
    //first time launching the app, so add the default list of media items to the Items collection
         ...
}

Testing the Background Transfer Service

Launch the application in the emulator to test. When the application loads, select one or more media items for download and tap the download button. Notice that the download progress message updates as each item is downloaded. Exit from the app before the download completes. Wait a few seconds, relaunch the application, and notice how the current state is reflected in the UI. Also note that the download progress continues to update. This occurs because we rewired the events on the existing requests when the application was reloaded.

Once a media item has successfully been downloaded, select the play button for the downloaded item to launch the video within the Media Player on the device.