W H I T E PA P E R

Fixing Design-Time Validation Errors

by Robert Dickau Principal Technical Training Writer, Flexera Software

Fixing Design-Time Validation Errors

Introduction
To help you detect and resolve potential problems in your installation project, you can perform several types of validation before you run the installation on a target system. The types of validation discussed in this white paper include: Build warnings and errors Internal Consistency Evaluator (ICE) validation Update and patch validation Addressing these types of design-time validation errors will help you avoid errors. This white paper also shows you how InstallShield helps you with design-time validation. 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 properties media 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 InstallShield 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 In addition, InstallShield provides an Automation interface, with which you can modify the contents of a project file without using the graphical environment. 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

Validat ing MSI Updates and Patches

Build Warnings and Errors

As InstallShield builds your project, status messages are displayed in the output window at the bottom of the development environment.

For a command-line build using IsCmdBld.exe, status messages are displayed at the command prompt. If any errors or warnings occur, they are displayed in the Build tab of the output window, as well as in the Tasks tab. The Tasks tab contains links to the InstallShield Knowledge Base for the latest information about resolving these warnings. (This requires a live Internet connection.)

the locations of source files on the development system. Whenever you add a file to a component, InstallShield by default creates a path variable or reuses an existing path variable to represent that files location. If you move the source file, instead of having to reestablish the file link, you can simply assign the path variable a new value in the Path Variables view of the InstallShield environment. (The InstallShield help library also describes registrybased and environment variablebased path variables, with which you can modify path variable values without having to modify the project file.) In addition, if you have source directories that contain lists of files that are continually changing, you can use dynamic file linking. With dynamic linking, you specify a directory and optional file name masks for inclusion and exclusion. Each build process then copies all of the matching files in the dynamic link into the corresponding component. An important consideration regarding file linking is that a dynamically linked file cannot be the key file of its component. However, a component can contain any combination of static and dynamic links, and therefore a solution is to set a statically linked file as the key file, additionally marking the key file as an exclusion to the dynamic link. Moreover, when using dynamic file linking, it is important to specify a previous package in the build settings to ensure File, Component, and Media table keys are synchronized between builds. For more information, see the InstallShield help topic Upgrade Considerations. Another error related to missing data on the build system is 1024 (File not found. Cannot stream the file into the Binary file.), which occurs if a file used by a custom action or dialog box (such as a DLL or bitmap file) has been moved or deleted. Similarly, build error 7017 occurs if your project includes merge modules or other redistributables that are not present on your build system. Other errors sometimes related to missing source files are 6271 (File file not found. An error occurred building the MsiFileHash table record) and 1501 (Could not compress file into file.cab).

Addressing Build Errors and Warnings

Build errors and warnings typically refer to missing or unexpected source files or merge modules, but can refer to any condition that prevents a build from completing. For example, the build process reports error 1014 (Cannot rename directory) if an installation inside the build folder is running, or if Windows Explorer or a command prompt is pointing to the build folder. In addition, the InstallShield environment will prevent you from entering some project settings that would cause the package to fail at deployment time. For example, a project cannot use DATABASE or PATCH as an internal Directory-table identifierthe way INSTALLDIR or SystemFolder is a Directory identifieras these are reserved identifiers used by Windows Installer. If you try to define a component destination folder with internal identifier DATABASE, the environment will rename the identifier to a valid value such as DATABASE_DIR1. (If, however, you use the Direct Editor to define a Directory called DATABASE or PATCH, the build process will report error 6262.) TIP: When you manually search the InstallShield Knowledge Base for a particular build warning or error number, omit the minus sign in the search. For example, instead of searching for 1014, search for 1014.

Design Issues and Build Warnings

In addition to issues related to source files, some build warnings address design issues in your project. A deferred custom action must be placed between InstallInitialize and InstallFinalize in the Execute sequence of an installation. To help detect problems with improper placement of deferred actions, the build process generates warning 6524 if it detects a deferred custom action outside the range of InstallInitialize and InstallFinalize. TIP: By default, the build process will continue to completion even if any build errors occur. To cancel a build, you can click the Stop Build toolbar button, or press Ctrl+Break. To specify always to stop a build if an error occurs, you can pull down the Tools menu and select Options; in the General tab, select the check box labeled Stop build process when first error is encountered.

Errors Regarding Missing Source Files

If the build process cannot find a source file, because it has been renamed or deleted, the build process returns error 6103 (Could not find file file) and 1007 (Cannot copy source file to target directory). Two features of InstallShield that can help you work with source files are path variables and dynamic file linking. Path variables are variables used by the InstallShield build process to represent

Flexera Software: InstallShield White Paper Series

Validat ing MSI Updates and Patches

If you use the command-line build tool IsCmdBld, the -x switch enables you to stop the build when the first error occurs, and the -w switch lets you specify that build warnings should be treated as errors.

