Because Windows Installer installations do not contain an explicit script, the debugging techniques are different from those generally used with programming languages. The techniques described in this white paper include: • Investigating Windows Installer error codes • Generating and interpreting Windows Installer log files • Using the InstallShield MSI Debugger This white paper also discusses how InstallShield® helps you with run-time logging and debugging.

1. W H I T E PA P E R
MSI Run-Time Logging
and Debugging
by Robert Dickau
Principal Technical Training Writer, Flexera Software

2. MSI Run-Time Logging and Debugging
Introduction It is also assumed you are familiar with some of the wizards
Because Windows Installer installations do not contain an available with InstallShield, such as the Release Wizard and
explicit script, the debugging techniques are different from those Component Wizard.
generally used with programming languages. The techniques
described in this white paper include: • The Release Wizard, available under the Build menu
and also from the Releases view, lets you describe the
• Investigating Windows Installer error codes properties—media type, compression settings, and so
• Generating and interpreting Windows Installer log files forth—of a release, and then builds the specified release
• Using the InstallShield MSI Debugger image.
• The Component Wizard, available by right-clicking a feature
This white paper also discusses how InstallShield® helps you with in the Setup Design view, lets you create special types of
run-time logging and debugging. components, such as components for COM servers, fonts,
and Windows services.
Using the InstallShield Environment
This white paper frequently refers to the InstallShield The InstallShield Help Library contains information about using
development environment. It is assumed you are familiar with the every view and wizard in the InstallShield environment. The help
general layout of the InstallShield interface, which contains a list library is available when you press F1 with any view selected;
of views with which you can modify different portions of your you can also select Contents from the Help menu to view the
installation project. help library.
In addition to the graphical environment, InstallShield provides
several tools for modifying and building projects from the
command line or an external script. For example, to build a
project from the command line, batch file, or other automated
process, you can use the executable IsCmdBld.exe. The
IsCmdBld executable is located in the System subdirectory of the
InstallShield distribution directory.
To rebuild a project, you pass IsCmdBld the project file path, the
product configuration name, and the release name that you want
to rebuild. A sample command appears as follows:
iscmdbld -p C:ProductName.ism -a BuildConfig -r
ReleaseName
For example, the General Information view is where you set
general product and project properties; the Setup Design view Learn More about InstallShield
enables you to edit the features, components, and component If you wish to learn more about the capabilities of
data used by your project; the Registry view enables you to InstallShield, please visit the Flexera Software Web site
modify the registry data installed by your installation program; at www.flexerasoftware.com/installshield
and the Direct Editor view gives you access to the raw MSI
database tables.
2 Flexera Software: InstallShield White Paper Series

