App lifecycle

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

This topic describes the lifecycle of a Windows Runtime app, from the time it is deployed through its removal. By launching, suspending, and resuming your app appropriately, you ensure that your customer has the best possible experience with your app.

App execution state

This illustration represents the transitions between app execution states. We describe these states and events in the next several sections. For more info about each state transition and what your app should do in response, see the reference for the ApplicationExecutionState enumeration.

Deployment

In order for an app to be activated in any way, it must first be deployed. Basic deployment is taken care of either when a user installs your app or when you use Visual Studio to build and run your app locally during development and testing. For more info on this and on advanced deployment scenarios, see App packages and deployment.

App launch

An app is launched whenever it is activated by the user and the app process was previously in the NotRunning state. An app could be in the NotRunning state because it has never been launched, because it was running but then crashed, or because it was suspended but then couldn't be kept in memory and was terminated by the system.

When an app is launched, Windows displays a splash screen for the app. To configure this splash screen, see "Adding a splash screen" (HTML or XAML).

While the splash screen is displayed, your app code should ensure that the app is ready for its user interface to be displayed to the user. The primary tasks for the app are to register event handlers and set up any custom UI it needs for loading the initial page. These tasks should only take a few seconds. If an app needs to request data from the network or needs to retrieve large amounts of data from disk, these activities should be completed outside of activation. An app can use its own custom loading UI or an extended splash screen while it waits for these long running operations to finish. See "How to extend the splash screen" (HTML or XAML) and the Splash screen sample for more info. After the app completes activation, it enters the Running state and the splash screen disappears (and all its resources and objects are cleared). Showing a window, returning from the activation handler, and completing a deferral are specific ways that an app completes activation. For more info, see "How to activate an app" (HTML or XAML).

App activation

An app can be activated by the user through a variety of contracts and extensions. To participate in activation, your app must register to receive the WinJS activated event (HTML) or override the OnActivated method (XAML). (For HTML, WebUIApplication.activated is another event you can handle for activation.)

Your app's activation code can test to see why it was activated and whether it was already in the Running state. Apps can be activated using any of these activation types:

Apps that are built for Windows 8.1 and later can be activated by any of the above, or can be activated with these activation types.

Windows Phone apps can be activated with these types.

Your app can use activation to restore previously saved data in the event that the operating system terminates your app, and subsequently the user re-launches it. Windows may terminate your app after it has been suspended for a number of reasons. The user may manually close your app, or sign out, or the system may be running low on resources. If the user launches your app after Windows has terminated it, the app receives an activated event (HTML) or Application.OnActivated callback (XAML) and the user sees the splash screen of your app until the app is activated. You can use this event to determine whether your app needs to restore the data which it had saved when it was last suspended, or whether you must load your app’s default data. Because the splash screen is up, your app code can invest some processing time to get this done without there being any apparent delay to the user, but previously-mentioned concerns about long-running operations also apply if you're restarting or continuing. The activated/OnActivated event data includes a PreviousExecutionState property that tells you which state your app was in before it was activated. This property is one of the values from the ApplicationExecutionState enumeration:

Note  Current user session is based on Windows logon. So long as the current user hasn't explicitly logged off, shut down, or Windows hasn't restarted for other reasons, the current user session persists across events such as lock screen authentication, switch-user and so on.

PreviousExecutionState could also have a value of Running or Suspended, but in these cases your app was not previously terminated and therefore you don’t have to worry about restoring data.

Note  

If you log on using the computer's Administrator account, you can't activate any Windows Runtime app.

For more info, see App extensions.

OnActivated versus specific activations in a XAML app

