WH

ITE

PA

PE

R

MSI Run-Time Logging and Debuggingby Robert DickauPrincipal Technical Training Writer, Flexera Software

MSI Run-Time Logging and Debugging

Introduct ionBecause Windows Installer installat ions 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:

• Invest igat ing Windows Installer error codes• Generat ing and interpret ing Windows Installer log files• Using the InstallShield MSI Debugger

This white paper also discusses how InstallShield® helps you with run-t ime logging and debugging.

Using the InstallShield EnvironmentThis white paper frequent ly 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 port ions of your installat ion project.

For example, the General Information view is where you set general product and project propert ies; 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 installat ion program; and the Direct Editor view gives you access to the raw MSI database tables.

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 propert ies—media type, compression sett ings, and so forth—of 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 addit ion 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 distribut ion directory.

To rebuild a project, you pass IsCmdBld the project file path, the product configurat ion 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

2 Flexera Software: InstallShield White Paper Series

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

MSI Run-Time Logging and Debugging

3Flexera Software: InstallShield White Paper Series

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

Windows Installer Run-Time ErrorsIf Windows Installer encounters a fatal error at deployment t ime, an error dialog box similar to the following is displayed. The

error dialog box displays a numeric error code, along with a descript ion 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 descript ions, see the Windows Installer Help Library topic “Windows Installer Error Messages”.

The following sect ions describe the causes and resolut ions of some of the most common Windows Installer error codes.

Error 2762 and Deferred Act ionsDeferred custom act ions must be scheduled between the standard InstallInit ialize and InstallFinalize act ions, which enclose the Windows Installer script-generat ion process. (The InstallShield build process reports build warning –6524 for this error, and the ICE validat ion process reports an ICE77 error.) If you encounter Windows Installer error 2762, you should either move your deferred act ion somewhere between InstallInit ialize and InstallFinalize, or modify it to use immediate execut ion.

Errors 1720–1723 and Failed Custom Act ionsBy default, Windows Installer will exit the installat ion program if a custom act ion fails. When using executable and DLL custom act ions, for example, failure means that the EXE or DLL returned a nonzero value. If a custom act ion fails, Windows Installer reports one of the error codes from 1720 through 1723.

If you are the author of the custom act ion 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 act ion funct ion, return the constant IDOK (value 1) to indicate success. To enable the installat ion and a DLL or script custom act ion to communicate, you should use propert ies instead of return values to pass values back and forth.

If you are not the author of the custom act ion source, you can

modify the Return Processing sett ing in the act ion propert ies to ignore the return code.

Error 2732 and the Directory TableThe Directory table contains the values of propert ies used as component dest inat ions and locations of exist ing files. The values of Directory-table propert ies, such as SystemFolder and ProgramFilesFolder, are evaluated during the standard cost ing operat ions, which occur when the act ions from CostInit ialize through CostFinalize run. Because Directory-table property values are unavailable unt il these act ions run, any custom actions that refer to Directory propert ies will cause the installat ion to fail with error 2732. For example, if you have a launch-an-executable act ion that launches Notepad.exe from WindowsFolder, you must schedule the act ion after the CostFinalize act ion to avoid error 2732.

Error 1327 and Hard-Coded Drive LettersAs a rule, you should use Windows Installer propert ies to refer to the locations of special directories on the target system. For example, instead of installing direct ly to “C:\Program Files\”, you should use the property [ProgramFilesFolder]. In some cases, however, it might be necessary to hard-code the dest inat ion for some files used in the installat ion. At run t ime, if Windows Installer is unable to find the drive letter, it will return error 1327.

In addit ion, error 1327 can occur on some systems if the locat ions of such system folders as MyPicturesFolder are not defined in the target system’s registry, or point to nonexistent directories.

Similarly, error 1606 (“Could not access locat ion…”) can occur if the installat ion refers to a network resource that is not available when the installat ion is running.

Error 1406 and the ProductVersion PropertyWindows 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 direct ly 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 strict ly numeric value.

Errors 2727 and the Directory TableThe locations of dest inat ion directories—such as INSTALLDIR and SystemFolder—on the target system are defined by entries in the Directory table of the MSI database. If a component’s dest inat ion directory does not appear in the Directory table, however, Windows Installer reports error 2727.

To create a new dest inat ion folder—that is, create a new Directory entry—you can use a component’s Dest inat ion

MSI Run-Time Logging and Debugging

Flexera Software: InstallShield White Paper Series4

property. In the Dest inat ion 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 dest inat ions, and then drag and drop file icons into the new dest inat ion folder.

For other errors, you should consult the Windows Installer Help Library and the InstallShield Knowledge Base for descript ions and suggested resolut ions.

Windows Installer Log FilesThe primary technique for debugging a Windows Installer installat ion 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 act ions, feature and component states and act ions, and the values of propert ies used by the installat ion.

The following sect ions describe the different techniques for generat ing and interpret ing a Windows Installer log file.

Creat ing a Log FileYou 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 installat ion, you can specify alternat ive options after the /L value.

