Background agents for Windows Phone 8

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

Scheduled Tasks and background agents allow an application to execute code in the background, even when the application is not running in the foreground. The different types of Scheduled Tasks are designed for different types of background processing scenarios and therefore have different behaviors and constraints. This topic describes the scheduling, duration, and limitations of scheduled tasks.

This topic contains the following sections.

Types of Scheduled Tasks

The following are the types of Scheduled Tasks. Note that ScheduledTask derives from ScheduledAction. The code that runs in the background is placed in a class that derives from ScheduledTaskAgent, which derives from BackgroundAgent.

Scheduled Task Type

Description

PeriodicTask

Periodic agents run for a small amount of time on a regular recurring interval. Typical scenarios for this type of task include uploading the device’s location and performing small amounts of data synchronization.

ResourceIntensiveTask

Resource-intensive agents run for a relatively long period of time when the phone meets a set of requirements relating to processor activity, power source, and network connection. A typical scenario for this type of task is synchronizing large amounts of data to the phone while it is not being actively used by the user.

Background Agent Lifecycle

An application may have only one background agent. This agent can be registered as a PeriodicTask, a ResourceIntensiveTask, or both. The schedule on which the agent runs depends on which type of task it is registered as. The details of the schedules are described later in this topic. Only one instance of the agent runs at a time.

The code for the agent is implemented by the application in a class that inherits from BackgroundAgent. When the agent is launched, the operating system calls OnInvoke(ScheduledTask). In this method, the application can determine which type of ScheduledTask it is being run as, and perform the appropriate actions. When the agent has completed its task, it should call NotifyComplete()()() or Abort()()() to let the operating system know that it has completed. NotifyComplete should be used if the task was successful. If the agent is unable to perform its task – such as a needed server being unavailable - the agent should call Abort, which causes the IsScheduled property to be set to false. The foreground application can check this property when it is running to determine whether Abort was called.

Constraints for all Scheduled Task Types

The following constraints apply to all Scheduled Tasks.

Constraint

Description

Unsupported APIs

There is a set of APIs that cannot be used by any Scheduled Task. Using these APIs either will cause an exception to be thrown at run time or will cause the application to fail certification during submission to Store. For the list of restricted APIs, see Unsupported APIs for background agents for Windows Phone 8.

Memory usage cap

Periodic agents and resource-intensive agents can use no more than 20 MB of memory at any time on devices with 1 GB of memory or more. On lower-memory devices, the limit is 11 MB. Audio agents have the memory caps described below. If a Scheduled Task exceeds these memory caps, it is terminated immediately.

Both types of background audio agents are hosted in the same process and share the following maximum memory limits.

  1. 25 MB on Windows Phone 8 with Windows Phone 8 Update 3 (that is, with a version equal to or greater than 8.0.10492).

  2. 20 MB on Windows Phone 8 without Windows Phone 8 Update 3 (that is, with a version less than 8.0.10492).

  3. 15 MB on Windows Phone OS 7.1.

When running under the debugger, memory and timeout restrictions are suspended. You can use the ApplicationMemoryUsageLimit API to query the memory limit for both foreground applications and background agents.

Reschedule required every two weeks

Use the ExpirationTime property of the ScheduledTask object to set the time after which the task no longer runs. This value must be set to a time within two weeks of the time when the action is scheduled with the Add(ScheduledAction) method. When the application associated with the task is run in the foreground, it may reschedule the task and reset the expiration time to up two weeks from the current time.

There are a few cases where an app’s background agent will not expire or will be automatically renewed.

  • If the Tile for your app is pinned to the phone’s Start screen, the expiration time for your background agent schedule is automatically extended to two weeks whenever your background agent calls Update(ShellTileData) to update the Tile. For more information, see Tiles for Windows Phone 8.

  • If your app is selected by the user to display notifications on the on the lock screen, the expiration time for your background agent schedule is automatically extended to two weeks whenever your background agent calls Update(ShellTileData) to update the lock screen. For more information, see Lock screen notifications for Windows Phone 8.

  • If your app auto-uploads photos using a resource-intensive agent, the resource-intensive agent schedule will not expire as long as the user has enabled this feature for your app in the photos+camera settings page. For more information, see Auto-upload apps for Windows Phone 8.

Agents unscheduled after two consecutive crashes

Both periodic and resource-intensive agents are unscheduled if they exit two consecutive times due to exceeding the memory quota or any other unhandled exception. The agents must be rescheduled by the foreground application.

Constraints for Periodic Agents

The following are the schedule, duration, and general constraints for Periodic agents.

Constraint

Description

Scheduled interval: 30 minutes

Periodic agents typically run every 30 minutes. To optimize battery life, periodic agents may be run in alignment with other background processes and therefore the execution time may drift by up to 10 minutes.

Scheduled duration: 25 seconds

Periodic agents typically run for 25 seconds. There are other constraints that may cause an agent to be terminated early.

Battery Saver mode can prevent execution

Battery Saver mode is an option that the user can enable on the device to indicate that battery life should be prioritized. If this mode is enabled, periodic agents may not run, even if the interval has elapsed.

Per-device periodic agent limit

To help maximize the battery life of the device, there is a hard limit on the number of periodic agents that can be scheduled on the phone. It varies per device configuration and can be as low as 6. There is another limit, which is lower than the hard limit, after which the user is warned that they have multiple background agents running and may, therefore, experience faster battery consumption.

Caution:
If you attempt to add a periodic background agent when the device’s limit has been exceeded, the call to Add(ScheduledAction) will throw an InvalidOperationException. Because the per-device limit on periodic agents is low, it is likely that your application will encounter this exception. For this reason, it is very important that you catch this exception when adding periodic agents so that your application does not crash. Example code for this can be found in Background agent best practices for Windows Phone 8.

Constraints for Resource-intensive Agents

The following are the schedule, duration, and general constraints for Resource-intensive agents.

Constraint

Description

Duration: 10 minutes

Resource-intensive agents typically run for 10 minutes. There are other constraints that may cause an agent to be terminated early.

External power required

Resource-intensive agents do not run unless the device is connected to an external power source.

Non-cellular connection required

Resource-intensive agents do not run unless the device has a network connection over Wi-Fi or through a connection to a PC.

Minimum battery power

Resource-intensive agents do not run unless the device’s battery power is greater than 90%.

Device screen lock required

Resource-intensive agents do not run unless the device screen is locked.

No active phone call

Resource-intensive agents do not run while a phone call is active.

Cannot change network to cellular

If a resource-intensive agent attempts to call AssociateToNetworkInterface(Socket, NetworkInterfaceInfo) specifying either MobileBroadbandGSM()()() or MobileBroadbandCDMA()()(), the method call fails.

If a device reaches a state where all of the required conditions are met and a resource-intensive agent is launched, and then the device state changes so that any of the conditions are not met, the resource-intensive agent is terminated immediately.

Warning

Due to the constraints on the device that must be met for resource-intensive agents to run, it is possible that the agent will never be run on a particular device. For example, if a user does not have access to Wi-Fi or a PC, they may never have a non-cellular connection and the resource-intensive agents on their device will never run. Also, resource-intensive agents are run one at a time, so as more applications that use resource-intensive agents are installed on a device, the likelihood of an agent running becomes even less. You should consider this when designing your application.

See Also

Other Resources

Background agent best practices for Windows Phone 8

How to implement background agents for Windows Phone 8