App activation and deactivation for Windows Phone 8

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

This topic describes the lifecycle of Windows Phone app and how your app should handle activation and deactivation. On Windows Phone, only one app is running in the foreground at any given time. This is enforced to make sure that the app that the user is actively using has the resources necessary to provide a smooth and responsive experience. Because only one app runs in the foreground at a time, when the user switches away from an app, it is either suspended or terminated, depending on the context and the way that the user navigated away. The Windows Phone application model provides a set of events and related APIs that allow your app to handle activation and deactivation in a way that provides a consistent and intuitive user experience.

Note

Location-aware apps are able to run in the background while they are actively tracking location. For more information, see How to run location-tracking apps in the background for Windows Phone 8.

This topic contains the following sections.

• The Windows Phone app lifecycle
• Summary of Execution Model Events and Application Actions

The Windows Phone app lifecycle

The following image illustrates the lifecycle of a Windows Phone application. In this diagram, the circles are application states. The rectangles show either application- or page-level events where applications should manage their state.

This section discusses the application lifecycle for Windows Phone apps and highlights the actions that your app should take at each step. It refers to events and properties of the PhoneApplicationPage and the PhoneApplicationService objects. These objects are provided for you as part of any of the Windows Phone managed application project templates included with Windows Phone SDK. To see code examples of using these APIs, see How to preserve and restore page state for Windows Phone 8 and How to preserve and restore app state for Windows Phone 8. For a simplified checklist of the events and the actions that your application should perform, see Summary of Execution Model Events and Application Actions.

The Launching Event

A user can launch a new instance of your app by selecting it from the installed applications list or from a Tile on Start in addition to other means, such as tapping on a toast notification associated with the app or selecting the app from the Photos Extras menu. When your app is launched this way, it should present a user interface that makes it clear to the user that a new instance the app was launched. It’s ok to provide context about the user’s previous experience with the app, such as a list of recent documents the user viewed, but it shouldn’t appear as though the user is returning to a previously running instance of the app.

When a new instance of your app is launched, the Launching event is raised. To help ensure that your app loads quickly, you should execute as little code as possible in the handler for this event. In particular, avoid resource-intensive tasks like file and network operations. You should perform these tasks on a background thread after your app has loaded for the best user experience.

Running

After being launched, an app is Running. It continues to run until the user navigates forward, away from the app, or backwards past the app’s first page. Windows Phone apps shouldn’t provide a mechanism for the user to quit or exit. Apps also leave the Running state when the phone’s lock screen engages unless you have disabled application idle detection. For more information, see Idle detection for Windows Phone 8.

The OnNavigatedFrom Method

The OnNavigatedFrom(NavigationEventArgs) method is called whenever the user navigates away from one of the pages in your app. This can happen as the result of normal page navigation within your application, but it is also called if the user navigates away from your app. Whenever this method is called, your application should store the page state so that it can be restored if the user returns to the page and the page is no longer in memory. The exception to this is backward navigation. The NavigationMode property can be used to determine if the navigation is a backward navigation, in which case there is no need to save state because the page will be re-created the next time it is visited.

In some cases, you may want to save state in the OnNavigatingFrom(NavigatingCancelEventArgs) method as well. In particular, you will need to do this to store the state of a MediaElement control.

The Deactivated Event

The Deactivated event is raised when the user navigates forward, away from your app, by pressing the Start button or by launching another application. The Deactivated event is also raised if your application launches a Chooser. For more information about Choosers, see Launchers and Choosers for Windows Phone 8. This event is also raised if the device’s lock screen is engaged, unless application idle detection is disabled.

In the handler for the Deactivated event, your application should save any unsaved application data so that it can be restored at a later time, if necessary. Windows Phone applications are provided with the State object, which is a dictionary you can use to store application state. If the operating system tombstones your app, as discussed below, it will save this dictionary and return it to you if your app is reactivated..

