Fixing Design-Time Validation Errors


Published on

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.

Published in: Technology
1 Comment
  • Be the first to like this

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

No notes for slide

Fixing Design-Time Validation Errors

  1. 1. W H I T E PA P E R Fixing Design-Time Validation Errors by Robert Dickau Principal Technical Training Writer, Flexera Software
  2. 2. Fixing Design-Time Validation ErrorsIntroduction It is also assumed you are familiar with some of the wizardsTo help you detect and resolve potential problems in your installation available with InstallShield, such as the Release Wizard andproject, you can perform several types of validation before you run Component Wizard.the installation on a target system. The types of validation discussedin this white paper include: • The Release Wizard, available under the Build menu and also from the Releases view, lets you describe the properties— • Build warnings and errors media type, compression settings, and so forth—of a release, • Internal Consistency Evaluator (ICE) validation and then builds the specified release image. • Update and patch validation • The Component Wizard, available by right-clicking a feature in the Setup Design view, lets you create special types ofAddressing these types of design-time validation errors will help components, such as components for COM servers, fonts,you avoid errors. This white paper also shows you how and Windows services.InstallShield® helps you with design-time validation. The InstallShield Help Library contains information about usingUsing the InstallShield Environment every view and wizard in the InstallShield environment. TheThis white paper frequently refers to the InstallShield development InstallShield Help Library is available when you press F1 withenvironment. It is assumed you are familiar with the general layout any view selected; you can also select Contents from the Helpof the InstallShield interface, which contains a list of views with menu to view the help library.which you can modify different portions of your installation project. 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 generalproduct and project properties; the Setup Design view enables you Learn More about InstallShieldto edit the features, components, and component data used by your If you wish to learn more about the capabilities ofproject; the Registry view enables you to modify the registry data InstallShield, please visit the Flexera Software Web siteinstalled by your installation program; and the Direct Editor view at you access to the raw MSI database tables.2 Flexera Software: InstallShield White Paper Series
  3. 3. Validat ing MSI Updates and PatchesBuild Warnings and Errors the locations of source files on the development system. WheneverAs InstallShield builds your project, status messages are displayed in you add a file to a component, InstallShield by default creates athe output window at the bottom of the development environment. path variable or reuses an existing path variable to represent that file’s 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 registry- based and environment variable–based path variables, with which you can modify path variable values without having toFor a command-line build using IsCmdBld.exe, status messages are modify the project file.)displayed at the command prompt. In addition, if you have source directories that contain lists of filesIf any errors or warnings occur, they are displayed in the Build tab that are continually changing, you can use dynamic file linking.of the output window, as well as in the Tasks tab. The Tasks tab With dynamic linking, you specify a directory and optional filecontains links to the InstallShield Knowledge Base for the latest name masks for inclusion and exclusion. Each build processinformation about resolving these warnings. (This requires a live then copies all of the matching files in the dynamic link into theInternet connection.) 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.Addressing Build Errors and WarningsBuild errors and warnings typically refer to missing or unexpected Moreover, when using dynamic file linking, it is important tosource files or merge modules, but can refer to any condition that specify a “previous package” in the build settings to ensure File,prevents a build from completing. For example, the build process Component, and Media table keys are synchronized betweenreports error –1014 (“Cannot rename directory…”) if an installation builds. For more information, see the InstallShield help topicinside the build folder is running, or if Windows Explorer or a “Upgrade Considerations”.command prompt is pointing to the build folder. Another error related to missing data on the build system is –1024In addition, the InstallShield environment will prevent you from (“File not found. Cannot stream the file into the Binary file.”), whichentering some project settings that would cause the package to fail occurs if a file used by a custom action or dialog box (such asat deployment time. For example, a project cannot use DATABASE a DLL or bitmap file) has been moved or deleted. Similarly, buildor PATCH as an internal Directory-table identifier—the way error –7017 occurs if your project includes merge modules or otherINSTALLDIR or SystemFolder is a Directory identifier—as these are redistributables that are not present on your build system. Otherreserved identifiers used by Windows Installer. If you try to define errors sometimes related to missing source files are –6271 (“Filea component destination folder with internal identifier DATABASE, file not found. An error occurred building the MsiFileHash tablethe environment will rename the identifier to a valid value such as record…”) and –1501 (“Could not compress file into”).DATABASE_DIR1. (If, however, you use the Direct Editor to define aDirectory called DATABASE or PATCH, the build process will report Design Issues and Build Warningserror –6262.) In addition to issues related to source files, some build warnings address design issues in your project.TIP: When you manually search the InstallShield Knowledge Basefor a particular build warning or error number, omit the minus sign A deferred custom action must be placed between InstallInitializein the search. For example, instead of searching for “–1014”, and InstallFinalize in the Execute sequence of an installation. Tosearch for “1014”. help detect problems with improper placement of deferred actions, the build process generates warning –6524 if it detects a deferredErrors Regarding Missing Source Files custom action outside the range of InstallInitialize and InstallFinalize.If the build process cannot find a source file, because it hasbeen renamed or deleted, the build process returns error –6103 TIP: By default, the build process will continue to completion even(“Could not find file file”) and –1007 (“Cannot copy source file if any build errors occur. To cancel a build, you can click the Stopto target directory”). 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 andTwo features of InstallShield that can help you work with source select Options; in the General tab, select the check box labeledfiles are path variables and dynamic file linking. Path variables “Stop build process when first error is encountered”.are variables used by the InstallShield build process to representFlexera Software: InstallShield White Paper Series 3
  4. 4. Validat ing MSI Updates and PatchesIf you use the command-line build tool IsCmdBld, the -x switch To perform ICE validation using the command-line build toolenables you to stop the build when the first error occurs, and the IsCmdBld, you can pass it the -m switch, followed by the path-w switch lets you specify that build warnings should be treated to the validation file (.cub file) to use. The Microsoft .cub files areas errors. stored in the Support subdirectory of the InstallShield distribution:ICE Validation IsCmdBld -p ProjectName.ism -a FullBuild -r cdromInternal Consistency Evaluator (ICE) validation tests your MSI -m “C:Program FilesInstallShieldSupportdarice.cub”database records for different types of data that can lead toundesirable or unpredictable run-time behavior. There are over NOTE: There are separate merge module validation rules for merge100 predefined ICE rules, testing for such conditions as duplicated module (.msm) projects. In the InstallShield environment, you cancomponent codes, missing properties and dialog boxes, and invalid select Build > Validate > Merge Module Validation Suite. From thescheduling for various types of built-in and custom actions. (The command line, you can validate the database using the validationgraphical editors and referential integrity features of the InstallShield file mergemod.cub.environment ensure that many types of ICE failures do not occur.)Because ICE validation is performed on an MSI database and not You can specify that InstallShield should perform ICE validationan ISM project file, your project must build successfully before you whenever you perform a build by pulling down the Tools menu,can perform this type of validation. selecting Options, and then selecting the Validation tab. In the Validation tab, select the check box labeled “Perform validationYou perform ICE validation in the InstallShield environment by using”, and then select the desired validation suite.pulling down the Build menu, selecting Validate, and then selectingFull MSI Validation Suite.As with build errors and warnings, ICE errors and warnings appearin the Tasks tab of the output window.(The output window in InstallShield displays only ICE warnings anderrors. If you use another tool such as Orca to perform validation, Using the Customize button, you can additionally select rules withinyou might see additional informational messages regarding the ICE a validation suite to skip.validation process.) The Windows Installer Help Library contains a summary of ICEThe Validate tab also lists any ICE warnings or errors that occur, messages in the topic “ICE Reference”; and also provides a specificand provides a hyperlink to a text log file that contains the page for each ICE error, describing typical scenarios in which thevalidation results. Validation log files are saved in a subdirectory error occurs and how to address the error.called ValidationFiles, relative to the release folder.In addition, the Direct Editor view highlights tables, records, andfields related to the validation error or warning.TIP: You can right-click an error or warning in the Tasks tab of theoutput window and select “Go to Direct Editor”, which selects thecorresponding record in the Direct Editor view.4 Flexera Software: InstallShield White Paper Series
  5. 5. Validat ing MSI Updates and PatchesICE Warnings You Can Ignore ICE33 warnings can often be safely ignored, especially if youThe following paragraphs describe some ICE warnings that can be intend not to use Windows Installer advertisement functionality.safely ignored. Common ICE ErrorsICE36 and ARPPRODUCTICON The following sections describe some of the most common ICEAn advertised Windows Installer installation is one that installs warnings and errors.application “entry points”, such as shortcuts, COM information, andfile-extension information on a user’s system, but does not install any ICE09 and SystemFolder Componentsapplication files or registry information until the user invokes one of In legacy installation programs, application libraries (DLLs andthese entry points. Because the targets of these entry points will not other files) were commonly installed to the System folder duringinitially be installed, Windows Installer requires any icon resources installation. Two problems with this behavior are: One of theseused by these entry points to be extracted and stored separately libraries would sometimes be installed over a newer version ofinside the MSI database. To this end, the Icon table is used to the library, and sometimes the library would inadvertently bestore icons used by advertiseable shortcuts, COM classes, and removed during uninstallation while other applications stillfile extensions. required the library.ICE36 warns if any icons in the Icon table appear to be unused, The Windows Installer file-overwrite rules (along with Systemwhich means the MSI database is larger than necessary. However, File Protection) help prevent the first problem from occurring. Tosome ICE validation suites overlook the possibility that resources avoid the problem of system libraries being removed when otherin the Icon table can refer to the ARPPRODUCTICON property, applications need them, a requirement is that any componentwhich specifies the icon to appear in the application’s Add or having a destination of [SystemFolder] be marked as Permanent.Remove Programs entry. Therefore, ICE36 errors that refer to That is, any files installed to the System folder will permanentlyARPPRODUCTICON can safely be ignored. remain there. If a file needs to be removed during uninstallation, it should be installed to a vendor-specific folder in the CommonICE17 and InstallShield SQL Dialog Boxes Files folder.ICE17 tests various characteristics of user-interface controls,including checking that PushButton controls have associated control ICE09 verifies that a component with [SystemFolder] as itsevents; icons used for controls are available in the Binary table; destination is marked permanent. To fix ICE09 errors, select theand that ComboBox, ListBox, and RadioButton controls have referenced component in the Components view or Setup Designcorresponding data in the respective tables. view and set its Permanent property to Yes.With InstallShield projects, validation will report an ICE17 ICE57 and Per-User Datawarning for the SQL dialog boxes SQLBrowse and SQLLogin, Some Windows Installer Directory properties can resolve to differentwhich create their data dynamically at run time. These warnings locations based on the type of installation being performed. Forcan safely be ignored. example, the ProgramMenuFolder and DesktopFolder properties resolve to a location available to all users of a system for a per-ICE33 and the Registry Table machine installation, and to a location available only to the currentThe self-registration process for COM servers—commonly called self- user for a per-user installation. Similarly, registry data you placeregistering DLLs and OCXs—places the registration information in under the root key HKEY_USER_SELECTABLE is installed to eitherthe target system’s registry. COM information is typically written to HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER based onthe keys HKCRCLSID{CLSID} and HKCRCom.Prog.Id when the the type of installation being performed. Whether a per-machineDllRegisterServer entry point of the COM library is invoked. Calling or per-user installation is taking place depends on the value ofthe DllRegisterServer function in a COM library is often called the ALLUSERS property, which is typically set by the Customer“legacy self-registration”. Information dialog box.For reasons related to various Windows Installer features (such A single Windows Installer component should not contain bothas advertisement, rollback, and per-user installations), it is per-machine and per-user data, because doing so can result in anrecommended that you use the COM-related MSI tables (Class, incomplete installation for other user accounts on the target system.ProgId, and AppId) instead of registering the COM server directly. Instead, a single component should contain only per-machineEven so, there is some COM information that does not fit into the data or only per-user data. ICE57 reports an error if a componentMSI COM-table schema (such as threading model information) that contains both types of data.must be placed in the Registry table. ICE33 warnings appear forthis type of information. (These warnings often occur in projects that NOTE: ICE57 is related to ICE38, which validates that everyuse Microsoft merge modules.) component installed to the user’s profile has a key path in HKEY_CURRENT_USER; and is also related to ICE91, whichThe same applies to file-extension information: On a target system, reports a warning for resources are being installed to a per-user-onlyfile-association information is ultimately written to the keys HKCR. location (such as AppDataFolder), which can cause errors for aext and HKCRExt.Prog.Id, but for MSI advertisement should be per-machine installation.placed in the Extension, Verb, and ProgId tables.Flexera Software: InstallShield White Paper Series 5
  6. 6. Validat ing MSI Updates and Patches ICE44 and Deleted Dialog Boxes Tools menu, select Options, select the Preferences tab, and clear The flow of dialog boxes in a Windows Installer project is handled the check box labeled “Uninstall before installing”. by the NewDialog control events on the Next and Back buttons of each dialog box. To reorder dialog boxes, you should adjust the For a complete list of errors and their descriptions, see the arguments of the NewDialog control events for the Back and Next InstallShield Help Library topic “Validators”. buttons for the affected dialogs. If you simply delete a dialog box from the Dialogs view, the validation process will return an ICE44 Summary error, which indicates that the target of a NewDialog control event This white paper discusses types of validation you can perform does not exist in the project. Fixing ICE44 errors avoids Windows before you run the installation on a target system. Addressing Installer run-time error 2803. these types of design-time validation errors will help you avoid errors. This white paper also shows you how InstallShield helps For other ICE warnings and errors, you should consult the Windows you with design-time validation. Installer Help Library and the InstallShield Knowledge Base, as ICE failures tend to be very specific. Begin a Free Evaluation of InstallShield TIP: You can search your project for a particular string in the Direct You can download a free trial version of InstallShield from Editor view. Pressing Ctrl+F opens a standard Find panel, with which the Flexera Software Web site at: you can search the currently selected table or all tables for a given string. An advanced technique is to create custom ICE validation rules. Want to learn more best practices for building quality Upgrade and Patch Validation installations? Another type of validation performed by the InstallShield build Join an InstallShield training class – visit process is validation that tests for common errors in authoring an for available classes. update installation. The errors and warnings displayed differ for major upgrades, minor upgrades, and patches. Also, if you have a critical installation project but are short on developer bandwidth or expertise, Flexera Software’s TIP: A first step for addressing many problems related to updates Professional Services team can help. Learn more at: and patches is to use the Patch Optimization setting in the Release Wizard. In the Advanced Settings panel of the Release Wizard, in installations.htm. 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 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 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 the6 Flexera Software: InstallShield White Paper Series
  7. 7. 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. IA_WP_Time-Validation_Oct11