W H I T E PA P E R

MSI Run-Time Logging and Debugging

by Robert Dickau Principal Technical Training Writer, Flexera Software

MSI Run-Time Logging and Debugging

Introduction
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. It is also assumed you are familiar with some of the wizards available with InstallShield, such as the Release Wizard and Component Wizard. The Release Wizard, available under the Build menu and also from the Releases view, lets you describe the propertiesmedia type, compression settings, and so forthof a release, and then builds the specified release image. The Component Wizard, available by right-clicking a feature in the Setup Design view, lets you create special types of components, such as components for COM servers, fonts, and Windows services. The InstallShield Help Library contains information about using every view and wizard in the InstallShield environment. The help library is available when you press F1 with any view selected; you can also select Contents from the Help menu to view the 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 enables you to edit the features, components, and component data used by your project; the Registry view enables you to modify the registry data installed by your installation program; and the Direct Editor view gives you access to the raw MSI database tables.
2

Using the InstallShield Environment

This white paper frequently refers to the InstallShield development environment. It is assumed you are familiar with the general layout of the InstallShield interface, which contains a list of views with which you can modify different portions of your installation project.

Learn More about InstallShield If you wish to learn more about the capabilities of InstallShield, please visit the Flexera Software Web site at www.flexerasoftware.com/installshield

Flexera Software: InstallShield White Paper Series

MSI Run-Time Logging and Debugging

In addition, InstallShield provides an Automation interface, with which you can modify the contents of a project file without using the graphical environment.

modify the Return Processing setting in the action properties to ignore the return code. Error 2732 and the Directory Table The Directory table contains the values of properties used as component destinations and locations of existing files. 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 1327 and Hard-Coded Drive Letters As a rule, you should use Windows Installer properties to refer to the locations of special directories on the target system. For example, instead of installing directly to C:\Program Files\, you should use the property [ProgramFilesFolder]. In some cases, however, it might be necessary to hard-code the destination for some files used in the installation. At run time, if Windows Installer is unable to find the drive letter, it will return error 1327. In addition, error 1327 can occur on some systems if the locations of such system folders as MyPicturesFolder are not defined in the target systems registry, or point to nonexistent directories. Similarly, error 1606 (Could not access location) can occur if the installation refers to a network resource that is not available when the installation is running. Error 1406 and the ProductVersion Property Windows Installer reports error 1406 if the installer is unable to write data to the registry, often because of insufficient privileges or an invalid key being specified. For example, Windows does not allow a subkey to be created directly under HKEY_LOCAL_ MACHINE. A less obvious cause of error 1406 is an invalid ProductVersion format. Windows Installer expects the product version to be of the form a.b.c, where a, b, and c are all numbers. If the ProductVersion property contains any alphabetic characters, as in the value 1.0.beta, Windows Installer reports error 1406. In this case, the product version should be modified to a strictly numeric value. Errors 2727 and the Directory Table The locations of destination directoriessuch as INSTALLDIR and SystemFolderon the target system are defined by entries in the Directory table of the MSI database. If a components destination directory does not appear in the Directory table, however, Windows Installer reports error 2727. To create a new destination folderthat is, create a new Directory entryyou can use a components Destination
3

Windows Installer Run-Time Errors

If Windows Installer encounters a fatal error at deployment time, an error dialog box similar to the following is displayed. The

error dialog box displays a numeric error code, along with a description of the error. After the user dismisses the error dialog box, Windows Installer displays the SetupCompleteError dialog box, which informs the user that no system changes have taken place. In the InstallShield Dialogs view, the error dialog box is called SetupError, and the text of each error message is taken from the Error table of the MSI database. For a complete list of built-in Windows Installer error codes and descriptions, see the Windows Installer Help Library topic Windows Installer Error Messages. The following sections describe the causes and resolutions of some of the most common Windows Installer error codes. Error 2762 and Deferred Actions Deferred custom actions must be scheduled between the standard InstallInitialize and InstallFinalize actions, which enclose the Windows Installer script-generation process. (The InstallShield build process reports build warning 6524 for this error, and the ICE validation process reports an ICE77 error.) If you encounter Windows Installer error 2762, you should either move your deferred action somewhere between InstallInitialize and InstallFinalize, or modify it to use immediate execution. Errors 17201723 and Failed Custom Actions By default, Windows Installer will exit the installation program if a custom action fails. When using executable and DLL custom actions, for example, failure means that the EXE or DLL returned a nonzero value. If a custom action fails, Windows Installer reports one of the error codes from 1720 through 1723. If you are the author of the custom action executable or DLL, you should modify it to return a zero value (in C code, you can use the constant ERROR_SUCCESS) to indicate success. For a VBScript action function, return the constant IDOK (value 1) to indicate success. To enable the installation and a DLL or script custom action to communicate, you should use properties instead of return values to pass values back and forth. If you are not the author of the custom action source, you can
Flexera Software: InstallShield White Paper Series

