Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Supporting your app with background tasks (HTML)

Applies to Windows and Windows Phone

The topics in this section show how to run your own lightweight code in the background by responding to triggers with background tasks. Background tasks are separate JavaScript files that the OS runs in the background. You can use background tasks to provide functionality when your app is suspended or not running. In JavaScript, you can also run background tasks on a timer.

Background tasks use the Windows.UI.WebUI.WebUIBackgroundTaskInstance namespace to get information about the current instance of the background task. You register background tasks by using a BackgroundTaskBuilder object. The background task JavaScript file is specified as the entry point while registering the background task.

To get started quickly with a background task, see Quickstart: Create and register a background task.

Background tasks for system events

Your app can respond to system-generated events by registering a background task with the SystemTrigger. An app can use any of the following system event triggers (defined in SystemTriggerType) without being placed on the lock screen.

Trigger nameDescription

InternetAvailable

The Internet becomes available.

NetworkStateChange

A network change such as a change in cost or connectivity occurs.

OnlineIdConnectedStateChange

Online ID associated with the account changes.

SmsReceived

A new SMS message is received by an installed mobile broadband device.

TimeZoneChange

The time zone changes on the device (for example, when the system adjusts the clock for daylight saving time).

 

For more info see How to respond to system events with background tasks.

Conditions for background tasks

You can control when the background task runs, even after it is triggered, by adding a condition. Once triggered, a background task will not run until all of its conditions are met. The following conditions (represented by the SystemConditionType enumeration) can be used.

Condition nameDescription
InternetAvailable

The Internet must be available.

InternetNotAvailable

The Internet must be unavailable.

SessionConnected

The session must be connected.

SessionDisconnected

The session must be disconnected.

 

For more info see How to set conditions for running a background task.

Application manifest requirements

Before your app can successfully register a background task, it must be declared in the application manifest. For more info see How to declare background tasks in the application manifest.

Background tasks for lock screen-capable apps

Apps can be placed on the lock screen to show real-time information to the user at a glance. The following real-time triggers can be used to run lightweight custom code in the background for apps that are on the lock screen:

