Windows Installer and Restart Manager: MSI Files-In-Use V2

Introduction

Files-In-Use functionality is among the countless services that Windows Installer exposes for setup authors to leverage for their application install/maintenance. This functionality lets setup authors display the processes that hold on to files that would be updated by this install. The user would want to shut those processes before continuing with the install to ensure that the install wouldn’t require a reboot. The current Files-In-Use mechanism involves enumerating the HKEY_PERFORMANCE_DATA key using registry API for information on processes and the PE images that they have held in-use. This works well in scenarios where the process holding the file in use has a visible window that the user can shut down.

Usage of the new Restart Manager API’s will allow Windows Installer to display processes such as: system services, tray applications or applications that have no visible window that require shutting down to avoid a reboot. Additionally, Restart Manager provides additional functionality above-and-beyond enhanced files in use detection, including:

·      Shutting down of all or selected processes.

·      Automatic restart of processes that were shutdown to install the in-use files.

·      Ability to join a currently running Restart Manager session to consolidate shutdown/reboot across multiple installations.

·      Appilications that had been shut down, have the opportunity to be restarted to a state that they were before being shut down.

Terminology

Sessions. Sessions in this blog refer to Terminal Service sessions. On Vista services run in session 0, while users log in to different non-zero sessions.

Client. Client in this blog refers to the invoker of the install. Remember that while an install could be invoked by a call to MsiInstallProduct, MsiApplyMultiplePatches, etc., the install (updating the system) is actually performed by the Windows Installer service. This is a different process running in session 0 (on Vista).

Comparison of Pre-Vista Files-In-Use Vs Vista Files-In-Use

Basic UI

A new dialog resource is added to Windows Installer on Vista that is displayed when running in basic UI mode. This dialog, unlike its legacy counterpart displays the processes that are holding onto files-in-use. Additionally, this dialog will also provide users with the option to shutdown/restart these processes to avoid the reboot. The figure below compares the basic UI files-in-use dialog boxes on Pre-Vista and Vista. Note how due to the better detection mechanism of restart manager, we are able to display a service that needs to be stopped for this install to actually avoid a reboot.

Full UI

When run in full UI, to leverage the restart manager’s abilities completely, the package author could provide a new MsiRMFilesInUse dialog box. See the image below for a comparison of how the old files-in-use dialog looks on XPSP2 and how the new RM files-in-use dialog on Vista looks like.

External UI

Pre-Vista, external UI handlers could listen to files-in-use messages using the INSTALLLOGMODE_FILESINUSE flag. These setups would then receive a INSTALLMESSAGE_FILESINUSE message with list of processes that need to be shutdown for the install to not require a reboot. These setups will continue to receive these messages even on Vista.

New setups, however, will get chance to leverage the Windows Installer-Restart Manager interaction to shutdown and restart those processes automatically. Such setups could listen to the INSTALLMESSAGE_RMFILESINUSE message after they subscribe to it in their call to MsiSetExternalUI by specifying INSTALLLOGMODE_RMFILESINUSE in the flags to this call. The table below summarizes Windows Installer’s response to various return values from an external UI that handles the INSTALLMESSAGE_RMFILESINUSE message

No UI

When a silent install is performed, Windows Installer will use restart manager to detect the processes that need to be shutdown to mitigate the reboot and will request restart manager to automatically shutdown these processes. Upon completion of the update, Windows Installer will request restart manager to start up the processes.

Controlling Windows Installer’s interaction with Restart Manager

Windows Installer provides the following properties and policy to let setup authors and IT admins fine tune their setup’s behavior:

MSIRESTARTMANAGERCONTROL: This property specifies whether the Windows Installer package uses the Restart Manager or FilesInUse Dialog functionality.

MSIRMSHUTDOWN: This property determines how applications or services that are affected by an update should be shut down while a reboot is being mitigated.

MSIDISABLERMRESTART: This property determines whether applications or services that are affected by an update are restarted when a reboot is being mitigated by Windows Installer's interaction with Restart Manager

DisableAutomaticApplicationShutdown: This policy specifies whether Windows Installer uses the Restart Manager or FilesInUse Dialog functionality.

Custom Actions and Restart Manager

Setup authors could add additional resources that need to be released as part of the setup using the restart manager session handle that Windows Installer provides to them via MsiRestartManagerSessionKey property.

Custom actions can query the value of the MsiRestartManagerSessionKey property and use it in a call to RmJoinSession API. Custom actions that call RmJoinSession API must call RmEndSession API too once they are finished adding resources. Also, custom action should not call the RmShutdownApplications, RmGetAffectedApplications and RmRestartApplications API directly and should just use the restart manager’s resource addition/filtering API.

Since all files-in-use detection and process shutdown would be completed in InstallValidate action, the MsiRestartManangerSessionKey property will be cleared in Windows Installer’s InstallValidate action.

Windows Installer-Restart Manager Interaction in Detail

