Share via


Guidelines for background tasks (Windows Runtime apps)

[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.

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 task classes should report progress, cancellation, and completion. For more info 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.

**Use BackgroundTaskDeferral:  **If your background task class runs asynchronous code, make sure to use deferrals. Otherwise your background task might be terminated prematurely when the Run method completes. For more information, see Quickstart: Create and register a background task.

Alternatively, request one deferral, and use async/await to complete asynchronous method calls. Close the deferral after the await method calls.

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.

async void CheckAppVersion()
{
    String appVersion = String.Format("{0}.{1}.{2}.{3}",
            Package.Current.Id.Version.Build,
            Package.Current.Id.Version.Major,
            Package.Current.Id.Version.Minor,
            Package.Current.Id.Version.Revision);

    if (Windows.Storage.ApplicationData.Current.LocalSettings.Values["AppVersion"] != appVersion)
    {
        // Our app has been updated
        Windows.Storage.ApplicationData.Current.LocalSettings.Values["AppVersion"] = appVersion;

        // Call RemoveAccess
        BackgroundExecutionManager.RemoveAccess();
    }

    BackgroundAccessStatus status = await BackgroundExecutionManager.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.

  • In the Run method, request deferrals for each asynchronous method call, and close them when the method is done.

    Or, use one deferral with async/await.

  • 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.

  • Don't specify an Executable element in the manifest unless you are using a trigger that should be run in the same context as the app (such as the ControlChannelTrigger).

  • 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 PushNotificationTrigger, ControlChannelTrigger, or 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.

Quickstart: Create and register a background task

How to register a background task

How to declare background tasks in the application manifest

How to debug a background task

How to trigger suspend, resume, and background events in Windows Store apps (when debugging)

Other related lock screen guidance

Lock screen overview

Displaying tiles on the lock screen

Guidelines and checklist for lock screen tiles