WH

ITE

PA

PE

R

Fixing Design-Time Validation Errorsby Robert DickauPrincipal Technical Training Writer, Flexera Software

Fixing Design-Time Validat ion Errors

Introduct ionTo help you detect and resolve potent ial problems in your installat ion project, you can perform several types of validat ion before you run the installat ion on a target system. The types of validat ion discussed in this white paper include:

• Build warnings and errors• Internal Consistency Evaluator (ICE) validat ion• Update and patch validat ion

Addressing these types of design-t ime validat ion errors will help you avoid errors. This white paper also shows you how InstallShield® helps you with design-t ime validat ion.

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 Informat ion 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 informat ion 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 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

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

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

Validat ing MSI Updates and Patches

3Flexera Software: InstallShield White Paper Series

Build Warnings and ErrorsAs 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 informat ion about resolving these warnings. (This requires a live Internet connect ion.)

Addressing Build Errors and WarningsBuild errors and warnings typically refer to missing or unexpected source files or merge modules, but can refer to any condit ion that prevents a build from complet ing. For example, the build process reports error –1014 (“Cannot rename directory…”) if an installat ion inside the build folder is running, or if Windows Explorer or a command prompt is point ing to the build folder.

In addit ion, the InstallShield environment will prevent you from entering some project sett ings that would cause the package to fail at deployment t ime. For example, a project cannot use DATABASE or PATCH as an internal Directory-table ident ifier—the way INSTALLDIR or SystemFolder is a Directory ident ifier—as these are reserved ident ifiers used by Windows Installer. If you try to define a component dest inat ion folder with internal ident ifier DATABASE, the environment will rename the ident ifier 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 part icular build warning or error number, omit the minus sign in the search. For example, instead of searching for “–1014”, search for “1014”.

Errors Regarding Missing Source FilesIf 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

the locat ions 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 exist ing path variable to represent that file’s locat ion. 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 registry-based and environment variable–based path variables, with which you can modify path variable values without having to modify the project file.)

In addit ion, if you have source directories that contain lists of files that are cont inually changing, you can use dynamic file linking. With dynamic linking, you specify a directory and opt ional 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 considerat ion regarding file linking is that a dynamically linked file cannot be the key file of its component. However, a component can contain any combinat ion of stat ic and dynamic links, and therefore a solut ion is to set a stat ically linked file as the key file, addit ionally 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 sett ings to ensure File, Component, and Media table keys are synchronized between builds. For more informat ion, see the InstallShield help topic “Upgrade Considerat ions”.

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 act ion 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 somet imes 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”).

Design Issues and Build WarningsIn addit ion to issues related to source files, some build warnings address design issues in your project.

A deferred custom act ion must be placed between InstallInit ialize and InstallFinalize in the Execute sequence of an installat ion. To help detect problems with improper placement of deferred act ions, the build process generates warning –6524 if it detects a deferred custom act ion outside the range of InstallInit ialize and InstallFinalize.

TIP: By default, the build process will cont inue to complet ion 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 Opt ions; in the General tab, select the check box labeled “Stop build process when first error is encountered”.

Validat ing MSI Updates and Patches

Flexera Software: InstallShield White Paper Series4

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.

ICE Validat ionInternal Consistency Evaluator (ICE) validat ion tests your MSI database records for different types of data that can lead to undesirable or unpredictable run-t ime behavior. There are over 100 predefined ICE rules, test ing for such condit ions as duplicated component codes, missing propert ies and dialog boxes, and invalid scheduling for various types of built-in and custom act ions. (The graphical editors and referent ial integrity features of the InstallShield environment ensure that many types of ICE failures do not occur.) Because ICE validat ion is performed on an MSI database and not an ISM project file, your project must build successfully before you can perform this type of validat ion.

You perform ICE validat ion in the InstallShield environment by pulling down the Build menu, select ing Validate, and then select ing Full MSI Validat ion 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 validat ion, you might see addit ional informat ional messages regarding the ICE validat ion 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 validat ion results. Validat ion log files are saved in a subdirectory called Validat ionFiles, relat ive to the release folder.

In addit ion, the Direct Editor view highlights tables, records, and fields related to the validat ion error or warning.

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.

To perform ICE validat ion using the command-line build tool IsCmdBld, you can pass it the -m switch, followed by the path to the validat ion file (.cub file) to use. The Microsoft .cub files are stored in the Support subdirectory of the InstallShield distribut ion:

IsCmdBld -p ProjectName.ism -a FullBuild -r cdrom-m “C:\Program Files\InstallShield\Support\darice.cub”

NOTE: There are separate merge module validat ion rules for merge module (.msm) projects. In the InstallShield environment, you can select Build > Validate > Merge Module Validat ion Suite. From the command line, you can validate the database using the validat ion file mergemod.cub.

You can specify that InstallShield should perform ICE validat ion whenever you perform a build by pulling down the Tools menu, select ing Opt ions, and then select ing the Validat ion tab. In the Validat ion tab, select the check box labeled “Perform validat ion using”, and then select the desired validat ion suite.

Using the Customize button, you can addit ionally select rules within a validat ion 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.