For the XAML activation model and Application class, the OnActivated method is the means to handle all possible activation types. However, it's more common to use different methods to handle the most common activation types, and use OnActivated only as the fallback method for the less common activation types. For example, Application has an OnLaunched method that's invoked as a callback whenever ActivationKind is Launch, and this is the typical activation for most apps. There are 6 more On* methods for specific activations: OnCachedFileUpdaterActivated, OnFileActivated, OnFileOpenPickerActivated, OnFileSavePickerActivated, OnSearchActivated, OnShareTargetActivated. Starting templates for a XAML app have an implementation for OnLaunched and a handler for Suspending, with both of these incorporating methods from the SuspensionManager class that comes predefined in each template. Describing what SuspensionManager does is outside the scope of this topic; for more info see C#, VB, and C++ project templates for apps.

App suspend

An app can be suspended when the user switches away from it or when the device enters a low power state. Most apps are suspended when the user switches away from them.

When the user moves an app to the background, Windows waits a few seconds to see whether the user immediately switches back to the app. If the user does not switch back within this time window, Windows suspends the app.

If an app has registered an event handler for the WinJS checkpoint event (for HTML) or the Application.Suspending event (for XAML), this code is called immediately before the app is suspended. You can use the event handler to save relevant app and user data. We recommended that you use the application data APIs for this purpose because they are guaranteed to complete before the app enters the Suspended state. For more info, see Accessing app data with the Windows Runtime. You should also release exclusive resources and file handles so that other apps can access them while your app isn't using them.

Generally, your app should save its state and release its exclusive resources and file handles immediately when handling the suspending event, and the code should not take more than a second to complete. If an app does not return from the suspending event within 5 seconds on Windows and between 1 and 10 seconds on Windows Phone, Windows assumes that the app has stopped responding and terminates it.

Windows attempts to keep as many suspended apps in memory as possible. Keeping these apps in memory ensures that users can quickly and reliably switch between suspended apps. However, if there aren't enough resources to keep your app in memory, Windows can terminate your app. Individual apps don't receive notification that they are being terminated, so the only opportunity you have to save your app's data is during suspension. When an app determines that it is activated after being terminated, it should load the application data that it saved during suspend so that the app functions as it did before it was suspended.

There are some app scenarios where the app must continue to run to complete background tasks. For example, your app can continue to play audio in the background; for more info, see "How to play audio in the background" (HTML or XAML). Also, background transfer operations continue even if your app is suspended or even terminated; for more info, see "How to download a file" (HTML or XAML).

For guidelines, see Guidelines for app suspend and resume.

For example code, see "How to suspend an app" (HTML or XAML).

App visibility

When the user switches from your app to another app, your app is no longer visible but remains in the Running state until Windows can suspend it. If the user switches away from your app but activates or switches back to it before it can suspended, the app remains in the Running state.

Your app doesn't receive an activation event when app visibility changes, because the app is still running. Windows simply switches to and from the app as necessary. If your app needs to do something when the user switches away and back, it can handle the visibilitychange event (for HTML) or Window.VisibilityChanged event (for XAML).

The visibility event is not serialized with the suspend/resume or activation events. Don't assume that these events come in a particular order.

App resume

A suspended app is resumed when the user switches to it or when the device comes out of a low power state.

For an enumeration of the states that your app can be in when your app is resumed, see ApplicationExecutionState. When an app is resumed from the Suspended state, it enters the Running state and continues from where it was when it was suspended. No app data is lost, so long as it was stored in memory. Therefore, most apps don't need to do anything when they are resumed. However, the app could have been suspended for hours or even days. So if your app has content or network connections that may have gone stale, these should be refreshed when the app resumes. If an app registered an event handler for the WebUIApplication.resuming event (HTML) or Application.Resuming event (XAML), it is called when the app is resumed from the Suspended state. You can refresh your app content and data using this event handler.

Note  

HTML apps usually don't need to handle resuming specifically, because activated fires in the same circumstances. You can use ActivationKind info from the activated event data to determine whether the app is resuming; this pattern is shown in the default.js file for starting project templates.

If a suspended app is activated to participate in an app contract or extension, it receives the Resuming event first, then the Activated event.