MSI Run-Time Logging and Debugging

property. In the Destination property, select Browse, create, or modify a directory entry, and then create the directory in the Browse for Directory panel. Similarly, you can use the Files and Folders view to create new destinations, and then drag and drop file icons into the new destination folder. For other errors, you should consult the Windows Installer Help Library and the InstallShield Knowledge Base for descriptions and suggested resolutions.

installation launcher setup.exe, you can use the /v switch to pass command-line switches through to msiexec.exe, as in the following example. Note that there must be no space after the /v switch and the arguments you pass through to msiexec.exe. setup /v/L*v C:\everything.log You can also embed environment variables in the command line. The following command creates a log file called everything. log inside the users Temp directory, the location of which is represented by the environment variable %temp%. setup /v/L*v \%temp%\everything.log\ To embed double quotes in the string you pass to /v, which is necessary in case the directorys name contains spaces, use the escape sequence \. With Windows Installer versions 4.0 and later, you can indicate that a log file should always be created, by using the MsiLogging property. In InstallShield, you can use the General Information setting Create MSI Logs to control automatic logging.

Windows Installer Log Files

The primary technique for debugging a Windows Installer installation is to create a log file during deployment. As described later in this document, a Windows Installer log file contains information about file-overwrite decisions, the success or failure of built-in and standard actions, feature and component states and actions, and the values of properties used by the installation. The following sections describe the different techniques for generating and interpreting a Windows Installer log file. 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 installer should log verbose information (v) about everything (*) the installer does. To narrow the range of data logged by the installation, you can specify alternative options after the /L value. 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: p: e: w: i: v: Display the final value of all MSI properties. Display all error messages. Display warning messages. Display action status messages. Write verbose information to the log file.

As an alternative, you can specify that you want a log file always to be created when the user launches setup.exe. In the Media view group, select the Releases view, and then select the desired release icon and the Setup.exe tab; in the MSI Command Line Arguments setting, enter the desired /L switch.

NOTE: Logging cannot be initiated from within a running installation, for example, from a custom action. Instead, logging must be initiated from the command line or an installation launcher, such as setup.exe. Windows Installer also supports a Logging machine policy setting. The Logging policy causes Windows Installer to create a randomly named log file in the users Temp folder for each installation, regardless of how it is launched. To set the Logging policy, select Run from the Start menu, and enter gpedit.msc. This launches the Group Policy Editor. The Windows Installer policy settings are available in the section Computer Configuration >Administrative Templates > Windows Components > Windows Installer, as displayed in the following figure.

