|
Restart Applications
This command uses the available with and newer operating systems to perform an orderly shutdown and restart of applications during an installation. This enables safe updates to the file resources being consumed by those applications.
When using the engine, the is invoked automatically by , and does not ordinarily need to be manually invoked using this command. However, where applications are not directly updated by your installation, and yet are still affected by your installation, you may still need to manually invoke this command. For instance, you could be registering some custom components you are installing with their intended applications, where those applications need to be shut down for the component registrations to succeed.
The Native Engine does not automatically invoke the , and instead employs other heuristics to prevent application and/or system restart when installing. However, you may determine in your testing that these heuristics are insufficient to prevent a reboot, in which case you may manually invoke this command to prevent such reboots where possible.
This command works by way of sessions, where:
- A session is started successfully when applications consuming the file resources to update have been shut down successfully. If applications could not be shut down successfully, a session does not start.
- A successfully started session must later be ended when file resources have finished updating. Ending a session restarts applications that were previously shut down, restoring the state that they were in at the time of shutdown.
While you may create multiple independent sessions during your installation using this command, each new session incurs a non-trivial performance penalty. Therefore, it is recommended that you batch your use of the into as few sessions as possible.
Request shutdown of applications and/or services using the following files
To start a manager session, first invoke this command with this option selected.
Files
Enter the full list of file resources that your installer is updating here, one file per line. The will check for applications and/or services currently consuming those resources. Click the button to visually add a file to the list from the list of files that you are installing. Please note that you are not limited to the list of files you are installing with your setup, and may freely specify files already present on the target system independent of your installation.
To directly shut down applications and/or services without specifying the individual resources the may be consuming, you may directly enter the application and/or service binary names here.
All file paths may use variables and must refer to the locations of the file resources and/or applications/services exactly as they would be found on the target system.
Not every specified resource must to exist. Non-existent resources will be safely ignored.
This field is ignored when ending a previously started session.
Force shutdown of applications without support for the Restart Manager
Not all applications are compatible with the , however they may still be closed successfully. To force the closure of incompatible applications, check this box. Incompatible applications closed in this manner may not be restarted successfully by the upon ending the session.
Checking this box reduces the error rates encountered when using this command, even when used with applications which are compatible with the .
This field is ignored when ending a previously started session.
Restart applications that were previously closed as part of the Restart Manager session below
To end a session, invoke this command with this option selected.
You must only end sessions which were successfully started.
Variable for Restart Manager Session
This field is interpreted differently, based on whether a session is being started or ended.
When Starting Sessions
When creating a new session, this variable holds one of the following values in the case of an error:
| Value | Meaning |
|---|---|
| ERROR | Some or all of the applications do not support the , or another error occurred. You may reduce the incidence of errors by forcing application shutdown in instances where the is not supported; however this will not eliminate other types of errors. |
| NONVISTA | The is not available on operating systems earlier than , and this command is being ignored by your installation. |
If no unexpected errors occurred within the , and if all requested applications natively support the (or if you chose to force application shutdown in cases where native application support is unavailable), this variable receives a session identifier. Typically, session identifiers start with the number 0, and increase by 1 for each new session created before concluding a successfully started session. The operating system supports a maximum of 64 simultaneous sessions.
This session identifier must be later used when invoking this command for a second time to end the session, which automatically restarts applications that were closed as part of the session startup process, and restores the state they were in at their time of shutdown. Please note that state preservation and automatic restart may only be available for applications which explicitly support the .
When Ending Sessions
When ending a previously started session, this variable does not receive new data.
This variable must instead identify the session being ended, by supplying the session identifier returned in the variable previously used while starting the session. Therefore, you may reuse the same variable name you had supplied while starting the session (of course, assuming you have not modified its value since), to end a session that was successfully started.
Notes
- For operating systems older than , consider using alternative commands such as Terminate Program and Terminate Process.
- During an installation or maintenance operation, if you are using the engine, or the Native Engine where the $DELAYUNTIL_APPLYCHANGES$ pre-defined variable is set to TRUE, ensure to shut down applications before calling Apply Install, and to restart applications after having called Apply Install.
- During an installation or maintenance operation with the Native Engine where the $DELAYUNTIL_APPLYCHANGES$ pre-defined variable is set to FALSE, shut down applications before installing any of the resources they may have locked, and restart applications after no more resources remain to be installed which they may have locked. In other words, while you may still delay restarting applications until after Apply Install, you would need to ensure that application shutdown is requested and processed before any system modification commands such as Install Files or Install Service execute.
- During an uninstallation, regardless of the setup engine type or delayed processing mode, ensure to shut down applications before calling Apply Uninstall, and to restart applications after having called Apply Uninstall.
- The will not restart any elevated applications, or any applications running under the context of another user. Only applications running under the currently logged on user will be restarted. However, the will still close such applications.