3. MSI Run-Time Logging and Debugging
In addition, InstallShield provides an Automation interface, with modify the Return Processing setting in the action properties to
which you can modify the contents of a project file without using ignore the return code.
the graphical environment.
Error 2732 and the Directory Table
Windows Installer Run-Time Errors The Directory table contains the values of properties used as
If Windows Installer encounters a fatal error at deployment time, component destinations and locations of existing files. The
an error dialog box similar to the following is displayed. The values of Directory-table properties, such as SystemFolder and
ProgramFilesFolder, are evaluated during the standard costing
operations, which occur when the actions from CostInitialize
through CostFinalize run. Because Directory-table property
values are unavailable until these actions run, any custom
actions that refer to Directory properties will cause the
installation to fail with error 2732. For example, if you have
a launch-an-executable action that launches Notepad.exe
from WindowsFolder, you must schedule the action after the
CostFinalize action to avoid error 2732.
error dialog box displays a numeric error code, along with a Error 1327 and Hard-Coded Drive Letters
description of the error. After the user dismisses the error dialog As a rule, you should use Windows Installer properties to refer
box, Windows Installer displays the SetupCompleteError dialog to the locations of special directories on the target system. For
box, which informs the user that no system changes have example, instead of installing directly to “C:Program Files”,
taken place. you should use the property [ProgramFilesFolder]. In some cases,
however, it might be necessary to hard-code the destination
In the InstallShield Dialogs view, the error dialog box is called for some files used in the installation. At run time, if Windows
SetupError, and the text of each error message is taken from Installer is unable to find the drive letter, it will return error 1327.
the Error table of the MSI database. For a complete list of
built-in Windows Installer error codes and descriptions, see the In addition, error 1327 can occur on some systems if the
Windows Installer Help Library topic “Windows Installer locations of such system folders as MyPicturesFolder are not
Error Messages”. defined in the target system’s registry, or point to nonexistent
directories.
The following sections describe the causes and resolutions of
some of the most common Windows Installer error codes. Similarly, error 1606 (“Could not access location…”) can
occur if the installation refers to a network resource that is not
Error 2762 and Deferred Actions available when the installation is running.
Deferred custom actions must be scheduled between the
standard InstallInitialize and InstallFinalize actions, which Error 1406 and the ProductVersion Property
enclose the Windows Installer script-generation process. (The Windows Installer reports error 1406 if the installer is unable to
InstallShield build process reports build warning –6524 for this write data to the registry, often because of insufficient privileges
error, and the ICE validation process reports an ICE77 error.) If or an invalid key being specified. For example, Windows does
you encounter Windows Installer error 2762, you should either not allow a subkey to be created directly under HKEY_LOCAL_
move your deferred action somewhere between InstallInitialize MACHINE.
and InstallFinalize, or modify it to use immediate execution.
A less obvious cause of error 1406 is an invalid ProductVersion
Errors 1720–1723 and Failed Custom Actions format. Windows Installer expects the product version to be
By default, Windows Installer will exit the installation program of the form a.b.c, where a, b, and c are all numbers. If the
if a custom action fails. When using executable and DLL custom ProductVersion property contains any alphabetic characters, as
actions, for example, failure means that the EXE or DLL returned in the value “1.0.beta”, Windows Installer reports error 1406.
a nonzero value. If a custom action fails, Windows Installer In this case, the product version should be modified to a strictly
reports one of the error codes from 1720 through 1723. numeric value.
If you are the author of the custom action executable or DLL, Errors 2727 and the Directory Table
you should modify it to return a zero value (in C code, you can The locations of destination directories—such as INSTALLDIR
use the constant ERROR_SUCCESS) to indicate success. For and SystemFolder—on the target system are defined by entries
a VBScript action function, return the constant IDOK (value in the Directory table of the MSI database. If a component’s
1) to indicate success. To enable the installation and a DLL or destination directory does not appear in the Directory table,
script custom action to communicate, you should use properties however, Windows Installer reports error 2727.
instead of return values to pass values back and forth.
To create a new destination folder—that is, create a new
If you are not the author of the custom action source, you can Directory entry—you can use a component’s Destination
Flexera Software: InstallShield White Paper Series 3