When an app is suspended, it does not receive network events that it registered to receive. These events are not queued, they are simply missed. Therefore, your app should test the network status when it is resumed.

For guidelines, see Guidelines for app suspend and resume.

For example code, see "How to resume an app" (HTML or XAML).

Note  In Windows Phone Store apps, for a XAML app, OnLaunched is called each time the user launches the app from Start tile or app list, even when the app is currently suspended in memory. On Windows, launching a suspended app from Start tile or app list doesn’t call this method.

App close

Generally, users don't need to close apps, they can let Windows manage them. However, users can choose to close an app using the close gesture or by pressing Alt+F4 on Windows or by using the task switcher on Windows Phone. You can't include any UI in your app to enable the user to close your app, or it won't pass the Store certification process.

There's no special event to indicate that the user has closed an app.

After an app has been closed by the user, it's suspended and terminated, and then enters the NotRunning state.

In Windows 8.1 and later, after an app has been closed by the user, the app is removed from the screen and switch list but not explicitly terminated.

Note  If your app depends on the closed-by-user behavior of Windows 8, you can enable this behavior in your app when you upgrade it to Windows 8.1. To enable the closed-by-user behavior of Windows 8, set your Windows 8.1 app to terminate when the last window is closed with the ApplicationView.TerminateAppOnFinalViewClose property.

If an app has registered an event handler for the Suspending event, it is called when the app is suspended. You can use this event handler to save relevant application and user data to persistent storage.

Closed-by-user behavior: We recommend that you decide how your app behaves when it's activated after being closed by the user. It may make no difference to you whether the app was terminated by Windows or by the user. If your app needs to do something different when it is closed by the user than when it is closed by Windows, you can use the activation event handler to determine whether the app was terminated by the user or by Windows. See the descriptions of ClosedByUser and Terminated states in the reference for the ApplicationExecutionState enumeration. If you're maintaining a Windows 8 app, note that the handling for ClosedByUser is potentially different than for a Windows 8.1 app.

We recommend that apps not close themselves programmatically unless absolutely necessary. For example, if an app detects a memory leak, it can close itself to ensure the security of the user's personal data. When you close an app programmatically, the system treats this as an app crash.

App crash

Apps are required to follow the system crash experience, which is to simply return to the Start screen. The system crash experience is designed to get users back to what they were doing as quickly as possible, so you shouldn't provide a warning dialog or other notification because that'll cause a delay for the user. The disappearance of the app should make it clear to the user that something went wrong.

If your app crashes, stops responding, or generates an exception, Windows asks the user for consent to send a problem report to Microsoft. Microsoft provides a subset of the error data in the problem report to you so that you can use it to improve your app. You'll be able to see this data in your app's Quality page in your Dashboard.

When the user activates an app after it crashes, its activation event handler receives an ApplicationExecutionState value of NotRunning, and should display its initial UI and data. After a crash, don't routinely use the app data you would have used for Resuming with Suspended because that data could be corrupt; see Guidelines for app suspend and resume.

App removal

When a user deletes your app, the app is removed, along with all its local data. Removing an app doesn't affect the user's data that was stored in common locations, such as files in the Documents or Pictures libraries.

App lifecycle and the Visual Studio project templates

For either HTML or XAML apps, basic code that is relevant for app lifecycle is provided in the starting Visual Studio project templates. The basic app handles launch activation and displays its primary UI even before you've added any of your own code. For more info, see JavaScript project templates for Store apps or C#, VB, and C++ project templates for apps.

Application lifecycle key APIs

• Windows.ApplicationModel namespace
• Windows.ApplicationModel.Activation namespace
• Windows.ApplicationModel.Core namespace
• Windows.UI.WebUI namespace (HTML)
• Windows.UI.Xaml.Application class (XAML)
• Windows.UI.Xaml.Window class (XAML)
• WinJS.Application namespace (HTML)

Related topics

Guidelines for app suspend and resume

App activated, resume, and suspend sample (JavaScript)