How to suspend an app (HTML)

Article
08/31/2015

Learn how to save important application data when the system suspends your Windows Runtime app. When your app is suspended by the system it can later be terminated without warning. It is important to save the user’s current state in the app so that when the app is relaunched you can restore that state. The user should never know that the app was suspended and terminated in the background.

The following steps will show you how to register for the checkpoint event and use it to save some basic app state.

Instructions

Step 1: Register for the checkpoint event

Register for the checkpoint event in the global scope. This event indicates that your app is being suspended by the system. After your app is suspended it could be terminated by the system to free system resources. Because of this, it’s important to save your app’s data during the checkpoint event.


var app = WinJS.Application;

app.addEventListener("checkpoint", checkpointHandler);

Step 2: Save application data before suspension

When your app handles the checkpoint event, it has the opportunity to save its important application data in the handler function for the checkpoint event. The app can use the sessionState object to save simple application data synchronously. The sessionState object persists data so that the app can access it during activation after termination.

function checkpointHandler(eventArgs) 
{
    var stateObject = new Object();

    // TODO: Populate the state object with app data

    // Save the state object to the session object
    app.sessionState.stateObject = stateObject;
}

Step 3: Release exclusive resources and file handles

When your app handles the checkpoint event, it also has the opportunity to release exclusive resources and file handles. Examples of exclusive resources are cameras, I/O devices, external devices, and network resources. Explicitly releasing exclusive resources and file handles helps to ensure that other apps can access them while your app isn't using them. When the app is activated after termination, it should open its exclusive resources and file handles.

Remarks

The system suspends your app whenever the user switches to another app or to the desktop. The system resumes your app whenever the user switches back to it. When the system resumes your app, the content of your variables and data structures is the same as it was before the system suspended the app. The system restores the app exactly where it left off, so that it appears to the user as if it's been running in the background.

The system attempts to keep your app and its data in memory while it's suspended. However, the OS can terminate your app for a number of reasons after it has been suspended. Some examples of when this may happen are: the user manually closes your app, the user logs out, or the system is running low on resources. When the user switches back to an app that has been terminated, the app receives an activated event and should check whether its sessionState objects are defined. If the objects are defined, the app should load that data.

The system doesn't notify an app when it's terminated, so your app must save its application data and release exclusive resources and file handles when it's suspended, and restore them when the app is resumed from suspend or activated after termination.

Note If you need to do asynchronous work when your app is being suspended you will need to defer completion of suspend until after your work completes. You can use the setPromise method on the checkpoint event arg’s detail property to delay completion of suspend until after you complete the promise.

Note To improve system responsiveness in Windows 8.1 and Windows Phone, apps are given low priority access to resources after they are suspended. To support this new priority, the suspend operation timeout is extended so that the app has the equivalent of the 5-second timeout for normal priority on Windows and between 1 and 10 seconds on Windows Phone. You cannot extend or alter this timeout window.

A note about debugging using Visual Studio: Visual Studio prevents Windows from suspending an app that is attached to the debugger. This is to allow the user to view the Visual Studio debug UI while the app is running. When you're debugging an app, you can send it a suspend event using Visual Studio. Make sure the Debug Location toolbar is being shown, then click the Suspend icon.