Auto-upload apps for Windows Phone 8

July 21, 2014

This topic describes how your app can automatically upload photos to a photo storage service using a background agent. Apps that provide auto-upload functionality register for the auto-upload extension and launch to an auto-upload settings page when launched from the Settings app. To perform uploads, an auto-upload app must use a resource-intensive background agent, using the ResourceIntensiveTask class. Unlike other background agents, resource-intensive agents for auto-upload apps do not expire.

Important noteImportant Note:

Because of constraints on the phone that must be met for resource-intensive agents to run, it’s possible that the agent will never run on a particular phone. For example, if a user doesn’t have access to Wi-Fi or a PC, they may never have a non-cellular connection and the resource-intensive agents on their phone will never run. Also, resource-intensive agents run one at a time, so as more apps that use resource-intensive agents are installed on a phone, the likelihood that an agent will run becomes even less. You should consider this when you design your app.

This topic contains the following sections.

Apps that provide auto-upload functionality launch to a settings page when they are launched from the Settings app. In the Settings app, the photos+camera settings page lists an apps link at the bottom of the page. That link launches the auto-upload apps page, shown in following image.

Auto-upload apps from the Settings app

Apps that support auto upload are listed on this page. When tapped, each of those apps launch to an auto-upload settings page.

To designate that your app supports auto upload, register for the Photos_Auto_Upload extension. Extensions are specified in the WMAppManifest.xml file. Just after the Tokens element, inside the Extensions element, the auto-upload extension is specified with the following Extension element.


<Extension ExtensionName="Photos_Auto_Upload"
           ConsumerID = "{5B04B775-356B-4AA0-AAF8-6491FFEA5632}"
           TaskID="_default"/>


The Windows Phone Manifest Designer does not support extensions; use the XML (Text) Editor to edit them. For more info, see How to modify the app manifest file for Windows Phone 8.

When your app is launched from the Settings app, a deep link URI that contains a special keyword is used to launch your app. When the deep link URI contains the keyword ConfigurePhotosUploadSettings, launch your app to a settings page on which a user can configure the auto upload. The following code shows a URI mapper class that maps launches from the Settings app to an app’s auto-upload setting page.

using System;
using System.Windows.Navigation;

namespace CustomMapping
{
    class CustomUriMapper : UriMapperBase
    {
        public override Uri MapUri(Uri uri)
        {
            // The incoming URI
            string tempUri = uri.ToString();

            // Search for a specific deep link URI keyword
            if (tempUri.Contains("ConfigurePhotosUploadSettings"))
            {
                // Launch to the auto-upload settings page.
                return new Uri("/AutoUploadSettingsPage.xaml", UriKind.Relative);
            }

            // Otherwise perform normal launch.
            return uri;
        }
    }
}

In this example, the URI mapper maps the incoming URI to a page named AutoUploadSettingsPage.xaml by replacing the incoming URI with a URI for the auto-upload settings page. The URI returned by that method is then used by the root frame of the app to launch the first page when the app starts. The root frame uses the custom URI mapper because it is assigned as the app initializes. The following code shows how a URI mapper named CustomMapping.CustomUriMapper is assigned in the InitializePhoneApplication method of the App.xaml.cs file.

// Do not add any additional code to this method
private void InitializePhoneApplication()
{
    if (phoneApplicationInitialized)
        return;

    // Create the frame but don't set it as RootVisual yet; this allows the splash
    // screen to remain active until the application is ready to render.
    RootFrame = new PhoneApplicationFrame();
    RootFrame.Navigated += CompleteInitializePhoneApplication;

    // Handle navigation failures
    RootFrame.NavigationFailed += RootFrame_NavigationFailed;

    // Assign the custom URI mapper class to the application frame.
    RootFrame.UriMapper = new CustomMapping.CustomUriMapper();

    // Ensure we don't initialize again
    phoneApplicationInitialized = true;
}

An app that supports auto upload will need two parts: a foreground app project to display the settings page (and other pages), and a background agent to perform the upload.

The background agent must be a resource-intensive agent (it must be registered as a Microsoft.Phone.Scheduler.ResourceIntensiveTask). A resource-intensive agent typically runs for 10 minutes when given the opportunity. It requires a non-cellular connection and an external power source, among other things. For more information about background agents and their constraints, see Background agents for Windows Phone 8.

When you create a resource-intensive agent for your auto-upload app, do not set an expiration time for the task. This will ensure that the agent doesn’t expire if your app hasn’t been opened for 14 days.

Before your app can perform automatic uploads, it will need to provide a way for users to enter their user credentials to the photo storage web service. Your foreground app can use the settings page for this task, but you don’t have to use the same page. For storing user credentials, we recommend encrypting them with the ProtectedData class. For more info, see How to encrypt data for Windows Phone 8.

You background agent is responsible for monitoring the media library, and for keeping track of what photos need to be uploaded. It also needs to track upload status so that it can resume an upload if the phone loses connectivity. For more info about accessing the media library, see the Media Library section in Data for Windows Phone 8.

Show:
© 2014 Microsoft