Control Channel:  Background tasks can keep a connection alive, and receive messages on the control channel, by using the ControlChannelTrigger. For more info see How to use the control channel trigger. (Note that control channel background tasks can only be implemented in C# or C++.) The ControlChannelTrigger is not supported on Windows Phone.

Timer:  Background tasks can run as frequently as every 15 minutes, and they can be set to run at a certain time, by using the TimeTrigger. For more info see How to run a background task on a timer.

Push Notification:  Background tasks respond to the PushNotificationTrigger to receive raw push notifications. For more info see How to receive raw notifications.

  • Applies to Windows

The user must place your app on the lock screen before the app can use these background tasks. An app can request lock screen access by calling RequestAccessAsync. This presents a dialog box asking the user to "allow" or "don't allow" your app on the lock screen. An app is only allowed to ask for lock screen access once; any subsequent calls to RequestAccessAsync are ignored.

  • Applies to Windows Phone

Windows Phone apps can use all of the supported background triggers without being pinned to the lock screen. However, a phone app must call RequestAccessAsync before registering any of the background trigger types.

To ensure that your Windows Phone app continues to run properly after you release an update, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. For more information, see Guidelines for background tasks (Windows Runtime apps).

System event triggers for lock screen-capable apps

Note  The SystemTriggerType enumeration includes the following system event triggers that are only usable by lock screen-capable apps. An app must be placed on the lock screen before it can register a background task with any of these system event triggers.

Trigger nameDescription

UserPresent

The background task is triggered when the user becomes present.

UserAway

The background task is triggered when the user becomes absent.

ControlChannelReset

The background task is triggered when a control channel is reset.

SessionConnected

The background task is triggered when the session is connected.

 

The following system event triggers are also for lock screen-capable apps. These triggers can be registered even when the app is not on the lock screen, making it possible to recognize when the user has moved the app on or off the lock screen.

Trigger nameDescription

LockScreenApplicationAdded

An app tile is added to the lock screen.

LockScreenApplicationRemoved

An app tile is removed from the lock screen.

 

Background task resource constraints

Background tasks are lightweight. Keeping background execution to a minimum ensures the best user experience with foreground apps and battery life. This is enforced by applying resource constraints to background tasks:

  • CPU usage is limited as follows.

    CPU usage quotaRefresh time
    Windows App not on lock screen

    1 second

    2 hours

    WindowsApp on the lock screen

    2 seconds

    15 minutes

    Windows Phone App

    2 seconds

    15 minutes

     

  • When running on battery (DC power), background tasks also have a network data usage limit. This limit is a function of the amount of energy used by the network interface, so it varies depending on the device and network environment - but it can be estimated.

    The following table characterizes network data throughput, assuming a resource constrained WiFi network capable of 1Mbps of average data throughput. To estimate the correct limit, multiply by the average megabits per second (Mbps) of the connection. For example, an app can use 25 MB of data every 2 hours on a 10Mbps WiFi connection if it's placed on the lock screen. The example WiFi interface assumes minimal interference.

    Refresh period15 minutes2 hoursDaily
    Data limit (on lock screen)0.469 MBn/a45 MB
    Data limit (not on lock screen)n/a0.625 MB7.5 MB

     

    Note  The network data usage limit is lifted when the device is plugged in (AC power), but the CPU usage quota still applies. Similarly, the CPU and network resource constraints are suspended for an app's background tasks while the user is interacting with it in the foreground.

  • Applies to Windows Phone

Additional background task resource constraints for Windows Phone

In addition to the resource constraints described in the previous section, background tasks on Windows Phone also have the following constraints.

Memory constraints

Due to the resource constraints for the phone form factor, especially for low-memory devices, background tasks for Windows Phone apps have a memory limit that determines the maximum amount of memory the background task can use. If your background task exceeds this limit, it will be terminated immediately. The memory allocation depends on the type of background task as well as the total system memory of the device on which it's running. You should consider these limits while developing and testing your app. You can also use the MemoryManager APIs to query your current memory usage and limit in order to adjust your usage at runtime. The following table lists the memory caps, in megabytes, for the specified background task types for different amounts of total system memory on the device.

Background task type512 MB1 GB2 GB or greater
Location163040
Bluetooth161616
Servicing Complete101010
Other background tasks163040
Limit while debugging304050

 

Per-device limit for apps with background tasks for low-memory devices

On phones with 512 MB of memory, there is a limit to the number of apps that can be installed on a device and use background tasks at any given time. If this number is exceeded, the call to RequestAccessAsync, which is required to register all background tasks on Windows Phone, will fail.

Battery Saver

On Windows Phone, the Battery Saver feature, when enabled, will prevent background tasks from running when the device is not connected to external power and the battery goes below a specified amount of power remaining. This will not prevent you from registering background tasks.

Maintenance trigger

Your app can also run tasks as frequently as every 15 minutes by using the maintenance trigger. Instead of requiring placement on the lock screen, maintenance tasks only run when the device is plugged in to AC power. For more info see How to use maintenance triggers.

Background task for sensors and devices

Your app can access sensors and peripheral devices from a background task with the DeviceUseTrigger class. You can use this trigger for long-running operations such as data synchronization or monitoring. Unlike tasks for system events, a DeviceUseTrigger task can only be triggered while your app is running in the foreground and no conditions can be set on it. Depending where it's running (PC or phone), a DeviceUseTrigger background task supports different APIs, and is subject to different policies. To learn more about these differences, see Accessing sensors and devices from a background task.

Some critical device operations, such as long running firmware updates, cannot be performed with the DeviceUseTrigger. Such operations can be performed only on the PC, and only by a privileged app that uses the DeviceServicingTrigger. A privileged app is an app that the device's manufacturer has authorized to perform those operations. Device metadata is used to specify which app, if any, has been designated as the privileged app for a device. For more info, see Device sync and update for Windows Store device apps.

Managing background tasks

Background tasks can report progress, completion, and cancellation to your app using events and local storage. Your app can also catch exceptions thrown by a background task, and manage background task registration during app updates. For more info see:

How to handle a cancelled background task

How to get a list of pending background tasks

How to monitor background task progress and completion

How to use the ServicingComplete trigger

Related topics

Conceptual guidance for multitasking in Windows 8
Introduction to Background Tasks
Launching, resuming, and multitasking
UI guidance for the lock screen
Displaying tiles on the lock screen
Guidelines and checklist for lock screen tiles
Related background task guidance
Guidelines and checklist for background tasks
How to debug a background task
How to trigger suspend, resume, and background events in Windows Store apps (when debugging)
Accessing sensors and devices from a background task
Device sync and update for Windows Store device apps

 

 

Show:
© 2014 Microsoft