1.    During engine initialization, if Windows Installer’s interaction with RM is not disabled by a property/policy the service starts up an RM session and sets the MsiRestartManangerSessionKey property.

2.    During costing, Windows Installer adds file resources that it wants RM to monitor.

3.    During InstallValidate, Windows Installer requests RM to find out what all processes need to be shutdown for the install to succeed.

a.   If RM detects that the file is held in use by a critical process or the client of this setup or a custom action server or by the Windows Installer service itself then a reboot can not be mitigated. In such a case:

i.   For legacy MSI packages it will continue the install.

ii. For new MSI packages with MsiRMFilesInUse dialog it will send out 1610 error message.

b.    If the package is authored such that the services detected by RM would be shutdown because of the authoring of the Service* tables then those services will not be displayed in the files-in-use dialogs.

4.      It then sends a message to the client requesting it to see if it can shutdown these applications. Upon receiving this message, the client then interacts with RM and compiles a list of processes that it can shutdown. If in this process:

a.    RM finds that a process is being run in another user’s session then, it informs the caller that it cannot shut it down.

b.    RM finds that the client does not have enough credentials to shutdown the process then, it informs the caller that it cannot shut it down.

5.    If the client detects any reboot, it informs the service of this. The service then warns the user that a reboot might be needed (as outlined in 3.a.i and 3.a.ii).

6.    If the client does not detect any reboot then the client sends the INSTALLMESSAGE_RMFILESINUSE message to:

a.    External UI handlers (if one exists that has specified using the INSTALLLOGMODE_FILESINUSE flag).

b.    If External UI handlers do not handle the message, it is forwarded to the internal UI handler.

7.    Based on how the UI handlers respond to the INSTALLMESSAGE_RMFILESINUSE message, the service would continue its processing accordingly.

8.    If the UI handler requests Windows Installer to shut down the processes:

a.   Windows Installer service will request RM to shutdown any services that might have to be shutdown. If there are no services to shutdown then, nothing is done.

b.   Windows Installer service then requests the client to shutdown the required processes.

The way RM shuts down these processes can be controlled using the MSIRMSHUTDOWN property.

9.    If RM could not shutdown any of the processes, then Windows Installer displays 1611 message if the package has MsiRMFilesInUse dialog. If not, no message is displayed and the install continues (but a reboot might be needed). RM might not shutdown a process, if the process doesn’t respond to WM_ENDSESSION or WM_CLOSE messages or if it is a service, it does not respond to SCM requests.

10. If RM succeeds in shutting down the processes, then the install will not require any reboot.

11. If after Step 7, UI handlers request the service to send the INSTALLMESSAGE_FILESINUSE message, the service responds to the request.

12. Upon completion of the install, Windows Installer Service requests RM to restart all the services that it shutdown, while the client requests RM to restart all the applications that registered using the RegisterApplicationRestart API.

Windows Installer-Restart Manager-UAC

During non-GP (group policy) based first-time installs of non-UAC compliant MSI packages, Windows Installer interacts with UAC to obtain admin credentials before performing an install. Once, those credentials are obtained they are used through out the install.

Shutting down elevated processes

If during this install, any elevated processes are detected in the same session as the Windows Installer service, they will be shutdown by the Windows Installer service using the credentials provided by the user. If however, there was any elevated process running in the user’s session (different from the session that Windows Installer service is running), then the user will not be able to shut down those elevated processes because, the service cannot pass on credentials of the elevated process to an un-trusted client.

So, in a nutshell Windows Installer cannot mitigate reboots caused by elevated processes. However, this is possible if RM lets its callers shutdown processes across sessions. This is a work in progress that would hopefully be addressed post-Vista.

Shutting down services while applying a digitally signed patch

Windows Installer will not prompt users for elevated credentials when a patch is digitally signed and its signature recognized by the original MSI in its Digital* tables. In this case, Windows Installer service does not have the elevated admin credentials to stop services that are not part of the MSI package. So, it will not be able to shutdown those services. If however, the package is authored correctly then the services that the MSI cares about will be stopped before the files carried by it are updated, thereby mitigating the reboot.

How does my application restart in its old state after the update?

When Windows Installer requests restart manager to shutdown applications, restart manager sends out WM_QUERYENDSESSION, WM_ENDSESSION, WM_CLOSE respectively to GUI applications. When these applications receive these messages, they have the opportunity to save any user data and/or application state information to exit gracefully. This ability for applications to save their state is informally termed as freeze-dry. Applications that register with restart manager using the RegisterApplicationRestart API would be restarted when Windows Installer is done with the install and requests RM to restart all the applications that were shutdown and were registered with it. When these applications are restarted it would appear to the user that they were revived from their frozen state; hence the name: freeze-dry. Read the Guidelines for Applications and Services section on MSDN to learn more on how to support this cool new feature in your applications.

[Author: Hemchander Sannidhanam]

This posting is provided "AS IS" with no warranties, and confers no rights. Use of included script samples are subject to the terms specified at https://www.microsoft.com/info/cpyright.htm