Developing Quality Applications: Data Recovery

Data Recovery and Application Restart

Applications developed under Windows Vista® can be written so that users do not lose their work or documents because of a software problem beyond their control. Preserving a user's experience despite an unrecoverable application error is supported in Windows Vista by Windows Feedback through two complementary mechanisms:

• An application state persistence mechanism to save the state of the terminated application.

• An automatic restart technology to pick up the running of the terminated application.

Because data recovery is central to error handling and application feedback, this technology is available under Windows Feedback.

Resources

Windows Vista provides native access to its Data Recovery and Application Restart technologies through C-callable libraries. .NET Framework 3.0 applications can access this functionality through interoperability support in the Windows SDK. For more information, see Interoperability & Migration.

Libraries	Description
Kernel32.dll	The library containing all the Restart Manager technologies.

Headers	Description
Windows.h	The header file for application restart functionality.

Application and Persistence APIs	Description
RegisterApplicationRecoveryCallback	Notifies the system that the application supports saving its state, and provides a callback function to handle unrecoverable errors.
RecoveryInProgress	Notifies the system that the application is still saving its state.
RecoveryFinished	Notifies the system that the application has finished saving its state.
GetApplicationRecoveryCallback	Used to obtain the application persistence callback function registered by RegisterApplicationRecoveryCallback.

Application and Persistence Callback Functions	Description
APPLICATION_RECOVERY_CALLBACK	Data type used to specify the callback function that is used to save application state and provided through RegisterApplicationRecoveryCallback. Its signature is: DWORD RecoveryRoutine(LPVOID lpParam)

Application Restart APIs	Description
RegisterApplicationRestart	Used by client applications to register how they need to be restarted by the Restart Manager service.
GetApplicationRestart	Used to obtain restart information for a registered process.

Overview

The essentials of providing support both for data and application state persistence and for enabling automatic recovery are straightforward. It is not necessary for an application to support both Data Recovery and Application Restart technologies. For example, an application might use the Windows Vista data and state persistence mechanisms but have its own restart mechanisms. System services, for example, are restarted by the service host (Svchost.dll).

On the other hand, if state is preserved through other mechanisms, the application restart APIs might still be useful. As an example, the Restart Manager used with installers expects applications to save state on receipt of a signal sent to an application's WindowProc, but uses the restart APIs to start and stop applications.

Application State Persistence and Recovery Requirements

To ensure that Windows Vista will try to save an application's state when an unrecoverable error is encountered:

• Create a C-callable routine that is used to save the application's state.

• Register this routine with the system as the data-state handler.

An application should call the registration API on its startup and then maintain state information throughout the life of the application. If an unrecoverable error is encountered, the application's registered data state handler is called to save the state of the application at that point.

Automated Application Restart Requirements

To instrument an application to support automatic restart requires:

• A restart algorithm to be coded in the application, using data stored by the application persistence mechanism or some other mechanism for state storage

• The addition of a command-line switch that supports restarting

• The registration of the application as supporting restarting

Restart registration is performed through an API call, which specifies the command-line arguments used to initialize the application in restart mode.

Prioritizing State Persistence and Application Restart Support

The application restart priorities, detailed in the following paragraphs, are provided to assist developers when deciding whether to provide state persistence and data recovery support for applications.

Application Restart Priority

Priority 1: Applications that work directly on user documents or files. Examples would include image-editing applications, office tools such as word processors and integrated development environments (IDEs). Failure to provide data recovery with these applications places user enterprises at great risk and is documented as a primary source of user fear and frustration.

Priority 2: Applications supporting tasks with well-defined states and complicated configurations. These stateful applications depend on state information that would be lost during application interruption. Examples might include services, multi-step wizards, remote access sessions and document type conversion utilities. The value added here is that the application will be able to quickly restart, without interrupting work or disrupting the other applications that depend on the application.

Priority 3: Stateless applications or applications whose state information is preserved by another means (such as a system queue). These applications can easily be restarted manually, and in many cases (such as printing) this might be preferable to users.

Application State Persistence

Data recovery requires the persistence of an application's state and storage information after the detection of some unrecoverable error. If data is properly persisted, it can be used to initialize a new instance of an application.

Basics

The basic steps for ensuring that application data is persisted under Windows Vista are:

• Determine what state, file and status information is needed to restart an application. Developers may decide on exactly how to do this.

• Create an application and data persistence callback function, invoked by the system when an unrecoverable error is detected in the application. This routine implements an algorithm for saving state and data files. It must have the signature: DWORD RecoveryRoutine(LPVOID lpParam).

The application must register its support for data recovery, including specifying the data recovery callback function by calling RegisterApplicationRecoveryCallback. The application data recovery callback function will be called in the event of unrecoverable error detection.

Application and Data Persistence Callback Function

When writing an application and data persistence callback function, it is important to remember that:

• After the application is started, it is the persistence callback function's responsibility to notify Windows Feedback, at least every 5 (five) seconds, that it is saving application state by calling RecoveryInProgress. This function must be used to accurately reflect that the recovery routine has not stopped responding and is continuing to process data. For this reason, applications should not create a new thread that sleeps and calls RecoveryInProgress alongside threads persisting application state. If the API is not called in a timely manner, the application is assumed to be unable to continue saving state and will be terminated.

• An application state persistence routine is running in a failed process. In general, minimize the amount of work performed in the callback function so that the application can promptly finish saving state.