4. MSI Run-Time Logging and Debugging
property. In the Destination property, select “Browse, create, or installation launcher setup.exe, you can use the /v switch to
modify a directory entry”, and then create the directory in the pass command-line switches through to msiexec.exe, as in the
Browse for Directory panel. Similarly, you can use the Files and following example. Note that there must be no space after the /v
Folders view to create new destinations, and then drag and drop switch and the arguments you pass through to msiexec.exe.
file icons into the new destination folder.
setup /v”/L*v C:everything.log”
For other errors, you should consult the Windows Installer Help
Library and the InstallShield Knowledge Base for descriptions You can also embed environment variables in the command line.
and suggested resolutions. The following command creates a log file called everything.
log inside the user’s Temp directory, the location of which is
Windows Installer Log Files represented by the environment variable %temp%.
The primary technique for debugging a Windows Installer
installation is to create a log file during deployment. As setup /v”/L*v ”%temp%everything.log””
described later in this document, a Windows Installer log file To embed double quotes in the string you pass to /v, which is
contains information about file-overwrite decisions, the success necessary in case the directory’s name contains spaces, use the
or failure of built-in and standard actions, feature and component escape sequence ”.
states and actions, and the values of properties used by the
installation. With Windows Installer versions 4.0 and later, you can indicate
that a log file should always be created, by using the MsiLogging
The following sections describe the different techniques for property. In InstallShield, you can use the General Information
generating and interpreting a Windows Installer log file. setting “Create MSI Logs” to control automatic logging.
Creating a Log File
You generate a Windows Installer log file by passing msiexec.
exe the /L command-line switch, as in the following:
msiexec /i product.msi /L*v installinfo.log
The argument /L*v used in this command indicates that the As an alternative, you can specify that you want a log file
installer should log verbose information (v) about everything always to be created when the user launches setup.exe. In the
(*) the installer does. To narrow the range of data logged by Media view group, select the Releases view, and then select
the installation, you can specify alternative options after the /L the desired release icon and the Setup.exe tab; in the MSI
value. Command Line Arguments setting, enter the desired /L switch.
After the /L switch and flags, you specify the relative or absolute
path to the log file you want to create. If the file already exists, it
will be overwritten (unless you use the + switch, which specifies
to append to an existing log file). Note that Windows Installer
will report an error if you specify a nonexistent directory in which
to create the log file.
Some of the flags available to follow the /L switch are: NOTE: Logging cannot be initiated from within a running
installation, for example, from a custom action. Instead, logging
• p: Display the final value of all MSI properties. must be initiated from the command line or an installation launcher,
• e: Display all error messages. such as setup.exe.
• w: Display warning messages.
• i: Display action status messages. Windows Installer also supports a Logging machine policy
• v: Write verbose information to the log file. setting. The Logging policy causes Windows Installer to create
a randomly named log file in the user’s Temp folder for each
As described above, the asterisk (*) specifies to use all flags installation, regardless of how it is launched. To set the Logging
except the verbose information flag (v). For a complete list of policy, select Run from the Start menu, and enter gpedit.msc. This
logging flags, see the Windows Installer Help Library topic launches the Group Policy Editor.
“Command Line Options”.
The Windows Installer policy settings are available in the
You can similarly log an uninstallation using the following section Computer Configuration >Administrative Templates >
command: Windows Components > Windows Installer, as displayed in the
following figure.
msiexec /x {product-code} /L*v uninstallinfo.log
If you built your installation with InstallShield to use the
4 Flexera Software: InstallShield White Paper Series

