共用方式為

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.

 Basic UI

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.

Full UI

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

Return Value

Windows Installer’s action

IDOK

Will request Restart Manager to shut down and restart the applications that hold files in use

IDCANCEL

Will cancel the installation

IDIGNORE

The installation will go on, although a reboot will be required at the end

IDNO

If the package has MsiRMFilesInUse dialog then 1610 Message will be sent. If MsiRMFilesInUse dialog is not present then INSTALLMESSAGE_FILESINUSE message will be sent to the UI handlers.

IDRETRY

Will cause Windows Installer to send the legacy INSTALLMESSAGE_FILESINUSE message to the UI handlers

-1

Will be treated as an error and will end the installation

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

Comments

  • Anonymous
    January 15, 2007
    Thanks for documenting this important info.  I have a question regarding how we can leverage Restart Manager in our products.  We have our own patching UI that uses MsiApplyMultiplePatches and MsiSetExternalUIRecord.  We may be calling MsiApplyMultiplePatches several times in one user interaction with our patch UI - much like is done in the Windows Update experience.  Is there any way to avoid having applications restart at the end of each call to MsiApplyMultiplePatches?  For instance, can we use RmStartSession then hand off the session key to each MsiApplyMultiplePatches call, let any applications or services shutdown as needed, then call RmRestart after the last MsiApplyMultiplePatches completes?

  • Anonymous
    January 24, 2007
    This is fantastic information - you should publish for other MSI related behavior. eg What happens on restart when an MSI didn't full succeed: does it try a repair or does it try a silent install, or does it maintain a list of files which failed to copy?

  • Anonymous
    January 29, 2007
    How can I create msi file for my web application

  • Anonymous
    February 05, 2007
    The comment has been removed

  • Anonymous
    February 06, 2007
    To answer Daniel's question: We provide the MsiGetPatchFileList API for patch-chainers to get the list of files from several patches so that the chainer can manage the Restart Manager interaction. You can also apply multiple patches in the same transaction using the MsiApplyMultiplePatches API and we will handle the restart managr interaction for you.

  • Anonymous
    February 21, 2007
    Can you be any more specific about what can cause the installer to throw message 1611 in step 9)?  For example, if the RM finds that it can't shut down an application in step 4), would that lead to a 1611 message or a different message? I ask because I'm consistently getting a 1611 message in an installer I'm building, and trying to come up with a list of possible reasons it couldn't close the application.

  • Anonymous
    February 28, 2007
    I have one question. I have added  MsiRMFilesInUse authored dlg to my setup file. In Vista, I try to uninstall my application, when my application is running. In this case Installer is not showing the MsiRMFilesInUse dlg. In log file I am getting error code 1610. Could you please tell me, what I need to do extra to get the MsiRMFilesInUse dlg. Note: My MSI file shema is 200. My OS is Vista My MSI has MsiRMFilesInUse resource.

  • Anonymous
    June 12, 2008
    On the The OEM Ready Program page, OEM’s can download the OEM Ready Program Test Cases for Windows Vista