As described above, the asterisk (*) specifies to use all flags except the verbose information flag (v). For a complete list of logging flags, see the Windows Installer Help Library topic Command Line Options. You can similarly log an uninstallation using the following command: 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

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 action. A return value of 1 indicates that the action completed successfully; other common return values are 3, which indicates failure, and 0, which indicates the action was skipped or could not be executed. For a complete list of return codes, see the Windows Installer Help Library topic Logging of Action Return Values. (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 actions 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. MSI (c) (E0:E8): Skipping FindRelatedProducts action: not run in maintenance mode Action ended 25:01:01: FindRelatedProducts. Return value 0. Similarly, if an action is skipped because it has already been performed, the entry appears similar to the following: MSI (s) (B8:F8): Doing action: AppSearch Action start 25:49:03: AppSearch. MSI (s) (B8:F8): Skipping AppSearch action: already done on client side Action ended 25:49:03: AppSearch. Return value 0.

To set the policy, double-click the Logging entry. In the Logging Properties panel (pictured in the following figure), you should select Enabled, and then specify which logging flags you want the automatically generated log files to use. Note that the Logging policy is used only if the user does not specify to create a log file; if the user manually creates a log file, the users logging settings will be used instead of the policy settings.

As an alternative, you can create a string value called Logging under the registry key: HKLM\Software\Policies\Microsoft\Windows\Installer\ The Logging value should contain the string of letters, such as aeipw, indicating what types of data you would like the log file to record. Again, this creates a randomly named log file in the users Temp directory.

Information Contained in a Log File

A log file contains the following types of information: Success or failure of standard and custom actions Feature and component states and actions Property values at the end of the User Interface and Execute sequences File-overwrite explanations The Error table contains the error messages displayed in the SetupError dialog box during a full user interface installation. In
Flexera Software: InstallShield White Paper Series

Feature and Component States and Actions

The log file will also tell you which features and components were installed, removed, advertised, and so forth. Typical entries for features and components appear similar to the following: Feature: ProgramFiles; Installed: Absent; Request: Local; Action: Local Component: main_exe; Installed: Absent; Request: Local; Action: Local
5

MSI Run-Time Logging and Debugging

The Installed entry specifies the existing state of the feature or component; the Request entry specifies the requested installation state of the feature or component; and the Action entry specifies the action that will be performed on the feature or component. (The Request and Action entries will typically be the same.) If you see a component name you do not recognize, the component could be part of a merge module or one created by a dynamic file link that includes subdirectories. A component from a merge module will have a name similar to the following: component_name.12341234_5678_5678_9ABC_ ABCDEFABCDEF A component created as part of a dynamic link that includes subdirectories will appear similar to the following: _11223344556677889900AABBCCDDEEFF The most common Installed values are the following: Absent: The feature or component is not present on the target system. Local: Feature or component is installed on the local system. Source: Feature or component is installed to run from the installation source. Advertise: Feature is advertised. For the Request and Action entries, the following are the most common values: Absent: Feature or component is being uninstalled. Local: Feature or component is being installed to the local system. Source: Feature or component is being installed to run from the installation source. Advertise: Feature is being advertised. Reinstall: Feature being reinstalled as part of a maintenance operation or minor upgrade. Null: No action is being taken on the feature or component. For a complete list of possible values, see the Windows Installer Help Library topic Checking the Installation of Features, Components, Files.

BBAA-0099-8877-665544332211} Property(S): ProductLanguage = 1033 Property(S): ProductName = Sample App 3000 Property(S): ProductVersion = 1.2.3 Similarly, properties values at the end of the User Interface sequence appear with the (C) notation to denote the client process. As you have seen, only changed values of public properties are passed from the User Interface sequence to the Execute sequence; the values of private properties are reset to their defaults when execution switches to the Execute sequence. Similarly, property values do not flow backward from the 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.

File-Overwrite Information

The log file also provides information about why files were or were not overwritten. An entry for a first-time installation might appear as follows: File: C:\Program Files\Training\Sample.exe; To be installed; No patch; No existing file The entry indicates that there is no existing file with the name Sample.exe in the target directory, and therefore this will be installed. Windows Installer follows a set of default rules when determining whether to overwrite an existing file on the target system. For example, by default a versioned file will not overwrite an identical file, in which case the log contains an entry similar to the following: File: C:\Program Files\MinorUpgrade\UpdateMe.exe; Wont Overwrite; No patch; Existing file is of an equal version There are some techniques you can use to modify the default file-overwrite behavior. One of the techniques discussed was modifying the REINSTALLMODE property value to include the letter a, which indicates always to overwrite an existing file. In this case, the log entry would appear similar to the following: File: C:\Program Files\MinorUpgrade\UpdateMe.exe; Overwrite; No patch; REINSTALLMODE specifies all files to be overwritten If a file is not being installed on the target system, you can search for the files name in the log file to see why Windows Installer determined the file should not be installed. TIP: Under the InstallShield Tools menu is the InstallShield MSI Log Analyzer. This tool enables you to select a Windows Installer package to log, and then generates the log file. After generating a log file, you can select to view and analyze it; the tool displays an annotated version of the log file, along with a summary showing feature, component, and file actions, property values, and action status.

Properties