It is possible for an application to be completely terminated after Deactivated is called. When an application is terminated, its state dictionary is not preserved. So you should also store any unsaved state that should be persisted across application instances to isolated storage during the Deactivated event.

Dormant

When the user navigates forward, away from an app, after the Deactivated event is raised, the operating system will attempt to put the app into a dormant state. In this state, all of the application’s threads are stopped and no processing takes place, but the application remains intact in memory. If the app is reactivated from the dormant, it doesn’t need to do anything to re-establish state, because it has been preserved.

If new apps are launched after an app has been made dormant, and these applications requires more memory than is available to provide a good user experience, the operating system will begin to tombstone dormant applications to free up memory.

Tombstoned

A tombstoned app has been terminated, but the operating system preserves information about its navigation state and also preserves the state dictionaries the app populated during Deactivated. The device will maintain tombstoning information for up to five apps at a time. If an app is tombstoned and the user navigates back to the application, it will be relaunched and the application can use the preserved data to restore state.

The Activated Event

The Activated event is called when the user returns to a dormant or tombstoned app. Your app should check the IsApplicationInstancePreserved property of the event args to determine whether it is returning from being dormant or tombstoned. If IsApplicationInstancePreserved is true, then your app was dormant and state was automatically preserved by the operating system. If it is false, then your app was tombstoned and should use the state dictionary to restore application state. Applications should not perform resource-intensive tasks such as loading from isolated storage or a network resource during the Activated event handler because it increase the time it takes for the application to resume. Instead, these operations should be performed on a background thread after the application has loaded. Because the state dictionaries you saved during Deactivated are present in memory when your app is reactivated, you can use them to restore state without the overhead of resource-intensive file operations.

The OnNavigatedTo Method

The OnNavigatedTo(NavigationEventArgs) method is called when the user navigates to a page. This includes when the app is first launched, when the user navigates between the pages of the app, and when the app is relaunched after being made dormant or tombstoned. In this method, your app should check to see whether the page is a new instance. If it is not, then page state does not need to be restored. If the page is a new instance, and there is data in the state dictionary for the page, then you should use this data to restore the state of the page’s UI.

The Closing Event

The Closing event is raised when the user navigates backwards past the first page of an app. In this case, the app is terminated and no state is saved. In the Closing event handler, your app can save data that should persist across instances. There is a limit of 10 seconds for an app to complete all application and page navigation events. If this limit is exceeded, the application is terminated. For this reason, it is a good idea to save persistent state throughout the lifetime of the application and avoid having to do large amounts of file I/O in the Closing event handler.

Warning

If your app is terminated by the operating system while it is not in the foreground, the Closing event will not be raised. Your app can rely on receiving the Deactivated event, but not Closing. For this reason, you should perform all essential cleanup and state maintenance tasks in the Deactivated event handler.

Summary of Execution Model Events and Application Actions

The following table is a brief summary of the events that occur during the application lifecycle and the actions that apps should take for each event.

Event or method	Application action
Launching event	Execute very little code. Do not do resource-intensive operations like accessing isolated storage.
OnNavigatedFrom method	If not a backward navigation, save UI state to State dictionary.
Deactivated event	Save app state to State in case the app is tombstoned. Also, save persistent state to isolated storage in case the application is terminated. Do not destroy the app state in memory in case the app is made dormant.
Activated event	Check IsApplicationInstancePreserved. If true, do nothing. If false, use data in State to restore application state.
OnNavigatedTo method	Check whether the page is a new instance. If not, the state is automatically intact. Otherwise, if there is data in State, use it to restore UI.
Closing event	Save persistent application data to isolated storage.

Warning

The events described in this section give you opportunities to save and restore state as your application enters and leaves the foreground. However, the recommended practice is to save state data as the data changes. For example, the results of a web request can be saved to disk or the application state dictionary (or both) at the moment it arrives from the network. You should not wait until the Deactivated event occurs to store this data. Remember that all application lifecycle events enforce a limit of 10 seconds for an application to complete any tasks.