MSI Run-Time Logging and Debugging


Published on

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.

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

MSI Run-Time Logging and Debugging

  1. 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. 2. MSI Run-Time Logging and DebuggingIntroduction It is also assumed you are familiar with some of the wizardsBecause Windows Installer installations do not contain an available with InstallShield, such as the Release Wizard andexplicit script, the debugging techniques are different from those Component Wizard.generally used with programming languages. The techniquesdescribed 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 featureThis white paper also discusses how InstallShield® helps you with in the Setup Design view, lets you create special types ofrun-time logging and debugging. components, such as components for COM servers, fonts, and Windows services.Using the InstallShield EnvironmentThis white paper frequently refers to the InstallShield The InstallShield Help Library contains information about usingdevelopment environment. It is assumed you are familiar with the every view and wizard in the InstallShield environment. The helpgeneral 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 theinstallation 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 ReleaseNameFor example, the General Information view is where you setgeneral product and project properties; the Setup Design view Learn More about InstallShieldenables you to edit the features, components, and component If you wish to learn more about the capabilities ofdata used by your project; the Registry view enables you to InstallShield, please visit the Flexera Software Web sitemodify the registry data installed by your installation program; at the Direct Editor view gives you access to the raw MSIdatabase tables.2 Flexera Software: InstallShield White Paper Series
  3. 3. MSI Run-Time Logging and DebuggingIn addition, InstallShield provides an Automation interface, with modify the Return Processing setting in the action properties towhich you can modify the contents of a project file without using ignore the return code.the graphical environment. Error 2732 and the Directory TableWindows Installer Run-Time Errors The Directory table contains the values of properties used asIf Windows Installer encounters a fatal error at deployment time, component destinations and locations of existing files. Thean 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 Lettersdescription of the error. After the user dismisses the error dialog As a rule, you should use Windows Installer properties to referbox, Windows Installer displays the SetupCompleteError dialog to the locations of special directories on the target system. Forbox, 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 destinationIn the InstallShield Dialogs view, the error dialog box is called for some files used in the installation. At run time, if WindowsSetupError, 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 ofbuilt-in Windows Installer error codes and descriptions, see the In addition, error 1327 can occur on some systems if theWindows Installer Help Library topic “Windows Installer locations of such system folders as MyPicturesFolder are notError Messages”. defined in the target system’s registry, or point to nonexistent directories.The following sections describe the causes and resolutions ofsome 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 notError 2762 and Deferred Actions available when the installation is running.Deferred custom actions must be scheduled between thestandard InstallInitialize and InstallFinalize actions, which Error 1406 and the ProductVersion Propertyenclose the Windows Installer script-generation process. (The Windows Installer reports error 1406 if the installer is unable toInstallShield build process reports build warning –6524 for this write data to the registry, often because of insufficient privilegeserror, and the ICE validation process reports an ICE77 error.) If or an invalid key being specified. For example, Windows doesyou 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 ProductVersionErrors 1720–1723 and Failed Custom Actions format. Windows Installer expects the product version to beBy default, Windows Installer will exit the installation program of the form a.b.c, where a, b, and c are all numbers. If theif a custom action fails. When using executable and DLL custom ProductVersion property contains any alphabetic characters, asactions, 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 strictlyreports 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 Tableyou should modify it to return a zero value (in C code, you can The locations of destination directories—such as INSTALLDIRuse the constant ERROR_SUCCESS) to indicate success. For and SystemFolder—on the target system are defined by entriesa VBScript action function, return the constant IDOK (value in the Directory table of the MSI database. If a component’s1) 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 newIf you are not the author of the custom action source, you can Directory entry—you can use a component’s DestinationFlexera Software: InstallShield White Paper Series 3
  4. 4. MSI Run-Time Logging and Debuggingproperty. In the Destination property, select “Browse, create, or installation launcher setup.exe, you can use the /v switch tomodify a directory entry”, and then create the directory in the pass command-line switches through to msiexec.exe, as in theBrowse for Directory panel. Similarly, you can use the Files and following example. Note that there must be no space after the /vFolders 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 HelpLibrary 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 isWindows Installer Log Files represented by the environment variable %temp%.The primary technique for debugging a Windows Installerinstallation 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 iscontains information about file-overwrite decisions, the success necessary in case the directory’s name contains spaces, use theor failure of built-in and standard actions, feature and component escape sequence ”.states and actions, and the values of properties used by theinstallation. With Windows Installer versions 4.0 and later, you can indicate that a log file should always be created, by using the MsiLoggingThe following sections describe the different techniques for property. In InstallShield, you can use the General Informationgenerating and interpreting a Windows Installer log file. setting “Create MSI Logs” to control automatic logging.Creating 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.logThe argument /L*v used in this command indicates that the As an alternative, you can specify that you want a log fileinstaller 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 selectthe installation, you can specify alternative options after the /L the desired release icon and the Setup.exe tab; in the MSIvalue. Command Line Arguments setting, enter the desired /L switch.After the /L switch and flags, you specify the relative or absolutepath to the log file you want to create. If the file already exists, itwill be overwritten (unless you use the + switch, which specifiesto append to an existing log file). Note that Windows Installerwill report an error if you specify a nonexistent directory in whichto 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 eachAs described above, the asterisk (*) specifies to use all flags installation, regardless of how it is launched. To set the Loggingexcept the verbose information flag (v). For a complete list of policy, select Run from the Start menu, and enter gpedit.msc. Thislogging flags, see the Windows Installer Help Library topic launches the Group Policy Editor.“Command Line Options”. The Windows Installer policy settings are available in theYou 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.logIf you built your installation with InstallShield to use the4 Flexera Software: InstallShield White Paper Series
  5. 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 theTo set the policy, double-click the Logging entry. In the Logging action. A return value of 1 indicates that the action completedProperties panel (pictured in the following figure), you should successfully; other common return values are 3, which indicatesselect Enabled, and then specify which logging flags you want failure, and 0, which indicates the action was skipped or couldthe automatically generated log files to use. Note that the not be executed. For a complete list of return codes, see theLogging policy is used only if the user does not specify to create Windows Installer Help Library topic “Logging of Actiona 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 rununder 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 beenThe 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 fileto record. Again, this creates a randomly named log file in the MSI (s) (B8:F8): Doing action: AppSearchuser’s Temp directory. Action start 25:49:03: AppSearch. MSI (s) (B8:F8): Skipping AppSearch action: already done onInformation Contained in a Log File client sideA 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: LocalSetupError dialog box during a full user interface installation. In Component: main_exe; Installed: Absent; Request: Local; Action: LocalFlexera Software: InstallShield White Paper Series 5
  6. 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. 7. MSI Run-Time Logging and DebuggingWriting Custom Entries to a Log FileBy default, a custom action does not create entries in a log file(unless the action fails, in which case the generic error numberwill be returned). To enable your custom actions to write customdata to a log file, you can add code that uses the WindowsInstaller Session.Message method (in a VBScript custom action)or MsiProcessMessage function (in a DLL custom action) to writecustom strings to the log file, if logging is enabled.For example, the following VBScript function writes a custom Event Logging and MSI Self-Repairstring 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’, componentlogging if it was not already enabled. ‘{22222222-2222-2222-2222-222222222222}’ failed. The resource ‘C:Program FilesTrainingsample.exe’ doesWindows 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 causesApplication section of the event log, using the source MsiInstaller. self-repair, with which information you can determine why theTo 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 productsFor 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 itsSimilarly, 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 the event log. A full-UI installer shows errors in the SetupErrordialog box described earlier in this document. For a silentinstallation, 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. 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 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 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 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. 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.comSuite 400 +1 800-809-5659 +44 870-871-1111 +81 3-4360-8291Schaumburg, IL 60173 USA +44 870-873-6300Copyright © 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