5. MSI Run-Time Logging and Debugging
addition, the Error-table messages are those written to the event
log, as well as those written to the Windows Installer log file
when one is generated.
Action Return Values
The log file contains an entry for each standard and custom
action that the installer runs. A sample entry (for the standard
WriteRegistryValues action) appears similar to the following:
MSI (s) (B8:F8): Doing action: WriteRegistryValues
Action start 25:00:05: WriteRegistryValues.
Action ended 25:00:05: WriteRegistryValues. Return value 1.
The entry contains timestamp and return value information for the
To set the policy, double-click the Logging entry. In the Logging action. A return value of 1 indicates that the action completed
Properties panel (pictured in the following figure), you should successfully; other common return values are 3, which indicates
select Enabled, and then specify which logging flags you want failure, and 0, which indicates the action was skipped or could
the automatically generated log files to use. Note that the not be executed. For a complete list of return codes, see the
Logging policy is used only if the user does not specify to create Windows Installer Help Library topic “Logging of Action
a log file; if the user manually creates a log file, the user’s Return Values”.
logging settings will be used instead of the policy settings.
(The User Interface and Execute sequences are sometimes called
the client and server processes; this terminology is reflected in
the prefixes “(c)” and “(s)” in some log file entries. Therefore the
string “(s)” in the WriteRegistryValues entry above indicates that
the action ran in the Execute sequence.)
The log entry will also specify if the action’s condition failed,
using an entry similar to the following:
MSI (c) (E0:E8): Skipping action: LaunchConditions (condition
is false)
If an action is skipped because Windows Installer does not
perform it for a certain type of installation, the entry appears
similar to one of the following, reporting the return value 0:
MSI (c) (E0:E8): Doing action: FindRelatedProducts
Action start 25:01:01: FindRelatedProducts.
As an alternative, you can create a string value called Logging MSI (c) (E0:E8): Skipping FindRelatedProducts action: not run
under the registry key: in maintenance mode
Action ended 25:01:01: FindRelatedProducts. Return value 0.
HKLMSoftwarePoliciesMicrosoftWindowsInstaller
Similarly, if an action is skipped because it has already been
The Logging value should contain the string of letters, such as performed, the entry appears similar to the following:
“aeipw”, indicating what types of data you would like the log file
to record. Again, this creates a randomly named log file in the MSI (s) (B8:F8): Doing action: AppSearch
user’s Temp directory. Action start 25:49:03: AppSearch.
MSI (s) (B8:F8): Skipping AppSearch action: already done on
Information Contained in a Log File client side
A log file contains the following types of information: Action ended 25:49:03: AppSearch. Return value 0.
• Success or failure of standard and custom actions Feature and Component States and Actions
• Feature and component states and actions The log file will also tell you which features and components were
• Property values at the end of the User Interface and installed, removed, advertised, and so forth. Typical entries for
Execute sequences features and components appear similar to the following:
• File-overwrite explanations
Feature: ProgramFiles; Installed: Absent; Request: Local;
The Error table contains the error messages displayed in the Action: Local
SetupError dialog box during a full user interface installation. In Component: main_exe; Installed: Absent; Request: Local;
Action: Local
Flexera Software: InstallShield White Paper Series 5

