InstallShield 2019
Project • This information applies to the following project types:
| • | Advanced UI |
| • | Suite/Advanced UI |
Edition • The Advanced UI project type is available in the Professional edition of InstallShield. The Suite/Advanced UI project type is available in the Premier edition of InstallShield. For information about the differences between these two project types, see Advanced UI Projects vs. Suite/Advanced UI Projects.
The following information provides background information to help you resolve issues with Advanced UI and Suite/Advanced UI installations.
Reasons Why an Advanced UI or Suite/Advanced UI Installation May Run in Maintenance Mode
An Advanced UI or Suite/Advanced UI installation may run in maintenance mode in the following scenarios:
| • | An end user chooses to modify the product through the product’s Add or Remove Programs entry. |
| • | An end user reruns the Advanced UI or Suite/Advanced UI installation. |
| • | The detection conditions for one or more of the primary packages in the Advanced UI or Suite/Advanced UI installation are not configured properly. For information on configuring conditions for an Advanced UI or Suite/Advanced UI package, see Building Conditional Statements in Advanced UI and Suite/Advanced UI Projects. |
| • | A package in the Advanced UI or Suite/Advanced UI installation is configured erroneously to be a primary package instead of a dependency package, and the package is already installed on the target system. |
InstallShield creates maintenance mode conditions automatically, based on the detection conditions of all of the primary packages in the Advanced UI or Suite/Advanced UI project. The Advanced UI or Suite/Advanced UI engine uses these conditions to determine whether the Advanced UI or Suite/Advanced UI installation runs in maintenance mode. If any of the primary packages’ detection conditions evaluate as true (that is, if one or more of the primary packages seem to be installed already), the maintenance mode condition is true, and the Advanced UI or Suite/Advanced UI installation runs in maintenance mode.
Use the Package Type setting in the Packages view to indicate whether a package is a primary package or a dependency package.
To learn more about mode conditions, see Triggering Install Mode or Maintenance Mode of an Advanced UI or Suite/Advanced UI Installation.
Logging an Advanced UI or Suite/Advanced UI Installation to Troubleshoot Issues
If you are troubleshooting issues with an Advanced UI or Suite/Advanced UI installation, start with a debug log file. Debug log files provide some insight into the operations that an Advanced UI or Suite/Advanced UI installation performs at run time. To create a debug log file, run the Advanced UI or Suite/Advanced UI installation from the command line with /debuglog parameter. To generate a log file named InstallShield.log in the same directory as the Setup.exe file, pass just the command-line parameter. Note that this does not work if the Setup.exe file is in a read-only location. For example:
Setup.exe /debuglog
To specify the name and location of the log file, pass the path and name, as in the following example:
Setup.exe /debuglog"C:\PathToLog\setupexe.log"
Advanced UI and Suite/Advanced UI debug log files contain the following information:
| • | Initialization information from the Advanced UI or Suite/Advanced UI engine |
| • | Property values and property value changes |
| • | Information about the actions and installed states of features |
| • | Information about the detected state and eligibility of packages |
| • | Package command lines and launch result information |
| • | For an InstallScript package—Information that is logged by the InstallScript function SuiteLogInfo |
The default Advanced UI or Suite/Advanced UI user interface in Advanced UI and Suite/Advanced UI projects also logs information to the debug log file; however, in general, this information can be ignored. (UI information is typically prefixed with UI DLL: in the log.)
Note that when the Advanced UI or Suite/Advanced UI engine writes feature, package state, and Advanced UI or Suite/Advanced UI mode information to the log file, it writes only numeric values for the states. The following tables map the numeric values to state representations.
|
Log Value |
State |
|
0 |
No action will be taken for the feature. |
|
1 |
The feature will be installed. |
|
2 |
The feature will be removed. |
|
Log Value |
State |
|
0 |
The feature is not currently installed. |
|
3 |
The feature is installed. |
|
Log Value |
Installed State |
Action State |
|
0 |
The package is not installed. |
— |
|
1 |
The package is currently installed. |
The package will run its install operation. |
|
2 |
— |
The package will run its modify operation. |
|
3 |
— |
The package will run its repair operation. |
|
4 |
— |
The package will run its remove operation. |
|
5 |
— |
No action will be performed for the package. |
|
Log Value |
Install Mode |
|
0 |
First-time installation |
|
1 |
Maintenance/UI maintenance mode selection |
|
2 |
Maintenance/modify |
|
3 |
Maintenance/remove |
|
4 |
Maintenance/repair |
|
5 |
Stage only (The installation is run in stage-only mode, in which the Advanced UI or Suite/Advanced UI installation is staged—or uncompressed and copied to a specified location. Note that none of the packages in the installation are run in this mode.) |
Example Debugging Walkthrough
Debug log files can be useful in any number of scenarios where an Advanced UI or Suite/Advanced UI installation is not behaving in an expected manner. For example, suppose a Suite/Advanced UI project contains two packages: one .exe file and one .msi file, each associated with their own feature in the Suite/Advanced UI installation. At run time on some machines, even though both features appear to be selected, only the .exe package is installing. To begin troubleshooting this behavior, generate a debug log file on one of the machines that is encountering this behavior. Once the log file is available, verify that both features were in fact selected to be installed. The Suite/Advanced UI records logs information such as the following about each feature:
9-21-2011[03:07:04 PM]: Engine: determining suite feature states
9-21-2011[03:07:04 PM]: Initializing state for feature 'NewFeature'
9-21-2011[03:07:04 PM]: Default action state 1 for mode 0
9-21-2011[03:07:04 PM]: Initial feature state: 1
9-21-2011[03:07:04 PM]: Final feature state: 1
…
9-21-2011[03:07:04 PM]: Initializing state for feature 'NewFeature1'
9-21-2011[03:07:04 PM]: Default action state 1 for mode 0
9-21-2011[03:07:04 PM]: Initial feature state: 1
9-21-2011[03:07:04 PM]: Final feature state: 1
The above information indicates the initial states of features NewFeature and NewFeature1. Both have been initialized to a state of 1, indicating they are selected for installation. So the features in this Suite/Advanced UI installation do not appear to be an issue. Continuing on in the log, the following information is provided:
9-21-2011[03:07:10 PM]: Engine: setting parcel states as determined by feature selections
9-21-2011[03:07:10 PM]: Feature NewFeature setting parcel states, parent override: no, override state: 0
9-21-2011[03:07:10 PM]: Requesting action state 1 for parcel '{BA3EAE7A-0701-4CE0-9224-4F5C0F135792}'
9-21-2011[03:07:10 PM]: Containing feature is request state change to parcel {BA3EAE7A-0701-4CE0-9224-4F5C0F135792}, feature request: 1
At this point in the Suite/Advanced UI installation, the UI DLL has completed the UI selection phase and gathered all necessary data for the installation to start. The Suite/Advanced UI engine now determines what packages (referred to as parcels in the log file) will be installed based on the features with which they are associated. This information indicates package {BA3EAE7A-0701-4CE0-9224-4F5C0F135792} (this GUID comes from the Package GUID setting that is set in each package in an Advanced UI or Suite/Advanced UI project) is being requested to install (action state 1) from feature NewFeature (whose action state is selected to install). Looking forward a couple lines in the log provides the following information:
9-21-2011[03:07:10 PM]: Parcel is ineligible or the current parcel state and install mode to not allow parcel configuration
That line indicates that the package (the .msi package that is not installing as expected) has become ineligible. Looking for this package with the given package ID in the Packages view in the Suite/Advanced UI project shows that the package contains an eligibility condition. The condition indicates that the package is eligible if either (a) a package with a particular .msi product code and package code are already installed, or (b) an .msi package with a specific product code is installed, and the product version is not greater than the .msi package’s product version. The purpose of this condition is to prevent the package from installing if a newer version of this product is already installed.
Investigating further on the machine that produced this behavior shows that a newer version of the product is already present on the machine, causing the .msi package in the Suite/Advanced UI installation to become ineligible.
Debugging InstallScript Actions in a Suite/Advanced UI Installation
To troubleshoot issues with InstallScript actions in a Suite/Advanced UI installation, you can use the InstallScript Debugger. To debug the InstallScript actions in a Suite/Advanced UI installation, run the Suite/Advanced UI installation from the command line with /d parameter.
Note • Debugging InstallScript code requires the debug-information file Setup.dbg to be available. In addition, in order to debug an installation on a system other than your development machine, you need to copy certain files from your development machine to the debugging machine. To learn more, see Debugging an Installation on Any Computer.
The following command runs your InstallScript custom actions in the InstallScript Debugger:
Setup.exe /d
If the installation is located in a path at which they were originally compiled, you also need to specify the path to your debug symbols file (.dbg):
Setup.exe /d"Path-to-Setup.dbg"
See Also
Advanced UI and Suite/Advanced UI Setup.exe Command-Line Parameters
Setup.exe Return Values and Run-Time Errors (Advanced UI and Suite/Advanced UI Projects)
Preventing a Property Value from Being Written in Advanced UI and Suite/Advanced UI Debug Log Files
InstallShield 2019 Help LibraryApril 2019 |
Copyright Information | Flexera |