After the /L switch and flags, you specify the relat ive 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 exist ing 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: Display the final value of all MSI propert ies.• e: Display all error messages.• w: Display warning messages.• i: Display act ion status messages.• v: Write verbose information to the log file.

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 uninstallat ion using the following command:

msiexec /x {product-code} /L*v uninstallinfo.log

If you built your installat ion with InstallShield to use the

installat ion 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 user’s 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 directory’s 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 sett ing “Create MSI Logs” to control automatic logging.

As an alternat ive, 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 sett ing, enter the desired /L switch.

NOTE: Logging cannot be init iated from within a running installat ion, for example, from a custom act ion. Instead, logging must be init iated from the command line or an installat ion launcher, such as setup.exe.

Windows Installer also supports a Logging machine policy sett ing. The Logging policy causes Windows Installer to create a randomly named log file in the user’s Temp folder for each installat ion, 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 sett ings are available in the sect ion Computer Configurat ion >Administrat ive Templates > Windows Components > Windows Installer, as displayed in the following figure.

MSI Run-Time Logging and Debugging

5Flexera Software: InstallShield White Paper Series

To set the policy, double-click the Logging entry. In the Logging Propert ies 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 user’s logging sett ings will be used instead of the policy sett ings.

As an alternat ive, 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”, indicat ing what types of data you would like the log file to record. Again, this creates a randomly named log file in the user’s Temp directory.

Information Contained in a Log FileA log file contains the following types of information:

• Success or failure of standard and custom act ions• Feature and component states and act ions• 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 installat ion. In

addit ion, 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 ValuesThe log file contains an entry for each standard and custom action that the installer runs. A sample entry (for the standard WriteRegistryValues act ion) appears similar to the following:

MSI (s) (B8:F8): Doing act ion: WriteRegistryValuesAction start 25:00:05: WriteRegistryValues.Act ion ended 25:00:05: WriteRegistryValues. Return value 1.

The entry contains t imestamp and return value information for the act ion. A return value of 1 indicates that the act ion completed successfully; other common return values are 3, which indicates failure, and 0, which indicates the act ion was skipped or could not be executed. For a complete list of return codes, see the Windows Installer Help Library topic “Logging of Act ion 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 act ion ran in the Execute sequence.)

The log entry will also specify if the act ion’s condit ion failed, using an entry similar to the following:

MSI (c) (E0:E8): Skipping act ion: LaunchCondit ions (condit ion is false)

If an act ion is skipped because Windows Installer does not perform it for a certain type of installat ion, the entry appears similar to one of the following, report ing the return value 0:

MSI (c) (E0:E8): Doing act ion: FindRelatedProductsAct ion start 25:01:01: FindRelatedProducts.MSI (c) (E0:E8): Skipping FindRelatedProducts act ion: not run in maintenance modeAction ended 25:01:01: FindRelatedProducts. Return value 0.

Similarly, if an act ion is skipped because it has already been performed, the entry appears similar to the following:

MSI (s) (B8:F8): Doing act ion: AppSearchAction start 25:49:03: AppSearch.MSI (s) (B8:F8): Skipping AppSearch act ion: already done on client sideAction ended 25:49:03: AppSearch. Return value 0.

Feature and Component States and Act ionsThe log file will also tell you which features and components were installed, removed, advert ised, and so forth. Typical entries for features and components appear similar to the following:

Feature: ProgramFiles; Installed: Absent; Request: Local; Act ion: LocalComponent: main_exe; Installed: Absent; Request: Local; Act ion: Local

MSI Run-Time Logging and Debugging

Flexera Software: InstallShield White Paper Series6

The Installed entry specifies the exist ing state of the feature or component; the Request entry specifies the requested installat ion state of the feature or component; and the Act ion entry specifies the act ion 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

installat ion source.• Advert ise: Feature is advert ised.

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 installat ion source.• Advert ise: Feature is being advert ised.• Reinstall: Feature being reinstalled as part of a maintenance

operat ion or minor upgrade.• Null: No act ion is being taken on the feature or component.

For a complete list of possible values, see the Windows Installer Help Library topic “Checking the Installat ion of Features, Components, Files”.

Propert iesPropert ies are used to store global information used by the installat ion. For a normal, full-UI installat ion, the log file will contain the final values of propert ies 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 notat ion “(S)” to denote the “server” process.

Property(S): Manufacturer = Training Co.Property(S): ProductCode = {FFEEDDCC-

BBAA-0099-8877-665544332211}Property(S): ProductLanguage = 1033Property(S): ProductName = Sample App 3000Property(S): ProductVersion = 1.2.3

Similarly, propert ies values at the end of the User Interface sequence appear with the “(C)” notat ion to denote the “client” process. As you have seen, only changed values of public propert ies are passed from the User Interface sequence to the Execute sequence; the values of private propert ies are reset to their defaults when execut ion 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 act ion in the Execute sequence will not be available on the SetupCompleteSuccess dialog box, for example.

File-Overwrite InformationThe log file also provides information about why files were or were not overwritten. An entry for a first-t ime installat ion might appear as follows:

File: C:\Program Files\Training\Sample.exe; To be installed; No patch; No exist ing file