• Windows Vista provides the ability for a process to register as supporting application recovery and state persistence. The actual APIs used to preserve application state and user data must be created by the application developer.

Typically, applications use one of the following data persistence strategies:

• If state data is periodically saved by the application, the application persistence method might simply attempt to gracefully shut down the running process.

• The data persistence routine writes current state information to disk as quickly as possible. Data reconstruction and verification is delayed until application restart.

• The data persistence routine attempts to verify and correct data to be persisted and then writes it out to disk.

It is possible to combine all these methods, based on status information and the application state.

Note

It is very important that any data saved during an application's shutdown be fully accessible to a new instance of the application created during restart. Permissions should be set so that files can be read and, if necessary, modified.

Restarting Applications

In addition to registering, a restartable application requires the creation of a well-understood restart algorithm, one fully coordinated with the application's persistence algorithm.

Basics

For an application to be restartable requires:

• The application registering itself with the system as restartable by calling RegisterApplicationRestart.

  This registration call takes as an argument a string containing the command-line arguments passed to the application on restart. This string should not include the name of the executable, as the system will always prepend the executable's name.

• The implementation of a restart mechanism.

  This mechanism should be run if the application is started with the command-line arguments defined. The restart mechanism opens, reads and understands data saved by the application's state persistence algorithm. State persistence can be provided through Windows Feedback or by other mechanisms, such as periodic checkpoint files.

Restart Functionality

The exact form of an application's restart functionality will vary widely, depending on the sort of application, how data is preserved and how much user interaction is desired. Minimal support will require an application to:

• Support the command-line argument or arguments supplied to RegisterApplicationRestart.

• Be able to determine the location of any state information or files saved as part of persisting the application.

Best practices should include:

• A mechanism for verifying the correctness of data stored as part of application persistence, and handling corrupted data.

• Creating a duplicate of any data stored by the terminated application instance before modifying it.

• Prompting users for security information for access to sensitive data.

In Depth: Special Case: Services

Services do not typically require automatic restart functionality to handle restarts after unrecoverable problems. Instead, restart should be handled through the service host (Svchost.dll). A server's restart architecture should be designed to be compatible with the service host. However, the application state persistence mechanism is fully available for preserving the service state through an unrecoverable error, and on to restart. It is a best practice to ensure that a service's state was preserved through an unrecoverable error.

In Depth: Special Case: Handling Installation

Although the restart technology used by the Restart Manager to resume applications that were shut down as part of an upgrade or installation is the same as that used to resume applications after an unrecoverable error, the application state persistence technology is different.

Installers do not make use of the application and data persistence callback function registered by RegisterApplicationRecoveryCallback. Instead, a signal is sent to the application's WindowProc, and must be handled in that routine.

To fully support both data recovery and application restart following an unrecoverable error, and application resumption following an upgrade or installation operation, requires that a developer support both technologies for persisting an application's state and data.

To make restarting as easy as possible, the same application state persistence technology should be used for both cases; for example, one could explicitly call the application and data persistence callback function registered by RegisterApplicationRecoveryCallback from within the WindowProc when preserving state due to an installation-based shutdown.

Developing Applications That Can Be Updated Without Reboots

Windows Vista investments allow updates to the operating system and applications to be applied without needing to reboot the system. This is possible with a new technology called Restart Manager. Microsoft installers and patch management tools use these APIs for the following functionality:

• Identify which applications and services have loaded the files that are being replaced.

• Gracefully shutdown applications and services to release the locked files.

• Restart services and registered applications after the files have been replaced.

Applications can follow the guidelines below to ensure that updates can be applied with minimal interruption to the user:

• Use Microsoft Windows Installer to create setup files and updates. Windows Installer automatically takes advantage of Restart Manager.

• Gracefully shutdown when notified by Restart Manager.

• Save user data and application state before shutting down so that work is not lost without prompting the user to save their work.

• Register to be restarted automatically.

Note

Applications needing to create custom installers will need to implement Restart Manager.

Resources

Libraries	Description
Kernel32.dll	Library containing application restart functionality.

Headers	Description
Windows.h	Header file for application restart functionality.

Supporting API	Description
RegisterApplicationRestart	Used by client applications to register how they need to be restarted by the Restart Manager service.
GetApplicationRestart	Used by the Restart Manager service to determine how to restart its client applications.

Closing Applications and Services

Restart Manager closes Graphical User Interface applications, console applications and services using three different methods.

Closing Graphical User Interface (GUI) Applications

Graphical User Interface applications are defined as those supported by a WindowProc message pump. Restart Manager closes these applications by sending the following Windows Messages:

• A WM_QUERYENDSESSION message with an LPARAM value of ENDSESSION_CLOSEAPP.

• If the GUI application's WindowProc returns TRUE, Restart Manager sends a WM_ENDSESSION message with an LPARAM value of ENDSESSION_CLOSEAPP.

Closing Console applications

Console applications are closed by sending signals to the application's console control handler. A CTRL_SHUTDOWN_EVENT is raised by sending a CTRL_C_EVENT signal to the application.

Closing Services

Services and their dependent services are shutdown through Service Control Manager.

Restarting Graphical User Interface Applications and Console Applications

Restart Manager restarts GUI applications and console applications in the same methods described in the Data Recovery and Application Restart section.

Restarting Services

Services are restarted through the Service Control Manager.