Guidelines and checklist for background tasks (HTML)

Article
10/06/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Create better background tasks to support your app and ensure your app meets the requirements for running background tasks.

Background task guidance

Consider the following guidance when developing your background task, and before publishing your app.

Close your background tasks: Don't forget that the background task needs to call the close() method when it's done. If the background task doesn't close itself, the process running the background task can continue to consume memory and battery life even though the background task completed or was cancelled.

CPU and network quotas: Don't exceed the CPU quota or network data usage quota applied to your background task. Background tasks should be lightweight to save battery life and provide a better user experience for foreground apps. See Supporting your app with background tasks for the resource constraints applied to background tasks.

Manage background tasks: Your app should get a list of registered background tasks, register for progress and completion handlers, and handle those events appropriately. Your background tasks should report progress, cancellation, and completion. See How to get a list of pending background tasks, How to handle a cancelled background task, and How to monitor background task progress and completion.

Update the app manifest: Declare each background task in the application manifest, along with the type of triggers it is used with. Otherwise your app will not be able to register the background task at runtime. For more information, see How to declare background tasks in the application manifest.

Prepare for app updates: If your app will be updated, create and register a ServicingComplete background task (see SystemTriggerType) to help perform app updates that may be necessary outside the context of running in the foreground.

Background tasks for lock screen-capable apps on Windows: The lock screen is a shared resource. Only seven apps may be placed on the lock screen at any one time, and only one may show a wide tile. Your app can provide a good user experience by requesting lock screen access using the RequestAccessAsync method, and by making sure your app will still work without being on the lock screen. Apps that are not placed on the lock screen can still update tiles, update badges, send notifications, and register for system event triggers. The user experience when your app is in the foreground should never be disrupted even if the user has not placed your app on the lock screen.

Read the Lock screen overview to get a sense for whether or not the lock screen is the right place for your app.

Requesting to execute background tasks for Windows Phone Store apps:

Windows Phone Store apps can run all supported task types without being pinned to the lock screen. However, your app must call RequestAccessAsync before registering any type of background task. This method will return BackgroundAccessStatus.Denied if the maximum number of apps with background tasks across the system has been exceeded or if the user has explicitly denied background task permissions for your app in the device's settings.

For Windows Phone Store apps, if your app will be updated, you must call RemoveAccess and then RequestAccessAsync when your app launches after being updated. To determine when your app has been updated, you should track the version number of your app using a value stored in local settings. When your app is launched, check the version of your app, and if it is newer than the version in local settings then call RemoveAccess and RequestAccessAsync. To do this, add code similar the following and call it from the launching event handler for your app.

function checkAppVersion() {
    var localSettings = Windows.Storage.ApplicationData.current.localSettings;
    var pkgVersion = Windows.ApplicationModel.Package.current.id.version;
    var backgroundExecMgr = Windows.ApplicationModel.Background.BackgroundExecutionManager;

    var appVersion = pkgVersion.build + "." +
                        pkgVersion.major + "." +
                        pkgVersion.minor + "." +
                        pkgVersion.revision;

    if (localSettings.values["appVersion"] != appVersion)
    {
        // Our app has been updated
        localSettings.values["appVersion"] = appVersion;

        // Call removeAccess
        backgroundExecMgr.removeAccess();
    }
        
    backgroundExecMgr.requestAccessAsync();
}

Background task checklist

The following checklist applies to all background tasks.

Associate your background task with the correct trigger.
Add conditions to help ensure your background task runs successfully.
Handle background task progress, completion, and cancellation.
Do not display UI other than toasts, tiles, and badge updates from the background task.
Call close() when the background task is done working.
Use persistent storage to share data between the background task and the app.
Declare each background task in the application manifest, along with the type of triggers it is used with. Make sure the entry point and trigger types are correct.
Write background tasks that are short-lived. Don't exceed the CPU or network quotas shown in Supporting your app with background tasks.
Do not rely on user interaction in background tasks.
Check for background task registration errors. If appropriate, attempt to register the background task again with different parameter values.

Windows: Background task checklist for lock screen-capable apps

Follow this guidance when developing background tasks for apps that are capable of being on the lock screen. Follow the guidance in Guidelines and checklist for lock screen tiles.

Make sure your app needs to be on the lock screen before developing it as lock screen-capable. For more info see Lock screen overview.
Make sure your app will still work without being on the lock screen.
Request lock screen access using the RequestAccessAsync method.
Include a background task registered with TimeTrigger and declare it in the app manifest. Make sure the entry point and trigger types are correct. This is required for certification, and enables the user to place the app on the lock screen.
Write background tasks that are short-lived, even for lock screen-capable apps. Don't exceed the CPU or network quotas shown in Supporting your app with background tasks.
For Windows Phone Store apps, if the device becomes low on memory, background tasks may be terminated without any warning and without raising the OnCanceled event. This helps to ensure the user experience of the app in the foreground. Your background task should be designed to handle this scenario.