6. MSI Run-Time Logging and Debugging
The Installed entry specifies the existing state of the feature or BBAA-0099-8877-665544332211}
component; the Request entry specifies the requested installation Property(S): ProductLanguage = 1033
state of the feature or component; and the Action entry specifies Property(S): ProductName = Sample App 3000
the action that will be performed on the feature or component. Property(S): ProductVersion = 1.2.3
(The Request and Action entries will typically be the same.)
Similarly, properties values at the end of the User Interface
If you see a component name you do not recognize, the sequence appear with the “(C)” notation to denote the “client”
component could be part of a merge module or one created by a process. As you have seen, only changed values of public
dynamic file link that includes subdirectories. A component from a properties are passed from the User Interface sequence to the
merge module will have a name similar to the following: Execute sequence; the values of private properties are reset to
their defaults when execution switches to the Execute sequence.
component_name.12341234_5678_5678_9ABC_ Similarly, property values do not flow “backward” from the
ABCDEFABCDEF Execute sequence to the end of the UI sequence; a property
modified by an action in the Execute sequence will not be
available on the SetupCompleteSuccess dialog box, for example.
A component created as part of a dynamic link that includes
subdirectories will appear similar to the following: File-Overwrite Information
The log file also provides information about why files were or
_11223344556677889900AABBCCDDEEFF were not overwritten. An entry for a first-time installation might
appear as follows:
The most common Installed values are the following:
File: C:Program FilesTrainingSample.exe; To be installed;
• Absent: The feature or component is not present on the No patch; No existing file
target system.
• Local: Feature or component is installed on the local system. The entry indicates that there is no existing file with the name
• Source: Feature or component is installed to run from the Sample.exe in the target directory, and therefore this will be
installation source. installed. Windows Installer follows a set of default rules when
• Advertise: Feature is advertised. determining whether to overwrite an existing file on the target
system. For example, by default a versioned file will not overwrite
For the Request and Action entries, the following are the most an identical file, in which case the log contains an entry similar to
common values: the following:
• Absent: Feature or component is being uninstalled. File: C:Program FilesMinorUpgradeUpdateMe.exe; Won’t
• Local: Feature or component is being installed to the Overwrite; No patch; Existing file is of an equal version
local system.
• Source: Feature or component is being installed to run from There are some techniques you can use to modify the default
the installation source. file-overwrite behavior. One of the techniques discussed was
• Advertise: Feature is being advertised. modifying the REINSTALLMODE property value to include the
• Reinstall: Feature being reinstalled as part of a maintenance letter a, which indicates always to overwrite an existing file. In
operation or minor upgrade. this case, the log entry would appear similar to the following:
• Null: No action is being taken on the feature or component.
File: C:Program FilesMinorUpgradeUpdateMe.exe;
For a complete list of possible values, see the Windows Installer Overwrite; No patch;
Help Library topic “Checking the Installation of Features, REINSTALLMODE specifies all files to be overwritten
Components, Files”.
If a file is not being installed on the target system, you can search
Properties for the file’s name in the log file to see why Windows Installer
Properties are used to store global information used by the determined the file should not be installed.
installation. For a normal, full-UI installation, the log file will
contain the final values of properties at the end of the Execute TIP: Under the InstallShield Tools menu is the InstallShield MSI
sequence and at the end of the User Interface sequence. Property Log Analyzer. This tool enables you to select a Windows Installer
values at the end of the Execute sequence appear similar to the package to log, and then generates the log file. After generating
following, containing the notation “(S)” to denote the “server” a log file, you can select to view and analyze it; the tool displays
process. an annotated version of the log file, along with a summary
showing feature, component, and file actions, property values,
Property(S): Manufacturer = Training Co. and action status.
Property(S): ProductCode = {FFEEDDCC-
6 Flexera Software: InstallShield White Paper Series

7. MSI Run-Time Logging and Debugging
Writing Custom Entries to a Log File
By default, a custom action does not create entries in a log file
(unless the action fails, in which case the generic error number
will be returned). To enable your custom actions to write custom
data to a log file, you can add code that uses the Windows
Installer Session.Message method (in a VBScript custom action)
or MsiProcessMessage function (in a DLL custom action) to write
custom strings to the log file, if logging is enabled.
For example, the following VBScript function writes a custom Event Logging and MSI Self-Repair
string to the log file. An important type of information written to the event log is
the detail of why Windows Installer is performing a self-repair
Function WriteToLog( ) operation. This type of self-repair operation is typically manifested
by a small Windows Installer dialog box—similar to the following
Const msiMessageTypeInfo = &H04000000 figure—appearing when an application is launched through an
advertised shortcut.
Set msi = CreateObject(“WindowsInstaller.Installer”)
Set msgrec = msi.CreateRecord(2) ‘ record to hold log message
‘ field 0 is message “template”
msgrec.StringData(0) = “Action: [1], Message: [2]”
msgrec.StringData(1) = “SomeAction” ‘ string to put in [1] If this self-repair operation happens, the event log describes the
msgrec.StringData(2) = “Some description...” ‘ string to put in [2] product, feature, component, and resource involved. The log
entries appear similar to the following:
‘ write info message to log file; see the MSI Help Library
‘ for other message types Detection of product ‘{11111111-1111-1111-1111-
Session.Message msiMessageTypeInfo, msgrec 111111111111}’, feature ‘Main_Program’ failed during
request for component ‘{22222222-2222-2222-2222-
End Function 222222222222}’.
When you use this code in a custom action, the log file will Detection of product ‘{11111111-1111-1111-1111-
contain the line specified in the code. The function will not start 111111111111}’, feature ‘Main_Program’, component
logging if it was not already enabled. ‘{22222222-2222-2222-2222-222222222222}’ failed.
The resource ‘C:Program FilesTrainingsample.exe’ does
Windows Installer and the Event Log not exist.
Windows Installer automatically interacts with the event log.
For example, every successful installation writes an entry to the The log messages should display the missing resource that causes
Application section of the event log, using the source MsiInstaller. self-repair, with which information you can determine why the
To view the event log, you can use the Event Viewer utility resource is not present.
available in the Administrative Tools group.
TIP: Given a component code, you can determine the products
For example, a successful installation will create an event log that use it by calling the MsiEnumClients function or Installer.
entry similar to the following. ComponentClients property. Given a product code, you can get its
Similarly, warnings and fatal errors are also automatically written name and other properties by calling the MsiGetProductInfo function
or the Installer.ProductInfo property.
InstallShield MSI Debugger
The Additional Tools view group contains the MSI Debugger view,
which enables you to step through the actions performed by
your installation, and to view and modify the values of Windows
Installer properties as the installation progresses.
to the event log. A full-UI installer shows errors in the SetupError
dialog box described earlier in this document. For a silent
installation, Windows Installer errors appear in the event log,
since no dialog boxes are displayed.
To view the details of an event, you can double-click its entry.
Flexera Software: InstallShield White Paper Series 7

8. MSI Run-Time Logging and Debugging
The MSI Debugger view shows an ordered list of actions, where As you run the installation, you can watch the values of
each action name (and condition, if there is one) is displayed. properties change as different actions take place. This way,
Similar to the display of the Sequences view, the dialog boxes you can determine (for example) why conditions are failing
explicitly listed in the User Interface sequence—that is, listed in unexpectedly or why component destinations are being set to
the InstallUISequence table—are displayed as root-level actions, unexpected values.
while dialog boxes that follow are indented based on the Next-
button control events. Summary
This white paper discusses techniques for run-time logging and
To launch the debugger, you can pull down the Build menu, debugging, including investigating Windows Installer error
select the MSI Debugger submenu, and then select the desired codes, generating and interpreting Windows Installer log files,
operation: Toggle breakpoint (F9), step into (F11), or step over and using the InstallShield MSI Debugger.
(F10). You can press F5 to start debugging.
By default, the MSI Debugger toolbar is not displayed. To
Begin a Free Evaluation of InstallShield
You can download a free trial version of InstallShield from
display the toolbar, pull down the Tools menu and select
the Flexera Software Web site at:
Customize; in the Toolbars tab of the Customize panel, select
www.flexerasoftware.com/installshield/eval
the MSI Debugger check box.
Want to learn more best practices for building quality
installations?
Using the MSI Debugger, you can step through both the User Join an InstallShield training class – visit
Interface and Execute sequences, the latter in both immediate www.flexerasoftware.com/training for available classes.
and deferred modes.
Also, if you have a critical installation project but are short
To begin, select an action in the sequences and select Toggle on developer bandwidth or expertise, Flexera Software’s
Breakpoint (or press F9). This adds a stop-sign icon in the left Professional Services team can help. Learn more at:
margin next to the selected action; whenever you click the www.flexerasoftware.com/services/consulting/software-
MSI Debugging (right-pointing triangle) button or press F5, installations.htm.
execution
of your installer will continue to the next breakpoint.
At the bottom of the MSI Debugger window are lists in which
you can view and modify the values of the properties used by
your running installation. The left list displays the value of every
property used in your installation. The right list is initially blank,
and you can type in the names of properties of interest, and the
property value will be displayed. You can also modify property
values in either list by typing over the current value.
8 Flexera Software: InstallShield White Paper Series

9. Flexera Software LLC Schaumburg United Kingdom (Europe, Japan (Asia, For more office locations visit:
1000 East Woodfield Road, (Global Headquarters): Middle East Headquarters): Pacific Headquarters): www.flexerasoftware.com
Suite 400 +1 800-809-5659 +44 870-871-1111 +81 3-4360-8291
Schaumburg, IL 60173 USA +44 870-873-6300
Copyright © 2011 Flexera Software LLC. All other brand and product names mentioned herein may be the trademarks and registered trademarks of their respective owners.
IS_WP_RunTime-Logging_Oct11