To perform ICE validation using the command-line build tool IsCmdBld, you can pass it the -m switch, followed by the path to the validation file (.cub file) to use. The Microsoft .cub files are stored in the Support subdirectory of the InstallShield distribution: IsCmdBld -p ProjectName.ism -a FullBuild -r cdrom -m C:\Program Files\InstallShield\Support\darice.cub NOTE: There are separate merge module validation rules for merge module (.msm) projects. In the InstallShield environment, you can select Build > Validate > Merge Module Validation Suite. From the command line, you can validate the database using the validation file mergemod.cub. You can specify that InstallShield should perform ICE validation whenever you perform a build by pulling down the Tools menu, selecting Options, and then selecting the Validation tab. In the Validation tab, select the check box labeled Perform validation using, and then select the desired validation suite.

ICE Validation

Internal Consistency Evaluator (ICE) validation tests your MSI database records for different types of data that can lead to undesirable or unpredictable run-time behavior. There are over 100 predefined ICE rules, testing for such conditions as duplicated component codes, missing properties and dialog boxes, and invalid scheduling for various types of built-in and custom actions. (The graphical editors and referential integrity features of the InstallShield environment ensure that many types of ICE failures do not occur.) Because ICE validation is performed on an MSI database and not an ISM project file, your project must build successfully before you can perform this type of validation. You perform ICE validation in the InstallShield environment by pulling down the Build menu, selecting Validate, and then selecting Full MSI Validation Suite.

As with build errors and warnings, ICE errors and warnings appear in the Tasks tab of the output window.

(The output window in InstallShield displays only ICE warnings and errors. If you use another tool such as Orca to perform validation, you might see additional informational messages regarding the ICE validation process.) The Validate tab also lists any ICE warnings or errors that occur, and provides a hyperlink to a text log file that contains the validation results. Validation log files are saved in a subdirectory called ValidationFiles, relative to the release folder. In addition, the Direct Editor view highlights tables, records, and fields related to the validation error or warning.

Using the Customize button, you can additionally select rules within a validation suite to skip. The Windows Installer Help Library contains a summary of ICE messages in the topic ICE Reference; and also provides a specific page for each ICE error, describing typical scenarios in which the error occurs and how to address the error.

TIP: You can right-click an error or warning in the Tasks tab of the output window and select Go to Direct Editor, which selects the corresponding record in the Direct Editor view.
4

Flexera Software: InstallShield White Paper Series

Validat ing MSI Updates and Patches

ICE Warnings You Can Ignore

The following paragraphs describe some ICE warnings that can be safely ignored. ICE36 and ARPPRODUCTICON An advertised Windows Installer installation is one that installs application entry points, such as shortcuts, COM information, and file-extension information on a users system, but does not install any application files or registry information until the user invokes one of these entry points. Because the targets of these entry points will not initially be installed, Windows Installer requires any icon resources used by these entry points to be extracted and stored separately inside the MSI database. To this end, the Icon table is used to store icons used by advertiseable shortcuts, COM classes, and file extensions. ICE36 warns if any icons in the Icon table appear to be unused, which means the MSI database is larger than necessary. However, some ICE validation suites overlook the possibility that resources in the Icon table can refer to the ARPPRODUCTICON property, which specifies the icon to appear in the applications Add or Remove Programs entry. Therefore, ICE36 errors that refer to ARPPRODUCTICON can safely be ignored. ICE17 and InstallShield SQL Dialog Boxes ICE17 tests various characteristics of user-interface controls, including checking that PushButton controls have associated control events; icons used for controls are available in the Binary table; and that ComboBox, ListBox, and RadioButton controls have corresponding data in the respective tables. With InstallShield projects, validation will report an ICE17 warning for the SQL dialog boxes SQLBrowse and SQLLogin, which create their data dynamically at run time. These warnings can safely be ignored. ICE33 and the Registry Table The self-registration process for COM serverscommonly called selfregistering DLLs and OCXsplaces the registration information in the target systems registry. COM information is typically written to the keys HKCR\CLSID\{CLSID} and HKCR\Com.Prog.Id when the DllRegisterServer entry point of the COM library is invoked. Calling the DllRegisterServer function in a COM library is often called legacy self-registration. For reasons related to various Windows Installer features (such as advertisement, rollback, and per-user installations), it is recommended that you use the COM-related MSI tables (Class, ProgId, and AppId) instead of registering the COM server directly. Even so, there is some COM information that does not fit into the MSI COM-table schema (such as threading model information) that must be placed in the Registry table. ICE33 warnings appear for this type of information. (These warnings often occur in projects that use Microsoft merge modules.) The same applies to file-extension information: On a target system, file-association information is ultimately written to the keys HKCR\. ext and HKCR\Ext.Prog.Id, but for MSI advertisement should be placed in the Extension, Verb, and ProgId tables.