Validat ing MSI Updates and Patches

5Flexera Software: InstallShield White Paper Series

ICE Warnings You Can IgnoreThe following paragraphs describe some ICE warnings that can be safely ignored.

ICE36 and ARPPRODUCTICONAn advert ised Windows Installer installat ion is one that installs applicat ion “entry points”, such as shortcuts, COM informat ion, and file-extension informat ion on a user’s system, but does not install any applicat ion files or registry informat ion unt il the user invokes one of these entry points. Because the targets of these entry points will not init ially 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 advert iseable 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 validat ion suites overlook the possibility that resources in the Icon table can refer to the ARPPRODUCTICON property, which specifies the icon to appear in the applicat ion’s Add or Remove Programs entry. Therefore, ICE36 errors that refer to ARPPRODUCTICON can safely be ignored.

ICE17 and InstallShield SQL Dialog BoxesICE17 tests various characterist ics 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 respect ive tables.

With InstallShield projects, validat ion will report an ICE17 warning for the SQL dialog boxes SQLBrowse and SQLLogin, which create their data dynamically at run t ime. These warnings can safely be ignored.

ICE33 and the Registry TableThe self-registrat ion process for COM servers—commonly called self-registering DLLs and OCXs—places the registrat ion informat ion in the target system’s registry. COM informat ion 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 funct ion in a COM library is often called “legacy self-registrat ion”.

For reasons related to various Windows Installer features (such as advert isement, rollback, and per-user installat ions), it is recommended that you use the COM-related MSI tables (Class, ProgId, and AppId) instead of registering the COM server direct ly. Even so, there is some COM informat ion that does not fit into the MSI COM-table schema (such as threading model informat ion) that must be placed in the Registry table. ICE33 warnings appear for this type of informat ion. (These warnings often occur in projects that use Microsoft merge modules.)

The same applies to file-extension informat ion: On a target system, file-associat ion informat ion is ult imately written to the keys HKCR\.ext and HKCR\Ext.Prog.Id, but for MSI advert isement 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 advert isement funct ionality.

Common ICE ErrorsThe following sect ions describe some of the most common ICE warnings and errors.

ICE09 and SystemFolder ComponentsIn legacy installat ion programs, applicat ion libraries (DLLs and other files) were commonly installed to the System folder during installat ion. Two problems with this behavior are: One of these libraries would somet imes be installed over a newer version of the library, and somet imes the library would inadvertent ly be removed during uninstallat ion while other applicat ions st ill required the library.

The Windows Installer file-overwrite rules (along with System File Protect ion) help prevent the first problem from occurring. To avoid the problem of system libraries being removed when other applicat ions need them, a requirement is that any component having a dest inat ion of [SystemFolder] be marked as Permanent. That is, any files installed to the System folder will permanent ly remain there. If a file needs to be removed during uninstallat ion, it should be installed to a vendor-specific folder in the Common Files folder.

ICE09 verifies that a component with [SystemFolder] as its dest inat ion 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 DataSome Windows Installer Directory propert ies can resolve to different locat ions based on the type of installat ion being performed. For example, the ProgramMenuFolder and DesktopFolder propert ies resolve to a locat ion available to all users of a system for a per-machine installat ion, and to a locat ion available only to the current user for a per-user installat ion. 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 installat ion being performed. Whether a per-machine or per-user installat ion is taking place depends on the value of the ALLUSERS property, which is typically set by the Customer Informat ion 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 installat ion 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 user’s 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 locat ion (such as AppDataFolder), which can cause errors for a per-machine installat ion.

Validat ing MSI Updates and Patches

Flexera Software: InstallShield White Paper Series6

ICE44 and Deleted Dialog BoxesThe 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 validat ion 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-t ime 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 part icular string in the Direct Editor view. Pressing Ctrl+F opens a standard Find panel, with which you can search the current ly selected table or all tables for a given string.

An advanced technique is to create custom ICE validat ion rules.

Upgrade and Patch Validat ionAnother type of validat ion performed by the InstallShield build process is validat ion that tests for common errors in authoring an update installat ion. 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 Opt imizat ion sett ing in the Release Wizard. In the Advanced Sett ings 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 sett ing ensures that certain types of dynamic data in the File, Component, and Media tables is compat ible between builds.

Some of the common upgrade and patch validat ion failures are:

• Val004: Displays an error if a change to an exist ing component’s 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 validat ion is performed each t ime you build your project. You can also manually perform this type of validat ion by pulling down the Build menu, select ing Validate, and then select ing Upgrade Validat ion 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 installat ions from the InstallShield environment, pull down the

Tools menu, select Opt ions, select the Preferences tab, and clear the check box labeled “Uninstall before installing”.

For a complete list of errors and their descript ions, see the InstallShield Help Library topic “Validators”.

SummaryThis white paper discusses types of validat ion you can perform before you run the installat ion on a target system. Addressing these types of design-t ime validat ion errors will help you avoid errors. This white paper also shows you how InstallShield helps you with design-t ime validat ion.

Begin a Free Evaluat ion 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. IA_WP_Time-Validat ion_Oct11