Properties are used to store global information used by the installation. For a normal, full-UI installation, the log file will contain the final values of properties at the end of the Execute sequence and at the end of the User Interface sequence. Property values at the end of the Execute sequence appear similar to the following, containing the notation (S) to denote the server process. Property(S): Manufacturer = Training Co. Property(S): ProductCode = {FFEEDDCC-

Flexera Software: InstallShield White Paper Series

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 string to the log file. Function WriteToLog( ) Const msiMessageTypeInfo = &H04000000 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] msgrec.StringData(2) = Some description... string to put in [2] write info message to log file; see the MSI Help Library for other message types Session.Message msiMessageTypeInfo, msgrec End Function When you use this code in a custom action, the log file will contain the line specified in the code. The function will not start logging if it was not already enabled. If this self-repair operation happens, the event log describes the product, feature, component, and resource involved. The log entries appear similar to the following: Detection of product {11111111-1111-1111-1111111111111111}, feature Main_Program failed during request for component {22222222-2222-2222-2222222222222222}. Detection of product {11111111-1111-1111-1111111111111111}, feature Main_Program, component {22222222-2222-2222-2222-222222222222} failed. The resource C:\Program Files\Training\sample.exe does not exist. The log messages should display the missing resource that causes self-repair, with which information you can determine why the resource is not present. TIP: Given a component code, you can determine the products that use it by calling the MsiEnumClients function or Installer. ComponentClients property. Given a product code, you can get its name and other properties by calling the MsiGetProductInfo function or the Installer.ProductInfo property.

Event Logging and MSI Self-Repair

An important type of information written to the event log is the detail of why Windows Installer is performing a self-repair operation. This type of self-repair operation is typically manifested by a small Windows Installer dialog boxsimilar to the following figureappearing when an application is launched through an advertised shortcut.

Windows Installer and the Event Log

Windows Installer automatically interacts with the event log. For example, every successful installation writes an entry to the Application section of the event log, using the source MsiInstaller. To view the event log, you can use the Event Viewer utility available in the Administrative Tools group. For example, a successful installation will create an event log entry similar to the following. Similarly, warnings and fatal errors are also automatically written

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

MSI Run-Time Logging and Debugging

The MSI Debugger view shows an ordered list of actions, where each action name (and condition, if there is one) is displayed. Similar to the display of the Sequences view, the dialog boxes explicitly listed in the User Interface sequencethat is, listed in the InstallUISequence tableare displayed as root-level actions, while dialog boxes that follow are indented based on the Nextbutton control events. To launch the debugger, you can pull down the Build menu, select the MSI Debugger submenu, and then select the desired operation: Toggle breakpoint (F9), step into (F11), or step over (F10). You can press F5 to start debugging. By default, the MSI Debugger toolbar is not displayed. To display the toolbar, pull down the Tools menu and select Customize; in the Toolbars tab of the Customize panel, select the MSI Debugger check box.

As you run the installation, you can watch the values of properties change as different actions take place. This way, you can determine (for example) why conditions are failing unexpectedly or why component destinations are being set to unexpected values.

Summary

This white paper discusses techniques for run-time logging and debugging, including investigating Windows Installer error codes, generating and interpreting Windows Installer log files, and using the InstallShield MSI Debugger.

Begin a Free Evaluation of InstallShield

You can download a free trial version of InstallShield from the Flexera Software Web site at: www.flexerasoftware.com/installshield/eval

Using the MSI Debugger, you can step through both the User Interface and Execute sequences, the latter in both immediate and deferred modes. To begin, select an action in the sequences and select Toggle Breakpoint (or press F9). This adds a stop-sign icon in the left margin next to the selected action; whenever you click the MSI Debugging (right-pointing triangle) button or press F5, 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.

Want to learn more best practices for building quality installations? Join an InstallShield training class visit www.flexerasoftware.com/training for available classes. Also, if you have a critical installation project but are short on developer bandwidth or expertise, Flexera Softwares Professional Services team can help. Learn more at: www.flexerasoftware.com/services/consulting/softwareinstallations.htm.

Flexera Software: InstallShield White Paper Series

Flexera Software LLC 1000 East Woodfield Road, Suite 400 Schaumburg, IL 60173 USA

Schaumburg (Global Headquarters): +1 800-809-5659

United Kingdom (Europe, Middle East Headquarters): +44 870-871-1111 +44 870-873-6300

Japan (Asia, Pacific Headquarters): +81 3-4360-8291

For more office locations visit: www.flexerasoftware.com

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