ICE33 warnings can often be safely ignored, especially if you intend not to use Windows Installer advertisement functionality.

Common ICE Errors

The following sections describe some of the most common ICE warnings and errors. ICE09 and SystemFolder Components In legacy installation programs, application libraries (DLLs and other files) were commonly installed to the System folder during installation. Two problems with this behavior are: One of these libraries would sometimes be installed over a newer version of the library, and sometimes the library would inadvertently be removed during uninstallation while other applications still required the library. The Windows Installer file-overwrite rules (along with System File Protection) help prevent the first problem from occurring. To avoid the problem of system libraries being removed when other applications need them, a requirement is that any component having a destination of [SystemFolder] be marked as Permanent. That is, any files installed to the System folder will permanently remain there. If a file needs to be removed during uninstallation, it should be installed to a vendor-specific folder in the Common Files folder. ICE09 verifies that a component with [SystemFolder] as its destination is marked permanent. To fix ICE09 errors, select the referenced component in the Components view or Setup Design view and set its Permanent property to Yes. ICE57 and Per-User Data Some Windows Installer Directory properties can resolve to different locations based on the type of installation being performed. For example, the ProgramMenuFolder and DesktopFolder properties resolve to a location available to all users of a system for a permachine installation, and to a location available only to the current user for a per-user installation. Similarly, registry data you place under the root key HKEY_USER_SELECTABLE is installed to either HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER based on the type of installation being performed. Whether a per-machine or per-user installation is taking place depends on the value of the ALLUSERS property, which is typically set by the Customer Information dialog box. A single Windows Installer component should not contain both per-machine and per-user data, because doing so can result in an incomplete installation for other user accounts on the target system. Instead, a single component should contain only per-machine data or only per-user data. ICE57 reports an error if a component contains both types of data. NOTE: ICE57 is related to ICE38, which validates that every component installed to the users profile has a key path in HKEY_CURRENT_USER; and is also related to ICE91, which reports a warning for resources are being installed to a per-user-only location (such as AppDataFolder), which can cause errors for a per-machine installation.

Flexera Software: InstallShield White Paper Series

Validat ing MSI Updates and Patches

ICE44 and Deleted Dialog Boxes The flow of dialog boxes in a Windows Installer project is handled by the NewDialog control events on the Next and Back buttons of each dialog box. To reorder dialog boxes, you should adjust the arguments of the NewDialog control events for the Back and Next buttons for the affected dialogs. If you simply delete a dialog box from the Dialogs view, the validation process will return an ICE44 error, which indicates that the target of a NewDialog control event does not exist in the project. Fixing ICE44 errors avoids Windows Installer run-time error 2803. For other ICE warnings and errors, you should consult the Windows Installer Help Library and the InstallShield Knowledge Base, as ICE failures tend to be very specific. TIP: You can search your project for a particular string in the Direct Editor view. Pressing Ctrl+F opens a standard Find panel, with which you can search the currently selected table or all tables for a given string. An advanced technique is to create custom ICE validation rules.

Tools menu, select Options, select the Preferences tab, and clear the check box labeled Uninstall before installing. For a complete list of errors and their descriptions, see the InstallShield Help Library topic Validators.

Summary

This white paper discusses types of validation you can perform before you run the installation on a target system. Addressing these types of design-time validation errors will help you avoid errors. This white paper also shows you how InstallShield helps you with design-time validation.

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

Upgrade and Patch Validation

Another type of validation performed by the InstallShield build process is validation that tests for common errors in authoring an update installation. The errors and warnings displayed differ for major upgrades, minor upgrades, and patches. TIP: A first step for addressing many problems related to updates and patches is to use the Patch Optimization setting in the Release Wizard. In the Advanced Settings panel of the Release Wizard, in the Previous package field, enter the path to the MSI database for the previous release of your project. Using this setting ensures that certain types of dynamic data in the File, Component, and Media tables is compatible between builds. Some of the common upgrade and patch validation failures are: Val004: Displays an error if a change to an existing components files will prevent the component from being updated in a minor upgrade. Val006: Displays an error if a minor upgrade is being performed when a major upgrade should be; for example, because a component has been deleted or moved in the product tree. Val008: Displays an error if a record in the Upgrade table for a major upgrade contains invalid data. By default, upgrade and patch validation is performed each time you build your project. You can also manually perform this type of validation by pulling down the Build menu, selecting Validate, and then selecting Upgrade Validation Wizard. When you test an update project from the InstallShield environment, by default clicking the Run toolbar button causes any version of the product already on the system to be uninstalled. To properly test update installations from the InstallShield environment, pull down the

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. IA_WP_Time-Validation_Oct11