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
- Background Agent Lifecycle
- Constraints for all Scheduled Task Types
- Constraints for Periodic Agents
- Constraints for Resource-intensive Agents
- Related Topics
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 |
|---|---|
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. |
|
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.
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.
|
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. .gif "Caution note") 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.