The entry indicates that there is no exist ing 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 exist ing file on the target system. For example, by default a versioned file will not overwrite an ident ical file, in which case the log contains an entry similar to the following:

File: C:\Program Files\MinorUpgrade\UpdateMe.exe; Won’t Overwrite; No patch; Exist ing 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 exist ing 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 file’s 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 generat ing 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 act ions, property values, and act ion status.

MSI Run-Time Logging and Debugging

7Flexera Software: InstallShield White Paper Series

Writ ing Custom Entries to a Log FileBy default, a custom act ion does not create entries in a log file (unless the act ion fails, in which case the generic error number will be returned). To enable your custom act ions to write custom data to a log file, you can add code that uses the Windows Installer Session.Message method (in a VBScript custom act ion) or MsiProcessMessage funct ion (in a DLL custom act ion) to write custom strings to the log file, if logging is enabled.

For example, the following VBScript funct ion writes a custom string to the log file.

Funct ion 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) = “Act ion: [1], Message: [2]”msgrec.StringData(1) = “SomeAct ion” ‘ string to put in [1]msgrec.StringData(2) = “Some descript ion...” ‘ string to put in [2]

‘ write info message to log file; see the MSI Help Library‘ for other message typesSession.Message msiMessageTypeInfo, msgrec

End Funct ion

When you use this code in a custom act ion, the log file will contain the line specified in the code. The funct ion will not start logging if it was not already enabled.

Windows Installer and the Event LogWindows Installer automatically interacts with the event log. For example, every successful installat ion writes an entry to the Applicat ion sect ion of the event log, using the source MsiInstaller. To view the event log, you can use the Event Viewer ut ility available in the Administrat ive Tools group.

For example, a successful installat ion will create an event log entry similar to the following. Similarly, warnings and fatal errors are also automatically written

to the event log. A full-UI installer shows errors in the SetupError dialog box described earlier in this document. For a silent installat ion, 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.

Event Logging and MSI Self-RepairAn important type of information written to the event log is the detail of why Windows Installer is performing a self-repair operat ion. This type of self-repair operat ion is typically manifested by a small Windows Installer dialog box—similar to the following figure—appearing when an applicat ion is launched through an advert ised shortcut.

If this self-repair operat ion happens, the event log describes the product, feature, component, and resource involved. The log entries appear similar to the following:

Detect ion of product ‘{11111111-1111-1111-1111-111111111111}’, feature ‘Main_Program’ failed during request for component ‘{22222222-2222-2222-2222-222222222222}’.

Detect ion of product ‘{11111111-1111-1111-1111-111111111111}’, 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 funct ion or Installer.ComponentClients property. Given a product code, you can get its name and other propert ies by calling the MsiGetProductInfo funct ion or the Installer.ProductInfo property.

InstallShield MSI DebuggerThe Addit ional Tools view group contains the MSI Debugger view, which enables you to step through the act ions performed by your installat ion, and to view and modify the values of Windows Installer propert ies as the installat ion progresses.

MSI Run-Time Logging and Debugging

Flexera Software: InstallShield White Paper Series8

The MSI Debugger view shows an ordered list of act ions, where each act ion name (and condit ion, if there is one) is displayed. Similar to the display of the Sequences view, the dialog boxes explicit ly listed in the User Interface sequence—that is, listed in the InstallUISequence table—are displayed as root-level act ions, while dialog boxes that follow are indented based on the Next-button control events.

To launch the debugger, you can pull down the Build menu, select the MSI Debugger submenu, and then select the desired operat ion: 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.

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 act ion in the sequences and select Toggle Breakpoint (or press F9). This adds a stop-sign icon in the left margin next to the selected act ion; whenever you click the MSI Debugging (right-point ing triangle) button or press F5, execut ion of your installer will cont inue 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 propert ies used by your running installat ion. The left list displays the value of every property used in your installat ion. The right list is init ially blank, and you can type in the names of propert ies of interest, and the property value will be displayed. You can also modify property values in either list by typing over the current value.

As you run the installat ion, you can watch the values of propert ies change as different act ions take place. This way, you can determine (for example) why condit ions are failing unexpectedly or why component dest inat ions are being set to unexpected values.

SummaryThis white paper discusses techniques for run-t ime logging and debugging, including invest igat ing Windows Installer error codes, generat ing and interpret ing Windows Installer log files, and using the InstallShield MSI Debugger.

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

Want to learn more best pract ices for building quality installat ions? Join an InstallShield training class – visit www.flexerasoftware.com/training for available classes.

Also, if you have a crit ical installat ion project but are short on developer bandwidth or expert ise, Flexera Software’s Professional Services team can help. Learn more at: www.flexerasoftware.com/services/consult ing/software-installat ions.htm.

WH

ITE

PA

PE

R

Flexera Software LLC1000 East Woodfield Road, Suite 400Schaumburg, 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 locat ions visit:www.flexerasoftware.com

Copyright © 2011 Flexera Software LLC. All other brand and product names ment ioned herein may be the trademarks and registered trademarks of their respect ive owners. IS_WP_RunTime-Logging_Oct11