Académique Documents
Professionnel Documents
Culture Documents
User Guide
Version 2008
InstallShield 2008 User Guide
Part Number: ISP-1400-UG00
Product Release Date: 23-May-2007
Copyright Notice
Copyright © 1996–2007 Macrovision Corporation and/or Macrovision Europe Ltd. All Rights Reserved.
This product contains proprietary and confidential technology provided by and owned by Macrovision Europe Ltd., UK, and Macrovision Corporation of
Santa Clara, California, U.S.A. Any use, copying, publication, distribution, display, modification, or transmission of such technology in whole or in part in
any form or by any means without the prior express written permission of Macrovision Europe Ltd. and Macrovision Corporation is strictly prohibited.
Except where expressly provided by Macrovision Europe Ltd. and Macrovision Corporation in writing, possession of this technology shall not be construed
to confer any license or rights under any of Macrovision Europe Ltd. and Macrovision Corporation’s intellectual property rights, whether by estoppel,
implication, or otherwise.
ALL COPIES OF THE TECHNOLOGY and RELATED INFORMATION, IF ALLOWED BY MACROVISION CORPORATION, MUST DISPLAY THIS NOTICE OF
COPYRIGHT AND OWNERSHIP IN FULL.
Trademarks
Macrovision, AdminStudio, eMeta, eRights, eRights Suite, eRightsWEB, FLEXnet, FLEXnet Manager, FLEXnet Publisher, InstallAnywhere,
InstallAnywhere.NET, InstallShield, InstallShield Developer, InstallShield DevStudio, InstallShield Professional, OneClickInstall, QuickPatch, and
RightCommerce are registered trademarks or trademarks of Macrovision Corporation, or other Macrovision companies, in the United States of America
and/or other countries. All other brand and product names mentioned herein are the trademarks and registered trademarks of their respective owners.
1 InstallShield 2008 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
What’s New in InstallShield 2008. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
What Was New in Earlier Versions of InstallShield . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
What’s New in InstallShield 12 SP1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
What’s New in InstallShield 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Target System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Targeting 64-Bit Operating Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Using Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Help Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Using Context-Sensitive Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2 Welcome to Macrovision. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Macrovision Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Macrovision Professional Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Technical Support Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Contacting Macrovision Corporation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Installation Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Application Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Starting InstallShield for the First Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Welcome Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Displaying the Welcome Assistant After the Initial Launch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Starting InstallShield. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
InstallShield Start Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Working with Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Installation Projects Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Project Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
ISICE20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
InstallShield Best Practice Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847
ISBP01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
ISBP02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
ISBP03 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
ISBP04 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
ISBP05 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
ISBP06 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
ISBP07 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
ISBP08 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
ISBP09 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
ISBP10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
ISBP11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
ISBP12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
ISBP13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
ISBP14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
ISBP15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
ISBP16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
ISBP17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
ISBP18 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
ISBP19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
Understanding When an InstallScript Installation Reboots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
Debugging Windows Installer–Based Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
Starting the MSI Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
Setting Breakpoints in the MSI Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
Removing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
Viewing and Setting Properties in the MSI Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
Step Into Actions in the MSI Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
Step Through Actions in the MSI Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
Stopping the MSI Debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
Spanning Installations over Multiple Disks or CDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
Compressing Multi-Disk Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
Disk Spanning Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
Custom Disk Spanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
Creating Setup Launchers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
Distributing Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
Distributing Releases to a Folder or FTP Site Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
Preparing Installations for Internet Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
Distributing Releases on Floppy Disks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
Redistributable Files that Are Distributed with an InstallScript Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
36 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003
InstallShield is the most comprehensive installation-authoring solution for every platform, operating
system, and device. InstallShield lets you easily create Windows Installer and InstallScript installations
and extend them to database servers, Web services, and mobile devices.
The InstallShield Help Library contains information about the functionality and features of
InstallShield. The Help Library contains the following sections:
Section Description
What’s New in InstallShield 2008 Informs you about the new features and enhancements in InstallShield 2008.
What Was New in Earlier Versions Informs you about changes that were made in earlier versions of InstallShield.
of InstallShield
Welcome to Macrovision Introduces you to Macrovision Corporation, its history, its products, its professional
services, and the InstallShield Help Library.
Getting Started Contains information to help you become familiar with InstallShield, begin creating
an installation project, and customize the InstallShield user interface.
Tutorials Leads you step-by-step through the process of creating InstallScript and Basic MSI
installation projects, creating global installations, and adding DIM references to a
project.
Creating Installations Explains how to create user-friendly, reliable installations and guides you through
every step of the process—from specifying information for Add or Remove
Programs to building, testing, and deploying an installation.
Section Description
Designing Merge Modules Introduces some basic concepts to help you get started designing your own merge
modules that can be used in any of your installation projects or distributed for use
by other installation developers.
Creating Objects Explains how to design your own objects that can be used in any of your installation
projects or distributed for use by other installation developers.
Updating Applications Leads you through steps for planning and implementing the various types of
upgrades and patches for updating a product. Also explains how you can use
FLEXnet Connect to notify end users about upgrades and patches that are
available.
Additional Installation Options Discusses a broad range of options available in InstallShield: creating multilingual
installations, installing multiple instances of a product, defining installation
prerequisites, building conditional statements, searching for installed data, editing
installation tables, and more.
Integrating InstallShield with Contains details about integrating InstallShield with third-party tools such as source
External Applications code control software and Microsoft Visual Studio.
Automating Build Processes Provides information about the InstallShield automation interface, which enables
you to automate processes for creating installation projects without having to
directly open the InstallShield user interface.
Reference Contains comprehensive reference information for the InstallShield user interface;
the InstallScript language; errors and warnings that might occur when you create,
compile, build, or run your installation; tools that you can use from the command
line to perform tasks such as building a release and running an installation; the
InstallShield custom actions that are added to projects; and objects, methods,
properties, and collections used to modify an installation project through the
automation interface.
Frequently Asked Questions Directs you to help topics that answer many commonly asked questions about
InstallShield and project creation.
Note: Because the InstallShield Help Library is designed to interact with InstallShield, it is recommended that you open the
help from within InstallShield. Copying the help files to another folder or system causes many of its features to work
incorrectly.
For answers to many commonly asked questions and new information about InstallShield that do not
appear in the documentation, visit the Knowledge Base.
• Determining Whether a Target System with IIS 7 Has the IIS 6 Metabase Compatibility Feature
Support for the UAC Shield Icon on Dialog Buttons (Basic MSI Projects)
For any new Basic MSI projects that you create, the Install button on the ReadyToInstall dialog now has
the User Account Control (UAC) shield icon when the installation is run on Windows Vista systems.
In addition, you can now add the shield icon to any button in a Basic MSI dialog through the Dialog
Editor in the Dialogs view. If you are using InstallShield on a Windows Vista system, you can see the
shield icon on a button in the Dialog Editor as it will be displayed at run time.
Note that InstallShield does not support not support using .pfx files to sign media header files (.hdr
files), which are used for the One-Click Install type of installation for InstallScript projects. For this type
of installation, consider one of the following alternatives:
• Use .spc and .pvk files instead of a .pfx file for your digital signature.
• Build a compressed installation, which would enable you to sign with a .pfx file.
The new Signing tab in the Releases view is where you specify the digital signature information—
including the digital signature files granted to you by a certification authority—that InstallShield should
use to sign your files. The Signing tab is also where you specify which files in your installation should be
digitally signed. You can also use the Release Wizard to specify all of the digital signature information.
Previously, InstallShield included support for signing only the .msi, .hdr, and Setup.exe files. In
addition, InstallShield allowed you to specify .spc and .pvk files for the digital signature, but not .pfx
files.
To learn more, see the following:
• Digital Signing and Security
• Signing Tab
• Conditions Tab
• Specifying Which ICEs, ISICEs, and ISBPs Should Be Run During Validation
Ability to Require End Users to Scroll Through the EULA in the LicenseAgreement Dialog
InstallShield includes support for disabling the Next button on the LicenseAgreement dialog until the
end user reaches the end of the End-User License Agreement (EULA) text in the scrollable EULA control
through mouse or keyboard scrolling.
The end user must also select the I accept the terms in the license agreement option before the
Next button is enabled; this behavior is the same as with earlier releases of InstallShield.
The scroll requirement is not available in the LicenseAgreement dialog by default. To use this
functionality, you must add to your project the new Windows Installer DLL custom action called
WatchScroll. This custom action calls the EulaScrollWatcher.dll file. In addition, you must modify the
Next button’s Control conditions and add an event to the Memo control.
This is available for Basic MSI projects.
For detailed instructions, see Requiring End Users to Scroll Through the EULA in the LicenseAgreement
Dialog.
Enhancements
XML File Change Enhancements
Support for XML file changes has been expanded in InstallShield:
• Now you can test just the XML file changes that are configured for your project through the XML
File Changes view without having to build and run your entire installation.
• The XML File Changes view now supports namespaces in XML files.
Automatic Downgrade Prevention Entries in Basic MSI and InstallScript MSI Projects
To prevent end users from being able to install the current version of your product over a future major
version of the same product, the following conditions should be met: The Upgrades view should contain
a major upgrade item, the major upgrade item should be properly configured to prevent the current
version of your product from being installed over a future version, and your project should include a
properly configured and scheduled type 19 custom action.
When you create a new Basic MSI or InstallScript MSI project, InstallShield automatically adds support
for preventing the current installation from overwriting a future major version. To learn more, see the
following:
• Preventing the Current Installation from Overwriting a Future Major Version of the Same Product
• ISICE19
• ALLUSERS
• Setup.exe Tab
• Signing Tab
• .NET/J# Tab
• Internet Tab
• Postbuild Tab
• Creating Custom Actions in the Custom Actions and Sequences View (or the Custom Actions View)
• Reordering a Sequence
• Shortcuts View
Ability to Change the Product Version from the Command Line or Through an MSBuild Task
Parameter
The -y command-line parameter is available for command-line builds with IsCmdBld.exe and
IsSaBld.exe.
Use this parameter to specify a product version from the command-line build.
In addition, the InstallShield task for MSBuild now includes a ProductVersion parameter, which you can
use to specify the product version through MSBuild. This parameter is exposed as the property
InstallShieldProductVersion when the default targets file is used.
Using the -y command-line parameter or the InstallShield task ProductVersion parameter is especially
helpful if you want to increment the build version (the third field) of the product version.
To learn more, see:
• ISCmdBld.exe
Ability to Override Windows Installer Property Values from the Command Line
The -z command-line parameter is available for command-line builds with IsCmdBld.exe and
IsSaBld.exe. Use this parameter to override the value of a Windows Installer property or create the
property if it does not exist.
To learn more, see:
• ISCmdBld.exe
Usability Enhancements for the Files and Folders view, the Registry View, and the Redistributables
View
Several enhancements are available for the Files and Folders view:
• You can right-click a file in the Destination computer’s files pane and then click the new Open
Containing Folder command. Doing so opens a Windows Explorer window and displays the folder
that contains the file that you right-clicked.
• A new Add command is available when you right-click the Destination computer’s files pane.
Use this command to display an Open dialog box that lets you browse to the file that you want to add
to your project.
• The upper-right corner of this view has a new link (either Show Source Panes or Hide Source Panes).
Use this new link to show or hide the two top panes—the Source computer’s folders pane and
the Source computer’s files pane—in this view. You can hide the two panes, open a Windows
Explorer window, and drag and drop files from the Windows Explorer window to the two remaining
panes in InstallShield.
The Registry view also has a new link (either Show Source Panes or Hide Source Panes) in the upper-
right corner. Use this new link to show or hide the two top panes—the Source computer’s folders
pane and the Source computer’s files pane—in this view.
Two enhancements have also been made to the Redistributables view for Basic MSI and InstallScript
MSI projects:
• The right pane in this view shows details about the merge module, object, or setup prerequisite that
is selected in the upper-left pane. You can now hide or show the details pane by clicking the Show
Details or Hide Details link in the upper-right corner of this view.
• The Details pane that is displayed for setup prerequisites now shows complete information about
the selected setup prerequisite. This includes conditions, command-line parameters, and other
information that is configured for the prerequisite.
New Setting for Specifying Whether an IIS Web Server Should Allow the CMD Command to Be Used
for SSI #exec Directives
You can configure an IIS Web server to prevent the CMD command for the #exec directive from being
used to execute shell commands, or you can configure it to allow the CMD command to be used to
execute this type of command. The SSIEnableCmdDirective registry value for the
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters registry key is
what determines whether the CMD command is permitted.
The Internet Information Services view in InstallShield includes a new SSIEnableCmdDirective registry
value setting. This setting lets you specify how your installation should configure the
SSIEnableCmdDirective registry value on target systems. This setting also lets you specify that the
SSIEnableCmdDirective registry value should not be changed at installation run time; this is the default
behavior.
For more information, see Specifying Whether a Web Server Should Allow the CMD Command to Be
Used for SSI #exec Directives.
Ability to Specify Whether New SQL Connections Should Share the Same Windows Installer
Properties
A new SQL Scripts tab on the Options dialog box lets you specify how InstallShield should create new
database connections by default—either by using the same Windows Installer properties that were used
by default for the first connection in your project, or by using a unique set of new Windows Installer
properties.
This applies to the following project types: Basic MSI and InstallScript MSI.
For more information, see the following:
• Specifying Whether New SQL Connections Should Share the Same Windows Installer Properties
New Windows Installer Property for Specifying SQL Connections That Should Not Be Installed or
Uninstalled
InstallShield includes support for a new Windows Installer property called
IS_SQLSERVER_CXNS_ABSENT_FROM_INSTALL. Use this property to specify one or more
SQL connections that should be skipped during installation or uninstallation. To specify more than one
SQL connection, separate each with a semicolon (;). To skip all of the SQL connections, set the value of
this property to ALL. Using this property is helpful if you cannot uninstall a product because of a SQL
scripting error.
For details about SQL-related properties, see Overriding the Default SQL Run-Time Behavior.
Ability to Specify COM+ Component File Destinations from Within the Component Services View
The Component Services view has two new Destination fields on the Installation tab: one for a server
type of installation, and one for a proxy type of installation. Use these fields to specify the target
destination of the selected COM+ component files. Previously, the only way to specify the destination of
the components associated with a COM+ application was in the Components view or the Setup Design
view.
New Windows Installer Property for Specifying COM+ Applications to Be Installed After the
InstallFinalize Action
InstallShield includes support for a new Windows Installer property called
IS_COMPLUS_INSTALL_AT_FINALIZE. Use this property to specify one or more COM+
applications that should be installed by the ISComponentServiceFinalize action, which is called after the
InstallFinalize action. To specify more than one COM+ application, separate each with a semicolon (;).
To specify that all COM+ applications should be installed by the ISComponentServiceFinalize action, set
the value of this property to ALL.
Using this property is helpful if you want to install a COM+ application that contains .NET assemblies to
be installed to the GAC because Windows Installer does not commit the changes made in the in-script
session to the GAC until the InstallFinalize action.
Additional Predefined System Searches for Basic MSI and InstallScript MSI Projects
InstallShield has several new predefined system searches:
• Adobe Reader 7
• Adobe Reader 6
PropertySchemaVersion Property Value for Saving the Current Project as an InstallShield 12 Project
You can now save an InstallShield 2008 project as an InstallShield 12 project (.ism) through the
automation interface by using the new epv120 value for the PropertySchemaVersion property of the
ISWiProject object. For more information, see the description of the PropertySchemaVersion property.
The CreateProject method for the ISWiProject object now enables you to create merge module projects.
Previously, this method supported only Basic MSI, InstallScript, InstallScript MSI, and InstallScript
Object projects.
To learn more, see CreateProject Method.
The automation interface includes a new object and a new collection for dynamic file links. In addition,
the ISWiComponent object includes two new methods and a property that let you add
(AddDynamicFileLinking) and remove (RemoveDynamicFileLinking) a component’s dynamic file link,
as well as get the collection of dynamic file links (ISWiDynamicFileLinkings).
For more details, see:
• ISWiDynamicFileLinking Object
• ISWiDynamicFileLinkings Collection
• ISWiComponent Object
• AddDynamicFileLinking Method
• RemoveDynamicFileLinking Method
The automation interface includes a new object and a new collection for configuring path variables in a
project. In addition, the ISWiProject object includes two new methods and a property that let you add
(AddPathVariable) and remove (DeletePathVariable) a path variable from a project, as well as get the
collection of path variables (ISWiPathVariables).
To learn more, see:
• ISWiPathVariable Object
• ISWiPathVariables Collection
• ISWiProject Object
• AddPathVariable Method
• DeletePathVariable Method
The automation interface includes new objects and collections for configuring languages and string
entries in a project. The ISWiLanguage object includes two methods and a property that let you add
(AddStringEntry) and remove (DeleteStringEntry) a string entry from a project, as well as get the
collection of string entries (ISWiStringEntries). In addition, the ISWiProject object includes a new
property (ISWiLanguages) that gets the collection of languages included in the current project.
For more information, see:
• ISWiLanguage Object
• ISWiLanguages Collection
• ISWiStringEntry Object
• ISWiStringEntries Collection
• AddStringEntry Method
• DeleteStringEntry Method
• ISWiProject Object
The automation interface includes a new object and a new collection for environment variables. In
addition, the ISWiComponent object includes two new methods and a property that let you add
(AddEnvironmentVar) and remove (RemoveEnvironmentVar) a component’s environment variables, as
well as get the collection of environment variables (ISWiEnvironmentVars).
• ISWiEnvironmentVar Object
• ISWiEnvironmentVars Collection
• ISWiComponent Object
• AddEnvironmentVar Method
• RemoveEnvironmentVar Method
ISWiProject Object Properties for Setting the Company Name, Company URL, and Company Phone Number
The ISWiProject object includes several new properties that let you specify values for General
Information view settings:
• CompanyName
• CompanyURL
• CompanyPhone
The ISWiRelease object includes several new properties that enable you to configure settings for
digitally signing files for releases at build time. The new properties are:
• CertificatePassword
• SignFiles
• SignFilesExclude
• SignFilesInclude
• SignSignedFiles
ISWiRelease Object Properties for Specifying Whether to Keep Unused Directories in the Directory Table
The ISWiRelease object includes a new KeepUnusedDirectories property that lets you specify whether
you want to want InstallShield to remove unused directories from the Directory table of the .msi file
when you build this release.
ISWiRelease Object Property for Configuring Whether to Postpone Any Reboot for Installing or Updating the .NET
Framework
The ISWiRelease object includes a new DotNetDelayReboot property that lets you specify whether you
want to postpone any reboot associated with installing or updating the .NET Framework on the target
system until after your installation has completed.
ISWiRelease Object Property for Specifying Whether to Display a Message Box Asking the End User if They Want to Install
the .NET Framework
The ISWiRelease object includes a new DisplayDotNetOptionDialog property. Use this property to
specify if a message box should be displayed at run time to let end users indicate whether the .NET
Framework should be installed.
The ISWiRelease object now includes several new properties that enable you to configure settings for
distributing releases to a folder or FTP site automatically at build time. The new properties are:
• DistributeToLoc
• DistributeToURLLoc
• DistributeToURLUserName
• DistributeToURLPassword
• DistributeAfterBuild
The ISWiSequence collection has a new RemoveSequenceRecord method that enables you to delete an
item from a sequence. To learn more, see RemoveSequenceRecord Method.
Basic MSI Projects Now Support Adding and Removing Support Files
The automation interface now includes support for the ISWiSetupFile and ISWiAdvancedFile objects in
Basic MSI projects. These objects include methods (AddSetupFile, DeleteSetupFile, AddAdvancedFile,
and DeleteAdvancedFile) that are now available in Basic MSI projects. Previously, these objects and
methods were available in only InstallScript, InstallScript MSI, and InstallScript Object projects.
To learn more, see:
• ISWiAdvancedFile Object
• ISWiAdvancedFiles Collection
• AddAdvancedFile Method
• DeleteAdvancedFile Method
• ISWiSetupFile Object
• ISWiSetupFiles Collection
• AddSetupFile Method
• DeleteSetupFile Method
• ISWiProject Object
Windows Vista and Internet Explorer 7 Support for One-Click Install Installations
One-Click Install installations in InstallScript projects can now be used on Windows Vista systems and
with Internet Explorer 7. The One-Click Install setup player is now an external .ocx file, instead of being
embedded in the Setup.exe file. The setup player downloads and then launches the Setup.exe file with
the appropriate command line. This enables end users who are using Windows Vista with limited
privileges to run the installation; if elevated privileges are required because of the required execution
level specified in the installation’s manifest, the appropriate User Account Control (UAC) prompt is
displayed when the Setup.exe file is launched.
To support this new behavior, a new Generate One-Click Install setting is available on the Internet tab in
the Releases view and on the Internet Options panel in the Release Wizard. If you select Yes for this
setting, InstallShield includes an .ocx file for the installation.
To learn more about One-Click Install installations, see the Typical Web Installation vs. One-Click
Install section of the documentation. In addition, see the following:
• Internet Tab
New and Enhanced Setup.exe and Update.exe Command-Line Parameters (InstallScript Projects)
Two new command-line parameters are available for Setup.exe and Update.exe:
• /installfromweb
• /media_path
In addition, the /L parameter now supports both hex and decimal language values.
To learn more, see Setup.exe and Update.exe Command-Line Parameters.
Downloader Web Release Type Supports More Location Options for .cab Files
The Downloader type of Web release now lets you specify whether InstallShield should create external
.cab files that are downloaded at installation time as needed. Previously, .cab files were always streamed
into the .msi package for the Downloader Web release type.
The new external .cab file options are available on the Downloader Options panel of the Release Wizard.
This panel is displayed in the Release Wizard if the media type is Web and the Web type is Downloader.
The Downloader Options panel has a new Create external .cab files check box. If you clear this check box,
the behavior is the same as it was previously: the .cab files are streamed into the .msi package. If you
select this check box, you can specify how .cab files should be created: one .cab file per feature, one .cab
file per component, or multiple .cab files based on a particular size that you specify.
Downloader and Install from the Web Types of Web Releases Embed All Transforms
The Downloader type of Web release and the Install from the Web type of Web release now always
embed all .mst and .ini files in the Setup.exe file.
New LaunchApplication and WaitForApplication Functions to Supersede LaunchAppAndWait for Launching Applications with
Elevated Privileges
The LaunchApplication function uses either the Windows API function CreateProcess or the Windows API
function ShellExecuteEx to launch the specified application. After the application is launched, the
installation can optionally call the new WaitForApplication function to wait for the application to
terminate.
The WaitForApplication function waits for a running application, and optionally all child applications that
are launched by the running application, to terminate before returning.
Note that calling LaunchAppAndWait now calls the following:
LaunchApplication( szProgram, szCmdLine, "", LAAW_STARTUPINFO.wShowWindow,
LAAW_PARAMETERS.nTimeOut, nOptions | LAAW_OPTION_CHANGEDIRECTORY | LAAW_OPTION_FIXUP_PROGRAM );
The new LaunchApplicationInit function is available. This function, which was added to match the naming
convention of the LaunchApplication function, has the same behavior as the
LaunchAppAndWaitInitStartupInfo function.
• WaitForApplication
• LaunchAppAndWait
• LaunchApplicationInit
Several new predefined constants are available:
• LAAW_OPTION_CHANGEDIRECTORY
• LAAW_OPTION_FIXUP_PROGRAM
• LAAW_OPTION_USE_SHELLEXECUTE
• LAAW_OPTION_WAIT_INCL_CHILD
In addition, the LAAW_OPTION_NO_CHANGEDIRECTORY is now obsolete. Passing this parameter
has no effect.
The following script variables are also now available:
• LAAW_SHELLEXECUTEINFO
• LAAW_SHELLEXECUTEVERB
New SdRMFilesInUse Dialog and OnRMFilesInUse Event Handler for Minimizing Reboots Through the Restart Manager
Infrastructure in InstallScript MSI Projects
A new SdRMFilesInUse function is available. This function displays a dialog that includes a list box
containing a list of the applications that are open and are locking files. The dialog also includes two radio
buttons that allow end users to specify whether the installation should attempt to use the Restart
Manager to shut down the applications that are locking files or overwrite the locked files (which most
likely results in the need for a reboot to complete the installation).
For InstallScript MSI projects, the new OnRMFilesInUse event handler displays the new SdRMFilesInUse
dialog. This event handler is called when the Restart Manager is enabled and Windows Installer 4.0
sends an INSTALLMESSAGE_RMFILESINUSE message to the installation.
• OnRMFilesInUse
The Compile/Link tab on the Settings dialog box, which is available from the Build menu in
InstallShield, now has an Include Paths box. Use this Include Paths box to specify which directories
InstallShield should search for source files that have been included in the main installation’s
InstallScript code through #include statements. It corresponds with the -i option for Compile.exe, the
command-line compiler.
To learn more, see Compile/Link Tab.
A new FOLDER_DOTNET_30 InstallScript variable is available. This variable stores the path of the
.NET Framework 3.0. The corresponding text substitution for this variable is
<FOLDER_DOTNET_30>.
The .NET Framework 3.0 writes the value InstallSuccess with value data of 1 to the registry to indicate
that it is installed. To support this new possible registry value, the
Is( DOTNETFRAMEWORKINSTALLED ) function has been enhanced to also check for the new value
InstallSuccess. The Is( DOTNETFRAMEWORKINSTALLED ) function also still checks for the value of
Install, which is used by earlier versions of the .NET Framework. For more information, see Is.
Two new constants are available for use with the Is function:
• REGDB_KEYPATH_DOTNET_30
• REGDB_VALUENAME_INSTALLSUCCESS
New Is Constant for Checking for the Presence of a Minimum Service Pack Number of the .NET Framework
Use the new DOTNETSERVICEPACKINSTALLED constant with the Is function to determine whether a
particular service pack—or a later version of the service pack—of the .NET Framework is installed. For
more information, see Is.
Several InstallScript functions for SQL support have been added or updated.
The following InstallScript functions are now available for InstallScript and InstallScript MSI projects:
• SQLRTInitialize2—Loads the SQLRT.dll file for InstallScript projects and the ISSQLSRV.dll file for
InstallScript MSI projects, and it uses the settings file to initialize the .dll file. This function
supersedes the SQLRTInitialize function.
• SQLServerSelectLogin2—Creates a login dialog that lets the targeted end user specify which SQL
Server should be used for the current connection, as well as which login credential should be used.
This dialog also optionally shows the connection name that is associated with the connection
information. In addition, it optionally allows the end user to specify which database catalog should
be used for the current connection. This function supersedes the SQLServerSelectLogin function.
• SQLDatabaseBrowse—Creates a dialog that lets the end user display a list of all database catalogs
available on the specified database server.
• SQLBrowse2—Creates a dialog that lets an end user display a list of all database servers that are
available on the network for the database technologies specified for a connection. This function
supersedes the SQLBrowse function.
• SQLRTPutConnectionInfo2—Sets the connection information (the default server, default database
catalog, default user name, and default password). This function supersedes the
SQLRTPutConnectionInfo function.
The following InstallScript functions are now available for InstallScript projects:
• SQLRTGetLastError2—Returns detailed information about the last error encountered by the SQL
run time and loads the proper SQL error message.This function supersedes the SQLRTGetLastError
function.
• SQLRTGetErrorMessage—Returns the descriptive message of the last error encountered by the SQL
run time when a connection is being opened.
• SQLRTGetScriptErrorMessage—Returns the descriptive message of the last error encountered by
the SQL run time when a SQL script is executing.
The following InstallScript function is now available for InstallScript MSI projects:
• SQLRTTestConnection2—Establishes a connection.This function supersedes the
SQLRTTestConnection function.
The following InstallScript functions, which were previously available only for InstallScript projects, are
now also available for InstallScript MSI projects:
• SQLRTGetConnections
• SQLRTGetConnectionInfo
• SQLRTPutConnectionInfo
• SQLRTGetConnectionAuthentication
• SQLRTPutConnectionAuthentication
InstallShield still supports the functions that are superseded by new versions of the functions. However,
if you upgrade a project that was created in InstallShield 12 or earlier to InstallShield 2008, InstallShield
does not automatically update the existing InstallScript code to use the new functions.
For more information, see:
• Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects
• SQL Functions
Use the new USER_INADMINGROUP constant with the Is function to determine whether a user is in
the Administrators group, regardless of whether that user is running the installation with a standard
access token. For more information, see Is.
Note that Is( USER_ADMINISTRATOR ) now returns FALSE if the user is in the Administrators group
but the group has the SE_GROUP_USE_FOR_DENY_ONLY security identifier (SID) attribute set (that
is, the user is running with a standard access token).
New Functions that Enable a .NET Library Loaded Through InstallScript to Be Unloaded Before the Installation Completes
• The DotNetUnloadAppDomain function unloads the specified .NET application domain and releases
any assemblies that are currently loaded into the specified application domain.
Support for Enabling Update Notifications During an Upgrade When the Original Installation Did Not Include FLEXnet
Connect
A new InstallScript function called RegDBDeleteItem is now available. The RegDBDeleteItem function
deletes values under the per application paths key or the application uninstallation key, depending on
the value of nItem. For more information, see RegDBDeleteItem.
A new InstallScript function called GetStatus is now available for InstallScript Object projects. The
GetStatus function retrieves the current status of the object; that is, the current value of Status.Number.
For more information, see GetStatus.
The LWTF_OPTION_APPEND_TO_FILE constant has been added to the InstallScript language. You
can pass this constant as the nOptions parameter for the ListWriteToFileEx function to append a list to an
existing file.
In addition, two existing nOptions constants have been renamed:
• LWFT_OPTION_WRITE_AS_ANSI is now LWTF_OPTION_WRITE_AS_ANSI.
• LWTF_OPTION_APPEND_TO_FILE
• LWTF_OPTION_WRITE_AS_ANSI
• LWTF_OPTION_WRITE_AS_UNICODE
use any obsolete API calls, and more. In addition, ISICE02 now verifies that .ocx, .sys, .cpl, .drv, and .scr
files are signed. Previously, ISICE02 verified only that .exe files are signed. ISICE06 now checks the
destination path of files that are in your installation and that have the same name as a Windows
Protected File. If the destination path for the file in your installation does not match the location of the
Windows Protected File, ISICE06 now displays a validation warning instead of a validation error.
When you validate your package, InstallShield lists any validation messages on the Tasks tab of the
Output window. Now you can double-click a validation message on the Tasks tab to jump to the area of
the Direct Editor that corresponds to the validation message. This functionality is available for ISICEs,
as well as for standard ICEs. Previously, it was available only for standard ICEs.
For more information, see:
• ISICEs
Additional Changes
For a list of issues that are resolved in InstallShield 12 SP1, see the release notes. The release notes are
available from the Help menu in InstallShield.
• Specifying Which ICEs, ISICEs, and ISBPs Should Be Run During Validation
• ISICEs
• Specifying the Required Execution Level for Your Setup Launcher on Windows Vista Platforms
• Guidelines for Creating Custom Actions that Meet Requirements of the Certified for Windows Vista
Program
This documentation now describes each of the built-in InstallShield custom actions that are added
automatically to InstallShield projects to support different functionality. See InstallShield Custom
Action Reference.
• The new Behavior tab lets you specify whether end users may skip the prerequisite installation. You
can also specify how the prerequisite installation should proceed if it appears that the target
machine does or does not need to be restarted.
• Now you can create prerequisite installation conditions for DWORD registry comparisons. You can
also create conditions for 64-bit machines.
For more details, see:
• Behavior Tab
view. Registry reflection keeps the 32-bit registry view and the 64-bit registry view in sync on a target
machine. Only 64-bit systems with Windows Installer 4.0 support this setting. Other systems ignore it.
For more specific information, see Enabling and Disabling Registry Reflection.
• Display Resource ID
• Description Resource ID
These new settings correspond with the four new columns in the Shortcut table for Windows Installer
4.0. To learn more, see Shortcut Properties.
.NET Compact Framework 2.0 and Other Mobile Device Redistributables Now Available
Several new redistributables are available for mobile device installations: .NET Compact Framework
2.0, SQL Mobile 2005, SQL Client 2.0, and SQL Mobile 2005 Replication. In addition, installations for
Smartphone 2002 and 2003 now support redistributables.
InstallScript Rearchitecture Enhancements for InstallScript MSI Projects and Basic MSI Projects
with InstallScript Custom Actions
The InstallScript MSI architecture has had a number of issues with security (COM/DCOM) and other
areas that can cause some installations to fail for various reasons. The architecture has been improved
dramatically for InstallShield 12 to resolve these issues and to make InstallScript MSI a more reliable
project type. The improvements also help increase the reliability of Basic MSI projects that include
InstallScript custom actions.
To learn more, see the following:
• Run-Time Behavior for Basic MSI Installations with InstallScript Custom Actions
Registry and File Filtering Enhancements for COM Extraction and Dependency Scanners
To prevent InstallShield from extracting undesired COM data from a COM server, you can edit a new
Filters.xml file that is installed with InstallShield. Editing this Filters.xml file enables you to customize
the list of registry keys that will be excluded from COM extraction.
The Filters.xml file also now lists files that the Static, Dynamic, and Visual Basic dependency scanners
will exclude or include. Previously, two different files—Userscan.ini and Iswiscan.ini—were used to list
excluded and included files.
For more information, see:
• Filtering Registry Changes for COM Extraction
• UNINSTALL_STRING
Two new InstallScript text substitutions are available:
• DISK1SETUPEXENAME
• SELECTED_LANGUAGE
For more information, see System Variables.
• BASICMSI
A new LANG_SUPPORTED predefined constant is available for use with the Is function. To learn more,
see Is.
A new ISOSL_WINVISTA predefined constant is available for use with the FeatureFilterOS function and
the SYSINFO structure variable. For more information, see FeatureFilterOS function and the SYSINFO.
The DoInstall function is now similar to the LaunchAppAndWait function. For more details, see DoInstall.
Upgrade Details
For InstallShield 12, a number of improvements were made to the InstallScript MSI architecture to
resolve issues with security (COM/DCOM) and other areas that can cause some installations to fail for
various reasons. The architecture was improved for InstallShield 12 to resolve these issues and to make
InstallScript MSI a more reliable project type. The improvements also help increase the reliability of
InstallScript projects, as well as Basic MSI projects that include InstallScript custom actions.
In addition, the merge module project type has been enhanced: it now has the same InstallScript view
that is available in Basic MSI projects. This enhanced version of the merge module project type replaces
the InstallScript MSI object project type, which is no longer available in InstallShield.
To learn more, see Upgrading Projects from InstallShield 11.5 or Earlier.
• Windows XP
• Windows Vista
Windows Installer 3.1 Windows 2000 SP3 or later, Windows Server 2003
Windows Installer 3.0 Windows 2000 SP3 or later, Windows Server 2003
• Pocket PC 2003
• Pocket PC 2002
• Pocket PC
• Palm-size PC 2.11
• Palm-size PC 2.01
• Handheld PC 2000
• Handheld PC Pro
• Handheld PC 2.0
• Smartphone 2003
• Smartphone 2002
Note that if a platform is not included in the list, it does not mean InstallShield does not support it. It
simply means that you cannot set conditions for that specific platform.
InstallShield includes support for the following Windows Mobile processors:
• ARM920
• ARM820
• ARM720
• Hitachi SH4
• Hitachi SH3E
• Hitachi SH3
• i686
• i586
• i486
• MIPS R4000
• MIPS R3000
• MIPS R2000
• SHx SH4
• SHx SH3
• StrongARM-XScale
• Administrative privileges
If you are writing applications for 64-bit Windows operating systems, you will need a way to install your
64-bit files. Although 32-bit installations run on 64-bit machines, they cannot install 64-bit files and
applications. The Windows Installer service provides support for 64-bit installations. These installations
can be designed and compiled on 32-bit machines, but they can run only on 64-bit machines. Through
the use of release flags, you can create one installation project for both 32-bit and 64-bit machines.
Using Help
Macrovision understands the importance of having useful information and help resources at your
fingertips. In addition to the inline help embedded within various views of the InstallShield interface,
InstallShield includes the Help Library (the online help library that is installed with InstallShield) and
HelpNet.
Help Conventions
In this documentation, reader alert and style conventions are used to bring your attention to specific
information or help you identify information.
Best Practices Best Practices alerts instruct you on the best way to accomplish a task.
Caution Cautions indicate that this information is critical to the success of the desired
feature or product functionality.
Edition-Specific Note Edition-specific notes indicate that the information applies to a specific edition of a
product (such as Professional or Premier edition).
Important Note Important notes are used for information that is essential for users to read.
Note Notes are used to draw attention to pieces of information that should stand out.
Project-Specific Note Project-specific notes are used to highlight information that may vary depending
on the project type used (such as a Basic MSI or Merge Module project).
Tip Tips are used to indicate helpful information that could assist you in better using
the desired function or feature.
Version-Specific Note Version-specific notes indicate that the information applies to a specific version of
a product (such as Version 9.0 or Version 11.0).
Windows Logo Windows Logo Guideline alerts accompany Microsoft logo compliance
Guideline requirements and recommendations.
Style Conventions
The following style conventions are used throughout this documentation.
User Interface On the File menu, click Open. User interface elements appear in bold when
Elements referenced in tasks.
File Name and My files are located in the File names and directory paths are presented
Directory Paths C:\MyDocuments\SampleCode directory. in a monospace typeface.
.INI File Text Insert the line LimitedUI=Y into the file to display Text in .INI files is presented in a monospace
only the Welcome dialog box when the Windows typeface.
Installer package is run.
Command-Line To run the installation silently, enter: Command-line statements and parameters
Statements are presented in a monospace typeface.
Setup.exe /s /v/qn
Environment Set the value of the windir environment variable to Environment variables are presented in a
Variables your monospace typeface.
Examples Create two groups, one called Admins and the Examples are presented in bold.
other called General.
Functions FeatureAddItem adds a new feature to a script- Functions are presented in bold.
created feature set.
Properties In the Name property, enter a name for this custom Properties are presented in bold.
control that is unique among all of the controls in
your project.
Screen Output If you type an incorrect parameter, the message Screen output (from a log file or from the
The system cannot find the path console) is displayed in a monospace
specified. is displayed. typeface, and in blue.
Company Information
Macrovision Corporation is the market leader in electronic licensing, installation, and digital rights
management (DRM) technologies. Over 50,000 software vendors and virtually all of the Fortune 1,000
companies use Macrovision’s technologies to maximize the value of their software.
Software Value Management solutions bridge the gap between pricing and packaging software on the
development side, and purchasing and managing that software on the enterprise side. Macrovision
markets the FLEXnet Software Value Management platform, which includes the InstallShield suite of
software installation, repackaging, and update solutions; these solutions are deployed on more than 500
million desktops worldwide. Macrovision holds more than 910 software licensing, DRM, and content
protection patents worldwide. Macrovision is headquartered in Santa Clara, California, and has offices
worldwide.
Macrovision Solutions
Maximize the Value of Your Software
Software Value Management is a set of best practices that enables software vendors and their enterprise
customers to maximize the value of the software applications they create, use, and maintain.
After an application is developed by the engineering department, publishers use Software Value
Management tools to maximize the application’s revenue potential. These tools include installers and
licensing tools that help publishers flexibly package, price, and protect their products. Their enterprise
customers use Software Value Management tools to maximize the productivity that they get from the
software they purchase. These tools enable corporate IT staff to repackage applications, resolve potential
conflicts, optimize license purchases, and manage updates.
• Sell Software • FLEXnet Publisher—Price, package, protect your product, and manage
software licenses throughout the product’s lifecycle to better meet market
• Distribute Software
needs and maximize revenue.
• Service Software
• Renew Software
Enterprise IS and IT: • InstallShield and InstallAnywhere—Tools for authoring installations and
• Buy Software software management for any operating system.
• Private, on-site courses customized to your company’s needs are also available.
Visit http://www.macrovision.com/services/education/index.shtml today to learn more or fill out our
online form.
• Get personalized assistance from Macrovision’s senior engineers and support technicians.
Visit http://www.macrovision.com/support/index.shtml to learn more.
• Work alongside our experts to learn invaluable techniques and best practices.
Visit http://www.macrovision.com/services/consulting/index.shtml to learn more or fill out our online
form.
Knowledge Base
The Knowledge Base is accessible from the Support section of the Macrovision Web site at http://
www.macrovision.com/support/index.shtml. It contains answers to many commonly asked questions
and includes new information about InstallShield that may not appear in the documentation. Click
InstallShield on this page to open the InstallShield-specific knowledge base. You can use the Knowledge
Base search engine to search articles by phrases, numbers, platforms, and version.
Support Site
In addition to enabling you to search the Knowledge Base, the Macrovision Support site at http://
www.macrovision.com/support/index.shtml enables you to:
• Obtain InstallShield updates.
• View webinars.
• Obtain InstallShield white papers, case studies, marketing materials, and training materials.
Online Communities
The online communities are another excellent resource when you have questions about using
InstallShield. In these communities, users like you share tips and ideas and help each other get the most
out of InstallShield. Visit the communities in the Support section of our Web site, available at http://
community.macrovision.com.
United States
Table 2-4: Europe, Middle East, and Africa Contact Information (cont.)
Macrovision Alicante Office Macrovision Corporation Tel: (34) 956 107 771
• Games Technologies Av. Jaime I El Conquistador
Email: gamesales@macrovision.com
1-3 Bajo El Campello
Alicante 03560
Spain
Asia Region
Macrovision Japan and Asia K.K. Macrovision Corporation Tel: (81) (3) 5774 6253
Japan Office Aoyama Diamond Building 3F
Fax: (81) (3) 5774 6269
1-1-8, Shibuya, Shibuya-ku
Tokyo 150-0002 Japan Email: Sales-Japan@macrovision.com
InstallShield provides powerful features and time-saving tools that make authoring reliable Windows
Installer and InstallScript installations easy. The InstallShield Help Library is a resource that will help
you harness the full potential of InstallShield. The help topics you might want to read first depend upon
your previous experience with InstallShield installation-authoring software. The table below directs you
to various topics based on your level of experience.
You have not created installations To learn general information about installations, refer to the following topics:
previously.
• Installation Fundamentals
• Application Lifecycle
You are new to InstallShield. If you have created installations previously but you do not have experience
using InstallShield, see the following topics:
• Working with the InstallShield Interface
• Working with Projects
• Basic MSI Project Tutorial
• Globalization Tutorial
• InstallScript Project Tutorial
• Supported Application Programming Languages
You have used other Macrovision If you have used other products from Macrovision Corporation, refer to any
products. of the following topics:
• Upgrading from Earlier InstallShield Versions
• Upgrading from Other InstallShield Editions
• Project Assistant
• Installation Projects Overview
You are an intermediate-level or If you are familiar with InstallShield, you may want to review the following
advanced-level user of InstallShield. topics:
• Command-Line Tools
• Errors and Warnings
• InstallScript Language Reference
• Running Installations in Silent Mode
Installation Fundamentals
An installation, in its simplest terms, is the “package” used to install your files and programs onto your
user’s machine. It is a complete collection of the application files, as well as logic that interacts with the
installer engine. The primary task of any installation is to transfer the application files from the source
medium to the end user’s computer. The complexities of the Windows operating system make it
anything but simple to create an effective, coherent installation without the aid of a utility such as
InstallShield.
An installation is divided into three levels: products, features, and components. The following diagram
illustrates this hierarchy:
A product is the highest level of organization in an installation project. A product is usually one main
application (for example, a word processor) and all of the files and data that the application requires; a
suite of applications may also be a product.
A feature is the smallest installable part of a product, from the end user’s perspective. As the designer of
an installation program, you usually allow the user to choose which features to install and which features
to leave on the source media. In a word processor product, the main executable may be one feature, and
optional dictionaries may be a separate feature. A feature should be self-contained, in the sense that a
feature should not require sibling features. For example, a thesaurus feature should not require a
dictionary feature that the user can choose not to install. However, you can design features to contain
subfeatures, which allow the end user finer control over which files and data to install.
Each feature in a project is made up of one or more components. A component is the smallest installable
part of a product from the installation developer’s perspective; components are invisible to the end user.
Each component contains files (and other resources) with similar properties. For example, all of the files
in a component will be installed in the same directory on an end user’s machine, and all of the files in a
component should apply to the same operating system or language. A dictionary feature might contain
several language-specific dictionary components. In addition to containing files, components generally
contain registry data, shortcuts, file extension information, and other system data to write to a user’s
machine.
When you are designing an installation, the overall task is to separate the product’s files into
components based on the files’ destination, operating system, language, and other properties, and to
associate each component with one or more features.
Application Lifecycle
Your application lifecycle should not end when your customer installs your application. As a software
vendor, the success of your application goes well beyond the initial installation on the customer’s
desktop. Customers expect to have easy access to product updates, enhancements, and critical
information. Your ability to communicate with your customers and monitor the health of your
application is vital to your ongoing growth and profitability.
Too often, software vendors require their customers to initiate communication. Vendors who are not
proactively creating an ongoing dialog are missing a tremendous opportunity. Unless the customer is an
active visitor to your Web site or public user communities, they miss important information about
updates, upgrades, hot fixes, and general technical bulletins. You miss revenue and service
opportunities.
The above diagram illustrates how FLEXnet Connect is used to manage the application lifecycle:
1. Create Install—InstallShield makes it easy for software developers to create installations that run on
any platform.
2. Run Install—Installations created with InstallShield technology have successfully installed on over
400 million machines worldwide.
3. Create Update—InstallShield enables software developers to rapidly build patches and updates.
4. Notify User—FLEXnet Connect notifies every user that a new update is ready to be installed.
5. Download & Install—FLEXnet Connect downloads the update and installs it in one seamless,
integrated process.
6. View Reporting—FLEXnet Connect provides immediate feedback on the update’s adoption rate.
Welcome Assistant
InstallShield provides a Welcome Assistant to help you determine which installation project type is best
for your needs.
Task To display the Welcome Assistant in InstallShield after the initial launch:
Starting InstallShield
Each time you open InstallShield (with the exception of the initial launch after installing the product),
you are taken directly to the InstallShield Start Page. The Start Page provides quick access to product
information, to recently opened projects, and to InstallShield resources.
Section Description
Project Tasks Click a project task to quickly create a new project, open an existing project, or browse to
one of the sample projects included with the InstallShield installation.
Help Topics Frequently accessed help topics are listed in this section. To access the entire InstallShield
Help Library from the Start Page, press F1 or click the Help Library link in the Resources
section.
(Recently Opened The section in the middle of the Start Page lists your most recently accessed projects, the
Projects) project types, and the dates on which they were last modified.
Getting Started Click the Getting Started heading for guidance on what areas of the InstallShield Help Library
to read, based on your level of experience with InstallShield and installation-authoring tools.
Resources The Resources section contains a number of links to connect you to helpful InstallShield
information.
• Help Library—Displays the InstallShield documentation.
• Support—Opens the Support page on the Macrovision Web site.
• InstallShield Community—Provides a Web-based forum where you can join other
InstallShield users, post questions, and search for answers.
• Webinars—Directs you to free Web-based seminars that help you evaluate InstallShield
and gain the most from your Macrovision products.
• Downloads—Offers a place where you can download the latest InstallShield merge
modules, objects, and setup prerequisites; service packs; patches; and more for the
version of InstallShield that you are using.
• Release Notes—Connects you to the release notes that are posted to the Knowledge
Base on the Macrovision Web site.
• Known Issues—Displays the Knowledge Base article that lists the known issues for the
version of InstallShield that you are using and provides information about workarounds
and resolutions.
Contact Us To provide feedback about InstallShield or join our Customer Experience Improvement
Program, click one of the links listed in this section.
• Redistributable (merge module or InstallShield object): contains logic and files needed to install
distinct pieces of functionality when included in an installation
• Transform: enables an administrator to apply modified settings to an Windows Installer installation
when deploying the installation
A project can be as simple or as complex as you need to meet your requirements. A simple project might
consist of files, components, features, and registry entries. More complex projects might consist of these
items plus redistributables, initialization file changes, and calls to external DLL functions.
Project Types
InstallShield offers a number of different project types to assist you in creating the optimal project for
your end users. When you first launch InstallShield, the Welcome Assistant helps you determine which
installation project type is best suited for your needs.
InstallScript The InstallScript installation project provides the flexibility afforded by the
InstallScript language and is driven by the proven InstallScript engine.
InstallScript Object Using the InstallScript Object project, you can create an InstallShield merge
module that uses InstallScript. This type of merge module, however, can be
consumed only by InstallShield.
Basic MSI A Basic MSI project uses Windows Installer to provide the user interface for
the installation. When you choose this project type, you need to create
features and components, and specify all application files and other
distributable data.
Merge Module Select this option to create your own merge modules. You need to create
any components and file associations.
QuickPatch This project type is recommended for installation authors who want to ship
small, single updates to their end users. QuickPatch authoring provides an
alternative to creating a patch configuration in the Patch Design view even
though it provides less customization. Creation of a QuickPatch begins with
the Create New QuickPatch Wizard.
Web Project The Web project type is essentially the same as the Basic MSI project type,
with the addition of IISROOTFOLDER support. The IISROOTFOLDER directory
variable is used to find the root directory of the Web server on a target
system.
MSI Database Select MSI Database to edit your installation project in Direct Edit mode.
This means that you can directly edit the Windows Installer tables within
InstallShield to configure your installation.
MSM Database Select MSM Database to edit your merge module in Direct Edit mode. This
means that you can directly edit the Windows Installer tables within
InstallShield to configure your merge module.
InstallScript MSI An InstallScript MSI project uses both InstallScript and Windows Installer
tables. With this project type, you need to create features and components,
and specify all application files and other distributable data.
Visual Basic 6.0 Wizard Select this option to launch the Visual Basic Wizard.
Visual Basic .NET Wizard Select this option to launch the Visual Studio .NET Wizard for Visual Basic
.NET, C# .NET, and Visual C++ .NET.
C# .NET Wizard Select this option to launch the Visual Studio .NET Wizard for Visual Basic
.NET, C# .NET, and Visual C++ .NET.
Visual C++ .NET Wizard Select this option to launch the Visual Studio .NET Wizard for Visual Basic
.NET, C# .NET, and Visual C++ .NET.
Smart Device Setup Wizard The Smart Device Setup Wizard guides you through the process of creating
installations for smart devices.
Compact Project A Compact project uses a special small installer engine to provide the user
interface for an installation. Although Compact installation projects have
some limitations—for example, English is the only language available for
the end-user interface—they enable you to create a very small executable
file (Setup.exe) that you can distribute to end users. This Setup.exe file is
a compressed, self-extracting file that contains all of the application files, as
well as the Compact installer engine.
InstallScript Projects
InstallScript projects use InstallScript to control the installation. It is recommended if you want a highly
customized run-time user interface, such as those including multimedia elements. InstallScript
installations are generally less desirable to systems administrators because they do not use the Windows
Installer database. In general, InstallScript projects are more flexible than Basic MSI projects and are
easier to debug.
The InstallScript project is recommended when you:
• Have advanced requirements for the user experience (the end-user dialogs).
• Prefer authoring the user experience using a procedural language rather than a set of tables.
• Are upgrading your project from InstallShield Professional and want to preserve as much of your
existing InstallScript code as possible.
• Want to use full-screen billboards during the user experience.
• Maximize the ability of users or other third parties to customize the installation for redeployment.
• Avoid writing scripting code and want to instead set properties and make table entries.
Note: InstallScript installations are generally less desirable to systems administrators because they require the use of
Setup.exe, rather than being self-contained in an .msi file, and may not be fully customizable prior to deployment. If your
software will be customized by corporate systems administrators prior to deployment, Macrovision recommends that you
create a Basic MSI installation project.
Feature Description
Setup Types view This view enables you to easily create different installation configurations for
your application. This view also lets you select the defaults for the Custom setup
type.
Billboard Support Run-time billboard support is available only for InstallScript projects. Billboards
let you show bitmaps to the end user while files are being transferred to their
machine. You can use these bitmaps to entertain or educate user.
Note: Macrovision recommends that you create a Basic MSI project if your software will be customized by corporate
systems administrators prior to deployment. It gives them the flexibility to create transforms for the installation package
and its associated properties, without repackaging your installation.
InstallScript MSI projects require Setup.exe because Setup.exe initiates the External UI for Windows Installer.
Basic MSI projects have the ability to run InstallScript code in the form of custom actions. As with
InstallScript projects, Basic MSI projects take advantage of other robust features provided by
InstallShield such as dialog authoring, the ability to call custom actions in standard Windows .dll files,
and the ability to specify support files.
Run-Time Behavior for Basic MSI Installations with InstallScript Custom Actions
2. Setup.exe launches MsiExec.exe to install the primary .msi file. (Setup.exe must be included in the
installation, or it must already be present on the target system.)
3. ISMsiServerStartup (immediate custom action) starts and initializes IDriver.exe.
4. Any sequenced InstallScript custom actions execute as follows.
a. Windows Installer finds the relevant entry point in ISScriptBridge.dll.
b. ISScriptBridge.dll finds the running IDriver.exe instance using the running object table
(ROT).
c. IDriver.exe executes relevant script code.
5. ISCleanUpSuccess shuts down IDriver.exe.
If you upgrade an InstallShield 11.5 or earlier project to InstallShield 2008, the run-time behavior is
updated to the behavior described for InstallShield 12 and later projects.
Note: Because this project type uses two different engines, it is more complex than pure InstallScript or Basic MSI
installation projects. It is recommended only for advanced users.
InstallScript MSI setups are less desirable to systems administrators because they require the use of Setup.exe, rather
than being self-contained in an .msi file, and may not be fully customizable prior to deployment. If your software will be
customized by corporate systems administrators prior to deployment, Macrovision recommends that you create a Basic
MSI project.
Note: InstallScript MSI projects require Setup.exe because Setup.exe initiates the External UI for Windows Installer.
Feature Description
Setup Types view This view allows the setup developer to easily create different predefined
installation configurations for your application, such as Typical or Compact. This
view also allows you to select the defaults for the Custom Setup Type.
Billboard Support Run-time billboard support is available only for InstallScript MSI projects.
Billboards allow you to show bitmaps to the user while files are being transferred
to their machine. You can use these bitmaps to entertain or educate the user.
The run-time behavior for InstallShield 12 and later InstallScript MSI projects is much different than the
behavior for InstallShield 11.5 and earlier because of some architecture enhancements. For more
information about the enhancements, see Upgrading Projects from InstallShield 11.5 or Earlier.
Note: There is no string table or path variable support in an MSI Database or MSM Database project.
You can directly edit an existing .msi file or .msm file, or directly create a new database by opening a new
MSI Database or MSM Database project. The data in this file should match what you would get if you
created a blank MSI project and built a database from that project.
QuickPatch Projects
A QuickPatch project is a specific type of project recommended for installation authors who want to ship
small, single updates to their users. Changes that are more extensive such as adding custom actions and
changing .ini data typically require a standard patch.
QuickPatch authoring provides a simple alternative to creating a patch configuration in the Patch Design
view, even though it provides less customization. Fundamentally, both patch creation methods produce
the same deliverable types: .msp and .exe files.
With a QuickPatch, you can do any of the following:
• Add new files to the original installation or an earlier QuickPatch.
• Remove custom actions that were included with the original installation but that do not apply to the
current QuickPatch project.
The creation of a QuickPatch project always begins with the Create New QuickPatch Wizard. Completing
the wizard ensures that all basic requirements for the QuickPatch project are met. Then you can
configure project settings once it opens in InstallShield.
Project: The Smart Device project type should be used only for straight-to-device installations that do not use ActiveSync
or any other desktop component.
• Create an installation where you want only the .cab files that can then be installed to the smart
device.
InstallShield
Task To run the Smart Device Setup Wizard from within InstallShield:
1. On the File menu, click New. The New Project dialog box opens.
2. On the Mobile tab, select the Smart Device Setup Wizard project type.
3. Enter a project name and location, and click OK. The Smart Device Setup Wizard opens.
Visual Studio
Task To run the Smart Device Setup Wizard from within Visual Studio:
1. After creating a smart device solution in Visual Studio, right-click the root of the Solution
Explorer, point to Add, and select New Project. The Add New Project dialog box opens.
2. In the project types list, select the Smart Device Setup Project from the InstallShield Projects
group. The Smart Device Setup Wizard opens.
Transform Projects
A transform (.mst file) is a simplified Windows Installer database that contains the differences between
two .msi databases. Transforms enable an administrator to apply modified settings to a database when
deploying an installation package.
InstallShield has a transform project type that enables you to edit .msi packages without having to
convert them to an InstallShield (.ism) project. You can save the changes made as a transform (.mst) file.
When you create a transform project or open a transform in InstallShield, the Open Transform Wizard
launches to gather information about the base .msi file and any additional transform files that you want
applied to the base .msi file.
Web Projects
Web projects provide the same general functionality and the same IDE look as Basic MSI projects, but
also offer IISROOTFOLDER support. The IISROOTFOLDER directory variable allows you to determine
the root directory of the Web server on a target system.
Using Projects
InstallShield allows you to create, edit, upgrade, and save numerous project types—from installation
projects to InstallShield object projects that allow you to reuse functionality within InstallShield.
The pages in this section cover a variety of topics, including how to create a particular project type, how
to create project templates, and what to expect when you upgrade from a different InstallShield product.
• Click the New Project button on the toolbar or on the InstallShield Start Page.
• Press Ctrl+N.
Any of these steps launches the New Project dialog, from which you can select the project that you want
to create. If you select an installation project in the New Project dialog, the Project Assistant launches to
help you create your project.
Note: In order to convert a ClickOnce package, you must have the .NET Framework redistributable and the Visual J# .NET
redistributable installed on your machine. Note that the version numbers of these two redistributables must match.
Task To create a .dim file and an InstallShield project from a ClickOnce package:
1. On the Tools menu, click Convert a ClickOnce Package. The ClickOnce Converter Wizard
opens.
2. Complete the wizard, which will guide you through the conversion process.
Tip: As an alternative, you can convert the ClickOnce package without using the wizard by running the
ClickOnce2Dim.exe application from the command line and specifying the appropriate command-line parameters. For
more information, see ClickOnce2Dim.exe.
Opening Projects
• On the File menu, click Open. In the Open dialog box, navigate to the project file.
• Press Ctrl+O.
• Click the Open an existing project link or click a recently opened project link on the InstallShield
Start Page.
1. On the File menu, click Open. The Open dialog box opens.
2. Click the Source Control button. A login dialog box for your source control program opens.
3. Log on to your source control program and browse to your project folder or database.
InstallShield gets the latest versions of every file in that project to a working directory.
Note: If you do not have a source control application on the system that has InstallShield, the Open dialog box does not
display the Source Control button.
1. On the File menu, click Open. The Open dialog box opens.
2. In the Files of type list, click Patch Creation Properties Files (*.pcp).
3. Select the .pcp file you want to edit and click Open.
Your patch project file opens in the Direct Editor.
Note: Some functionality may be limited when editing an MSI package in Direct Edit Mode.
1. Click the Open Project button on the toolbar. A browse dialog opens.
2. Select Windows Installer Packages (*.msi) from the Files of Type list.
3. Select the MSI package that you want to open.
4. Ensure that the Open as field is set to Auto, and click Open.
Note: By default, the IDE opens an MSI package in Direct Edit Mode.
The Open MSI/MSM Wizard can convert an existing Windows installer (.msi) package to an
InstallShield project (.ism) file, and open the new project to modify in the IDE.
Note: You can also open Patch Creation Project files (.pcp files) in InstallShield and edit them in the Direct Editor.
1. Click the Open Project button on the toolbar. A browse dialog opens.
2. Select Windows Installer Modules (*.msm) from the Files of Type list.
3. Go to the merge module and click Open.
The Open MSI/MSM Wizard prompts for specific information about the project you are creating, and
then opens your new merge module project in the IDE.
Task To automatically place your merge module project in the Modules folder:
Select the “Add to local merge module catalog” option in the Merge Module Options panel of the Release
Wizard.
Saving Projects
When you create a new project, it is saved automatically with the name and location that you provide in
the New Project dialog box.
InstallShield enables you to save a copy of the open project as a template or as a new project with a
different name and location. It also enables you to downgrade your project; that is, you can save your
project to an earlier InstallShield project (.ism) schema so that users who have an earlier version of
InstallShield, InstallShield DevStudio, or InstallShield Developer can open and maintain your project.
The topics in this section cover:
• Saving a Project with a New Name and Location
1. On the File menu, click Save As. The Save As dialog box opens.
2. In the Save in box, select the appropriate location.
3. Select or clear the Create ‘Project Name’ subfolder and save the project in the created
folder check box as appropriate. In both cases, a <Project Name> subfolder is created in the
Project Location box (on the File Locations tab of the Options dialog box).
If you select the Create ‘Project Name’ subfolder and save the project in the created
folder check box, the project file (.ism) is saved in the <Project Name> subfolder. If you clear the
check box, the project file is saved in the location specified in the Project Location box.
4. If the new project’s GUID should be different than the GUID of the original project, select the
Create and assign a new project GUID to the saved project check box. If the new project’s
GUID should be the same GUID of the original project, clear this check box.
5. To use the name that you specified in the File name box as the new project’s Name property (on the
Product Properties property sheet of the General Information view), select the Update the
project settings appropriately based on the new project name check box. If the new
project’s Name property should be the same as that of the original project, clear this check box.
Note: When you save a project with external dependencies, such as InstallScript files, your new project points to the
original copies of these files. Duplicate copies are not made. Therefore, before you delete your original project, ensure
that you do not delete any files that may be used by the new project.
• The ability to downgrade projects is available for the following project types: Basic MSI, InstallScript, InstallScript MSI,
Merge Module, Visual Basic 6.0 Wizard, Visual Basic .NET, C# .NET, and Visual C++ .NET, and Web.
• When you save your project to an earlier version of an InstallShield product, the schema of your project is modified to
conform to the earlier version; any tables or columns that are available in the later version of the InstallShield product
but not in the earlier version are lost during the downgrade process.
• If you save an InstallScript project as an earlier schema version, the script file (.rul) is not downgraded to the earlier
version; only the .ism file is downgraded. If a script file created or modified in the later version of the InstallShield
product contains functions that are not available in the earlier version, your script will not compile in the earlier
version.
1. On the File menu, click Save As. The Save As dialog box opens.
2. In the Save as type list, select the appropriate version of InstallShield, InstallShield DevStudio, or
InstallShield Developer.
3. Click Save.
If you continue to modify your project after downgrading it to an earlier version, InstallShield saves the
project to the earlier version by default. To upgrade your project to the later version, you have two
options:
• Use the Save As process again and select the later version.
• Close your project and then reopen it. InstallShield displays a message box that enables you to
convert the project to the later version.
Caution: This conversion is irreversible. After you convert your Basic MSI project to an InstallScript MSI project and save it,
you cannot convert your project back to a Basic MSI project. Before you convert your project, Macrovision recommends
that you back up your Basic MSI project.
Converting Projects
Converting Dialogs
Because an InstallScript MSI project uses resource-based dialogs—instead of using the Windows
Installer dialog–related tables—no Windows Installer–based dialogs from your original project are
available after the migration. You need to manually add any custom dialogs.
Your converted installation project contains the default InstallScript MSI dialogs. To review the default
dialogs, go to the InstallScript view and view the dialogs displayed in the OnFirstUIBefore and
OnFirstUIAfter events.
Caution: Converting a project from a Compact project type to a Basic MSI project type is irreversible.
GUIDs
GUID stands for Globally Unique Identifier. A GUID is 128 bits long, and the algorithm used to generate
a GUID guarantees each GUID to be unique. Because GUIDs are guaranteed to be unique, they can be
used to identify COM classes, Product Codes, and various other codes.
For example, after a product is installed, a key is created under
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall and is named
after the installation’s Product Code. At one time, this key was named after the Product Name. However,
this caused a potential conflict. If two installations were installed on the same machine, and both shared
the same Product Name, they would also share the same registry key. Because a GUID is now used, it
guarantees that this conflict does not occur.
An example GUID is {5D607F6A-AF48-4003-AFA8-69E019A4496F}. Any letters in a GUID must be in
uppercase.
Product Code or Product GUID The product GUID uniquely identifies your application.
Package Code or Package GUID (Windows Installer based projects only) The package code uniquely
identifies your installation package.
Patch GUID (Windows Installer based projects only) The patch GUID uniquely
identifies a patch package.
Upgrade Code or Upgrade GUID (Windows Installer based projects only) The upgrade GUID uniquely
identifies a family of products for upgrade purposes. It is important for
major upgrades.
For information on when you need to change GUIDs in your project, see the Knowledge Base article
Changing the Package/Product/Upgrade GUID and Version Number for Upgrades.
To specify a new default location for your installation projects, use the File Locations tab on the
Options dialog box.
Note: Although this folder is used for all new installation projects, any existing projects remain in the previous location.
Entire Projects
By saving a project as an InstallShield project template, you can create a project from the template that
is almost identical to the original project.
Registry Entries
When you export registry entries to a REG file, you can import that file into another component’s
registry data in the same project or an entirely different one.
End-User Dialogs
You can save all of your dialogs to an .rc file, export them individually to InstallShield dialog template
files, or export them directly to another project.
Components
To export a component to another project, right-click on the component and select Export Components
Wizard. Follow through wizard and the component and all of its data are added to the specified project.
Custom Actions
You can export a custom action to another project by right-clicking on the custom action in the Custom
Actions explorer and clicking Export. The Custom Actions explorer is in the Custom Actions and
Sequences view (in Basic MSI, InstallScript MSI, MSI Database, Transform, and Web projects) and the
Custom Actions view (in Merge Module and MSM Database projects).
• InstallScript files
• Merge modules
• Project templates
• SQL scripts
• System searches
Repositories provide you with the ability to reuse project elements in multiple projects and ensure
consistency. They also save you from having to duplicate work. For example, if many of the installations
for your organization’s products include a particular custom dialog, you can create that custom dialog
once and then publish it to your repository. Any time you want to use that dialog in another installation,
simply add the dialog from your repository to your project.
Two types of repositories are available in InstallShield:
• Local repository—A local repository is your own collection of installation elements that you want to
be able to reuse in multiple projects. A local repository is stored on your local machine, and it is not
available to other installation authors.
• Network repository—A network repository is a collection of installation elements that multiple
installation authors can access and reuse in their projects as needed. A network repository fosters
collaboration among installation authors; it is stored on a network. For information on configuring a
network repository, see Setting up a Network Repository.
Edition: Network repositories are available in the Premier edition of InstallShield only. Local repositories are available in
both the Premier and Professional editions of InstallShield.
Edition: Network repositories are available in the Premier edition of InstallShield only.
To configure a network repository, or to change the network repository settings, use the Repository tab
on the Options dialog box.
Project Templates
A project template (.ist file) contains all of the default settings and design elements that you want to use
as a starting point when you create an installation project or merge module project.
You can open a template in InstallShield and edit it as you would a project. To create a template, save
any project as an .ist file. For more information, see Creating Project Templates.
For instructions on starting a new project based on a template, see Basing New Projects on Templates.
InstallShield project templates serve only as a starting point for new projects. After you have created a
project based on a template, there is no link between the current project and the existing template. If you
change an element in the template, it does not affect the project that you created based on that template.
However, you can modify the template and create another project based on the updated version of the
template.
1. Edit the project to include the desired default properties, dialogs, features, and components.
2. In the General Information view, expand the General Information explorer, and then click
Project Properties.
3. For the Comments property, type a description of your template. The comments will be displayed
for this template in the New Project dialog box.
4. On the File menu, click Save As. The Save As dialog box opens.
5. In the Save As type box, select InstallShield Template (*.ist).
6. Type a file name (with the .ist extension) and select a location for the new template. The
recommended location for templates is a Templates folder within the project location folder.
7. Click OK.
You can open the template in InstallShield and make additional changes. You can use the final version of
your template to create a new project.
1. On the File menu, click New. The New Project dialog box opens.
2. Click the All Types tab.
3. Select the template that you want to use.
Note: To display templates that are stored in a repository, right-click in the box of project types and ensure that
Show Templates in Repository is enabled. To add a template to the tab, right-click in the box of project types and
then click Add New Template. Then browse to the desired template file (.ist file).
1. On the File menu, click New. The New Project dialog box opens.
2. Click the All Types tab.
3. Right-click the template that you want to publish and then click Publish Template to
Repository. The Publish Wizard opens.
4. Complete the panels in the Publish Wizard.
After you have created a project that is based on a template in your repository, there is no link between
the current project and the existing repository template. If you make a change to the template and then
republish it to the repository, it does not affect the project that you created based on the template.
However, you can create a new project based on the updated version of the template in the repository.
Sample Projects
A number of example project (.ism) files have been included with the InstallShield installation. These
projects are stored in the Samples and SamplesPro folders in the following location by default:
C:\Program Files\Macrovision\IS2008.
These projects show you how a certain aspect of an installation project—such as release flags—can be
implemented.
Project Assistant
Project: The Project Assistant does not appear in the following project types:
• InstallScript Object
• Merge Module
• MSM Database
• QuickPatch
• Smart Device
InstallShield provides a Project Assistant to help you quickly and easily build a basic installation project.
The Project Assistant provides a framework of installation project tasks to guide you through the project
creation process and provides pertinent information along the way.
Note: To learn how to use the Project Assistant to create an InstallScript or Basic MSI installation project, go through the
appropriate project tutorial. The tutorials take you step-by-step through the Project Assistant to create a basic installation
project.
Using the More Options, Other Places, and Help Links Sections in the Project
Assistant
The left column on each Project Assistant page contains one or more lists of links to help you in creating
your installation and finding information:
• More Options—Provides additional configuration options relating to the specific area on the Project
Assistant page. These are less common options that complete the functionality of the Project
Assistant.
• Other Places—The view in the Installation Designer that corresponds to the current Project Assistant
page. Clicking the link launches the full Installation Designer and activates that view.
• Help Links—This list provides links to help topics pertinent to the current Project Assistant page.
Task To navigate from one page of the Project Assistant to another, do one of the following:
• To navigate directly to a specific page, click the appropriate icon in the navigation bar at the bottom
of the page.
• To follow the Project Assistant steps sequentially, do one of the following:
• Press CTRL+TAB to move to the next page and CTRL+SHIFT+TAB to move to the previous
page.
• To move back to the Home page and view the installation design diagram, click the Home button on
the navigation bar.
Note: The Installation Designer and the Project Assistant run simultaneously. Any changes that you make in one are
reflected instantly in the other.
If you prefer to create your InstallShield project entirely from within the Installation Designer, you can
hide the Project Assistant so that its tab is not displayed in the InstallShield interface. Similarly, if the
Project Assistant is hidden, you can choose to display it.
When the Project Assistant command has a check mark next to it, the tab for the Project Assistant is
shown in the InstallShield interface. When the check mark is not displayed, the Project Assistant is
hidden.
If the Project Assistant command does not have a check mark, the Installation Designer becomes the
default tab whenever you create a new project.
Project: The ability to specify operating system requirements in the Project Assistant is available in the following project
types:
• Basic MSI
• InstallScript MSI
• Web
When you specify operating system requirements on the Installation Requirements page of the Project
Assistant, InstallShield creates launch conditions. These conditions are added to the LaunchCondition
table of your .msi file; you can view and edit this table in the Direct Editor.
Note: Features can contain subfeatures, subsubfeatures, and so forth, to as many levels as your installation program
requires.
Default Features
The default feature concept exists only in the Project Assistant. All resources (for example, files or
registry data) that are added to an installation project need to be associated with a feature. If a resource
is not associated with a feature, it is not installed to the target system at run time.
Using a default feature simplifies the authoring experience in the Project Assistant. You do not need to
worry about associating project resources with a feature to ensure that they are installed. When you add
registry data, create new shortcuts, or add files when All Application Data is selected, all of these
resources are added to the default feature. This ensures that all of the project resources you add in the
Project Assistant will be installed to the target system when an end user runs your installation.
7. Click Yes if you want to have those dependencies automatically added to your installation project.
Tip: To hide predefined folders, deselect them in the list of predefined folders.
Project: This page does not appear for Basic MSI projects. When you add files to a Basic MSI project in the Application
Files page, the Project Assistant handles adding any required redistributables.
The Application Redistributables page lets you specify any third-party technologies that your application
requires, for example, MDAC, MFC, or DirectX. You can use the option buttons to specify any such
requirements.
If your application requirements are not addressed by the displayed questions and option buttons, you
can click the Objects link to switch from the Project Assistant to the Installation Designer and see a
complete list of available objects and merge modules that encapsulate third-party technologies.
Object Contents
You might need to see the contents of an object to determine whether you need to add the object to your
installation project.
Creating Objects
InstallShield provides you with the capability to create your own InstallShield objects. You can use these
objects in your own installation projects or distribute them to other developers.
File Extensions
Filename-extension associations, or file associations, are registry settings that tell Windows what
application to use to open files of a certain type. For example, Windows typically opens text files (files
with the .txt extension) with Windows Notepad, and opens bitmap files (files with the .bmp extension)
with Microsoft Paint.
A file extension allows someone to identify the type of file without accessing the file. A suffix (.abc) is
appended to the file name. The file extension is also useful in that another application can recognize
whether the application can work with the file (for example, open the file or modify it), based on the
extension.
In InstallShield, you can register your own file extensions in the File Types view. Registering your file
extension instructs the target machine’s operating system to use your application to open files with your
file extension when an end user clicks on a file.
3. Select the shortcut location (Start Menu and/or Desktop) and browse to an alternate icon, if
necessary.
Task To associate registry data with a feature other than the default feature (Basic MSI projects only):
Task To use INSTALLDIR as a variable in the registry (Windows Installer-based projects only):
7. Double-click the My Installation Location key. The Edit Data dialog box opens.
8. In the Value Data field, type [INSTALLDIR].
At run time, the value of [INSTALLDIR] is replaced with the installation directory.
Application Paths
The application path registry key contains data that Windows uses as a private search path for the
specified application’s .dll files. If you install an application’s .dll files into a directory not found in the
PATH environment variable (and not into the application’s directory), you should set the appropriate
application path to include the .dll file directory during installation. Application path information is
stored in the registry under HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\App
Paths\AppName.exe.
1. Do you want to display a License Agreement Dialog?—Select Yes to browse to your license agreement
file.
2. Do you want to prompt users to enter their company name and user name?—Select Yes to display a
dialog requesting this information.
3. Do you want your users to be prompted to modify the installation location of your application?—Select
Yes to present a dialog that allows end users to change the installation location. See Allowing End
Users to Modify the Installation Location for more information.
4. Do you want users to be able to selectively install only certain parts of your application?—Select Yes to
allow end users to select which parts of the application they want to install. See Creating Selectively
Installable Installations for more information.
5. Do you want to give users the option to launch your application when the installation completes?—Select
Yes and browse to your application file. When this option is set to Yes, the final dialog in the
installation presents a check box that allows end users to immediately launch your application upon
clicking the Finish button.
Tip: To add a custom graphic to your installation dialogs, click the link in the More Options section of this page to launch
the Dialog Images dialog box.
License Agreements
In order to install your application, end users must agree to abide by certain legal requirements. For
example, most software vendors will not allow users to copy or distribute their software to others.
To ensure that the end user understands the legal requirements associated with installing your software,
your installation can present an End User License Agreement (EULA) in the License Agreement dialog
during run time. The EULA is a legal contract between you and the end user, with regard to the use of
your software.
The License Agreement dialog displays your license agreement text and contains a radio button group
(Yes or No). If the end user does not agree to accept the EULA, your software is not installed and the
installation terminates.
Task To add a License Agreement dialog to your project in the Project Assistant:
Project: Multilingual language support is available in the Premier edition of InstallShield. For more information, visit the
Macrovision Web site.
Note: You can specify the set of string data that you want to edit in the drop-down menu at the top of the page.
Task To export all of the string data in your project for translation:
Task After the strings in your text file are translated, you can import the strings back into your project:
The majority of the string data in an InstallShield project is used at run time when an end user runs the
installation. However, some of the string data is installed to the target system. For example, a localized
shortcut is localized string data that is installed to the end user’s system.
Note: The Single MSI Package option should be selected for machines that already have Windows Installer
installed them since no attempt will be made to check and install the engine if it is not there.
3. If you want InstallShield to automatically copy your installation to another location after the build
finishes, click the Optional distribution settings link for each build option and specify the
location.
If you want InstallShield to distribute your installation after the build finishes, click the Optional
distribution settings link for each build option and select the Distribute After Build check
box.
4. To digitally sign your Setup.exe file to assure your end users that the code within your application
has not been modified or corrupted, click the Digitally Sign Setup hyperlink. The Digitally
Sign Setup dialog box opens. Configure the settings as needed.
5. Click Build Installations.
The Output window opens, and the Build tab displays information about the progress of the build. The
build is finished when the Build tab displays the log file information.
Tip: The Signing tab in the Installation Designer lets you specify which portions of your installation should be digitally
signed at build time. InstallShield enables you to sign any and all of the following files in a release, depending on what type
of project you are using:
• Windows Installer package (.msi file) for Basic MSI, InstallScript MSI, Merge Module and Web projects
• Setup.exe file for Basic MSI, InstallScript MSI, and Web projects
• Media header file for InstallScript projects
• Package (self-extracting single-executable file) for InstallScript projects
Windows Logo Guideline: All executable files (including .exe, .dll, .ocx, .sys, .cpl, .drv, and .scr files) in an installation must
be digitally signed for the Certified for Windows Vista program.
ClickOnce Assistant
Project: The ClickOnce Assistant applies to the ClickOnce Deployment project type.
The ClickOnce Assistant makes creating and building a ClickOnce installation project quick and easy.
The ClickOnce Assistant provides a framework of installation project tasks to guide you through the
project creation process and provides pertinent information along the way.
The ClickOnce Assistant framework includes these components:
• Application Information Page
Task To navigate from one page of the ClickOnce Assistant to another, do one of the following:
• To navigate directly to a specific page, click the appropriate icon in the navigation bar at the bottom
of the page.
• To follow the ClickOnce Assistant steps sequentially, do one of the following:
• Press CTRL+TAB to move to the next page and CTRL+SHIFT+TAB to move to the previous
page.
Important: ClickOnce applications require the .NET Framework, so this is selected by default. It is strongly recommended
that you include the .NET Framework with your ClickOnce application.
1. In the tree control (with top node Destination Computer), select the folder node to which you want
to add the file.
2. Click Add Files. An Open dialog is displayed.
Tip: Once the .NET Framework is installed, the More Options section includes the option to automatically compute the
privileges your primary application assembly requires. This automated detection has limitations, so you should test the
detected settings for completeness.
Note: This page is only configurable if you chose to design a shell presence for the application on the Shell Integration
Page.
The Automatic Updates page provides a way to have your application automatically check for updates
when it is installed on a local machine. You can also make these updates required and specify an Internet
location for the application to look for updates.
Note: If you want InstallShield to distribute your installation after the build finishes, right-click the deployment type and
select Distribution options. Select the Distribute After Build check box and specify either a network or FTP location.
The Build tab on the output window displays information about the progress of the build. The build is
finished when the Build tab displays the log file information. To open the release folder containing the
installation files, right-click the deployment type and select Open Release Folder.
1. Click the Installation Designer tab at the top of the InstallShield interface.
2. Do one of the following to display the View List:
• On the View menu, click View List. The View List appears on the left side of the InstallShield
interface.
• Click the toolbar’s View List button.
1. Click the Installation Designer tab. The View List is displayed along the left side of the IDE. If
the View List is not displayed, see Displaying the View List.
2. In the View List, select the view you want to open. To see all available views, expand the View List
folders.
1. Right-click a toolbar and select the toolbar that you want to be displayed or hidden.
2. On the Tools menu, click Customize. The Customize dialog box opens. Select the check box for
each toolbar that you want to be displayed. Clear the check box for each toolbar that you want to be
hidden.
• On the Tools menu, click Customize. The Customize dialog box opens.
• Select or clear the Show tooltips check box depending on whether or not you want to display
tooltips.
Tip: To create your own custom toolbar, drag the button or menu to the empty gray area near the toolbars.
Tip: To create a custom toolbar, drag the button or menu from the Buttons box to an empty gray area near the existing
toolbars.
1. On the Tools menu, click Customize. The Customize dialog box opens.
2. Click New. The New Toolbar dialog box opens.
3. Type a descriptive name for the toolbar in the Toolbar name text box, and click OK.
4. Customize the new toolbar by adding menus or buttons.
Tip: Another way to create a custom toolbar is to drag a button or menu from the Buttons box to the empty gray area
near the existing toolbars. The new toolbar is listed in the Toolbars tab and given a default name. To change the name,
modify the text in the Toolbar name text box.
• Platforms Tab
COM Extraction
When you use InstallShield to extract COM information from a COM server, InstallShield puts the data
in the Registry table, instead of in the TypeLib table. Microsoft strongly advises against using the
TypeLib table, as described in the TypeLib Table topic on the MSDN Web site.
Unused Directories Automatically Removed from .msi File at Build Time by Default
Note that if you upgrade a Basic MSI, InstallScript MSI, or Merge Module project that was created in
InstallShield 12 or earlier to InstallShield 2008, the new Keep Unused Directories setting on the Build
tab in the Releases view is set to No. Therefore, if a directory that is listed in the Directory column of the
Directory table is not referenced in any known location in the .msi file, InstallShield removes it from the
Directory table of the .msi file that it creates at build time. For Basic MSI and InstallScript MSI projects,
this occurs after any merge modules are merged, but only directories that are present in the .msi file are
removed; therefore, if a merge module contains new unused directories in its Directory table, the new
unused directories are added to the installation.
Windows Server 2003 Conditions and 64-Bit Windows XP Conditions for Setup
Prerequisites
The operating system version number is 5.2 for both Windows Server 2003 and 64-bit Windows XP. As
a result, prerequisites that were created in InstallShield 12 and that required Windows Server 2003
could be installed on 64-bit Windows XP systems, and those that required Windows XP could not be
installed on 64-bit Windows XP systems.
To resolve this issue, the Setup Prerequisite Editor in InstallShield 2008 has been enhanced to enable
you to specify whether the target system is required to be a workstation, a server, or a domain controller.
To resolve this issue for an existing prerequisite that includes a Windows Server 2003 requirement or a
64-bit Windows XP requirement, open the prerequisite in the Setup Prerequisite Editor in InstallShield
2008. On the Conditions tab, select the condition that needs to be corrected and click Modify. In the
Select the operating system on which to run the setup requirement box, select the
appropriate operating system requirement. Doing this correctly sets the new Product (OS) Type setting
to the appropriate workstation, server, or domain controller value.
Automation Interface
If you use the automation interface with InstallShield or the Standalone Build, update your existing code
to reflect the new ProgIDs: IswiAuto14.ISWiProject or SAAuto14.ISWiProject.
The Display Save Options dialog setting was removed from the Releases view. Therefore, the
WebSaveOptionsDlg property, which corresponds with that setting, is no longer available for the
ISWiRelease object of automation interface.
DemoShield Support
DemoShield is no longer being sold by Macrovision or any authorized resellers and distributors. In
addition, it is no longer supported. Therefore, InstallShield no longer includes any DemoShield
integration.
• Validating Projects
To learn about the validators that are now available as InstallShield Best Practices, see:
• ISBP17 (which was previously known as ISICE13)
Each InstallScript custom action is handled by Each InstallScript custom action is handled by
ISScriptBridge.dll (a C++ MSI DLL), which forwards ISSetup.dll (a single C++ MSI DLL), which contains the
actual script execution to the ongoing IDriver.exe full InstallScript engine.
process.
A set of engine files is required. They must be installed by No engine files or ISScript.msi file is required.
ISScript.msi before the primary installation begins. ISSetup.dll is self-contained.
All InstallScript custom actions execute in a shared Each InstallScript custom action is independent and has its
IDriver.exe process. The IDriver.exe process own self-contained lifecycle. From the custom action entry
remains resident until a final shutdown custom action is point, ISSetup.dll starts the script engine, executes the
required. relevant script, and shuts down the engine.
• In-memory objects must be serialized in order to be shared between custom action invocations.
With the earlier model, InstallScript developers could store complex object-based data in global
variables. As with the aforementioned disadvantage, this may actually result in better InstallScript
code.
1. Before you convert your project, create a backup version of your project file and any InstallScript
files.
2. Open InstallShield 2008.
3. On the File menu, click Open. The Open dialog box opens.
4. Browse to select the project file (.ism) of the InstallShield 11.5 or earlier project that you want to
upgrade. A dialog box opens, prompting you to specify whether you want to upgrade the project.
5. Click Yes.
InstallShield upgrades your project and saves a backup copy of the project file (.ism).
To learn about possible manual changes that you may need to make to upgraded projects, see the
following:
• Upgrading InstallShield 11.5 or Earlier Basic MSI Projects that Have InstallScript Custom Actions
• Upgrading InstallShield 11.5 or Earlier QuickPatch Projects that Have InstallScript Custom Actions
• Creating Standard Patches for InstallShield 11.5 and Earlier InstallScript MSI Projects
• Upgrading InstallShield 11.5 or Earlier InstallScript MSI Object Projects or Projects that Contain
This Type of Object
(or, for example, an immediate InstallScript custom action with the MsiSetProperty function) to set a
property that matches the name of the custom action. The value of this property is then available in the
CustomActionData property within the deferred custom action.
For example, if you want to access a property such as SUPPORTDIR, you could create an immediate
custom action that is called MyCustomActionName and that sets the MyCustomActionName property to
[SUPPORTDIR], and then substitute "SUPPORTDIR" with "CutomActionData" in the MsiGetProperty
call:
MsiGetProperty(hMSI, "CustomActionData", szSupportDir, nLen)
• OnMoving
• OnMoved
• OnEnd
InstallShield no longer supports these event handler functions for Basic MSI projects that have
InstallScript custom actions. They are not called once the project is rebuilt with InstallShield 12 and
later. Note that these event handler functions still compile in InstallShield 12 and later; they are just not
called.
If you use these event handler functions in your project, you need to manually schedule custom actions
that call these functions. To learn how, see Creating and Scheduling InstallScript Custom Actions that
Call InstallScript Event Handlers for Basic MSI Projects.
To resolve this build error, remove this merge module from your project; you can do so by clearing its
check box in the Redistributables view.
For InstallShield 11.5 and earlier Basic MSI projects with InstallScript custom actions, several files were
stored in the Binary table:
• Setup.inx
• Isconfig.ini
• Isrt.dll
• ISScriptBridge.dll
• _isresXXXX.dll (where XXXX is the language—one .dll was included for each language included in
the installation)
• StringxXXXX.txt (where XXX is the language—one .txt was included for each language in the
installation)
For InstallShield 12 and later, all of these files (except ISScriptBridge.dll, which is no longer used) are
stored inside the ISSetup.dll file, and that is the only file that is stored in the Binary table.
The InstallScript engine file changes have not been known to cause any upgrade issues. These changes
are reported for informational purposes.
Creating and Scheduling InstallScript Custom Actions that Call InstallScript Event Handlers
for Basic MSI Projects
For InstallShield 12 and later, the predefined InstallScript event handler functions are no longer
available in Basic MSI projects with InstallScript custom actions. In InstallShield 11.5 and earlier, the
following InstallScript event handler functions were available for Basic MSI projects and InstallScript
MSI object projects:
• OnBegin
• OnMoving
• OnMoved
• OnEnd
InstallShield no longer supports these event handler functions for Basic MSI projects that have
InstallScript custom actions. They are not called once the project is rebuilt with InstallShield 2008. Note
that these event handler functions still compile in InstallShield 2008; they are just not called.
Similarly, these same predefined InstallScript event handler functions are not supported in InstallScript
MSI object projects that are converted to merge module projects automatically when they are opened in
InstallShield 2008. The functions are not called once the converted merge module project is built in
InstallShield 2008.
If you have these events in your Basic MSI or InstallScript MSI object project and you upgrade your
project to InstallShield 2008, you need to manually schedule custom actions that call the event handler
functions. The following instructions explain how to do so.
Task To manually schedule InstallScript custom actions that call the predefined InstallScript event handler
functions:
3. Add InstallScript custom actions that call your renamed InstallScript event handler functions:
a. In the View List under Behavior and Logic, click Custom Actions and Sequences (in
Basic MSI projects) or Custom Actions (in merge module projects).
b. In the center pane, right-click the Custom Actions explorer and then click New
InstallScript. InstallShield adds an InstallScript custom action.
c. Type a name for the custom action; use the same name that you used to rename the InstallScript
functions. For example:
• MyOnBegin
• MyOnMoving
• MyOnMoved
• MyOnEnd
d. Select the new InstallScript custom action that you created.
e. Set the Function Name setting to the name of the InstallScript function.
f. For the In-Script Execution setting, specify the value that is indicated in the table below.
4. Schedule the InstallScript custom action for the appropriate part of the installation:
a. In the View List under Behavior and Logic, click Custom Actions and Sequences.
b. Right-click the action or dialog that you want your InstallScript custom action to follow and
click Insert. The Insert Action dialog box opens, providing a list of all the actions and dialogs
that are currently associated with your project.
c. Select the InstallScript custom action that you created. If appropriate, enter a condition in the
Condition box for launching the InstallScript event.
d. Click OK.
To match the previous functionality as closely as possible, set the in-script execution in step 3f and
schedule the InstallScript custom actions in step 4b as follows:
MyOnBegin Immediate (default) In the Installation User Interface sequence just after the
SetupCompleteSuccess dialog. (In previous releases,
OnBegin was called as a result of the
ISMsiServerStartup custom action being called.)
MyOnMoving Deferred in system In the Installation User Interface sequence just after the
context SetupCompleteSuccess dialog. (In previous releases,
OnBegin was called as a result of the
ISMsiServerStartup custom action being called.)
MyOnEnd Deferred in system The last event in the Installation Execute sequence after
context the InstallFinalize action. (In previous releases, OnEnd
was called after all other events as a result of the
installation completing.)
• Global variables and pointers are no longer maintained between individual InstallScript custom
action calls. In addition, each InstallScript custom action initializes and uses its own individual
SUPPORTDIR. Therefore, you cannot share information across individual calls using files in
SUPPORTDIR. For more information, see Global Variables, Global Pointers, and SUPPORTDIR.
• Most Windows Installer properties are not available to deferred, commit, and rollback InstallScript
custom actions. For more information, see Windows Installer Properties and Deferred, Commit, and
Rollback InstallScript Custom Actions.
Another implication of this change is that each custom action initializes and uses its own individual
SUPPORTDIR. Therefore, you cannot share information across individual calls using files in
SUPPORTDIR, since each custom action invocation will have its own unique SUPPORTDIR. You can
share information using FOLDER_TEMP or some other file location.
Note that FOLDER_TEMP may not be the same path for all of your InstallScript custom actions. If you
have some InstallScript custom actions that run in system context and some that do not, they will have
different temp paths if the package is running in an elevated state. The InstallScript custom actions run
in the context of a different user, so storing files in the temp directory and retrieving it later may not
work in certain scenarios.
In InstallShield 12 and later, the following file is placed on the Disk1 image of the built installation:
ISSetup.dll
The Disk1 file changes have not been known to cause any upgrade issues. These changes are reported for
informational purposes.
For InstallShield 11.5 and earlier InstallScript MSI projects, several files were stored in the Binary
table:
• Setup.inx
• Isconfig.ini
• Isrt.dll
• ISScriptBridge.dll
• _isresXXXX.dll (where XXXX is the language—one .dll was included for each language included in
the installation)
• StringxXXXX.txt (where XXX is the language—one .txt was included for each language in the
installation)
For InstallShield 12 and later, all of these files (except ISScriptBridge.dll, which is no longer used) are
stored inside the ISSetup.dll file, and that is the only file that is stored in the Binary table.
The InstallScript engine file changes have not been known to cause any upgrade issues. These changes
are reported for informational purposes.
Creating and Scheduling InstallScript Custom Actions that Call InstallScript Event Handlers
for InstallScript MSI Projects
Several built-in InstallScript-related custom actions were eliminated in InstallShield 12 for InstallScript
MSI projects. If you upgrade an InstallScript MSI project from InstallShield 11.5 or earlier to
InstallShield 2008, InstallShield removes these built-in custom actions from your project. Because these
custom actions have been removed, some existing InstallScript events that were previously called by the
custom actions are now called directly from InstallScript. This article identifies the eliminated custom
actions and explains how add custom actions that call these InstallScript events so that the scheduling is
similar to the scheduling used in InstallShield 11.5 and earlier.
The eliminated custom actions also may affect your InstallScript MSI installation if you allow the
installation to run without the Setup.exe file so that the packages can be deployed through technologies
such as Active Directory. The procedure for implementing this is described in Knowledge Base article
Q108166 - HOWTO: Deploying an MSI Wrapped with an InstallShield Script-Based Setup.exe. Note that
if you follow the procedure that is described in that article and end users launch the .msi file directly,
some of the InstallScript events are never called. The reason that they are not called is that some of the
InstallScript event handler functions that were previously called by built-in InstallScript-related custom
actions are not called, since the InstallScript-related custom actions have been removed. If you configure
your installation according to the Q108166 article, you may also need to follow the instructions below to
add custom actions that call the built-in InstallScript events.
The following built-in InstallScript-related custom actions were eliminated in InstallShield 12. They are
removed from InstallScript MSI projects when they are upgraded from InstallShield 11.5 or earlier to
InstallShield 2008:
• ISCleanupSuccess
• ISCleanUpSuspend
• ISCleanUpUserTerminate
• ISCleaupFatalExit
• ISMsiServerStartup
• ISRebootPatchHandler
• ISRollbackCleanup
• ISStartup
• OnCheckSilentInstall (For details about changes for this custom action, see OnCheckSilentInstall.)
• OnFeaturesInstalled
• OnFeaturesInstalling
• OnInstallFilesActionAfter
• OnInstallFilesActionBefore
• OnMoved
• OnMoving
Because these custom actions have been removed, some existing InstallScript event handlers that were
previously called by the custom actions are now called directly from InstallScript. This includes the
following InstallScript event handlers that are called immediately before file transfer:
• Feature functions for Installing and Uninstalling
• OnGeneratedMSIScript
• OnGeneratingMSIScript
• OnInstallFilesActionBefore
• OnMoving
It also includes the following InstallScript event handlers that are called immediately after file transfer:
• Feature functions for Installed and Uninstalled
• OnMoved
• OnInstallFilesActionAfter
These changes were made to ensure that global variables and global pointers are still available for these
InstallScript event handler functions. However, because previously the events were called from custom
actions, the sequence of these events in relation to other custom actions that are called directly by
Windows Installer has changed. Therefore, you may need to adjust your InstallScript code appropriately
to account for these changes.
Except in the case of the feature event handlers, it is also possible to add custom actions that call these
event handler functions so that the scheduling is similar to the scheduling used in InstallShield 11.5 and
earlier. However, global variables and global pointers are not maintained between calls, as discussed in
the Global Variables, Global Pointers, and SUPPORTDIR section.
Calling OnFeatureInstalling, OnFeatureUninstalling, OnFeatureInstalled, or OnFeatureUinstalled from
a custom action during file transfer does not have any effect on the installation. This is because these
functions are called from InstallScript just before file transfer, and they do not have any effect when they
are called more than once.
Task To manually schedule an InstallScript custom action that calls a predefined InstallScript event handler
function:
3. Add an InstallScript custom action that calls your renamed InstallScript event handler function:
a. In the View List under Behavior and Logic, click Custom Actions and Sequences.
b. In the center pane, right-click the Custom Actions explorer and then click New
InstallScript. InstallShield adds an InstallScript custom action.
c. Type a name for the custom action; use the same name that you used to rename the InstallScript
function. For example:
• MyOnGeneratingMSIScript
• MyOnMoving
• MyOnMoved
d. Select the new InstallScript custom action that you created.
e. Set the Function Name setting to the name of the InstallScript function.
f. For the In-Script Execution setting, specify the value that is indicated in the table below.
4. Schedule the InstallScript custom action for the appropriate part of the installation:
a. In the View List under Behavior and Logic, click Custom Actions and Sequences.
b. Right-click the action or dialog that you want your InstallScript custom action to follow and
click Insert. The Insert Action dialog box opens, providing a list of all the actions and dialogs
that are currently associated with your project.
c. Select the InstallScript custom action that you created. If appropriate, enter a condition in the
Condition box for launching the InstallScript event.
d. Click OK.
To match the previous functionality as closely as possible, set the in-script execution in step 3f and
schedule the InstallScript custom actions in step 4b as follows:
In-Script
Custom Action Execution Location in the Sequence
OnMoving Deferred in In the Installation Execute sequence between the InstallInitialize and
system context AllocateRegistrySpace actions
OnFeaturesInstalling, Deferred in In the Installation Execute sequence between the InstallInitialize and
which calls all the feature system context AllocateRegistrySpace actions (after OnMoving)
Installing and Uninstalling
events that are defined.
Note: This will not have any
effect, as explained above.
OnInstallFilesActionBefore Deferred in In the Installation Execute sequence between the MoveFiles and
system context InstallFiles actions
OnFeaturesInstalled, which Deferred in In the Installation Execute sequence between the ScheduleReboot
calls all the feature system context and InstallFinalize actions (before OnMoved)
Installed and Uninstalled
events that are defined.
Note: This will not have any
effect, as explained above.
OnInstallFilesActionAfter Deferred in In the Installation Execute sequence between the InstallFiles and
system context PatchFiles actions
In-Script
Custom Action Execution Location in the Sequence
OnCheckSilentInstall
In InstallShield 11.5 and earlier, the OnCheckSilentInstall custom action automatically called the
OnMsiSilentInstall InstallScript event if the InstallScript MSI installation was being installed silently
without using Setup.exe (for example, if the following command-line was used: Msi.exe /i<Package> /
qn). In InstallShield 12 and later, this event is not called in InstallScript MSI installations. However, you
can add a custom action that calls the OnMsiSilentInstall event handler function. To do so, use the
aforementioned instructions, noting the following scheduling requirements in steps 3f and 4b:
In-Script
Custom Action Execution Location in the Sequence
Also, to ensure that the InstallScript event runs only in the expected scenario, add the following code to
the event:
cchValueBuf = MAX_PATH;
// Check whether Setup.exe is being used, if so just return.
MsiGetProperty(nHandle, "ISSETUPDRIVEN", szValueBuf, cchValueBuf);
if(StrLengthChars(szValueBuf)) then
return ISERR_SUCCESS;
endif;
Setup.exe Changes
The /deleter command-line parameter for Setup.exe is no longer needed. If you specify this parameter,
the installation will not run. Note that InstallScript installations no longer clone the installation
immediately when they are launched (unless, for example, the installation is running from the temp
folder because the /runfromtemp parameter is specified), so /deleter is no longer needed.
The /clone_nowait command-line parameter for Setup.exe is no longer needed. If you specify this
parameter, Setup.exe ignores it. Note that InstallScript installations no longer wait for the cloned
installation to complete by default unless the /clone_wait parameter is specified. For more information
on /clone_wait, see Setup.exe and Update.exe Command-Line Parameters.
Like InstallScript MSI and Basic MSI installations, InstallScript’s Setup.exe file returns meaningful
return codes. Therefore, if you are checking the return value of Setup.exe, in InstallShield 11.5 and
earlier, it would always be 0; in InstallShield 12 and later, Setup.exe returns an appropriate return value.
For details on the possible return codes, see Setup.exe Return Values and Run-Time Errors
(InstallScript Projects).
• Setup.ibt
In InstallShield 12 and later, the following files are placed on the Disk1 image of the built installation:
• ISSetup.dll
• _Setup.dll
The Disk1 file changes have not been known to cause any upgrade issues. These changes are reported for
informational purposes.
This change has not been known to cause any upgrade issues. This change is reported for informational
purposes.
Creating Standard Patches for InstallShield 11.5 and Earlier InstallScript MSI
Projects
InstallShield 12 and later does not support the creation of InstallScript MSI patches (using the Patch
Design view) where both the latest and previous setups were created with InstallShield 11.5 or earlier.
Creating a patch where the latest setup is created with InstallShield 12 or later and the previous setup
was created with InstallShield 11.5 or earlier has not been known to cause any issues.
where “InstallShieldMSIObjectName.4F635B62_07BF_4779_B74E_D80C29D508E3:0” is
information that is specific to the missing InstallScript MSI object. To resolve this build error, remove
this InstallScript MSI object from your project; you can do so by clearing its check box in the
Redistributables view.
Open the project in InstallShield. A dialog box opens to ask if you would like to upgrade your project.
• Billboard properties from Express projects will not be migrated since they are not supported in Basic MSI projects.
You will receive warning 701 when the billboards property is specified in earlier Express projects.
• If you migrate an Express project with a language that is not installed with your current version of InstallShield, you will
lose support for that language. Language support is available in the Premier edition of InstallShield. For more
information, visit the Macrovision Web site.
1. Open InstallShield.
2. On the File menu, click Open. The Open dialog box opens.
3. Select the InstallShield Professional project file (.ipr) that you would like to open.
4. Click Open.
Your project opens in InstallShield, and the extension changes from .ipr to .ism. A backup of your
original .ipr project is saved as ProjectName.ipr.bak in the same folder.
Note: In InstallShield 2008, support files are linked to a subfolder of the project folder; in InstallShield Professional,
support files were physically copied to a subfolder of the project folder.
Table 3-11: String Table Entries and Corresponding New System Variables
PRODUCT_NAME IFX_PRODUCT_NAME
Table 3-11: String Table Entries and Corresponding New System Variables (cont.)
PRODUCT_KEY IFX_PRODUCT_KEY
PRODUCT_VERSION IFX_PRODUCT_VERSION
TITLE_CAPTIONBAR IFX_SETUP_TITLE
FOLDER_NAME IFX_PRODUCT_NAME
TITLE_MAIN IFX_SETUP_TITLE
Note that you can remove only a subset of these string table values if you want some values to be
read from the string table and some to be read from the project settings. If you retain any of these
string table values, be sure to modify them as required, rather than changing the unused project
settings; in particular, when creating an update installation, be sure to update the value of the
PRODUCT_VERSION string table entry if it exists.
Click the following link for information on the initialization of these system variables.
• If your installation uses an event based script and you have overridden the default OnFirstUIBefore
event handler code, then to install files to the appropriate default location you must replace the
following code (from the 6.x version of OnFirstUIBefore):
TARGETDIR = PROGRAMFILES ^ @COMPANY_NAME ^ @PRODUCT_NAME;
with the following code (from the new default OnFirstUIBefore code) to set TARGETDIR:
/* Handles both end users with administrative or power user privileges and
end users without such privileges. */
if ( ALLUSERS ) then
TARGETDIR = PROGRAMFILES ^ IFX_COMPANY_NAME ^ IFX_PRODUCT_NAME;
else
TARGETDIR = FOLDER_APPDATA ^ IFX_COMPANY_NAME ^ IFX_PRODUCT_NAME;
endif;
If you are using a procedural script (one with a program…endprogram block), you need to update
the code in which you set TARGETDIR in order to set the default target directory appropriately for
users without administrator privileges.
• If your installation uses an event-based script and you have overridden the default
OnMaintUIBefore event handler code, and during uninstallation you want to remove all features
including those that are not listed in the media but only in the log file (see
FeatureRemoveAllInMediaAndLog for more information), then you must replace the following code
(from the 6.x version of OnMaintUIBefore):
with the following code (from the new default OnMaintUIBefore code):
MediaGetData( MEDIA, MEDIA_FIELD_MEDIA_FLAGS, nMediaFlags, szIgnore );
case REMOVEALL:
/* Properly handles updating. */
if( nMediaFlags & MEDIA_FLAG_UPDATEMODE_SUPPORTED ) then
FeatureRemoveAllInMediaAndLog();
else
FeatureRemoveAllInMedia();
endif;
If you are using a procedural script that supports script-based uninstallation you need to update
your call to ComponentRemoveAll appropriately.
• If your installation uses an event-based script and you have overridden the default OnFirstUIAfter
event handler code, to display the FLEXnet Connect–enabled InstallShield Wizard Complete dialog,
then you must replace the following code (from the 6.x version of OnFirstUIAfter):
bOpt1 = FALSE;
bOpt2 = FALSE;
szMsg1 = SdLoadString(IFX_SDFINISH_MSG1);
SdFinishEx(szTitle, szMsg1, szMsg2, szOption1, szOption2, bOpt1, bOpt2);
with the following code (from the new default OnFirstUIAfter code):
if ( BATCH_INSTALL ) then
SdFinishReboot ( szTitle , szMsg1 , SYS_BOOTMACHINE , szMsg2 , 0 );
else
// If FLEXnet Connect is enabled, show finish dialog that includes
// update check option.
if( ENABLED_ISERVICES & SERVICE_ISUPDATE ) then
if( SdFinishUpdateEx( szTitle, szMsg1, szMsg2, szOpt1, szOpt2, TRUE ) ) then
// Do not check for updates in silent mode.
if( MODE != SILENTMODE ) then
UpdateServiceCheckForUpdates( "", FALSE );
endif;
endif;
else
SdFinish ( szTitle , szMsg1 , szMsg2 , szOpt1 , szOpt2 , bvOpt1 , bvOpt2 );
endif;
endif;
• If you want your migrated installation to update the product that was installed by the 6.x version of
the installation, see the Version Number of the Already Installed Product section in Product Version
Numbers.
• If your script calls RegDBSetItem to alter the registry entries that are created by MaintenanceStart
(or DeinstallStart), and it makes those calls to RegDBSetItem in an event handler that is called
before the OnMoved handler (for example, OnMoving or <feature name>_OnInstalled), you must
move those calls to RegDBSetItem. MaintenanceStart is now called in the OnMoveData event
handler’s default code, whereas previously MaintenanceStart was called automatically immediately
after the maintenance/uninstallation feature was installed and before any other features were
installed.
• The InstallShield Professional 6.x default event handler code included the following lines in both
OnFirstUIBefore and OnMaintUIBefore:
SetStatusWindow( 0, "" );
Enable( STATUSEX );
StatusUpdate( ON, 100 );
In InstallShield 2008, this code has been relocated to the default OnMoveData event handler code,
so you have the following options:
• If you have not customized this code, you do not need to do anything because the redundant
calls will not cause a problem. You can safely remove this code from OnFirstUIBefore and
OnMaintUIBefore if you want to avoid code duplication.
• If you have customized this code and you want these customizations to apply regardless of what
user interface (UI) event is called, you should remove the code from OnFirstUIBefore and
OnMaintUIBefore, then override the OnMoveData event and place the customized code in place
of the default code.
• If you have customized the code and you want specific code depending on what UI event is
called, you should override OnMoveData, comment out the default code, and continue to use
your existing code. Note that in this case, if your installation supports updating you may also
want to customize OnUpdateUIBefore.
• The 6.x default event handler code included the following commented-out code in the
OnFirstUIBefore and OnMaintUIBefore events:
// TO DO: if you want to enable background, window title, and caption bar title
// SetTitle( @TITLE_MAIN, 24, WHITE );
// SetTitle( @TITLE_CAPTIONBAR, 0, BACKGROUNDCAPTION );
// Enable( FULLWINDOWMODE );
// Enable( BACKGROUND );
// SetColor( BACKGROUND, RGB( 0, 128, 128 ) );
If you activated this code and would like to ensure a consistent UI experience regardless of what UI
event is called, you can remove this code from OnFirstUIBefore and OnMaintUIBefore and then
override OnShowUI and customize the code appropriately.
• Many Windows API functions are declared in included header files (.h files) in InstallShield 2008. If
any of these functions are also explicitly declared in your script code, do one of the following:
• Remove your function declaration and use the declaration provided by InstallShield
Professional.
• If you are creating a script that needs to be compilable in both InstallShield 2008 and earlier
versions, surround your declaration with code like the following:
#if _ISCRIPT_VER < 0x700
prototype ...
#endif
You may also need to update code that calls a Windows API function, if the declaration defined by
InstallShield Professional is different than your declaration.
• In order that the end user interface flows smoothly, by default the installation initialization dialog
box remains displayed until the script displays a dialog box. To close the installation initialization
dialog box, call Disable(DIALOGCACHE) or any dialog box function.
• InstallShield 2008 does not support displaying Windows 95-style dialog boxes. InstallShield 2008
displays end-user dialog boxes with the Windows 2000 style, which conforms to Microsoft’s latest
guidelines for Windows user interfaces.
• An InstallShield Professional 6.x project is opened in InstallShield 2008 with its Engine File
Binding property set to Dynamic.
• The default keyboard shortcuts for the following script editor commands have been restored to the
values they had in version 5.x (in version 6.x these commands had no default keyboard shortcuts):
Replace Ctrl + H
Script Changes
The basic structure of an InstallShield Professional 5.x script is supported in the InstallScript project
type in InstallShield 2008. To compile a Professional 5.x script in InstallShield, you must first make the
following changes:
Preprocessor Directives
• Include the following statement at the beginning of your script:
#include "ifx.h"
• Remove any #define statements for SD_SINGLE_DIALOGS and its associated SD_<dialog name>
constants.
• You may need to remove some #define statements that define Windows constants if those
statements result in compiler errors. Many Windows constants are defined in Ifx.h or its included
files, such as Windefs.h (which is in the InstallShield folder’s Script\Isrt\Include subfolder).
Built-In Functions
• Remove the following functions, which were supported in Professional 5.x but are not supported in
InstallShield 2008. Some of these functions will compile, but they will not give the expected results.
Where possible, supported alternatives are suggested.
AddProgItemEx AddFolderIcon
CreateProgGroupEx AddFolderIcon
DeleteGroup DeleteProgramFolder
DeleteProgItem DeleteFolderIcon
GetGroupNameList GetFolderNameList
RegDBCreateKey RegDBCreateKeyEx
RegDBCreateKeyValue RegDBCreateKeyValueEx
RegDBGetKeyValue RegDBGetKeyValueEx
RegDBSetKeyValue RegDBSetKeyValueEx
• Call Disable(LOGGING) before any code that makes changes to the target system that you do not
want logged for uninstallation, and call Enable(LOGGING) after that code. This is necessary because
logging of changes for uninstallation is automatically enabled before any script code is executed.
Note that this is different from Professional 5.x installations in which logging did not begin until
DeInstallStart was called. If you have any installation actions that previously were not logged
because they occurred before DeInstallStart, you will need to add an additional Disable(LOGGING)
call before these installation actions to disable logging manually.
If you want your installation to display a background, you must call Enable(BACKGROUND). In
InstallShield 2008, the background is disabled by default, whereas in Professional 5.x it was enabled
by default. (In event-based scripts, code for customizing and displaying a background exists in
comment lines at the beginning of the default code for OnFirstUIBefore. To activate this code,
remove the slash characters at the beginnings of the desired lines.)
Note that some user-interface functions, such as PlaceBitmap, will not work properly (nor return a
negative value to let you know they failed) if the installation background is not enabled.
• If you pass GetSystemInfo a first argument of DRIVE and a third argument that is a UNC path, the
function correctly returns a negative value. Previously it returned zero, falsely indicating success,
although due to operating system limitations UNC paths are not supported in that case.
• When you call ParsePath with its third argument set to PATH and its second argument set to a UNC
path that includes only a server name without a trailing backslash (for example, "\\\\TheServer"),
the function correctly sets the first argument equal to a double backslash ("\\\\"). In Professional
5.x, the function would set the first argument equal to a single backslash ("\\").
• The Professional 5.x Help Library listed specific numeric return values, other than 0 (zero) for
success, for some functions. Some of these numeric values have changed for InstallShield 2008; a
script used in InstallShield 2008 should compare a function’s return value only to the constants that
are currently listed in that function’s help.
• In order for the end-user interface to flow smoothly, by default the installation initialization dialog
remains displayed until the script displays a dialog. To close the installation initialization dialog, call
Disable(DIALOGCACHE) or any dialog function.
• ComponentMoveData’s second argument no longer returns useful data.
• Passing a pointer to a string as the fourth argument of SendMessage no longer gives the expected
result. To pass string data to SendMessage, see the Additional Information section of the
SendMessage topic.
Predefined Constants
• Remove the following constants, which were supported in Professional 5.x but are not supported in
InstallShield 2008:
COMPONENT_VALUE_ALWAYSOVERWRITE
COMPONENT_VALUE_NEVEROVERWRITE
COMPONENT_VALUE_NEWERDATE
COMPONENT_VALUE_NEWERVERSION
COMPONENT_VALUE_OLDERDATE
COMPONENT_VALUE_OLDERVERSION
COMPONENT_VALUE_SAMEORNEWDATE
COMPONENT_VALUE_SAMEORNEWERVERSION
COMPONENT_FIELD_DESTINATION
COMPONENT_FIELD_OVERWRITE
• Remove statements that assign values to the following predefined variables (for example,
TARGETDISK="C:\\";). Such statements will not compile in InstallShield 2008; these constants are
now read-only.
CMDLINE
COMMONFILES
ERRORFILENAME
FOLDER_DESKTOP
FOLDER_PROGRAMS
FOLDER_STARTMENU
FOLDER_STARTUP
ISRES
ISUSER
ISVERSION
MODE
PROGRAMFILES
SUPPORTDIR
TARGETDISK (The value of this variable is automatically updated when TARGETDIR is changed.)
UNINST
WINDIR
WINDISK
WINSYSDIR
WINSYSDISK
DLLs
• When you called a DLL function in Professional 5.x, all string arguments were passed by reference;
in InstallShield 2008, you can pass a string argument by value. To specify the method for passing an
argument, in the function prototype, precede the argument’s data type with the BYREF or BYVAL
keyword; for example, MyDLL.MyFunc(BYREF NUMBER, BYVAL STRING). The InstallShield
2008 compiler includes the following compiler warnings to encourage the use of the appropriate
keyword.
• If your script includes DLL function calls where neither BYREF nor BYVAL has been specified,
you receive compiler warning W7507. To eliminate this warning, add the appropriate keyword
to the function prototype.
• If you specify a literal string for a string argument that is passed by reference, you receive
compiler warning W7511. To eliminate this warning, add the BYVAL keyword to the function
prototype.
When you call a function in an external DLL, make sure the same calling convention is used in the
script and the DLL. In Professional 5.x, the installation engine always used the stdcall convention
but would sometimes overlook an inconsistent DLL convention. The InstallShield 2008 engine does
not; it generates an error (exception 0x80040704) when the wrong calling convention is used.
In your script, you can declare a calling convention, either cdecl or stdcall, when declaring a DLL
function. For example:
prototype cdecl MyDLL.MyFunction (INT, INT);
If you do not explicitly declare a calling convention, InstallShield uses stdcall.
• In InstallShield 2008, InstallScript arrays are internally formatted as OLE Automation safe arrays,
not native C/C++ arrays. To pass an InstallScript array to a DLL function that expects a C/C++
array, you must place the array data in the expected format by calling GetCArrayFromISArray.
• In InstallShield 2008, a string variable whose address is stored in a pointer variable cannot be
changed by passing the pointer to a DLL function. To allow a DLL function to change the value of a
string variable, pass the variable itself as an argument to the function, after declaring the data type
of that argument specifying the BYREF operator.
• You no longer need to call the UseDLL function before calling a DLL that is located on Windows’
DLL search path. The DLL search path is the following:
1. The folder from which the application loaded.
2. The current folder.
3. The 32-bit Windows system folder.
4. The 16-bit Windows system folder.
5. The Windows folder.
6. The folders that are listed in the PATH environment variable.
Use this feature with caution; the values of the current folder and PATH environment variable on an
end user’s machine are not predictable.
Miscellaneous
• The undocumented array syntax ArrayName[nArrayIndex] is no longer supported. In InstallShield
2008, the syntax for all arrays is ArrayName(nArrayIndex).
• If you explicitly declare a return type for a script-defined function, you must specify the same return
type in the function definition, after the keyword "function", or the script will not compile. (If you do
not explicitly declare a return type, the return type is assumed to be NUMBER.) In previous versions
of InstallShield Professional, return types were assumed to be NUMBER regardless of explicit
specifications of other return types, so this issue did not arise.
• To place uninstall information under HKEY_CURRENT_USER, set the value of the ALLUSERS
system variable to FALSE.
• To pass a literal character as an argument to a built-in or user-defined function, you must pass its
numeric ASCII value.
• When processing the system variable CMDLINE, be aware that the following command line
switches are no longer used by Setup.exe and so are included in CMDLINE: -SMS, -z, -c, -e, -q, -t,
and -x. The -SMS switch is obsolete because now Setup.exe always stays in memory until the
installation is complete. The -z switch is obsolete because now Setup.exe initializes correctly even on
systems with more than 256 megabytes of memory.
• Remove Professional 5.x’s ODBC Template code, which will not compile in InstallShield 2008. This
is because the following function call is nested within the code:
ComponentGetData ( szMedia, szCompName,
COMPONENT_FIELD_DESTINATION, nvData, svDest );
In InstallShield 2008 this function call does not compile because the Destination property is a file
group property, not a component property.
Other Changes
• Pressing F3 no longer works to exit an installation.
• InstallShield 2008 installations do not support including special billboards for low-resolution
systems.
• If neither a source file nor the already-existing target file has a version number, and the source file’s
file group’s Overwrite property is "Newer Version", "Same or Newer Version", or "Older Version",
then the file on the target system is not overwritten. In Professional 5.x installations, the target file
would be overwritten.
• InstallShield 2008 does not support displaying Windows 95-style dialogs. InstallShield 2008
displays end-user dialogs with the Windows 2000 style, which conforms to Microsoft’s latest
guidelines for Windows user interfaces.
• The Lang key in a silent installation’s response (.iss) file’s [Application] section no longer has any
effect.
• In Professional 5.x installations, any registry key logged by the installer would be removed during
uninstallation in any case. In InstallShield 2008, keys created by RegDBCreateKeyEx and non-
shared keys in registry sets are removed only if the installer created the key, that is, the key did not
exist when the installation was run.
Function Names
Any InstallScript function name that referred to component now refers to feature. For example,
ComponentDialog is now FeatureDialog. The parameters for these functions have not changed. Click a
feature function to view the corresponding help topic.
ComponentAddItem FeatureAddItem
ComponentCompareSizeRequired FeatureCompareSizeRequired
ComponentDialog FeatureDialog
ComponentError FeatureError
ComponentErrorInfo FeatureErrorInfo
ComponentFileEnum FeatureFileEnum
ComponentFileInfo FeatureFileInfo
ComponentFilterLanguage FeatureFilterLanguage
ComponentFilterOS FeatureFilterOS
ComponentGetData FeatureGetData
ComponentGetItemSize FeatureGetItemSize
ComponentGetTotalCost FeatureGetTotalCost
ComponentInitialize FeatureInitialize
ComponentIsItemSelected FeatureIsItemSelected
ComponentListItems FeatureListItems
ComponentLoadTarget FeatureLoadTarget
ComponentMoveData FeatureMoveData
ComponentPatch FeaturePatch
ComponentReinstall FeatureReinstall
ComponentRemoveAll FeatureRemoveAll
ComponentRemoveAllInLogOnly FeatureRemoveAllInLogOnly
ComponentRemoveAllInMedia FeatureRemoveAllInMedia
ComponentRemoveAllInMediaAndLog FeatureRemoveAllInMediaAndLog
ComponentSaveTarget FeatureSaveTarget
ComponentSelectItem FeatureSelectItem
ComponentSelectNew FeatureSelectNew
ComponentSetData FeatureSetData
ComponentSetTarget FeatureSetTarget
ComponentSetupTypeEnum FeatureSetupTypeEnum
ComponentSetupTypeGetData FeatureSetupTypeGetData
ComponentSetupTypeSet FeatureSetupTypeSet
ComponentTotalSize FeatureTotalSize
ComponentTransferData FeatureTransferData
ComponentUpdate FeatureUpdate
ComponentValidate FeatureValidate
SdComponentDialog SdFeatureDialog
SdComponentDialogAdv SdFeatureDialogAdv
SdComponentMult SdFeatureMult
SdComponentTree SdFeatureTree
COMPONENT_INFO_ATTRIBUTE FEATURE_INFO_ATTRIBUTE
COMPONENT_INFO_LANGUAGE FEATURE_INFO_LANGUAGE
COMPONENT_INFO_OS FEATURE_INFO_OS
COMPONENT_INFO_ORIGSIZE FEATURE_INFO_ORIGSIZE
COMPONENT_INFO_COMPSIZE
COMPONENT_INFO_DATE
Note: The flags that are not available return -137,
which indicates that the option is not functional.
COMPONENT_INFO_DATE_EX
You can use the FeatureError function to provide
more information about the return value.
COMPONENT_INFO_TIME
COMPONENT_INFO_VERSIONLS FEATURE_INFO_VERSIONLS
COMPONENT_INFO_VERSIONMS FEATURE_INFO_VERSIONMS
COMPONENT_INFO_VERSIONSTR FEATURE_INFO_VERSIONSTR
COMPONENT_FIELD_CDROM_FOLDER FEATURE_FIELD_CDROM_FOLDER
COMPONENT_FIELD_DESCRIPTION FEATURE_FIELD_DESCRIPTION
COMPONENT_FIELD_DISPLAYNAME FEATURE_FIELD_DISPLAYNAME
COMPONENT_FIELD_FILENEED FEATURE__FIELD_FILENEED
COMPONENT_FIELD_FTPLOCATION FEATURE_FIELD_FTPLOCATION
COMPONENT_FIELD_HTTPLOCATION FEATURE_FIELD_HTTPLOCATION
COMPONENT_FIELD_IMAGE FEATURE_FIELD_IMAGE
COMPONENT_FIELD_MISC FEATURE_FIELD_MISC
COMPONENT_FIELD_PASSWORD FEATURE_FIELD_PASSWORD
COMPONENT_FIELD_SELECTED FEATURE_FIELD_SELECTED
COMPONENT_FIELD_SIZE FEATURE_FIELD_SIZE
COMPONENT_FIELD_STATUS FEATURE_FIELD_STATUS
COMPONENT_FIELD_VISIBLE FEATURE_FIELD_VISIBLE
COMPONENT_VALUE_CRITICAL FEATURE_VALUE__CRITICAL
COMPONENT_VALUE_HIGHLYRECOMMENDE FEATURE_VALUE__HIGHLYRECOMMENDED
D
COMPONENT_VALUE__STANDARD FEATURE_VALUE_STANDARD
//{{IS_SCRIPT_TAG(FunctionName)
InstallScript code...
//}}IS_SCRIPT_TAG(FunctionName)
Task When you open the project, a dialog box appears to ask if you would like to upgrade your project.
• Click Yes to upgrade your project. Your project opens in the IDE.
• Click No to leave the project unopened.
A backup copy of your original project is created and stored in the location specified in the dialog.
• Dialog Editor—The Dialog Editor enables you to modify the layout of existing end-user dialogs or
create new custom dialogs. Import and export dialogs to share them across projects. Construct
different dialogs for each language supported in the project.
• Automation interface—Use script to add new files, add or delete features, change the product name
and upgrade code, change release settings, change summary information stream items, change
release flags, change any property, initiate the build process, and more.
• Release customization—Define which project segments to compress, which features to place on
which disk, and which languages to include. Choose to filter application data based on language to
support localization efforts.
• Source code control integration—Simplify the process of checking projects in and out of your source
code control system and save space when differencing projects. The SCC integration in the Premier
and Professional editions of InstallShield supports integration with various source code control
systems.
• Project validation—Use standard cub files to validate both full projects and merge modules. With the
Best Practices Wizard, receive notification of deviations from setup guidelines and
recommendations for changes.
• Patch creation—In addition to enabling you to create QuickPatch projects, the Premier and
Professional editions let you create standard patches that contain updates to a previous installation.
• Manage multiple product versions—Build versions such as Evaluation, Debug, Standard, and
Advanced—from a single project. Allow specific features to be chosen for inclusion in a release
through user-defined flags.
• Support for InstallScript—The Premier and Professional editions of InstallShield include support for
InstallScript, a simple but powerful programming language. You can add InstallScript custom
actions to Windows Installer–based installations or create InstallScript projects, which use the
InstallScript engine instead of the Windows Installer engine to control the entire installation.
• Merge module authoring and editing—Package pieces of a project for reuse across application
installations. Reuse those you create or any of the ones included in the product. Edit and open
modules for greater customization.
• Project templates—Create project templates that contain all of the default settings and design
elements that you want to use as a starting point when you create an installation project or merge
module project.
• ClickOnce support—The Premier and Professional editions include a ClickOnce Deployment project
type, which provides a lightweight application deployment mechanism that is easy to use. The new
ClickOnce Assistant guides you through the project creation process, providing pertinent
information along the way.
• Device driver support—Device driver support in the Premier and Professional editions simplifies the
process of installing device drivers from installation using the Driver Installation Frameworks for
Applications (DIFxApp) from Microsoft.
• SQL support—Connect to SQL servers, import database schema and data, associate SQL scripts with
features, and more with SQL support.
• XML support—Use the XML File Changes view to specify how you want to edit one or more XML files
on target systems.
• Setup Prerequisite Editor—Use this tool to create new setup prerequisites and modify existing ones.
For additional details about the features included with each edition, visit the Macrovision Web site.
To learn about upgrading from one edition to another, see the appropriate topic:
• Upgrading from the Express Edition to the Professional or Premier Editions
Open the project in the Premier or Professional edition of InstallShield. A dialog box opens to ask if you
would like to upgrade your project.
InstallShield launches FLEXnet Connect, which checks for updates. When an update is available, you
can do the following:
• View the updates for your system.
This section contains tutorials that walk you through the process of creating an installation using
InstallShield.
Tutorial Description
Basic MSI Teaches you how to a Basic MSI installation project. The tutorial also provides
Project Tutorial information about the various tasks associated with installation projects and
introduces you to the views in the InstallShield interface in which you can
accomplish these tasks.
Globalization Shows you how to add languages and language-specific components to your
Tutorial project. Additionally, it shows you how to conditionally install components
based on the target system’s language.
Referencing a Leads you through the process of adding and configuring a DIM reference in a
DIM in a Basic Basic MSI project using InstallShield.
MSI Project
Tutorial
Note: This tutorial works in conjunction with the DIM tutorial that is available in
the InstallShield Collaboration Help Library.
This tutorial guides you through the process of creating, building, running, and enhancing an
InstallScript installation program using InstallShield.
The tutorial is divided into several steps. After the first step—Step 1: Creating, Building, and Testing
Projects—the other steps can be performed independently, and in any order, so you can focus on the
information relevant to your work.
In this tutorial, you will learn how to handle many of the tasks that an installation program needs to
address, including:
• Installing files
• Setting up shortcuts and registry data
• Conditionally installing data
• Changing the installation’s user interface
• Building release images
• Testing the installation
Throughout the tutorial are links to related topics in the Help Library.
Level Description
The installation program you will create in this tutorial installs and configures an application called
Tutorial App. The source files for Tutorial App are located in the Samples\ISDevTutorial subfolder of
your InstallShield folder (which is typically C:\Program Files\).
• Click the Create a new project link in the Start Page’s Project Tasks section (on the left of
the page).
• On the File menu, click New.
InstallShield creates a project file called ProjectName.ism, in this case Tutorial.ism. The project file
stores all the settings you make in the InstallShield user interface. To move a project to another
machine, copy the .ism file (and the installation source files) to the other system.
Tip: You can change the directory where new project files are created by choosing Options from the Tools menu, selecting
the File Locations tab, and entering the new location in the “Project Location” field.
Your new project is opened to its Project Assistant tab. To begin using the Project Assistant, click the
Next button in the lower right corner.
Tip: You can do the Project Assistant’s steps in any order, and switch at any time (by clicking the appropriate tab) between
the Project Assistant and the Installation Designer, in which you can add more complex and powerful elements to your
installation project.
1. In the Specify your company name edit box, type the name Tutorial Co.
2. In the Specify your application name edit box, type the name Tutorial App.
3. Leave the other fields unchanged.
The value you enter in the application name field is used in dialog boxes displayed to the end user, as the
display name for your application in Add or Remove Programs in the Control Panel. The application
name and company name you enter determine the default location of application shortcuts on the
Windows Start menu, and the default value for the TARGETDIR system variable, which specifies the default
destination for components’ files.
Note: Features can contain subfeatures, subsubfeatures, and so forth, to as many levels as your installation program
requires.
1. For the Do you want to customize your Installation Architecture? question, select Yes.
2. Select the existing DefaultFeature feature and rename it ProgramFiles.
3. Create a new feature called HelpFiles. To do so, click Installation Architecture and then click the
New button.
Adding Redistributables
The Application Redistributables page lets you specify any third-party technologies that your application
requires, for example, MDAC, MFC, or DirectX. You can use the option buttons to specify any such
requirements; if your application requirements are not addressed by the displayed questions and option
buttons, you can click the Objects link to switch from the Project Assistant to the Installation Designer
and see a complete list of available objects and merge modules that encapsulate third-party
technologies.
For this tutorial, leave all option button selections at No.
Creating Shortcuts
The Application Shortcuts page lets you specify shortcuts for your application’s files on the target
system’s desktop or Start menu. By default, this page displays a shortcut for each executable that you
have included in your installation project; you can delete these, and add shortcuts to other files that you
have included in your installation project.
For this tutorial, leave this page’s default specifications unchanged: a shortcut to Tutorial.exe on the
Start menu.
Note: An InstallScript project includes script code that by default creates the application uninstallation key
(Software\Microsoft\Windows\CurrentVersion\Uninstall\<GUID> under the HKEY_LOCAL_MACHINE or
HKEY_CURRENT_USER root key as appropriate) and its values and data; you do not need to specify these registry entries.
For this tutorial, do not specify any registry entries in this page. Registry entries are covered in Step 2,
Shortcuts and Registry Data, of the tutorial.
1. Select the No option button under the text "Do you want to display a License Agreement Dialog?"
2. Leave the other option buttons set to Yes.
Edition: Multilingual language support is available in the Premier edition of InstallShield. For more information, visit the
Macrovision Web site.
Task For this tutorial, change the display name of the HelpFiles feature by doing the following:
Maintenance Mode
When a user runs an installation program a second (or later) time for a product installed on their
system, the installation runs in maintenance mode. Maintenance mode allows the user to modify feature
selections from the first-time installation, repair the features already installed, or remove the entire
program.
3. Select the New Feature feature and set its Description property to This feature contains the
Tutorial App help files. As you enter each description, the IDE creates a string table entry—
displayed as {ID_STRINGn}—to represent each value.
4. Rename the features in the Features view to have the same names as their respective display
names. To rename a feature, click the feature twice to highlight its name, then type the new name.
At run time, if the end user chooses the Custom setup type, the installation program displays a dialog
box that prompts the user to select which features to install. This dialog displays features using the
display name and description you specified here.
Task For each setup type, select the features to be installed by selecting the boxes in front of the features’ names:
Task To add the source file Tutorial.html to a new component in the Help Files feature:
1. Go to the Files and Folders view (under the View List’s Application Data node).
2. Select Help Files from the feature list at the top of the view.
3. In the “Destination computer’s folders” area, right-click the Destination Computer icon and
verify that Show Components is selected.
4. Right-click the Application Target Folder icon and select New Component.
5. Rename the new component HelpComponent.
6. In the “Source computer’s folders” area, browse for the source folder containing TutorialHelp.html.
7. Drag the TutorialHelp.html icon from the “Source computer’s files” area and drop it on the
HelpComponent icon.
This type of file linking, where the list of files linked to a component does not change, is called static file
linking. To link to a directory (and possibly its subdirectories) whose contents might change between
builds, see Dynamic File Linking.
Tip: You can use the InstallShield dependency scanners to determine additional files required by your application that are
currently not included in your project. For example, Tutorial App uses MFC, so it will be necessary to add the MFC Runtime
object to your project in the Redistributables view if you intend to target systems that do not have the MFC run-time
libraries installed.
The next step of the tutorial explains how to build a release image for your installation project.
Building a Release
Before testing an installation program, it is necessary to build a release. A release image contains all of
the files to be distributed to the end user on a CD-ROM or floppy disk or from a network location.
The simplest way to build a new release is to use the Release Wizard. The Release Wizard is where you
specify release properties, such as the type of media (CD-ROM, for example) to use and whether to
compress files on the media. You can launch the Release Wizard by clicking the Release Wizard toolbar
button, or by choosing Release Wizard from the Build menu.
Click Next in the Welcome panel to specify your release settings. You can click Help in any panel for
more information about the current step.
• Select whether to place the compiled script file (.inx file) in a cabinet file
For this tutorial, leave the panel’s default settings unchanged.
Platforms Panel
In the Platforms panel, you can specify the operating systems you want to support in the current release.
For this tutorial, do not change the default selection: Use platforms specified by the Platforms
project property.
The wizard will build into your installation only those language-specific elements, including string tables
and dialog boxes, that you select in this panel. All language-independent resources, such as product
properties and built-in actions, are included as a matter of course.
For this tutorial, leave the default selections unchanged.
Click Next to specify which features you want to include in the current release.
Features Panel
In the Features panel, you can specify which features are included in the built release.
For this tutorial, do not change the default selection: Use the ‘Include in Build’ feature property
to determine inclusion.
After making changes to your project in later steps of the tutorial, you can rebuild the latest release by
clicking the Build toolbar button, choosing Build from the Build menu, or pressing F7.
You can now run the installation as you did previously in this tutorial. To run the installation as an
Internet installation, click the toolbar’s Open Release Folder button and launch Setup.htm.
The next step of the tutorial explains how to create shortcuts and registry data for an installation
program.
• Verify that your setup types have features associated with them.
• Verify that your features have components and files associated with them.
• After making any changes to your installation, it is necessary to rebuild your project by clicking the
Build button or pressing F7.
Creating Shortcuts
You create and modify shortcuts in the Shortcuts view. The properties of a shortcut include its display
name, its target executable and arguments, and the icon it displays. Using the Project Assistant, you
have already created a shortcut to Tutorial App in the end user’s Programs folder, under the Start menu.
Task In this step you create a shortcut on the end user’s desktop.
Display Name Tutorial App The IDE adds the display name to
the project’s string table (and
displays the string identifier in
braces in the Display Name field)
so that the name can be easily
localized to other languages.
Target <TARGETDIR>\Tutorial.exe
Icon Index 0
Tip: To create a shortcut to a file already located on the user’s machine, enter the path to the file—using system variables
to represent the path to the file, when possible. For example, to launch a copy of Windows Notepad located in the user’s
Windows or WinNT folder, enter the shortcut target as <WINDIR>\Notepad.exe.
1. Rebuild your project by clicking the Build toolbar button or pressing F7.
2. Run the project by clicking the Run button or pressing CTRL+F5 (first removing any existing
version of the program from your system). A shortcut to Tutorial App should be present in the
Programs folder of your Start menu.
Task To verify that the installation program created the registry data:
Task To add the HTML file to a new component associated with the Program Files feature:
1. In the Destination computer’s folders pane of the Files and Folders view, right-click
Application Target Folder and select New Component.
2. Rename the component OcxHTML.
3. Drag the file TutorialCtrl.html from the Source computer’s files view into the OcxHTML
component.
Task After rebuilding your release (by pressing F7) and running the installation (by pressing CTRL+F5), you can
verify that the file was registered properly:
1. Launch Tutorial App using its shortcut in the Programs menu, or by double-clicking its icon.
2. Choose COM Server Test from the Tutorial menu.
3. If the COM server was registered correctly, the HTML page displays a “success” message.
The next step of the tutorial demonstrates how to install files conditionally.
Task To create a component that will be installed only on Windows NT 4.0 and Windows 2000 systems:
Tip: Press CTRL+M to maximize the Script Editor; press CTRL+M again to restore it.
InstallScript project scripts use an event-driven model, where a series of predefined functions are called
in a specific order. For information about the built-in categories of event handlers and the order in
which event handler functions are called, see Event Handlers.
The functions already defined in your script appear in the Functions tree. To view or edit an existing
function, click its name in the Functions tree.
Note: Event handler functions are called even if they do not explicitly appear in your script. If an event handler function
does not appear in your script, its default code is used.
To add and edit an event handler function, select the desired event category (such as Before Move Data)
from the script editor’s left drop-down list, and then select the name of the desired event (such as Begin)
from the right drop-down list. Event handler functions that are already explicitly defined in your script
appear in boldface text.
For example, the OnBegin event handler is the first function called in an installation script, for both a
first-time installation and maintenance mode.
Task To add your own code to the OnBegin event handler, begin by creating the function:
1. Select Before Move Data from the event category list on the left.
2. Select Begin from the event handler list on the right.
The following code is added to your script:
//////////////////////////////////////////////////////////////////////////////
//
// FUNCTION: OnBegin
//
// EVENT: Begin event is always sent as the first event during
// installation.
//
//////////////////////////////////////////////////////////////////////////////
function OnBegin( )
begin
// TO DO: you may change default non-UI settings, for example
//
// You may also perform your custom initialization steps, check requirements, etc.
end;
You can place any code you want to execute at the beginning of your installation in the OnBegin function.
1. Delete the comments (lines beginning with //) between the lines reading begin and end;, and place
the text insertion point between the lines.
2. Press CTRL+I to launch the Function Wizard.
3. In the Function Category list, select Built-in dialog box.
4. In the Function Name list, select MessageBox.
5. Click Next.
6. In the szMsg field—which contains the message you want to display—type "Welcome to the Tutorial
installation!" (including the quotation marks).
7. In the nType drop-down list—which specifies the type of message box to display—select
INFORMATION.
8. Click Finish to paste your function call into the script.
Your OnBegin function should now appear as follows:
function OnBegin( )
begin
MessageBox ( "Welcome to the Tutorial installation!" , INFORMATION );
end;
Tip: If compiling the script results in any errors or warnings, you can double-click the error message to highlight the script
line where the error occurred.
When you run the installation program (by clicking the Run toolbar button, or by pressing CTRL+F5),
the message box appears before the Welcome dialog is displayed.
After you compile and run the installation, the message box appears only for a first-time installation,
and not for maintenance mode.
InstallScript
The InstallScript language contains over 250 functions for performing installation-related tasks, such as
working with the registry and INI files, testing characteristics of the target operating system, and
displaying dialogs. For details and examples, see the InstallScript Language Reference.
The next step of the tutorial explains how to modify the dialog boxes displayed by your installation
program.
Note: The OnMaintUIBefore and OnMaintUIAfter event handler functions are not called if the project’s Maintenance
Experience property is set to "No uninstall or maintenance".
A default InstallScript project created with the Project Assistant defines the OnFirstUIBefore event
handler function, which defines the user interface for a first-time installation. OnFirstUIBefore calls
dialog box functions to display the dialog boxes that you specified in the Project Assistant’s Installation
Interview page. For example, the following code displays a dialog box that prompts the end user to enter
a user name and company name:
szMsg = "";
szTitle = "";
nResult = SdRegisterUser( szTitle, szMsg, szName, szCompany );
The end user’s user name and company name are returned in the last two variables, which you can then
use in any way you want, for example, to create a registry key or check against information you have
stored in a file.
Task To replace the default user information dialog box with one that also prompts the user for a serial number,
you can replace the SdRegisterUser function with a call to SdRegisterUserEx:
Task To modify the dialog box so the password is hidden as the end user types it:
1. In the Dialogs view (which is under the List View’s User Interface node), right-click the
SdRegisterUserEx icon and select Edit.
2. Select the English (United States) icon.
3. In the Dialog Editor, select the edit field under the Serial Number label.
4. Change the Password property of the Edit control from False to True.
After rebuilding the project (by pressing F7) and running it (by pressing CTRL+F5), the serial number
entered by the user will be hidden.
Tip: To restore a dialog box to its default appearance, right-click the dialog box’s icon and select Revert Dialog to Default.
This tutorial guides you through the process of creating, building, running, and enhancing a Basic MSI
installation project using InstallShield.
The tutorial is divided into several steps. After the first step—Step 1: Creating, Building, and Testing
Your Project—the other steps can be performed independently, and in any order, so you can focus on the
information relevant to your work.
In this tutorial, you will learn how to handle many of the tasks that an installation program needs to
address, including:
• Installing files
• Setting up shortcuts and registry data
• Conditionally installing data
• Registering COM servers
• Changing the installation’s user interface
• Building release images
• Testing the installation
Throughout the tutorial are links to related topics in the InstallShield Help Library.
Level Description
Tutorial Files
The installation program you will create in this tutorial installs and configures an application called
Tutorial App. The source files for Tutorial App are located in the directory to which you installed
InstallShield. The default location is C:\Program Files\Macrovision\IS2008\Samples\ISDevTutorial.
1. Select New from the File menu, or click the New Project button in the toolbar. The New Project
dialog appears.
2. Click the Windows Installer tab and select the Basic MSI project type.
3. In the Project Name field, type Tutorial.
4. Leave the default setting for the Project Location field.
5. Select the Create the project in Project Name subfolder option.
6. Click OK to create your project and launch the Project Assistant.
InstallShield creates a project file called ProjectName.ism, in this case creating the project file
Tutorial.ism. The project file stores all the settings you make in the InstallShield IDE. To move a project
to another machine, copy the .ism file (and the installation source files) to the other system.
Tip: To change the default directory where new project files are created, type a new path in the Project Location field in
the Options dialog (File Locations tab).
1. Type TutorialCo in the Company Name field. This automatically updates the information in the
Web Address field.
2. Type TutorialApp in the Application Name field. The value you enter in the Application Name
field is used on dialogs displayed to the end user, and is used as the display name for your
application in the user’s Add/Remove Programs panel.
3. Leave the default values in the Application Version and Company Web Address fields.
4. In the Application Icon field, click browse button to browse to the Tutorial.exe location: the
InstallShield folder’s Samples\ISDevTutorial subfolder’s Tutorial.exe file. Open the .exe file and
select the Icon Index:0.
The Application Information panel will look like the following when you are finished.
The application name and company name you enter determine the default location of application
shortcuts on the Windows Start menu, and the default value for the INSTALLDIR property, which specifies
the default destination for your program’s files.
Note: The default value of INSTALLDIR is [ProgramFilesFolder]Your Company Name\Your Product Name. The special form
[ProgramFilesFolder] expands to the location of the user’s Program Files folder at run time. For a list of the other directory
properties that are defined by Windows Installer, see the System Folders Set by the Installer section in Windows Installer
Property Reference.
Software Requirements
If your application’s installation requires that a particular piece of software be installed on the target
system, select Yes and select the required software. To customize the run-time message that will be
displayed if the required software is not present on the target system, click on the run-time message and
edit.
Note: The run-time message is not displayed in this section until a software requirement is selected.
Note: Features can contain subfeatures, subsubfeatures, and so forth, to as many levels as your installation program
requires.
Your installation architecture currently contains a default feature, Tutorial_Files. The default feature is
always installed when an end user runs your installation. In this step, you will add another feature to the
installation architecture.
1. Select Yes for the Do you want to customize your Installation Architecture? option.
2. Right-click the Installation Architecture node and select New.
3. Name the new feature Help_Files.
When you finish this step, your installation architecture will look like this:
1. Select the Tutorial_Files feature from the drop-down list of features at the top of the page.
2. In the tree control (with top node Destination Computer), select the INSTALLDIR node.
3. Click Add Files. An Open dialog is displayed.
4. Browse to Tutorial.exe, which is located in the Tutorial Files source directory.
5. Click Open to add the file to the Tutorial_Files feature.
6. When the file you have added ... may have dependencies message appears, click No.
Tutorial.exe has no dependencies. The file is added to the feature and appears in the file list panel on
the right.
Note: The key icon next to the file indicates that this file is the key file of the feature’s component. Windows Installer
requires that most components have a single key file. The Windows Installer service uses a component’s key file for
several purposes, including checking for the file’s existence to determine if a component needs to be repaired and using
the key file as the default target for a shortcut. When you add an executable to a feature in a Basic MSI project, the Project
Assistant automatically sets it as the key file of the component it creates behind the scenes for the file. For more
information, see Setting Component Key Files.
Creating Shortcuts
The Application Shortcuts page lets you specify shortcuts for your application’s files on the target
system’s desktop or Start menu. By default, this page displays a shortcut for each executable that you
have included in your installation project. You can delete these, and add shortcuts to other files that you
have included in your installation project.
Click the Launch Tutorial.exe icon. Leave the default setting, Create shortcut in Start menu,
selected. InstallShield will create a shortcut to Tutorial.exe on the end user’s Start menu when the
installation is run.
1. Do you want to display a License Agreement Dialog?—Select No. If you selected Yes for this option,
you would be able to browse to your license agreement file.
2. Do you want to prompt users to enter their company name and user name?—Select Yes. The
installation displays a dialog requesting this information.
3. Do you want your users to be prompted to modify the installation location of your application?—Select
Yes. For more information, see Allowing End Users to Modify the Installation Location.
4. Do you want users to be able to selectively install only certain parts of your application?—Select Yes.
For more information, see Creating Selectively Installable Installations.
5. Do you want to give users the option to launch your application when the installation completes?—Select
Yes and browse to the Tutorial.exe file (located in [ProgramFilesFolder]TutorialCo\Tutorial). When
this option is set to Yes, the final dialog in the installation presents a check box that allows the end
user to immediately launch your application upon clicking the Finish button.
Edition: For language options in addition to the language that you chose when you installed InstallShield, you must have
the Premier edition of InstallShield. For more information, visit the Macrovision Web site.
Task For this tutorial, leave English (United States) selected and change the display names of the installation’s
features by doing the following:
The installation displays the dialogs that you specified in the Installation Interview page of the Project
Assistant. The values you entered in the Project Assistant are displayed to the end user in the
appropriate dialogs. For example, at run time, the default value of INSTALLDIR that you specified in the
Project Assistant appears in the Choose Destination Location dialog box. If the end user browses for a
different destination directory, INSTALLDIR stores the new value.
After the installation is complete, you can browse for the directory and find the files installed by your
installation. If the installation was successful, you will see the tutorial files installed.
Maintenance Mode
When a user runs an installation a second (or later) time for an application installed on their system, the
installation runs in maintenance mode. Maintenance mode allows the user to modify feature selections
from the first-time installation, repair the features already installed, or remove the entire application.
Click Uninstall.
Now that you have created a basic installation project, click the Installation Designer tab (near the top of
the InstallShield window) to expand and fine-tune your installation as illustrated in the next step of the
tutorial.
Note: The views displayed in the IDE differ, depending on the project type you create.
1. Open the Features view. The Features view is located in the Organization section of the View
List.
2. In the Features view, select the Tutorial_Files feature to display its property grid on the right.
3. Type the following text in the Description field: This feature contains the Tutorial application
files.
4. Select the Help_Files feature to display its property grid.
5. Type the following text in the Description field: This feature contains the Tutorial help files
As you enter the display names and descriptions, the IDE creates a string table entry—displayed as
{ID_STRINGn}—to represent each value.
At run time, if the end user chooses the Custom setup type, the installation program displays a dialog
that prompts the user to select which features to install. This dialog displays features using the display
name and description you specified here.
8. Click the Help_Component icon to display the component’s files in the Destination
computer’s files pane.
9. Because each component should have a key file, right-click the TutorialHelp.html file and select Set
Key File.
This type of file linking, where the list of files linked to a component does not change, is called static file
linking. To link to a directory (and possibly its subdirectories) whose contents might change between
builds, see Dynamic File Linking.
Tip: You can use the InstallShield dependency scanners to determine additional files required by your application that are
currently not included in your project. For example, Tutorial App uses MFC, so it will be necessary to add the MFC merge
module (MFC42.msm) to your project in the Redistributables view if you intend to target systems that do not have the MFC
run-time libraries installed.
The next step of the tutorial explains how to build a release image for your installation project.
Building a Release
Before testing an installation program, it is necessary to build a release to update your project settings. A
release image contains all of the files to be distributed to the end user on a CD-ROM or from a network
location.
The simplest way to build a release is to use the Release Wizard. The Release Wizard is where you specify
release properties, such as the type of media (CD-ROM, for example) to use and whether to compress
files on the media.
1. Click the Release Wizard button on the toolbar or choose Release Wizard from the Build
menu.
2. In the Welcome panel, click Next to begin defining your release settings.
Use the default settings (no filtering), and click Next to continue.
Setup Languages
In the Setup Languages panel, you specify which languages (from among the project languages) the user
interface of your installation program should display, and whether to display a dialog from which the
user can select the installation language.
Use the default settings (include English in the user interface), and click Next to continue.
Select Automatic, which lets the Release Wizard determine the disk image on which to place each
feature’s files.
For more information, see Spanning Installations over Multiple Disks or CDs.
You can have the IDE copy your built disk images to another directory using the Postbuild tab in the
Releases view.
• Verify that your features have components and files associated with them.
• After making any changes to your installation, it is necessary to rebuild your project by clicking the
Build button or pressing F7.
Creating Shortcuts
You create and modify shortcuts in the Shortcuts view. The properties of a shortcut include its display
name, its target executable and arguments, and the icon it displays.
Task In this step you will create a shortcut to Tutorial App in the user’s Programs folder, under the Start menu.
1. Open the Shortcuts view. The Shortcuts view is located in the System Configuration section
of the View List.
2. Right-click the Programs Menu folder icon, and select New Advertised Shortcut. The
Browse for a Component dialog appears.
3. In the dialog, select Tutorial_Files from the Feature drop-down menu and select Tutorial.exe
from the files list and click Open to close the dialog.
4. Rename the shortcut icon to an internal name such as Tutorial.
Tip: To create a shortcut to a file already located on the end user’s machine, set the Advertised property to No, and enter
the path to the file—using Windows Installer directory properties to represent the path to the file, when possible. For
example, to launch a copy of Windows Notepad located in the user’s Windows or WinNT folder, enter the shortcut target
as [WindowsFolder]Notepad.exe.
Tip: To write the value of a Windows Installer property to the registry, you can use the form [PropertyName]. In this
example, creating a registry value whose data is [INSTALLDIR] writes the value of INSTALLDIR to the registry.
At run time, if the end user selects a setup type or collection of features that includes the Tutorial.exe
component, the registry data is created on the target system.
1. Rebuild your project by clicking the Build toolbar button or pressing F7.
2. Run the project by clicking the Run button or pressing CTRL+F5 (first removing any existing
version of the program from your system). A shortcut to the Tutorial application should be present
in the Programs folder of your Start menu.
Task To verify that the installation program created the registry data:
1. Open the Files and Folders view. The Files and Folders view is located in the Application
Data section of the View List.
2. At the top of the Files and Folders view, select the Tutorial_Files feature from the Add new
components to the feature menu.
3. In the Destination computer’s folders pane, right-click the [INSTALLDIR] folder and select
Launch Component Wizard.
4. In the Welcome panel of the Component Wizard, select the Let me select a type and define the
component myself option and click Next.
5. In the Component Type panel, select the COM Server icon, type Tutorial.ocx in the
Component Name field, and click Next.
6. In the COM Server—Destination panel, verify that the destination is set to [INSTALLDIR].
7. In the COM Server File panel, click the browse button next to the COM Server File field and
browse for Tutorial.ocx in your tutorial files source directory. Click Next.
8. After the Component Wizard has extracted the COM information, review the COM information and
click Finish to create the component.
The next step is adding the HTML file to the component you just created.
1. In the Destination computer’s folders pane of the Files and Folders view, select the new
Tutorial.ocx component.
2. Drag the file TutorialCtrl.html from the Source computer’s files pane to the Destination
computer’s files pane.
3. Verify that Tutorial.ocx is marked as the key file of its component.
Note: See Registering COM Servers for other options for registering self-registering files, including extracting COM
information each time that you rebuild the release—for COM servers with interfaces that change between builds—or
calling the file’s self-registration functions.
Task After rebuilding your release (by pressing F7) and running the installation (by pressing CTRL+F5), you can
verify that the COM server was registered properly:
1. Launch Tutorial App using its shortcut in the Programs menu, or by double-clicking its icon.
2. Choose COM Server Test from the Tutorial menu.
3. If the COM server was registered correctly, the HTML page displays a “success” message.
The Component Wizard can also create components that install and configure fonts and Windows NT
services.
The next step of the tutorial demonstrates how to install files conditionally.
Task To create a component that will be installed only on systems running Windows 2000 or later:
1. Open the Setup Design view. The Setup Design view is located in the Organization section of
the View List.
2. Right-click the Help_Files feature and select New Component.
3. Rename the component Windows_NT_Files.
4. Expand the Windows_NT_Files component, click the Files icon for the component, and add the file
ReadmeNT.txt from your tutorial files source folder by right-clicking in the Files pane and browsing
to the file.
5. Right-click the .txt file and select Set Key File.
6. Click the Windows_NT_Files component to display the component’s property grid.
7. Select the component’s Condition property and click the browse button to launch the Condition
Builder dialog.
8. Create the following condition: VersionNT>=500. For information on creating conditions, see
Building Conditional Statements.
9. Click OK to close the Condition Builder dialog and add the condition.
After you rebuild (by pressing F7) and run the installation (by pressing CTRL+F5), and any files or other
data contained in the component will be installed only if the target system is running Windows 2000 or
later.
A Windows Installer condition is a statement of logic that compares a property value against a constant
value, or tests if a property exists. For example, Windows Installer defines properties called ScreenX and
ScreenY, which contain the user’s monitor resolution in pixels. A Windows Installer condition that
checks that the user has at least 800 by 600 resolution would read “(ScreenX>=800) And
(ScreenY>=600)”.
Conditions can also test if a property is defined. For example, the AdminUser property is set only if the
user has administrative privileges, and a condition that tests if a user has administrative privileges is
simply “AdminUser”.
Task To create a component that will be installed only if the user has administrative privileges:
• Modifying the layout and properties of a dialog using the Dialog Editor.
1. Open the Dialogs view. The Dialogs view is located in the User Interface section of the View
List.
2. Right-click the All Dialogs node and select New Dialog. The Dialog Wizard launches. Click
Next to dismiss the Welcome panel.
3. In the Dialog Template panel, select Interior.isd and select the Insert this dialog in a User
Interface sequence option.
4. In the User Interface panel, select Installation from the User Interface Sequence menu
and select Install Welcome in the list of dialogs. Based on these selections, InstallShield will
insert your new dialog in sequence immediately following the Install Welcome dialog.
5. In the Dialog Position and Condition panels, leave the default settings, and click Finish. Your
new dialog appears in the Dialogs list.
6. Right-click on the dialog and select Rename. Rename the dialog WelcomeBitmap.
Using the same technique, you can insert additional dialogs in your installation program’s user
interface.
Task In this step, you will modify the WelcomeBitmap dialog that you just created:
1. First, create a bitmap (using a program like Microsoft Paint) that measures 300 by 150.
2. Open the Dialogs view.
3. Expand the WelcomeBitmap dialog’s node. Click English (United States) to open the Dialog
Editor.
4. Click the Dialog Bold Title text box at the top of the dialog. In the Text field, type Welcome
Bitmap. This changes the dialog’s main title.
5. Click the Dialog Normal Description text box at the top of the dialog. In the Text field, type
Displays my welcome bitmap. This changes the dialog’s description.
6. Click the Bitmap button on the Dialog Control toolbar and use the cursor to drag a box on the
dialog. Set the Height to 150 and the Width to 300.
7. In the File field browse to the bitmap file that you created in step 1.
After rebuilding the project (by pressing F7) and running it (by pressing CTRL+F5), the Welcome
Bitmap dialog will appear after the Install Welcome dialog.
The Globalization tutorial introduces you to the tools and options that InstallShield provides for creating
a global installation package. A global installation is one that has the potential to run in many different
languages. Depending on how you choose to build your installation, you can either include all the
languages in one package and let the end user select the language, or you can build individual
installation packages for each language that you target. This tutorial walks you through the process of
creating an all-encompassing installation.
Edition: The Premier edition of InstallShield must be installed on your development system in order to successfully
complete this tutorial. For more information, visit the Macrovision Web site.
If you have not already done so, you may want to run through the Basic MSI tutorial to familiarize
yourself with how to create an installation package. When finished with the Basic MSI Tutorial, you will
have an Basic MSI installation project that is ideal for adding additional languages. The complete project
file for the Basic MSI tutorial was installed with this product in the InstallShield folder’s Samples\ISDev
Tutorial\Tutorial subfolder. You can use the Tutorial project file or the Othello file that is used in the
tutorial steps.
Project: Almost all of the information in the tutorial also applies to InstallScript installation projects. Differences are
explicitly noted in the tutorial text.
Open Othello.ism, which is located in the InstallShield folder’s Samples\Basic Install\Program Files
subfolder.
Project: Othello.ism is a Basic MSI installation project. Almost all of the information in this tutorial also applies to
InstallScript installation projects; differences are explicitly noted in the tutorial text.
Note: The International setup for InstallShield does not update the string tables in existing installation projects. You need to
import the string tables for these languages.
1. Right-click on the German string table under the String Tables icon in the Project explorer.
Select Import String Table.
2. Navigate to the InstallShield folder’s Languages subfolder, and select the 1031 (UNICODE).txt file.
3. A dialog appears, asking you if you would like to overwrite the contents of the current string table.
Click Yes to all.
Repeat the steps above to import the Polish string table, this time selecting 1045 (UNICODE).txt. To
view a list of decimal language identifiers, see Language Identifiers.
1. The component Program_Executables contains a shortcut to the file Othello.exe. Select the
Shortcuts icon on the tree below this component.
2. In the Shortcuts explorer, expand the tree below Programs Menu and click on the Othello
shortcut. The shortcut’s property sheet opens.
Currently, the Display Name property is Othello. If you do not specify a display name, the name
that you gave the shortcut will double as the display name. So, since this shortcut is called Othello,
the display name is always going to be Othello. This name is not entered into the string table and is
therefore, not localizable. However, if you enter a new display name for the shortcut, a new entry
will be created in all of your string tables.
3. To enter a display name, double-click the Display Name property and enter the name.
For the Shortcut Description property, you are going to enter your new string directly into the string
table. Then, you will associate that string with the shortcut’s description.
1. Click on the Shortcut Description property and then click on the String Tables tab at the
bottom of the screen.
2. Enter an identifier for this new string. To maintain consistency with the other strings that you have
created, enter NEW_STRING3.
3. Click in the Value field and enter the following sentence: This is the description of the Othello
shortcut.
4. Right-click your new string table entry and choose Select String. Your new string is now entered as
the value for the Shortcut Description property.
Project: In an InstallScript or InstallScript Object project, the default script code for the OnFilterComponents event handler
function automatically excludes from the file transfer all components that are specific to languages other than the
language the installation is using. In InstallScript and InstallScript Object projects, the components do not have a Condition
property.
Now that you have created your language-specific components, you need to include logic that will let the
installer know which of these components should be installed. By specifying a component condition, you
can determine the default language of the target system and then install the appropriate file. Each of the
three language-specific components that you created will need a condition. If that condition evaluates to
True, the component is installed.
1. Click on the German_Readme component, and select the Condition property from the component
property grid. Click the browse button to open the Component Condition Builder, and begin
building your component’s condition.
2. From the Properties field, select SystemLanguageID. Click Add to include this property in your
condition.
3. From the Operators field, select the equals sign (=). Click Add to include this operator in your
condition.
4. In the edit box, you will see SystemLanguageID =, which reflects the selections you previously
made. Next you need to provide a value that will be checked when the installation is run. Because
you are currently editing the German component, enter 1031 after the equal sign. 1031 is the
language ID for German. Since the component is installed only if this equation evaluates to true
(that is, the target machine is running with German as the default language), this component is not
installed on any machine that is not running in German.
Follow the same steps from above to add a condition to the Polish_Readme component. Instead of using
1031 as the language value, use 1045, which is the language ID for Polish.
You need to choose one language as your default language. For this example, English is the default.
Therefore, the condition you use for the English_Readme component differs from the other two.
Click on the English_Readme component and select the Condition property from the component
property grid to the right. Click the browse button to open the Component Condition Builder, and
begin building your component’s condition. Your final condition should appear as follows:
SystemLanguageID<>1045 AND SystemLanguageID<>1036
With this logic, if the language of the target machine is not German or Polish, the English_Readme
component is installed.
Identifier Value
NEW_STRING1 Programmdateien
Identifier Value
In most translation situations, you export your entire string table for translation. However, for the
purposes of this tutorial, it is easier to edit the string tables within the IDE.
1. Click the Run Setup button on the toolbar. The Choose Setup Language dialog appears. This
dialog is always displayed in the default language that you chose for your installation.
2. To run your installation, Select German (Standard) and click OK. From this point forward, every
dialog is displayed in German.
Note: After an installation is run in a particular language, Windows Installer caches this information and always runs the
installation in that language, regardless of the choice you make in the Language Selection dialog.
As the Installation Wizard progresses, you may notice that some buttons are not properly sized. You can
easily fix this problem by opening the Dialog Editor and resizing the controls so the text fits in the
control.
In the Custom Setup panel (in German it is called Angepasstes Setup), the feature name is now
Programmdateien. Your localized string table entries are a part of the installation.
1. Open the Start menu and select Programs. The Othello shortcut is displayed as Othello
Verknpfung. On a machine running Windows 2000 or later, you can see the shortcut’s description,
which also appears in German.
2. Navigate to the installation directory for Othello. It should be in <Program Files
Folder>\Shakespeare Inc\Othello. The readme file that you installed is called Deutsch.txt.
A DIM is an XML-format manifest that contains information about files and other data that will
ultimately be included in an installation. In the collaborative model of installation authoring, which
provides a solution enabling collaboration between application developers and installation developers,
application developers create the DIMs. Each DIM can then be referenced by the installation developer
in a Basic MSI project using InstallShield and consumed during the build of the installation itself.
Tutorial Overview
This tutorial covers the following information about referencing a DIM in a Basic MSI project:
• Adding a DIM Reference to a Basic MSI Project
Objective
The main objective of this tutorial is to add and configure a DIM reference in a Basic MSI project using
InstallShield.
Audience
The intended audience for this tutorial is installation developers who will reference DIMs (created by
application developers) in a Basic MSI project before building an installation using InstallShield. Some
knowledge of creating and building projects using InstallShield is assumed.
Tutorial Files
Sample DIMs are included in the Samples subfolder within the InstallShield Collaboration Program
Files folder. The default installation location is C:\Program
Files\Macrovision\IS2008\Samples\DIMReferenceTutorial.
Sample project files referenced in the tutorial (such as Othello.ism) are included in the Samples
subfolder within the InstallShield Collaboration Program Files folder. The default installation location is
C:\Program Files\Macrovision\IS2008\Samples\Basic Install.
Create a Basic MSI project, and then save the project as Test.ism.
Figure 8-1: Context Menu Command to Add a DIM Reference in the Setup Design View
You can use the Setup Design view to add new DIM references to your project. As with components, if a
DIM reference is not yet associated with a feature, the DIM icon has a red exclamation point ( ).
You can use the Setup Design view to associate a DIM that already exists in the project with a feature. In
the Setup Design view, right-click the desired feature, click Associate DIM References, and then select
the desired DIM.
If the DIM has been modified since the time your project was last loaded, you can right-click the DIM
icon and click Refresh.
In the next task, you will add a DIM reference using the Setup Design view.
6. Browse for the DemoApp.dim file, which is in the Samples subfolder within the InstallShield Program
Files folder. The default location is:
C:\Program Files\Macrovision\IS2008\Samples\DIMReferenceTutorial
7. Click Open.
InstallShield adds DemoApp.dim to the Setup Design explorer in the Setup Design view.
Figure 8-2: Context Menu Command to Add DIM Reference in the DIM References View
You can also use the DIM References view to add new DIM references to your project. As with
components, if a DIM reference is not yet associated with a feature, the DIM icon has a red exclamation
point.
You can associate an existing DIM with a feature using the Setup Design view. In the Setup Design view,
right-click the desired feature, click Associate DIM References, and select the desired DIM icon.
If the DIM has been modified since the time your project was last loaded, you can right-click the DIM
icon and select Refresh.
On the Variables tab, you see any build variables and run-time variables that the developer defined in
the DIM.
For build variables, you must set the Value field to an existing InstallShield path variable. The value
authored in the DIM is displayed in the Unit Test Value column. For run-time variables, you must set the
Value field to a hard-coded value or to a Windows Installer property.
On the Meta Info tab, you see a read-only view of the meta tags defined by the application developer.
These tags can contain special instructions for using the DIM; therefore, it is recommended that you
read the meta tags before building your project.
The Data tab displays a summary of the types of data contained in the DIM.
DIMs do not contain shortcuts because it is typically your responsibility, as the installation developer, to
specify where shortcuts should be placed on a target system. This helps ensure that all product shortcuts
are created in the same directory of the Programs menu, for example. To create a shortcut to a file inside
a DIM, you can use the Shortcuts view. When you right-click the folder in which the shortcut should be
created, click New Shortcut to File in DIM.
You are then prompted to select the desired DIM, file set, and specific file.
On the Dependencies tab, you see the dependencies of the selected DIM. For each dependency, you must
select the .dim file that satisfies the dependency.
In the next task, review the contents of the DIM reference that you added to your project.
Task To set the source path directory for a dependency in a DIM reference:
1. In the DIM References explorer, select DemoApp.dim, and then click the Dependencies tab.
2. For the DemoShared dependency, click the Source Path field, and then click the ellipsis button
(...).
3. Browse for DemoShared.dim. The default location is:
C:\Program Files\Macrovision\IS2008\Samples\DIMReferenceTutorial
4. Click Open. InstallShield adds the path to DemoShared.dim in the Source Path field. In addition,
InstallShield adds a DIM dependency to the DIM References explorer. By default, InstallShield
always lists any dependencies associated with a DIM when you set the source path location of the
dependency.
5. Save your project.
Building your project is essentially the final step to consuming a DIM after you add a DIM reference to
your project (assuming that you have created a complete installation containing all the necessary
elements of an installation). Now that you have a basic understanding of how to add a DIM reference,
complete the next task to create and build an actual installation that has consumed a DIM.
Before working on the next task, you will need to close your Test.ise project, and then open the
Othello.ism sample project. The default installation location is C:\Program
Files\Macrovision\IS2008\Samples\Basic Install. Then you will add a DIM reference to DemoApp.dim.
4. Click Open.
InstallShield adds DemoApp.dim to the Setup Design explorer in the Setup Design view.
After you add a DIM reference, remember to review the contents of the referenced DIM and resolve any
variables or source path directories. In the next task, you will set the source path directory for the
dependency specified in the DemoApp.dim reference that you added to Othello.ism.
5. Click Open. InstallShield adds the path to DemoShared.dim in the Source Path field. In addition,
InstallShield adds a DIM dependency to the DIM References explorer. By default, InstallShield
always lists any dependencies associated with a DIM when you set the source path location of the
dependency.
Congratulations! You have just completed the “Referencing a DIM in a Basic MSI Project” tutorial.
If you have ever installed an application onto your computer, you have seen an installation in action—
from the end user’s perspective. An installation’s primary task is to transfer files from the source
medium to the local drive. An installation often also displays a user interface to obtain end user
selections, configures the target system (for example, makes any required registry entries and creates
shortcuts), and enables modification or uninstallation of the installed application. Creating an
installation involves performing some or all of the following tasks.
and other applications from your installation. Windows Installer-based installations, including
InstallScript MSI installations, can use custom actions to run InstallScript, VBScript, or JavaScript code,
call .dll functions, run executable files, or run other installation packages.
Configure Servers
A server side installation may need to create and manage new Internet Information Services (IIS) Web
sites, manage COM+ applications and components, or manage and organize SQL scripts by server
connections and settings.
Create Trialware
Offering prospective customers a free trial version of your product can be a highly effective sales tool,
but it carries the risk that some will abuse the privilege and continue to use the product without paying
for it. InstallShield enables you to create a protected trial version of your product without requiring you
to modify the source code.
Windows Logo Guideline: The Windows Logo Guideline alert appears throughout the InstallShield Help Library whenever
the information relates to complying with the Certified for Windows Vista program guidelines.
InstallShield
To complement the new Windows Installer technology, InstallShield provides an intuitive GUI to
simplify and automate the process of creating application installations.
InstallShield Wizards
Several wizards have been designed to simplify the installation creation process.
• You can create an optimal installation for your application using the Component Wizard, which
helps you take full advantage of the Windows Installer service. Enable the Best Practices option to
have InstallShield ensure that your setup is created in compliance with Setup Best Practices. To
make the most of Windows Installer features using Setup Best Practices, click Options on the Tools
menu, and then select the Enforce Setup Best Practices option.
• After opening an existing project or creating a new one, you can create new components according to
best practices using the Component Wizard in the Components view.
• After creating your components, you can create custom actions using the Custom Action Wizard.
• With the Release Wizard, you can create a shippable .msi file from your project. The wizard prompts
for information such as media type, setup languages, and setup launcher options.
One of the goals of Windows Vista and User Account Control (UAC) is to allow users to run as standard
users all of the time. Elevation should rarely be required; if it does occur, it should occur for as short of a
duration as possible.
Several different areas of InstallShield affect whether an installation triggers UAC consent or credential
prompts for elevated privileges. Understanding these different settings will help you create the
appropriate UAC experience for your installation when end users run it on Windows Vista systems. It
will also enable you to try to minimize the number of UAC prompts that are displayed during your
installation.
• Advertise If Prerequisites Are Elevated—Use this setting in the Releases view to specify whether the
.msi file should be advertised—and if so, whether it should be run silently or with the full user
interface (UI)—after the setup prerequisites in the installation have been successfully installed with
elevated privileges on Windows Vista machines. The advertisement may allow end users to avoid the
UAC prompt that would otherwise be displayed for an .msi package that requires elevated privileges.
For more information, see Specifying Whether a Product Should Be Advertised If Its Prerequisites
Are Run with Elevated Privileges.
Note the following UAC-related behavior on Windows Vista:
• If Required Execution Level is set to Invoker, any setup prerequisites in your installation do not
require administrative privileges, and Require Administrative Privileges is set to No, end users
should see no UAC prompts during installation.
• If Required Execution Level is set to Invoker, your installation includes setup prerequisites that
require administrative privileges, and Require Administrative Privileges is set to No, end users
should see one UAC prompt—plus up to one additional UAC prompt for each reboot—during
installation.
• If the full user interface of the setup prerequisite installation is displayed, Windows Installer
displays a message box that lists all of the prerequisites that must be installed. If one or more of the
setup prerequisites that need to be installed require administrative privileges, the Install button on
the message box has the shield icon to alert the end user that elevated privileges are required.
• If the installation is continuing after a reboot and privileges must be elevated, the OK button of the
continuation message box has the shield icon. If privileges do not need to be elevated, the shield
button is not displayed.
• If your installation includes more than one setup prerequisite that must be installed on a target
machine and one or more of those setup prerequisites requires administrative privileges, the UAC
prompt is displayed before the first setup prerequisite is installed. This may allow elevated privileges
to be used for all prerequisites without requiring separate UAC prompts for each prerequisite
installation. Note, however, that if a setup prerequisite installation causes a reboot, administrative
privileges are lost, and a UAC prompt may be displayed if any of the remaining prerequisites require
administrative privileges.
• Note that if Require Administrative Privileges is set to No but your .msi package tries to perform a
task for which it does not have adequate privileges, Windows Installer may display a run-time error.
• If privileges are elevated at the end of an installation and the SetupCompleteSuccess dialog launches
the product, elevated privileges are carried over to your product. In most cases, running an
application with elevated privileges is discouraged.
Sample Scenarios
The following sections contain examples that illustrate different combinations of values for the
aforementioned settings in InstallShield. The diagrams show when Windows Vista requests elevated
privileges for standard users or administrative users who have limited privileges. The examples are
based on the default UAC settings on Windows Vista systems.
Example 1: UAC Prompt Is Displayed for a Prerequisite that Requires Administrative Privileges;
.msi File Is Advertised
The example 1 diagram shows an installation that requires elevation for one of its setup prerequisites
and for its .msi file. Windows Vista displays only one UAC prompt because the .msi file is successfully
advertised after the setup prerequisite is installed with elevated privileges.
Figure 9-1: Example 1—Diagram of an Installation that Has Invoker as the Required Execution Level and that Advertises
the .msi Package
Example 2: UAC Prompt Is Displayed for Setup.exe and After a Reboot for a Prerequisite that
Requires Administrative Privileges
The example 2 diagram shows an installation that requires elevation for Setup.exe, all three setup
prerequisites, and the .msi file. Because the Setup.exe file has a manifest that specifies Administrator as
the required execution level, elevated privileges are used for each part of the installation. The second
UAC prompt is displayed because elevated privileges are lost during a reboot.
Figure 9-2: Example 2—Diagram of an Installation that Has Administrator as the Required Execution Level
File Costing
File costing takes into account the fact that some files are overwritten by newer versions which decreases
the file cost. These values are dependent upon the volume to which each file is to be installed or
removed, and are recalculated when a component’s directory association is changed.
File costs are determined for each component, depending on whether it is installed locally, installed to
run from the source media, such as a CD, or removed.
With InstallShield, you can set your application’s disk usage. This allows you to control file costing by
choosing to run your application from the source media, from the local machine, or to install it when
required. Note that running your application from the source enhances application resiliency and
conserves space on an end user’s system.
Application Resiliency
If Windows Installer cannot provide a component, the Windows Installer technology enables
applications to try to repair the component or to reinstall the component if the corresponding file is
corrupted or the current file is older than the available version.
Source Resiliency
In addition to supporting application resiliency, the Windows Installer supports source resiliency
through the Source List, which can include network locations, URLs, or compact discs from which
applications are installed on-demand. Administrators can use the Group Policy Editor to disable this
functionality.
• Basic MSI
• InstallScript MSI
To prevent end users from being able to install the current version of your product over a future major
version of the same product, the Upgrades view should contain a major upgrade item, the major upgrade
item should be properly configured to prevent the current version of your product from being installed
over a future version, and your project should include a properly configured and scheduled type 19
custom action.
When you create a new Basic MSI or InstallScript MSI project, InstallShield automatically adds support
for preventing the current installation from overwriting a future major version:
• The Upgrades view contains a major upgrade item called ISPreventDowngrade.
The Products sharing my Upgrade Code option is selected on the Common tab of the major
upgrade item. The value of the Upgrade Code setting on the Advanced tab is {000000000000-
0000-0000-0000-00000000}. When you build a release, InstallShield uses the release’s upgrade
code (set in the General Information view, or overridden for the release’s product configuration in
the Releases view) for the major upgrade item.
InstallShield sets the Detect Property setting of this major upgrade item to
ISFOUNDNEWERPRODUCTVERSION and configures the other settings as appropriate.
• The Custom Actions and Sequences view contains a custom action called ISPreventDowngrade, a
type 19 custom action that Windows Installer launches when an end user tries to install the current
version of your product over a future major version.
InstallShield schedules the ISPreventDowngrade custom action for the user interface and execute
sequences of the installation sequence to ensure that Windows Installer runs it if appropriate,
regardless of what user interface level is used. In addition, InstallShield uses
ISFOUNDNEWERPRODUCTVERSION as the condition for this custom action.
The following instructions explain how to manually add this support for projects that you created in
InstallShield 12 or earlier and then upgraded to InstallShield 2008.
Task To manually add support for preventing end users from being able to install the current version of your
product over a future major version:
1. Use the Upgrades view to add a major upgrade item to your project.
2. On the Common tab, select the Products using my Upgrade Code option.
3. Configure the settings on the Advanced tab for the major upgrade item as follows:
a. In the Minimum Version setting, specify the product version that you are using for your
current project.
b. Leave the Maximum Version setting blank. If a value is listed for this setting, delete it.
c. If your project includes multiple languages, specify the language identifiers in the Language
setting.
d. In the Detect Only setting, select Yes; for all of the other Yes-No settings, select No.
e. In the Detect Property setting, type a descriptive name such as the following one:
FOUNDNEWERVERSION
4. Add and schedule a type 19 custom action for your project to handle scenarios where an end user
tries to install the current version of your product over a future major version:
a. In the Custom Actions and Sequences view, right-click the Custom Actions explorer and
click New Error.
b. Select the new custom action.
c. In the Error Message setting, type the error message text that should be displayed when an
end user tries to install the current version of your product over a future major version.
d. In the Install UI Sequence and Install Exec Sequence settings, select After
FindRelatedProducts.
e. In the Install UI Condition and Install Exec Condition settings, type the value that you
specified in step 2f.
Task To prepare a base installation that can later be updated by non-administrator patches:
Tip: The digital signature settings are also available in the Releases view.
The Windows Installer design enables you to sign a package with one certificate and also allow patches
that are signed with a different certificate. The following instructions explain how to add to the base
installation the additional certificates for the patches.
1. Use a tool such as Signcode.exe to sign a dummy file. The Signcode.exe file is located in the
following directory:
InstallShield Program Files Folder\System
11. In the PatchCertificate field, type a unique name for your patch certificate.
12. In the DigitalCertificate field, select the entry that you created for the MsiDigitalCertificate
table in step 4.
InstallShield includes several settings for platforms, platform suites, and languages.
• Setup Languages—Use this setting to specify the languages that you want to be available for you to
select for components or releases in your project. In general, if a language is not listed for this
setting at the language level, you cannot designate that a particular component or release in your
project is targeted for that language.
The Setup Languages setting is available for InstallScript and InstallScript MSI projects. To access
this setting, open the General Information view and click Project Properties. You can also configure
this setting through the Project Settings dialog box: on the Project menu, click Settings, and click the
Languages tab.
Note: Specifying platforms at the project level does not create target system requirements for running the installation. If
you want to create target system requirements in an InstallScript project, use the SYSINFO structure to identify the
operating platform of the target system.
For information on how to specify target system requirements for InstallScript MSI projects, see Specifying Operating
System Requirements in the Project Assistant.
• Operating Systems—If a component is specific to one or more operating systems, use this setting to
indicate those operating systems. If the target machine's operating system does not match one of the
operating systems that are specified for this setting, the component is not installed.
By default, components are operating system independent, meaning that none of the component's
data are specific to certain operating systems.
The Operating Systems setting is available for InstallScript and InstallScript MSI projects. To access
this setting, open the Components view and select a component.
• Platform Suite(s)—If a component is specific to one or more platform suites, use this setting to
indicate the suites. If you specify more than suite, you can indicate whether all or any of the suites
must be present on the target machine in order for the component to be installed.
By default, components are platform suite independent, meaning that none of the component's data
are specific to a particular platform suite.
This setting provides an additional later of filtering beyond the Operating Systems setting. Set the
Platform Suite(s) setting only if necessary, and be sure to select only those platform suites that are
required for the proper functioning of your application. For example, if a component should be
installed on both the Home and Professional editions of Windows XP, you can leave Suite
Independent as the value for this setting; selecting Windows XP for the Operating Systems setting
encompasses both editions.
The Platform Suite(s) setting is available for InstallScript projects. To access this setting, open the
Components view and select a component.
• Language(s)—If a release is specific to one or more languages, use this setting to indicate the
languages. If the language specified for a component does not match one of the languages that is
selected for this setting, the component is not included in the release.
The Language(s) setting is available for InstallScript projects. To access this setting, open the
Releases view and select a release. You can also configure this setting through the Setup Languages
panel in the Release Wizard.
• Data Languages—If a release is specific to one or more languages, use this setting to indicate the
languages. If the language specified for a component does not match one of the languages that is
selected for this setting, the component is not included in the release.
The Data Languages setting is available for InstallScript MSI projects. To access this setting, open
the Releases view and select a release. You can also configure this setting through the Setup
Languages panel in the Release Wizard.
Controlling Support for Platforms, Platform Suites, and Languages at Run Time
for InstallScript Projects
During run time of InstallScript installations, you can control the platforms, platform suites, and
languages that your installation supports by calling the FeatureFilterOS and FeatureFilterLanguage
functions.
In the OnFilterComponents event handler, the framework typically calls these functions with the
platforms, platform suites, and languages that match the target system so that only the appropriate
components are installed. By calling FeatureFilterOS or FeatureFilterLanguage, you can override this
default behavior to install or prevent the installation of components based on any platform, platform
suite, or language criteria that you specify.
As you begin creating your installation project, you will need to specify important installation
information at the outset. Installation information can be defined by the high level properties and
considerations you need to set and determine about the organization in your installation. This includes
specifying product and project properties and configuring add or remove programs properties among
other tasks discussed in this section of the help library.
1. Go to the General Information view by clicking the General Information shortcut on the View
List.
2. Click Project Properties to display the property sheet on the right.
3. Select the property to edit by clicking its value field in the property sheet.
4. Enter a new value for the property or edit an existing value.
5. Press Enter to see the changes take effect.
Multi-Instance Only when the installation is rerun from Multiple—a separate entry for each
the Add or Remove Programs installation
You can select these options from the Maintenance Experience property in the Project Properties view.
If there are multiple instances of your application on a machine, when a non-silent update installation
for your application runs on that machine, it displays the Qualifying Product(s) Detected dialog. This
dialog allows the end user to select the instance to which the update should be applied. If the update
installation is silent, the update is applied to the first instance that is found, and the Qualifying
Product(s) Detected dialog is not displayed.
Note: The Maintenance Experience property works in conjunction with two other properties:
• Update Mode Supported (also in Project Properties of the General Information view)—If this property is set
to Yes, you cannot set the Maintenance Experience property to No uninstall or maintenance.
• Enable FLEXnet Connect (in the Update Notification view)—If this property is set to Yes, you cannot set the
Maintenance Experience property to No uninstall or maintenance.
In addition, if the Maintenance Experience property is set to No uninstall or maintenance, you cannot
set the Update Mode Supported property or the Enable FLEXnet Connect property to Yes.
Note: Your InstallShield project file (.ism) retains the .ism file extension when you save it in XML or Binary format.
Value Description
Yes Calls the Maintenance UI functions in your script. When an end user attempts to reinstall your
application or uninstall from the Add/Remove panel, the Program Maintenance dialog is
displayed.
No The Maintenance UI functions are not called in your script. When an end user installs your
application to a system that currently has your application installed, the application is uninstalled.
If the end user tries to uninstall your application from the Add/Remove Programs panel, the
application is uninstalled without displaying the Program Maintenance dialog.
Note: Setting this property to No affects the uninstallation only if the product is uninstalled via the Add/Remove panel. If
the product is uninstalled via Setup.exe, the Enable Maintenance property has no effect.
OnMaintenance Functions
OnMaintUIBefore
The OnMaintUIBefore event handler responds to the Maintenance UI Before event. It performs tasks
that must take place before the reinstallation of features for a maintenance installation of an application.
OnMaintUIAfter
The OnMaintUIAfter event handler responds to the Maintenance UI AFter event. It performs tasks that
must take place after the reinstallation of features for a maintenance installation of an application.
Options
Show only selected languages
If you want the Setup Languages pane to list only languages whose check boxes are selected, select this
check box.
Windows Installer databases (.msi and .msm files) are implemented as COM structured storage, and
COM structured storage files usually contain a Summary Information Stream. The Summary
Information Stream contains information about your company and the software being installed. For
more information, see Accessing the Summary Information Stream Panel to learn how to view your file’s
summary information.
For a description of each Summary Information Stream property, see Summary Information Stream
View.
Windows Logo Guideline: In order to achieve Designed for Windows logo, you are required to set these properties.
1. Right-click on the .msi file or .msm file and select Properties from the context menu.
2. Click the Summary tab to view the summary information.
Tip: You can also set the Template Summary property for a product configuration in the Releases view. Any value entered
in the Releases view overrides the value set in the General Information view.
Syntax
List the processor type first, followed by your installation’s default language. For language, enter any
four-digit language ID or 0 (zero) for language neutral.
• Separate the two categories with a semicolon.
• If you have multiple entries in the processor category—for example, Alpha and Intel—separate them
with a comma.
Caution: If your installation targets 64-bit machines, do not enter both Intel and Intel64 in this field. Doing so causes your
installation to fail. Also, if you enter Intel64, your installation will not run on 32-bit operating systems.
If the processor-type condition fails, the installer displays an error message and then exits.
To specify that the package is language-independent, you can use the syntax Intel; or Intel;0.
Leaving the first portion empty indicates that the package is processor-independent. If a language is not
specified, InstallShield provides the release languages in the Summary Information Stream.
If you have not entered a value for a particular Add or Remove Programs property, a sample value
appears in grey text. This value is meant to serve as an example and is not included in the final .msi
database.
The Add/Remove Programs view allows you to set much of the information that is displayed to the end
user through Add or Remove Programs in the Control Panel.
Project: In an InstallScript MSI project, you can specify that you want to hide your application’s entry in Add or Remove
Programs by selecting Yes for the Hide Add/Remove Panel Entry setting in the Releases view.
Note: These settings work only on systems running Windows 2000 or later.
Project: In a Windows Installer-based project, special formatting is required to properly display a path when the Readme
file is installed as part of your installation; see the following section. In an InstallScript project, enter a hard-coded path or
a URL, or specify a path relative to a system variable enclosed by angle brackets, for example,
<TARGETDIR>\Readme.txt. This data is written to the target system’s registry by the default OnMoveData event handler
function.
[$MyComp]Readme.htm. The path is not resolved because this property is merely setting the initial
value of the Windows Installer property ARPREADME, and formatted strings are never resolved for
Windows Installer properties.
InstallShield’s solution is to use a custom action to set ARPREADME with the value you enter in the IDE
for the Readme file. By setting it with the SetARPReadme custom action, the path is resolved during the
installation. For example, Readme.doc might be a file in the component Help_Files. In this case, enter
[$Help_Files]Readme.doc for the Add/Remove Programs property. Assuming Help_Files is installed to
C:\Program Files\MyCompany\MyProduct\Help, the path to the Readme in Add/Remove Programs
will read C:\Program Files\MyCompany\MyProduct\Help\Readme.doc.
Instead of the component name, you can use the file key. Do not use a folder from the Directory table
because it will not be resolved at run time. The file key is visible in the IDE under the Key column in a
component’s file list. The file key is not as reliable as the component name, because it is subject to
change if the files are dynamically linked or the release uses patch optimization. Continuing the example
above, if Readme.doc has a file key of F501_Readme.doc, enter [#F501_Readme.doc] for the Read Me
property. If it installed to the same folder, Add/Remove Programs will again display C:\Program
Files\MyCompany\MyProduct\Help\Readme.doc.
The custom action SetARPReadme is added every time the Read Me property contains a string and the
Installation Execute sequence contains the CostFinalize action. SetARPReadme is inserted into the
Installation Execute and User Interface sequences directly after CostFinalize.
1. Go to the General Information view by clicking the General Information shortcut on the
View List.
2. Click Product Properties to display the property sheet on the right.
3. Select the property to edit by clicking its value field in the property sheet.
4. Enter a new value for the property or edit an existing value.
5. Click elsewhere in the property sheet to see the changes take effect.
Caution: No validation is made during design time. Use valid syntax and double-check to ensure that your statements
evaluate to the expected outcome. For more information and example conditions, see Building Conditional Statements.
Windows Logo Guideline: According to Windows logo requirements, the default destination of your application’s files
must be a subfolder of the Program Files folder or the end user’s Application Data folder, regardless of the language of the
target system. If you use ProgramFilesFolder as the parent folder for your product’s Destination Folder property, your files
are installed to the correct location. The initial value for this property is [ProgramFilesFolder][company name]\[product
name].
Note: Selecting a new folder property from the drop-down list overwrites the contents of the edit box. You can specify a
subfolder of any folder property by separating subfolders with a backslash—for example, [ProgramFilesFolder]My
Company\Program.
Caution: Because the product code uniquely identifies your product, changing the code after distributing a release of
your product is not recommended.
• Under the informational registry key in accordance with Windows logo requirements. The
informational values are found in
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\<product
code>
and are used in the Add/Remove Programs panel to allow an end user to change or remove your
product.
Tip: In an InstallScript or InstallScript MSI project, you can use the UNINSTALL_DISPLAYNAME variable to specify a
different product display name in the user’s Add/Remove Programs panel.
Caution: If you want to include an ampersand (&) in your product name, you must use two ampersands (&&) to display the
name properly in end user dialogs. For example, to display “New & Improved Product”, you should enter the product name
as “New && Improved Product”.
Note: The MinVersion property of the Signature table finds only a file that is greater than that version. Therefore, if you
want to find 1.00.11, the value of your MinVersion property should be 1.00.10. The Windows Installer documentation
states this differently.
The installation registers the major and minor version numbers as required by Windows logo guidelines,
and the entire version string is displayed in Add or Remove Programs. The version number is important
because Windows Installer uses it in part to determine whether to apply an upgrade.
You can configure this setting in the Product Properties area of the General Information view.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The upgrade code is a string that is used to upgrade your application. Enter the string GUID in the
Upgrade Code field in the Product Properties View or click the Generate GUID button that appears
below the property sheet to generate a GUID. The setup registers this GUID as required by Windows
logo guidelines.
When you create a later version of your application to upgrade this version, enter this version’s upgrade
code GUID in the later version’s Upgrade table via the Upgrades view when you author a new upgrade
item.
Task To specify whether your installation should be logged each time that Windows Installer 4.0 is used to run it:
Task To customize the types of messages that are logged once you have set the Create MSI Logs setting to Yes:
1. In the View List under Behavior and Logic, click Property Manager.
2. Change the value of the MsiLogging property as appropriate. For a list of valid parameters for this
property, see MsiLogging Property in the Windows Installer Help Library that is posted to the
MSDN Web site.
InstallShield changes the value of the Create MSI Logs setting to Custom. Note that if you change it
from Custom to Yes, any custom parameters that you defined for the MsiLogging property in the
Property Manager will be overwritten with the default value. If you change it to No, InstallShield deletes
any custom parameters from the MsiLogging property.
Note: When you create a new Merge Module project, the name that you specify in the New Project dialog box should have
35 characters or fewer. This is because the name that you enter is used with the GUID in the ModuleID field of the
ModuleSignature table of your merge module file, and the limit for the object name portion of the ModuleID field is a
maximum of 35 characters.
Property Description
Version Type the complete version number for the merge module. The version number must contain
only numbers, and it must be in the format aaa.bbb.ccccc, where aaa represents the
major version number, bbb represents the minor version number, and ccccc represents the
build number. The maximum value for the aaa and bbb portions is 255. The maximum value
for ccccc is 65,535.
Application Type Select the type of application from the list or type the name of an application type if it is not
listed. This information is stored in the project file and is for your reference only. It is never
displayed to the end user.
Table 10-3: Merge Module Settings in the General Information View (cont.)
Property Description
INSTALLDIR Specify the default destination folder where this merge module’s files will be installed.
Instead of hard-coding a path, you can select a Windows Installer folder property (in square
brackets) from the list.
Separate further levels of subfolders with a backslash—for example:
[ProgramFilesFolder]MyApp\Bin
The value you enter here is assigned to the property INSTALLDIR, which is the default
destination folder for all of your merge module’s components.
Note: If you would like to let the users of this module override the default destination
directory, select [TARGETDIR] in this field.
To comply with Windows logo requirements, your application’s default destination must be a
subfolder of the Program Files folder, which can vary depending on the system’s locale and
user settings.
If you specify [ProgramFilesFolder], as in the default value for the INSTALLDIR property, then
this module’s files are always installed to the correct location.
Module ID GUID This property shows the GUID for the merge module. To generate a new GUID, click this
property, and then in the pane at the bottom of the view, click the Generate GUID button.
Note: In merge modules, the Package Code and Merge Module GUID are separate. The
Package Code is stored in the Summary Information Stream. The Module ID GUID is stored
in the ModuleSignature table.
The ModuleID column has the module signature the following format:
YourMergeModule.<some GUID>. This corresponds to the <some GUID> that appears in
the ModuleSignature table.
The Module ID GUID is appended to all merge module GUID foreign keys. For example, if you
create a component in a merge module project and look in the Direct Editor, you will see
ComponentName.<some GUID>. This <some GUID> corresponds to the GUID in the
ModuleSignature table.
Windows Logo Guideline: According to Windows logo requirements, you must install your merge module’s files to a
subfolder of the [Program Files] folder, regardless of the language of the target system. If you use ProgramFilesFolder as
the parent folder for your merge module’s Destination Folder property, your files will be installed to the correct location.
The initial value for this property is [ProgramFilesFolder]Your Company Name\Your Product Name.
Caution: When creating a typical MSI setup, merge modules are automatically associated with your setup when you add a
file that is already contained within a merge module. When you are creating a merge module and you add a file that is
already contained within another merge module, you will receive a Setup Best Practices alert telling you to set that merge
module as a dependency. The IDE does not create the dependency for you.
1. Expand the Merge Module Properties node in the General Information view.
2. Click Module Dependencies to display the Module Dependencies view.
3. In the Local Gallery section, right-click the desired merge module and choose Select. The selected
merge module is added as a dependency, and its data appears in the Module Dependencies grid.
1. Click the grid cell labeled Click here to add a new item (or right-click the grid and select New).
2. Complete the Name, Version, Language, and Module ID fields manually.
Note: Be careful when entering the Module ID, as the IDE does not check to ensure that this is correct. You will not know if
it fails until you try to run the installed program.
Dependency information entered in the Module Dependencies view is written to your project’s
ModuleDependency table, which you can view using the Direct Editor.
1. Expand the Merge Module Properties node in the General Information view.
2. Click Module Exclusions to display the Module Exclusions view.
3. In the Local Gallery section, right-click the desired merge module and choose Select. The selected
merge module is added as a dependency, and its data appears in the Module Exclusions grid.
1. Click the grid cell labeled Click here to add a new item (or right-click the grid and select New).
2. Complete the Name, Max. Version, Min. Version, Language, and Module ID fields
manually.
Tip: Select Language Independent to allow your module to run on all languages.
You can set this property in the Merge Module Properties view.
The primary task of an installation is to transfer files from your distribution media to your end user’s
hard drive. In an InstallShield installation, files are organized in a hierarchy: files are included in
components; components are associated with features (and optionally subfeatures); and, in InstallScript
and InstallScript MSI installations, features are associated with setup types.
At run time, your end user simply selects the setup type—or, if you allow it, the features and
subfeatures—that he or she wishes to install. End users do not see components, which you use to group
your files according to their type and purpose. For example, files that are installed to the same target
folder can be placed in the same component, as can self-registering files.
A file often relies on functions in other files to perform a task. However, you may not be aware of all
these other files—known as dependencies—when you include your application’s files in your project. To
help you identify dependencies, InstallShield offers three dependency scanners that automatically add
these files to your project.
In addition to including individual files in your project, you can also include redistributables (merge
modules and InstallShield objects), which contain logic and files needed to install distinct pieces of
functionality. For example, to include Microsoft Visual Basic run-time files in your installation, you can
simply associate the Microsoft Visual Basic Virtual Machine merge module with one of your project’s
features.
Designing Installations
There are two main perspectives in an installation project—that of the developer and that of the end
user. In InstallShield, these perspectives are addressed in detail in the Components and Features views,
respectively.
Components
Components represent the developer’s view of the product. They are installation authoring tools that
help the developer organize similar application data—such as files, registry entries, and shortcuts—into
logical groups.
To enable the end user to choose which features to install, you should divide your application into
components that correspond with the features of your application.
Using InstallShield, you can also publish your project’s components.
Note: The conditions that you specify for the Publish Components, Publish Features, or Publish Product actions are not
validated during design time, so use proper syntax and check to ensure that the condition produces the expected
outcome.
Features
Features are the building blocks of an application from the end user’s perspective. Each feature
represents a specific piece of functionality for your product—such as the help files. End users should be
able to install and uninstall discrete features of your product.
For example, an end user with limited hard drive space could elect not to install a product tutorial. If the
user subsequently purchases another computer or frees resources on an existing one, the previously
uninstalled product tutorial could then be installed.
You should separate your application into features that correspond to the components of your
application.
• Windows Installer requires that every file in a component be installed to the same directory. If you
need to install a directory structure, each subdirectory must correspond to a separate component.
• The resources in a component should require the same conditions.
• To take full advantage of Windows Installer repair functionality, each .exe, .dll, and .ocx file should
be placed in its own component, and each should be the component’s key file. The Best Practices
option of the Component Wizard can create components for you using this rule.
• Similarly, each .chm or .hlp file should be placed in its own component, along with any
corresponding .chi or .cnt file.
• No resource should be included in more than one component, even across products. If a
component’s resources are required by more than one product, consider creating a merge module
with the shared resources.
• When mapping a component to one or more features, ensure that all parts of a component map to
the features.
• When testing your installation, you may want to divide your application into several components to
thoroughly measure its performance.
• To eliminate confusion, keep any information pertaining to the management of the system or
application transparent to the user.
Note: Path variables are used during the development of your installation project. These paths do not apply to the target
machines where the application is being installed. Rather, they are used to link to source files for your installation project.
When the project is built, those links are evaluated and the files they point to will be built into the installation.
InstallScript Path
Predefined Path Variable Value Variable
<ISProductFolder> C:\Program
Files\Macrovision\IS2008
Project: Windows Installer based projects only: The Path Variable Recommendation dialog box enables you to specify
whether you want to use predefined path variables. This dialog box is launched if you enter a hard-coded path when
inserting a source file into your installation and you have selected the Always display the Path Variable Recommendation
dialog to me check box on the Path Variables tab of the Options dialog box. If you enter a path that is included in a
predefined path variable, InstallShield suggests that you use the path variable rather than the hard-coded path.
You can also use predefined path variables when defining the value for a standard path variable. You
may want to define a standard path variable to a subfolder of a predefined variable. For example,
<ProgramFilesFolder>\Macrovision could be used as the value for a standard path variable.
Predefined path variables are smart variables. This means they are set to the correct directory, even if
your WINNT directory is located on your D drive instead of your C drive. If you change the default
project location on the File Locations tab of the Options dialog box, InstallShield updates this variable to
reflect the new directory.
Column Description
Name Enter the name of your variable in this column. You do not need to enter angle
brackets, but the path variable will appear in brackets whenever it is used in a
path.
For example, if your variable is named MyRegVar and a component’s files are
linked to the folder contained in its value, the component’s Link To folder will
read <MyRegVar>.
Column Description
Defined Value In this column, define the value of the path variable.
Note: You can also refer to other path variables in the defined value by
enclosing the referenced path variable name in angled brackets. For example, if
you have a path variable called MyRoot with a value of C:\, you can refer to it in
a path variable definition for another variable, such as Games. The actual path
for the Games variable might be C:\Programs\GameFiles, but you can define
Games as <MyRoot>\Programs\GameFiles. However, if you attempt to self-
reference a path variable, the literal string is used instead. For example,
defining Games as <MyRoot>\Programs\<Games> actually results in Games
defined as C:\Programs\<Games>.
Current Value This is a read-only column containing the actual path that the variable points to.
This is a useful reference for environment and registry path variables, since they
are defined outside InstallShield.
Column Description
Type Double-click ia field n this column to view a list of possible path variable types.
Environment Variables
Environment path variables enable you to define your own path variables based on certain values on the
Environment dialog box.
1. Right-click My Computer and click Properties. The System Properties dialog box opens.
2. On the Advanced tab, click Environment Variables.
A common scenario where environment path variables may be useful is when performing a build from
the command line. If you do nightly builds on a machine dedicated to that purpose, you may need to
change the path variables from the command line. While this is not directly supported with
InstallShield, you can change the value of environment variables from the command line. As long as you
use environment path variables, you can define the paths to your project’s files from either a batch file or
the command line. These paths are evaluated when the installation project is built, and the correct paths
to the files will be used.
When you are adding files to components in Windows Installer–based projects, you should be aware of
Setup Best Practices. By default, the Setup Best Practices Wizard monitors your setup design and alerts
you if you have violated Best Practices.
You can add files to your project in the Setup Design view (for installation projects) or the Components
view, and in the Files and Folders view.
Files Explorer
The Files and Folders view contains a file explorer that allows you to drag and drop files from folders on
your source machine to folders on the destination machine. The two left panes in the files explorer
contain folders and the two right panes display the files located within those folders.
Note: In installation projects (including InstallScript and Basic MSI), the Files and Folders view includes the Add new
components to the feature list above the file explorer panes. This list contains all of the features in your project. When you
add files in this view, new components may need to be created. From this list, select the feature with which you want to
associate these new components.
Tip: You can specify how INSTALLDIR is displayed in the Destination computer’s folders pane of the Files and Folders
view by setting your preference on the Directory tab of the Options dialog box.
Alternately, you can drag an entire folder onto one of the destination folders, thereby adding a new
subfolder to the target folder that contains the source folders files. This new subfolder has the same
name as the source folder.
Task To display the components in your installation and the files that are associated with them:
Note: (Windows Installer–based projects only) You can launch the Component Wizard by right-clicking a folder icon and
then clicking Launch Component Wizard.
Table 11-3: Commands Available from the Context Menu in the Files and Folders View
Command Description
Add Adds the folder, subfolders, and/or files selected. This is the
same as the default drag-and-drop behavior.
Add Preserving Source Adds the selected folder, subfolders, and/or files while
Structure preserving the file/folder structure found on the source
computer.
This command is available only if the source folder matches
a predefined Windows destination folder. In addition, the
destination on which you drop the file or folder must be the
Destination Computer.
Add Folder(s) Only Adds only the folders selected and any subfolders contained
in the selected folder. Does not add any files contained
within the selected folders or subfolders.
Add Folder(s) Only Preserving Adds only the folders selected and any subfolders contained
Source Structure in the selected folder. Does not add any files contained
within the selected folders or subfolders. This option also
preserves the folder structure found on the source
computer.
This option is available only if the source folder matches a
predefined Windows destination folder. In addition, the
destination on which you drop the file or folder must be the
Destination Computer.
File Properties
You can set a number of properties for each file that is to be installed on the target system.
Tip: The recommended method for installing self-registering files with Windows Installer is to write the registration
information to the .msi database tables (Class, ProgID, and others). Instead of marking a file as self-registering, you can
use the component’s advanced settings, extract the COM information at build time, or extract the COM information when
you add a file in the Files and Folders view in order to register the ProgIDs, type libraries, and so on. Using the advanced
settings works whether you are installing the file in the installation or advertising it for “just-in-time installation.” A further
advantage is that the file can be unregistered if the installation fails.
Even if you set the component’s COM Extract at Build property to No, any information that is contained
in the COM Registration advanced setting will nonetheless be registered during installation. You might
want to check the COM Registration advanced setting and the component’s registry data to verify that
the entries are intentional and do not conflict with those made by the self-registration functions.
File Associations
Project: This information does not apply to InstallScript or InstallScript Object projects.
File associations are registry settings that tell Windows what application to use to open files of a certain
type. For example, Windows typically launches Notepad.exe when a text (.txt) file is opened.
To view and modify registered file types on your system, open Windows Explorer, and on the Tools
menu, click Folder Options. Use the File Types tab of the Folder Options dialog box to see how the file
associations are configured.
Similarly, you can identify the application that is associated with a given file by right-clicking the file in
Windows Explorer and then clicking Properties.
On Windows NT 4 and Windows 9x systems, file association information is stored under the root
HKEY_CLASSES_ROOT. On systems running Windows 2000 or later, file associations are stored in
both HKLM\SOFTWARE\Classes and HKCU\SOFTWARE\Classes; you can see a merged view of the
data under HKEY_CLASSES_ROOT.
appropriate part of the registry, and the entry links your file type to your application through the
ProgID. The ProgID, which is sometimes called a file type’s application identifier or tag name, uniquely
identifies your application and ensures that your association is recognized by the operating system.
Project: This information does not apply to InstallScript or InstallScript Object projects.
If your application manipulates files with a unique file extension, you can register your file type. For
example, if your application manipulates files with the .xyz extension, registering the file type instructs
the operating system to open the file with your application when the user double-clicks its icon.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
5. In the File Types explorer, right-click Extensions and click New Extension. InstallShield
creates a new extension with the default name New ExtensionN, where N is a unique number.
6. Type your extension without the dot (for example, enter ext instead of .ext).
Project: This information does not apply to InstallScript or InstallScript Object projects.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
5. In the File Types explorer, right-click the extension and click Delete.
Project: This information does not apply to InstallScript or InstallScript Object projects.
The extension properties determine the registry entries for your file extension, as well as the ProgID
associated with it. Detailed help is available in the help pane in InstallShield when you click each
property.
Project: This information does not apply to InstallScript or InstallScript Object projects.
By default, the verb open is added to your file extension.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
5. In the File Types explorer, right-click the extension and click New Verb. InstallShield creates a
new verb with the default name New VerbN, where N is a unique number.
6. Type the name of your new verb. You can use any of the canonical verbs, such as open, print, find,
and properties.
7. Select the new verb to edit its properties. Its property sheet opens to the right.
Project: This information does not apply to InstallScript or InstallScript Object projects.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
Project: This information does not apply to InstallScript or InstallScript Object projects.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
5. In the File Types explorer, right-click the extension and click New MIME Type. InstallShield
creates a new MIME type with the default name MIME TypeN, where N is a unique number.
6. Type the MIME type; for example, image/jpeg.
Click the MIME type to view its Class ID property. Click the Class ID property to edit it in the lower pane.
Press CTRL+V to paste a class ID into the property field.
Project: This information does not apply to InstallScript or InstallScript Object projects.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
5. Right-click the MIME type and click Delete.
Creating ProgIDs
Project: This information does not apply to InstallScript or InstallScript Object projects.
The ProgIDs item in the File Types explorer contains all of the programmatic identifiers—ProgIDs, also
known as application identifiers or tag names when they support file types—that you want to associate
with file extensions. A file type’s ProgID is an arbitrary string, but it should be unique on the target
system. One ProgID naming convention is to append the word file to your extension without a dot—the
.ext extension might use the ProgID extfile. Another convention is to name a file-type ProgID after the
application used to open the file type, as in SampleApp.Document.
For example, an .xyz file extension could point to a xyzfile ProgID, and all of the .xyz file-type
information would be registered under xyzfile.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
5. In the File Types explorer, click the extension. The extension properties are displayed in the right
pane.
6. In the ProgID property, type the name of your ProgID. InstallShield adds your ProgID under
ProgIDs in the File Types explorer.
7. In the File Types explorer, click the new ProgID and then set its properties.
Removing ProgIDs
Project: This information does not apply to InstallScript or InstallScript Object projects.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click File Types. The File Types explorer opens.
5. In the File Types explorer, click the extension. The extension properties are displayed in the right
pane.
6. In the ProgID property, delete the ProgID.
Destination Folders
When you add files to your installation project, you do so by placing them in a destination folder. The
following destination folders are provided by default. Each one is dynamic, meaning that they do not use
hard-coded paths. Instead, the value for each destination folder is obtained from the operating system of
the target machine.
The following folders are available only for InstallScript projects:
Script-Defined Folders This folder allows you to create folders whose location is determined in
your script. Files cannot be added directly to this folder, but only to its
subfolders; to create a subfolder, right-click the folder and select New
Folder. Specify a folder name that is enclosed in angle brackets, for
example, <MYFOLDER>; to assign the folder a location through your script,
call FeatureSetTarget.
Application Target Folder This folder’s location is determined by the value of the system variable
TARGETDIR.
Program Files This folder’s location is the 32-bit Program Files folder.
Program Files (64-bit) This folder’s location is the 64-bit Program Files folder.
Program Files\Common Files This folder’s location is the 32-bit Common Files folder.
Program Files (64-bit)\Common Files This folder’s location is the 64-bit Common Files folder.
(64-bit)
Support Folder This folder’s location is determined by the value of the system variable
SUPPORTDIR.
Windows\Windows System This folder’s location is the 32-bit Windows System folder.
Windows\Windows System (64-bit) This folder’s location is the 64-bit Windows System folder.
The following folders are available only for Basic MSI and InstallScript MSI projects:
Table 11-5: Default Destination Folders for Basic MSI and InstallScript MSI Projects
AppDataFolder This property holds the full path to the current user’s Application Data
folder. A typical value of this property is as follows:
C:\WINNT\Profiles\UserName\Application Data
Table 11-5: Default Destination Folders for Basic MSI and InstallScript MSI Projects (cont.)
CommonAppDataFolder This is the full path to the folder containing application data for all users. A
common path is:
CommonFiles64Folder The value of this property is the full path to the 64-bit Common Files folder.
This property requires Windows Installer version 2.0 or later.
CommonFilesFolder The value of this property is the full path to the 32-bit Common Files folder.
DesktopFolder This property is used to hold the full path to the Desktop folder for the
current user. If the setup is being run under Windows NT 4 or Windows
2000 or later for All Users, and the ALLUSERS property is set, then the
DesktopFolder property should hold the full path to the All Users desktop
folder.
FavoritesFolder The FavoritesFolder property contains the full path to the Favorites folder
for the current user.
FontsFolder This property holds the full path to the Fonts folder.
IISROOTFOLDER This property stores the root directory of the Web server on a target
system. If you are using IIS functionality in your installation project and you
have added a Web site, then IISROOTFOLDER is automatically added.
For more information, see Adding IISROOTFOLDER Support.
INSTALLDIR This property stores the default destination folder for your installation
program’s files. You can set an initial value for INSTALLDIR in the General
Information view.
LocalAppDataFolder The location of locally stored application data. A typical value for this
property is:
MyPicturesFolder Full path to the current user’s MyPicturesFolder, which is commonly in the
following location:
PersonalFolder This property holds the full path to the current user’s Personal folder.
ProgramFiles64Folder This property holds the full path to the 64-bit Program Files folder. This
property requires Windows Installer version 2.0 or later.
ProgramFilesFolder This property holds the full path to the 32-bit Program Files folder.
ProgramMenuFolder This property is used to hold the full path to the Program menu for the
current user. If the installation is being run under Windows NT 4 or Windows
2000 or later for All Users, and the ALLUSERS property is set, then the
ProgramMenuFolder property should hold the full path to the All Users
Programs menu.
Table 11-5: Default Destination Folders for Basic MSI and InstallScript MSI Projects (cont.)
SendToFolder This property holds the full path to the current user’s SendTo folder.
StartMenuFolder This property is used to hold the full path the Start menu folder for the
current user. If the installation is being run under Windows NT for All Users,
and the ALLUSERS property is set, then the StartMenuFolder property
should hold the fully qualified path to the All Users program menu.
StartupFolder This property is used to hold the full path to the Startup folder for the
current user. If the setup is being run under Windows NT 4 or Windows
2000 or later for All Users, and the ALLUSERS property is set, then the
StartupFolder property should hold the full path to the All Users program
menu.
System16Folder This property holds the full path to the folder containing the system’s 16-bit
.dll file. (In Windows Installer version 2.0, this property is no longer used.)
SystemFolder This property holds the full path to the 32-bit Windows system folder.
System64Folder This property holds the full path to the 64-bit Windows system folder. This
property requires Windows Installer version 2.0 or later.
TempFolder This property holds the full path to the Temp folder.
TemplateFolder This property holds the full path to the current user’s Templates folder.
WindowsFolder This property holds the full path to the Windows folder.
WindowsVolume This property holds the volume of the Windows folder. It is set to the drive
where Windows is installed.
1. Right-click a folder and click New Folder, or click a folder and press INSERT.
2. For the name of the folder, type the destination path—for example, a\b\c. This creates a folder
structure with a at the top, b below a, and c below b.
• You cannot set any properties such as Shared, Permanent or Never Overwrite for a dynamically
linked file.
• You cannot change default file settings (such as Read-Only or Hidden).
• You cannot launch a dynamically linked file from the Setup Complete Success end-user dialog.
Note: Before you define any file links in an installation project, you should select the proper feature from the list at the top
of the view. Because files are added to components, new components may be created for you when files are added to
your installation. Select the feature with which you want to associate these new components.
3. For a Windows Installer–based project: right-click a component and click Dynamic File Linking.
The Component Properties dialog box opens.
For an InstallScript-based project: right-click a component and click File Linking. The Link Type
dialog box opens.
4. Define the dynamic link and click OK.
Project: In an InstallScript project, a single component cannot contain both static and dynamic file links.
InstallScript Projects
5. Click OK.
Note: This information does not apply to InstallScript and InstallScript Object projects.
ExampleFeature
ExampleComponent
Files
If you have enabled path variable recommendation, you will be prompted for a path variable that
represents this path.
Select the Include subfolders check box. Data Files contains the subfolders and files shown below:
Data Files
blank.gif
blue.gif
Othello.exe
red.gif
Readme
Deutsch.txt
English.txt
Polski.txt
Click OK in the dialog box to accept the rest of the default settings.
Notice that only the files in the root of Data Files are added to ExampleComponent’s file list, which
should resemble the following list:
blank.gif
blue.gif
Othello.exe
red.gif
Note: Because the components corresponding to subdirectories in the dynamic link are generated at build time, they are
not displayed in InstallShield. Instead, files contained in subdirectories will be displayed in the Files list after the
subdirectory name, as in:
Blank.gif
Blue.gif
Readme\Deutsch.txt
Readme\English.txt
Readme\Polski.txt
Note: Windows Installer does not support the concept of subcomponents. When you include subfolders in a dynamic file
link, standalone components are created for each subdirectory.
Project: Components in InstallScript and InstallScript Object projects do not have key files.
A file contained in a dynamic link cannot be the key file of a component.
To set a key file for a component containing a dynamic link, add a static link to the desired file, and then
set the static link to be the key file of the component. In the dynamic link settings, enter the full name of
the key file in the Exclude files with the following extensions field.
For example, you might have a source directory containing several .txt files, and you want the file called
Key.txt to be the key file. First, add a static link to Key.txt to a component, and set Key.txt as the key file.
Next, create a dynamic link with the same source folder, setting the Include files with the following
extensions setting to *.txt and the Exclude files with the following extensions setting to
Key.txt.
For a dynamic link that includes subdirectories, the build process sets the first file in a subdirectory’s
component as the key file of the dynamically generated component.
Task To change a component’s file linking from dynamic or static (or vice versa):
Note: Within a component, file links must be either static or dynamic. A single component cannot contain both static and
dynamic file links.
• File Language—All other things being equal, the file that is the same language as the installation is
maintained over different language versions of the file. The only exception to this rule applies to
multiple language files. Files with multiple languages are maintained over single language versions
of a file.
• Date—If the modified date of a file already present on the target machine is later than the creation
date of that file, the file is not overwritten. This rule protects user preference files from being wiped
out during an upgrade or reinstallation.
Windows Installer installs components as a whole, so the comparisons described above are performed
on the key file of each component under consideration. If it is determined that the key file should be
installed, all the data in the component will be installed.
Note: The REINSTALLMODE property can be set to modify the default file-versioning rules. For details, see the Windows
Installer Help Library.
Companion Files
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The use of companion files enables you to bind the installation action of one file to another file. For
example, if your installation project has two files—FileA.exe and FileB.dat—companion files let you
bind FileB.dat to FileA.exe so that if FileA.exe needs to be installed or reinstalled, then FileB.dat is
also installed or reinstalled. If FileA.exe needs to be uninstalled, then FileB.dat is also uninstalled.
1. In the Files and Folders view, add the versioned file to your project.
2. Open the Components view.
3. In the Components explorer, expand the component that contains the file that you just added, and
then click Files. Note the value in the Key column for that file.
4. Right-click the file and then click Add.
Note: InstallShield generates a unique file key every time you add a file. Therefore, if you remove the file that you have
created a binding to, it is possible that the file key will not persist. You would need to update the version of the unversioned
file.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The Lock Permissions table is used to secure individual portions of an application in a locked-down
environment. It can be used with the installation of files, registry keys, and created folders.
Access the Lock Permissions table by clicking the Permissions button in a particular folder’s or file’s
Properties dialog box. You can also access the Permissions option through the context menu of any
registry key or by clicking the browse button in the Destination Permissions field from a component’s
property grid.
Note: Because permissions require NTFS partition, they work only on Windows NT, 2000, or XP systems.
Names
From the Names grid, you can enter any combination of Domain and User names.
Note: To add an entry, right-click the grid and click New. You can modify or delete entries using the same context menu.
You can enter [%USERDOMAIN] in the Domain field to represent the current user’s domain, and
[LogonUser] (or any other property name in square brackets) in the User field to represent the user
running the installation.
Permissions
In this section, select the permissions that you want to set for the file or folder. These permissions are
the same ones that appear in the Windows OS when setting permissions. Once you make a selection, you
can click Advanced to specify other permissions associated with the high level one that you initially
select.
For more information about lock permissions, see LockPermissions Table in the Windows Installer Help
Library.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
When you drag and drop new files in the Files and Folders view or in the Files subview under a
component, you can statically extract COM data for self-registering files. This is an alternative to
extracting COM registration data at build time.
This option is also available in the COM Registration node under Advanced Settings in the Components
view.
Right-click the file (or in the COM Registration node, right-click COM Registration) and click
Extract COM Data for Key File.
Note: This option is enabled only if the file is an .exe file or a file that is self-registering, and if the file is the component’s
key file.
Project: This information applies only to InstallScript and InstallScript Object projects.
When you include a font file—.ttf, .ttc, or .fon file—in your installation project (using either the
Components view or the Files and Folders view), the file is automatically marked internally to be
registered on the target machine if you have enabled global font registration. At run time, the
OnInstalledFontFile event handler function is called immediately after each font file is installed; the
default code for this event handler function calls the RegisterFontResource function to register the font if
it is internally marked for registration.
Font Titles
InstallShield determines the font title that the installation registers for the font in the following manner:
• For an .fon file, InstallShield—by default—reads the font title from the registry of the source system.
If no title can be found in the registry, InstallShield stores the file name as the font title. For an .fon
file in a component whose Link Type property is set to Static, InstallShield displays the font title in
the Font title box on the file’s File Properties dialog box.
• For a TrueType file (.ttf or .ttc file), by default the installation reads the font title from the file at run
time, and at design time no text is displayed in the Font title box.
• For all three types of files, in a component whose Link Type property is set to Static, if you enter
non-default text in the Font title box, the installation registers that text as the font title.
Project: This information applies only to InstallScript and InstallScript Object projects.
Task To install a font file to the Windows font folder, do either of the following:
• In the Files and Folders view, place the font file in the Destination computer’s folders pane’s
Fonts Folder folder, which is a subfolder of the Windows folder.
• In the Components view, place the font file in a component whose Destination property is set to
<FOLDER_FONTS>.
Project: This information applies only to InstallScript and InstallScript Object projects.
You can enable or disable automatic registration of font files globally.
Project: This information applies only to InstallScript and InstallScript Object projects.
You can enable or disable automatic registration of font files for individual files.
1. Open the Components view, Setup Design view, or Files and Folders view.
2. Right-click the font file and click Properties. The Properties dialog box opens.
3. To enable automatic registration of the font file, select the Register Font File check box.
To disable automatic registration, clear the Register Font File check box.
4. Click OK.
Using Components
Components are elements of the application from the installation developer’s perspective. Components
are not visible to the end user. When the user selects a feature for installation, the installer determines
which components are associated with that feature and then those components are installed.
Components of an application would contain the executable binary files, data files, shortcuts, help
system files, and registry entries.
You can create and modify components in the Setup Design view (for installation projects) or the
Components view.
Component-Feature Relationships
Files
Expand a component’s tree in the Setup Design view or the Components view and click Files to view a
list of all files associated with that component. To learn how to add files, see Adding Files to
Components.
Project: This information does not apply to InstallScript or InstallScript Object projects.
InstallShield makes adhering to Setup Best Practices easier by alerting you to Best Practices violations
while you are creating components in the Setup Design view and in the Component Wizard. By following
these guidelines, you can create clean installations that distribute reusable components efficiently and
avoid problems that result from file incompatibility.
When you are creating components in the Setup Design view, the Setup Best Practices Wizard monitors
the files that you add to the components, alerts you when you have done anything that conflicts with
Best Practices, and then gives you the opportunity to correct the action in the wizard. To turn off the
wizard’s automatic scanning of your setup design, select Options from the Tools menu.
InstallShield checks for compliance with the following Setup Best Practices:
Components should not contain Each component should contain only one portable
multiple .exe, .dll, .ocx, .chm, or executable file (an .exe, .dll, or .ocx file) or WinHelp file (.hlp
.hlp files file). Windows Installer components are designed such that
all of the advanced settings and component properties, such
as the GUID code, refer ideally to a single portable
executable file or help file. Place other .exe, .dll, .ocx, and
.hlp files into new components.
One reason for this rule is that, at run time, if the user
chooses Repair for an installed product, Windows Installer
checks for the existence of each installed component’s key
file. If the key file is missing, Windows Installer reinstalls the
missing component. Therefore, if a file that is not the key file
of a component is missing, it is not restored during repair
mode.
Use merge modules Merge modules contain all of the files, registry entries, and
logic necessary to install a distinct piece of functionality. You
should not distribute a file for which a merge module is
available. Using merge modules also helps you comply with
two related requirements—the Best Practice to avoid
associating a file with more than one component and the
Windows logo guideline not to ship any core components.
If the Best Practices monitoring option is enabled, the Setup
Best Practices Wizard alerts you whenever you try adding to
a component any file that is part of the merge modules that
InstallShield provides.
You should also be aware of the following component creation Setup Best Practices, to which
InstallShield does not automatically alert you:
Table 11-7: Setup Best Practices for which InstallShield Does Not Automatically Provide Alerts
Put a shortcut target in its own Any file that serves as the target for a shortcut requires its
component own component. That file must be the key file for the
component.
Group other files into Organize all files that do not fall into any of the above
components categories in components according to the files’
requirements, such as a common destination folder or
version checking.
Table 11-7: Setup Best Practices for which InstallShield Does Not Automatically Provide Alerts (cont.)
Component Creation
You can create an installer component in one of the following ways:
• User—Create a new component in the Setup Design view (in installation projects only) or the
Components view.
• Easiest—Use the Component Wizard to allow InstallShield to define components for you according
to Setup Best Practices.
• Recommended—Use the Component Wizard to select a component type and then define your
component manually.
Creating Components
For installation projects, you can create a new component in the Components view and then associate it
later with a feature, or you can create a component under a specific feature in the Setup Design view, as
described below. Note that the Setup Design view is not available in merge module projects.
Note: In installation projects, components that are not associated with a feature are displayed with the orphaned
component icon ( ).
In InstallScript projects, the following characters are invalid in component names:
\ / : * ? " ’ < > |
When you create a component, its property sheet is displayed to the right. You should immediately
specify the component’s properties, including the required Component Code (Windows Installer–based
projects only) and Destination properties.
After you have created a component and specified its properties, you can associate your application’s
files, registry entries, and shortcuts with it.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. Right-click the component and click Delete from project.
The component is permanently deleted from your project.
Component-Feature Associations
A component can be associated with as many features or subfeatures as necessary. For example, a text
editor product might have two features—an editor and a spell checker. Both the editor and spell checker
have dependencies that are in a System .dll files component. When designing this installation, you
should associate the System .dll files component with both the editor and the spell checker features.
You can associate components with features in the Setup Design view. There are two ways to associate
components with features in the Setup Design view, depending on whether or not the component
already exists. For more information, see Associating New Components with Features and Associating
Existing Components with Features.
Note: Components that are not associated with a feature are displayed with the orphaned component icon:
• To copy an existing component, press CTRL while you drag the component from one feature to
another.
• All files should be installed with the same conditions (including operating system and language).
Create new components organized around your files’ installation needs and component properties. You
should also be aware of Setup Best Practices when adding files to a component. Setup Best Practices
ensure that you write clean installations and distribute reusable components effectively.
Task Use one of the following methods to associate files with this component:
• Drag and drop files from Windows Explorer onto the file list.
• Right-click in the file list and click Add. In the resulting dialog box, browse to select as many files as
you want to add from that folder. Click Open.
Task Use one of the following methods to associate files with this component:
• Drag and drop files from Windows Explorer onto the file list.
• Right-click in the file list and click Add. In the resulting dialog box, browse to select as many files as
you want to add from that folder. Click Open.
InstallShield creates links to your application’s files. These links are used to locate the files when you
build a release of your installation. If any of these links becomes invalid, File Not Found appears next to
the file.
All of the above methods for adding files link the files statically, which means that the file links do not
change if new files are added to or removed from the source folder. For an alternative to static linking,
see Adding Dynamic File Links to Components.
Project: For installation projects, you can create shortcuts in the Shortcuts view.
Before you can create a shortcut, you must create a component that contains the file to which the
shortcut is going to link.
Project: This information does not apply to Basic MSI projects or InstallScript MSI projects.
In the Components or Setup Design view, right-click the component’s Static File Links subnode
and then click New Folder.
Project: This information does not apply to InstallScript or InstallScript Object projects.
Both components and features have a destination property, but there are some differences in how they
are used when an end user runs your installation.
Note: If you want all the components in a feature to be installed to the feature’s destination, you must set all of the
components’ destinations to match the feature’s destination.
Windows Logo Guideline: According to Windows logo requirements, the default destination of your application’s files
must be a subfolder of the end user’s Program Files folder. If you use INSTALLDIR or ProgramFilesFolder as the parent
folder for your feature’s Destination property, your files will be installed to the correct location.
1. Select the component in the Components view or the Setup Design view (for installation
projects) to open its property sheet.
2. Click the Destination property to display a list of available destinations.
3. Select a Windows Installer folder property (in square brackets) from the list or select Browse,
create, or modify a directory entry to display the Browse for Directory dialog box.
The changes that you make are reflected in the property sheet.
Note: If the component’s destination is set to something other than INSTALLDIR, the components are installed to the
destination specified for each component and changing INSTALLDIR has no effect on the components’ destinations.
An installer folder property such as INSTALLDIR specifies a default value. An end user can change this value by setting a
property when launching Msiexec.exe at the command line or by selecting a new destination folder for a feature in the
Custom Setup dialog.
Note: To install an assembly to the Global Assembly Cache, the .NET Scan at Build component property must be set to
either Properties Only or Dependencies and Properties.
Task To specify the target destination of a component’s files from the script:
b. In the component’s property grid, click the value of the Destination property and in the list,
select the name of the subfolder that you created in step 1.
To create a new component and specify the target destination of its files:
a. In the Files and Folders view, drag the desired file or files from the Source computer’s
folders pane and drop them on the subfolder that you created in step 1. InstallShield creates a
new component with the default name FilesN.
b. In your script, call FeatureSetTarget to assign a target location to the subfolder that you created
in step 1; for example:
AskDestPath( "" , "Choose a location for the XYZ files." , svEndUserSelectedPath, 0 );
ComponentSetTarget( MEDIA , "<My Script-defined Folder>" , svEndUserSelectedPath);
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component and click Files.
3. Right-click in the files list and click Set Key File. The file icon ( ) for that file is replaced with a
key icon ( ).
A component can have either one key file or one key path. If you have already set a key file or a key path
for a component, a warning message box appears if you try to set another key file. Click Yes in the
message box to replace the existing key file or key path with the new key file.
Note: You cannot specify a key file in the Files and Folders view. Key files must be set in either the Setup Design or
Components view.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component and click Files.
3. Right-click the key file and click Clear Key File.
Task To specify whether a component’s files, registry entries, and other data are uninstalled:
1. In the Setup Design view (in installation projects only) or the Components view, select the
component that you want to configure. InstallShield displays its settings in the right pane.
2. In Basic MSI, InstallScript MSI, Merge Module, and Direct MSI, and Direct MSM projects—
Configure the Permanent setting as appropriate:
• If the component data should not be uninstalled when end users uninstall the product, select
Yes.
• If the component data should be uninstalled, select No.
In InstallScript and InstallScript Object projects—Configure the Uninstall setting as appropriate:
• If the component data should not be uninstalled when end users uninstall the product, select
No.
• If the component data should be uninstalled, select Yes.
The Permanent and Uninstall settings apply to all types of data that are associated with a component.
This includes files, registry entries, shortcuts, XML file changes, and SQL scripts.
1. Verify that you have the Premier edition of InstallShield installed on your system.
2. Include the language in your installation by selecting it in the Setup Languages property in the
Project Properties view.
3. Include the language in your release.
Note: Components are installed based on the end user’s selection of the installation language in the Language dialog
(enabled in the Setup Languages panel of the Release Wizard), rather than on the locale of the system on which the
installation is run.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
1. Open the Setup Design view (in installation projects only) or the Components view.
2. Right-click the component and click Export Components Wizard.
Tip: You can also access the Export Components Wizard from the Project menu in InstallShield.
When you export a component into a project, a copy of this component is added to the specified .ism file,
along with all of the component’s data, such as its files, shortcuts, registry entries, and advanced
settings. Any string table entries, properties, and path variables used in the dialog are also copied to your
new project.
If the target .ism file already has a component of the same name with different properties, the Resolve
Conflict dialog box opens to offer you options for resolving the conflicts.
Publishing Components
The Publishing advanced setting for a component enables you to specify publishing information for your
component. Publishing is a type of advertising (just-in-time installation) in which no user-interface
elements are created for the component during installation, but the component can be installed through
Add or Remove Programs or when an installed component requests the published component from the
installer.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that you want to publish, and under Advanced Settings,
select Publishing. The Publishing explorer appears in a separate pane.
3. Right-click the Publishing explorer and then click New ComponentID to generate an ID for
your new component. InstallShield adds a unique componentID and a corresponding qualifier.
4. In the Publishing explorer, click the new qualifier and configure its value in the property grid.
In the Custom Actions and Sequences view, you can set the conditions that need to be fulfilled in order
for your product to be advertised on the target system.
namespace MyInstall
{
///
/// Summary description for Class1.
///
[System.ComponentModel.RunInstallerAttribute(true)]
public class MyInstallClass : Installer
{
public MyInstallClass()
{
}
public override void Install(IDictionary stateSaver)
{
base.Install(stateSaver);
foreach(string strKey in Context.Parameters.Keys)
{
MessageBox.Show(strKey + " is " + Context.Parameters[strKey]);
}
}
statically ( ) linked files are listed in the view. The view displays each file’s name, size, date the file
was last modified, key, and version.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that should contain the file and click Files. The Files view
opens.
3. Right-click in the Files view and click Add. The Open dialog box opens.
4. Browse to the file that you want to add.
5. Click Open. The Path Variable Recommendation dialog box opens.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that contains the file and click Files. The Files view opens.
3. Right-click the file that you want to delete and click Delete.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that should contain the file and click Files. The Files view
opens.
3. Right-click in the Files view and click Dynamic File Linking. The Modify Dynamic Links dialog
box opens.
4. Click New Link. The Dynamic File Link Settings dialog box opens.
5. Enter a source folder path and select the appropriate settings.
6. Click OK. The Path Variable Recommendation dialog box opens.
7. Make a selection and click OK. The Modify Dynamic Links dialog box appears with your
selections.
8. To repeat the process and add another dynamic link, click New Link, or click OK to close the dialog
box.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that contains the file and click Files. The Files view opens.
3. Right-click in the Files view and click Dynamic File Linking. The Modify Dynamic Links dialog
box opens.
4. Click the link that you want to modify.
5. Click Modify. The Dynamic File Link Settings dialog box opens.
6. Modify the settings and click OK.
7. Click OK to close the Dynamic File Linking dialog box and update the link settings.
Note: Dynamically linked files are updated each time that you navigate to the component’s Files view.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that contains the file and click Files. The Files view opens.
3. Right-click in the Files view and click Dynamic File Linking. The Modify Dynamic Links dialog
box opens.
4. Click the link that you want to delete and click Delete.
5. Click OK.
• For installation projects only: Right-click a feature in the Setup Design view and select
Component Wizard.
• For installation projects and merge module projects: Right-click Components in the explorer of
the Components view and click Component Wizard.
• The wizard looks at every file that you add to see if it is already included in your project. If the file is
a duplicate, the wizard does not create a component for it.
• A new component must be created for each portable executable file (.exe, .dll, or .ocx file). The
component bears the name of the portable executable file. The wizard creates a GUID for the
Component Code property and sets the portable executable file as the component’s key file.
• The Component Wizard attempts to extract registration information for each portable executable
file. If it succeeds, the wizard creates a COM server component and writes the data to the
component’s COM Server advanced setting.
• Every help (.hlp) file that you specify will reside in its own component along with its associated
contents (.cnt) file. The component is named after its help file. The wizard creates a GUID for the
Component Code property and makes the help file the component’s key file. The same rule applies to
HTML Help (.chm) files and the .chi files that accompany them.
• The Component Wizard puts all font (.ttf and .ttc) files into a single component called Font Files.
The wizard creates a GUID for the Component Code property and sets the first file in the list as the
key file. Any .fon files that you specify will automatically be included in the AllOtherFiles component
that is created. Since .fon files do not have a title, they will not be added to the Font table in the .msi
package. To have these files added as fonts, you will need to use the Fonts option in the Component
Wizard.
• Any files that do not fall into the above categories are grouped into a single component named All
Other Files. The wizard creates a GUID for the Component Code property and sets the first file in the
list as the key file.
Note: If your COM server is an executable, you must put an OLESelfRegister attribute with the value of 1 into the Version
section of the component’s resource file.
The destination folder for the font component is set to the destination folder that you chose in the
Component Wizard. After the component is created, you can set its Destination Folder to the Windows
Installer folder property FontsFolder (that is, use [FontsFolder] as the destination), the usual default
location for fonts. Place square brackets around FontsFolder, as you would when specifying
[INSTALLDIR].
Task If the font was not registered on your system, you must specify the font title by doing the following:
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that contains the font file and click Files. The Files view
opens.
3. Right-click the font file and click Properties. The Properties dialog box opens.
4. In the Font title box, type a font title in the format FontName (FontType)—for example, Roman (All
res).
5. Click OK.
• For installation projects only: Right-click a feature in the Setup Design view and select
Component Wizard.
• For installation projects and merge module projects: Right-click Components in the explorer of
the Components view and click Component Wizard.
The Let me select a type and define the component myself option of the Component Wizard
supports the following component types:
• COM servers
• Font files
• Control NT services
• Install NT services
Installing Fonts
Although you can create a component in one of several ways, the easiest way to install a font (a .ttf, .fon,
or .ttc file) in an installation is to create a Fonts component in the Component Wizard.
Tip: An alternative to creating a Fonts type component is to select the Setup Best Practices option in the Component
Wizard and let InstallShield create a Fonts component for you from your font files.
In the Component Wizard, the panels that are displayed depend on the selections made in previous
panels. For example, the Add New Fonts panel is not displayed unless you selected I also want to add
fonts not installed on this system in the Add Installed Fonts panel.
Controlling NT Services
InstallShield 2008
Create a Control NT Service component to start or stop a service during installation or uninstallation.
For example, you might need to delete a running service before updating it in your installation.
Although you can create a component in several ways, the recommended method for controlling an NT
service is to launch the Component Wizard and select the Control NT Service option.
Installing NT Services
Although you can create a component in several ways, the recommended method for installing NT
services is to launch the Component Wizard and select the Install NT Services option.
Tip: If the file also runs as a COM server, a better way to create the component is to select the COM Server component
type and specify that it contains an NT service. Once you have provided all the COM registration data, the Component
Wizard prompts you for the same information about the service that you must provide for the Install NT Services
component type.
When the wizard has created the component, you can edit the services’ installation information in the
component’s NT Services advanced setting. Windows Installer passes these values to the Windows API
function CreateService() to install each service onto the target system and register it with the Service
Control Manager (which maintains the system’s database of services and exposes an interface for
controlling these services).
Component Properties
When you create a component, it has default properties, depending on whether you created the
component using a view, or using a wizard.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. Select the component and edit its property sheet.
Note: The following properties apply only if the component’s key file is a .NET assembly: .NET Scan at Build, .NET
Application File, .NET Installer Class, and .NET COM Interop.
Destination Windows Set permissions for the directory folder. Click the ellipsis
Permissions Installer based button (...) to launch the File and Directory Lock
Permissions dialog box.
Remote Installation Windows Leave the files on the source medium, such as a CD-
Installer based ROM or network drive.
COM Extract at Windows Specifies whether to extract COM information from the
Build Installer based component’s COM servers (if any) every time that you
perform a build.
.NET Scan at Build All Indicate whether you want the key file of this component
scanned for .NET dependencies or properties at build
time. Select an option from the list. If the key file is not a
.NET assembly, the key file is not scanned for .NET
dependencies or properties.
.NET Application Windows This property is used when this component is scanned
File Installer based at build time (based on the .NET Scan at Build property)
or by the Static Scanning Wizard. The scanner uses this
property—along with the component destination—to
determine the value of the File Application property for
the assembly. This field can be left blank.
.NET Installer Class Windows This property is pertinent only if this component’s .NET
Installer based assembly contains a class derived from
System.Configuration.Install.Installer. Select Yes to
ensure that—at installation time—the assembly’s Install,
Commit, Rollback, and Uninstall methods will be called
at the appropriate times.
.NET COM Interop Windows Select Yes to enable the .NET COM interop for the
Installer based assembly in this component. At installation, registry
entries are created on the target system that allow COM
objects to call your .NET assembly.
Reg File to Merge Windows Specify the complete path or click the ellipsis button (...)
at Build Installer based to browse to a .reg file to merge it with the component’s
registry entries at build time.
.NET Precompile Windows If this property is set to Yes, at run time, the installation
Assembly Installer based creates a native image from the .NET assembly and
installs it to the native image cache on the target
system. This allows the assembly to load and execute
faster, because it restores code and data structures
from the native image cache rather than from just-in-time
(JIT) compilation.
Never Overwrite Windows Indicate whether you want your installation to overwrite
Installer based a file if it exists on the target system.
64-Bit Component Windows Set this option to Yes to mark this component as 64 bit.
Installer based If a 64-bit component is included in your installation, the
installation cannot be run on 32-bit machines.
For more information, see Targeting 64-Bit Operating
Systems.
Source Location Windows Install files of the same name from different
Installer based components.
Disable Registry Windows Registry reflection keeps the 32-bit registry view and the
Reflection Installer based 64-bit registry view in sync on the target machine.
To enable registry reflection for all existing and new
registry keys that are affected by the selected
component, select No, which is the default value.
To disable registry reflection on all existing and new
registry keys that are affected by this component,
select Yes. Windows Installer calls the
RegDisableReflectionKey function on each key being
accessed by the component. This function disables
registry reflection for the specified key. Disabling
reflection for a key does not affect reflection of any
subkeys.
Comments All Specify comments about this component for your own
use in InstallShield.
Operating Systems InstallScript, Specify the operating systems on which this component
InstallScript MSI should be installed.
Platform Suite(s) InstallScript, Specify to what platform suites, if any, the component is
InstallScript specific.
Object
FTP Location InstallScript, Enter an FTP location that you want to associate with
InstallScript the component.
Object
HTTP Location InstallScript, Enter an HTTP location that you want to associate with
InstallScript the component.
Object
Miscellaneous InstallScript, Enter a text string that you want to associate with the
InstallScript component.
Object
.NET Assembly InstallScript, Specify whether the component’s files are installed as
InstallScript local .NET assemblies or not installed as assemblies.
Object
Link Type InstallScript, Specify whether the component’s file links are static or
InstallScript dynamic and, if the latter, how the links are determined
Object at the time of the release build.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. Select the component.
3. Set the Shared property to Yes.
The changes you make are reflected in the property sheet.
Windows Logo Guideline: Windows logo guidelines require you to increment a reference count when installing shared
files and to decrement the count when uninstalling. Core component files (which they recommend you not install) should
not be refcounted.
Project: The component’s Condition property is not available for InstallScript or InstallScript Object projects.
Using the component’s Condition property, you can enter a statement that the installer must evaluate
before setting up your component’s data on the target system. The component will not be installed if its
condition evaluates to false. However, the component will be installed or advertised if its condition
evaluates to true, assuming that its feature is selected for installation.
1. Type the condition directly into the Condition(s) box, or build the condition statement by doing
the following:
a. In the Properties list, select a property and click Add. InstallShield adds the property to the
Condition(s) box.
b. In the Operators list, select the operator and click Add. InstallShield adds the operator to the
Condition(s) box.
c. In the Condition(s) box, type a value to complete the condition.
2. Click OK.
Caution: No validation is made during design time. Use valid syntax and double-check to ensure that your statement
evaluates to the expected outcome. For more information and for example conditions, see Building Conditional
Statements.
Project: This information does not apply to InstallScript or InstallScript Object projects.
The Remote Installation component property determines whether the component’s files are installed on
the target system or run from the source medium, such as a CD-ROM or network server. The default
value for a new component is Favor Local, which means that the component’s files are installed on the
target system.
Task To change this value so the component’s files run only from the source medium:
1. Open the Setup Design view (for installation projects only) or the Components view.
2. Select the component.
3. Click the value for the Remote Installation property to display a list, and then select Favor Source.
Selecting Optional gives this component the Remote Installation property of its feature.
The changes you make are reflected in the property sheet.
Caution: Set this property to Favor Local if the component contains an NT service. Although an end user could change
the feature’s installation state through the Custom Setup dialog box, the Windows Installer cannot install a service
remotely.
Project: This information does not apply to InstallScript or InstallScript Object projects.
The component’s Remote Installation property always overrides the feature’s Remote Installation
property. For example, if a component’s Remote Installation property is set to Favor Local, its files are
installed on the target system regardless of the feature’s Remote Installation property.
The files are run from the source medium when a component’s Remote Installation property is set to
Favor Source. Set the component’s Remote Installation property to Optional if you want its feature to
dictate whether or not the files run from the source medium.
When a component is associated with more than one feature and the component’s Remote Installation
property is set to Optional, the files are installed locally if any of its features is set to Favor Local. If the
component is set to Favor Local or Favor Source, the files are installed accordingly.
Project: This information does not apply to InstallScript or InstallScript Object projects.
By selecting Yes for the component’s COM Extract at Build property, you indicate that you want
InstallShield to scan the component’s key file for COM registration data whenever you build a release.
The extracted information is placed into the installation package (.msi file) so that Windows Installer
registers the COM server when it is installed or advertised. All the necessary registry settings made by
the components /RegServer will be extracted when you select Yes for this property.
Unlike the Component Wizard, the build process does not write the extracted COM information to the
project (.ism) file. Instead, it is dynamic, in that it is updated each time that you rebuild. It also means
that you can rebuild an existing release through InstallShield or the command line even when you do not
have write access to the project file.
Note: The PATH system variable on the build machine must be set to include the directories of all of the .dll files to which
the COM server links; otherwise, the file will fail to register and COM information will not be extracted.
The build feedback (displayed in the Output window and in the build log files) details the registration
information that was extracted.
Resolving Conflicts
Despite setting COM Extract at Build to Yes, you can still specify COM information under the
component’s COM Registration advanced setting and in the component’s Registry explorer. The existing
information will always be registered when the component is installed.
If entries are detected under COM Registration, InstallShield asks you if you want to delete them when
COM Extract at Build is set to Yes. If any conflicts are found during the build, you receive a warning
about the item in the advanced setting that was overwritten with the dynamically acquired data.
Even with these safeguards, you might want to check the COM Registration advanced setting and the
component’s registry data to verify that the entries are intentional and do not conflict with the data
extracted at build time.
Note: (Windows Installer projects only) The build-time scan does not scan the key file of a component if the key file is not
a .NET assembly file.
Several options are available from the .NET Scan at Build property:
Option Description
None Do not scan the key file of this component for .NET
dependencies or properties.
Properties Only
Dependencies and Properties Scan the key file of this component for .NET dependencies
and (in Windows Installer projects) properties. Add missing
dependencies and properties to the installation project.
Project: (Windows Installer projects only) In order to install an assembly to the Global Assembly Cache, the .NET Scan at
Build property must be set to either Properties Only or Dependencies and Properties.
The setting of this property affects how the Static Scanning Wizard scans the files in your project.
Project: This information does not apply to InstallScript or InstallScript Object projects.
The .NET Application File property is used when the component is scanned at build time (based on the
.NET Scan at Build property) or by the Static Scanning Wizard. The scanner uses this property—along
with the component destination—to determine the value of the File Application property for the
assembly.
The scanning algorithm works in the following way to populate the .NET assembly’s File Application
property:
1. The scanning algorithm checks the component’s Destination property. If the value is
[GlobalAssemblyCache], the .NET assembly’s File Application property is set to null.
2. If the component’s destination is something other than [GlobalAssemblyCache], the scanning
algorithm checks the component’s .NET Application File property. If this value is not null, the value
of this property is used to set the assembly’s File Application property.
3. If the component’s destination is something other than [GlobalAssemblyCache] and the .NET
Application File property is null, the component’s key file is used to set the assembly’s File
Application property.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. Select the component.
3. Click the Languages property to see the help and list of languages below the property sheet.
4. Select the check box for each language to which this component’s data apply.
Note: Only 64-bit systems with Windows Installer 4.0 support registry reflection. Other systems ignore the registry
reflection setting.
If an end user installs a 64-bit application that has a component with registry reflection enabled,
Windows Installer makes the associated registry changes in the 64-bit view of the registry, and the
reflector copies the registry changes to the 32-bit registry view. Similarly, if an end user then installs a
32-bit application that modifies the same registry key or value, Windows Installer makes the associated
registry changes in the 32-bit view of the registry, and the reflector copies the registry changes to the 64-
bit registry view.
If registry reflection is disabled, Windows Installer calls the RegDisableReflectionKey function on each
key being accessed by the component. This function disables registry reflection for the specified key.
Disabling reflection for a key does not affect reflection of any subkeys.
Task To enable or disable registry reflection for all new and existing registry keys that are affected by a
component:
Transitive Components
Components that were installed but whose conditions evaluate to false upon reinstallation are removed.
Because of this special feature, which allows you, in effect, to swap components during reinstallation,
components with a Reevaluate Condition property set to Yes are considered transitive components.
Consider an application that requires a different .dll file depending on whether it is installed on
Windows NT 4.0 or Windows 2000. You could create a component for each file and attach a condition to
each component to check the version of the operating system. The component for Windows 2000 would
have the following condition:
VersionNT=500
VersionNT<500
When installed under Windows NT 4.0, the appropriate version of the .dll file is installed and the
Windows 2000 version is not. What happens if the end user upgrades to Windows 2000? When the
product is reinstalled, the Windows NT 4.0–specific component is uninstalled, and the Windows 2000–
specific component is installed (as long as these components are both transitive).
Windows Logo Guideline: Windows logo-compliant applications must function correctly when the operating system is
upgraded to Windows 2000 or later. Although the Application Specification recommends that you use the same binaries
for other operating systems and Windows 2000 and later, the Reevaluate Condition property offers you an alternative for
meeting this requirement.
Project: For InstallScript projects, this functionality is handled by the component’s Overwrite property.
Set the Never Overwrite property to Yes or No:
• If you select Yes, the file—if it exists on the target system—is never overwritten, regardless of the file
version. Selecting Yes for this property overrides file versioning rules.
• If you select No and the file version on the target system is newer than the version being installed,
the file on the target system is not overwritten. However, if the version being installed is newer, the
file on the target system is overwritten.
Windows Installer checks only for the existence of the component’s key file when determining if it
should install the component. If the component’s key file does not exist on the target system, Windows
Installer will install the component as if the Never Overwrite property were set to No.
Project: This information does not apply to InstallScript or InstallScript Object projects.
A component’s Source Location property names a subfolder where the component’s files will be stored
in the source disk images, if the component’s files are not compressed. The component’s files will be
copied to this subfolder in your release image.
This property does not require a value, and in most cases, can be left blank. If you enter a value, it must
be a valid Windows folder name.
One instance where the Source Location property could be used is when you are creating an installation
that contains more than one language. In this scenario, you can have multiple files with the same name.
You can create a component for each language and set the Source Location property for each one. With
the Source Location property set, any file with the same name can be copied onto the disk in two
different locations, without the risk of being overwritten.
For example, create two components called German and English. For the first component, set the Source
Location property to GermanVersion. For the second, set the Source Location property to
EnglishVersion. Create two files called Test.txt, giving them slightly different contents. Assign each file
to a component.
When you build your setup with uncompressed files, two separate folders on the disk images will be
created, one called GermanVersion and one called EnglishVersion. Separate versions of Test.txt will be
copied to each of these folders, but neither copy will be overwritten.
Note: The Source Location property is not the same as the destination location. While it is conceivable that you might
want to copy both versions of the file to the end user’s machine, it is more likely that you would want to filter the files by
language.
Advanced Settings
Project: This information does not apply to InstallScript or InstallScript Object projects.
A component’s advanced settings allow you to fulfill installation requirements for special component
types. For example, when you copy an .ocx file to the target system, you must register its classes,
ProgIDs, and type libraries so that the file’s methods can be properly accessed. Advanced settings use
Windows Installer’s built-in functionality for registering COM servers; setting up ODBC drivers, data
sources, and translators; installing or controlling NT services; and registering a file association.
By specifying the advanced settings, you can publish your component and register COM servers, file
extension servers, and MIME types. If the component is selected, an advanced setting is made on the
target system when the component is installed or advertised. That way, the file is ready to execute once it
is installed. Publishing components—a type of advertising—is accomplished through the Publishing
advanced setting.
Option Description
Application Paths Use this advanced setting to specify the paths to your component’s files
and folders. When you run your installation, it will create an App Paths key
for your component under the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\A
pp Paths\ProgramName.exe.
Assembly Use this advanced setting to install a Win32 or .NET assembly when a
specified component is installed.
Option Description
COM Registration In the COM Registration explorer, you can enter or modify registration
information for the COM server that you have set as your component’s
key file. The COM Registration advanced setting is intended to replace
self-registration, which is a violation of Setup Best Practices.
The recommended way to specify file registration is to use the
Component Wizard and have it automatically extract the necessary
information for you. Use the COM Registration explorer only if you need to
make advanced modifications.
Control NT This advanced setting allows you to control an NT service when the
Services component is installed or uninstalled.
File Types This advanced setting registers information about a file type on the target
system when the component is installed or advertised.
Install NT Services If this component’s key file contains one or more NT services, use the
Install NT Services advanced setting to specify installation information for
the services.
ODBC Resources The ODBC Resources advanced setting allows you to modify the driver,
data source name, or translator attributes that you created for this ODBC
resource in the ODBC Resources view.
You cannot add or remove an ODBC resource in this advanced settings
view. You can only edit its attributes. You must use the ODBC Resources
view to add a new ODBC resource, and you would need to delete the
component altogether to remove the ODBC resource from your project.
Publishing Use this advanced setting to publish your component. Publishing is a type
of advertising (just-in-time installation) in which no user-interface elements
are created for the component during installation, but the component can
be installed through the Add or Remove Programs or when an installed
component requests the published component from the installer.
Device Driver The Device Driver advanced setting enables you to specify whether the
current component includes a device driver, the type of driver, and the
order in which the project’s device drivers (not just the current
component’s device drivers) should be installed.
Other Data The Other Data advanced setting lists various Windows Installer tables
that are related to the component.
Project: This information does not apply to InstallScript or InstallScript Object projects.
When you add a .NET assembly as the key file of a component, InstallShield automatically adds values to
the .NET Assembly property grid when the component is scanned at build time, or when you run the
Static Scanning Wizard.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. Click the component to expand it.
3. Click the Advanced Settings item to expand it.
4. Click the Assembly item under Advanced Settings.
5. Click the .NET Assembly item to display the property grid.
Property Description
Manifest The Manifest property contains the name of the first .exe or
.dll file in the associated component.
File Application Select an .exe file to install the .NET assembly to the
selected application’s private cache. Select Global Assembly
Cache to have the .NET assembly installed to the target
system’s global assembly cache. The setting of this property
affects the component’s Destination property. If the File
Application property is set to GlobalAssemblyCache, the
component’s Destination property is also set to
GlobalAssemblyCache. For optimal advertising and repair,
set this property to the .NET executable file that uses the
assembly in this component.
Name The name for the .NET assembly. To enter a new name, type
it in the field.
PublicKey Token The .NET assembly’s public key token. This property is not
required.
For more information about the .NET assembly properties, see the MSDN Library.
Project: This information does not apply to InstallScript or InstallScript Object projects.
The App Paths registry key is a useful installation-related key that helps an executable file find its .dll
files without having to modify the PATH environment variable. An executable file’s App Paths key looks
like this:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App
Paths\Filename.exe
A program’s App Paths key typically contains a value named Path, which should contain a semicolon-
delimited list of directories where the program’s .dll files could be located. Windows uses this key to find
your application and its .dll files if their locations are not already in the system’s path. If an end user
moves or renames your application’s executable file through the Explorer shell, Windows automatically
updates the file’s App Paths key.
Project: This procedure does not apply to InstallScript or InstallScript Object projects.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click the Application Paths item under Advanced Settings.
5. In the File column, select the file for which you would like to create a key.
6. In the Application Path column, enter the paths to the file’s dependencies, or select a Windows
Installer folder property from the list rather than hard-coding a path. Separate multiple paths with a
semicolon (;).
7. Click OK.
Project: This procedure does not apply to InstallScript or InstallScript Object projects.
The easiest way to specify an application path for your component is to use the component’s key file as
the application path.
Note: Do not use hard-coded paths, such as C:\MyDir, in the Application Path column. Instead, use Windows Installer
folder properties enclosed in square brackets—for example, [INSTALLDIR]MyDir or
[CommonFilesFolder]MyProgram—or the name of the component enclosed in square brackets and preceded by a
dollar sign—for example, [$ComponentName]. The installer will resolve these values and write the resulting locations to
the App Paths key.
Once you run the Device Driver Wizard, which adds the table and entries, custom actions, features, and
components needed to include device drivers in your installation, you can set properties associated with
a component that includes a device driver. The following information describes the various options that
you can set within InstallShield.
The Device Driver advanced setting’s Common tab within the Components view enables you to specify
whether the current component includes a device driver and, if so, select desired run-time installation
options. The Sequence tab enables you to specify the order in which the project’s device drivers (not just
the current component’s device drivers) should be installed.
The following sections describe the device driver settings that you can configure on the advanced
setting’s Common tab.
Options Description
Always overwrite any existing Replace any existing driver for the device with this driver. If
device driver this check box is cleared and a driver already exists for the
device, your driver is not installed.
Do not show Connect Device to Select this option to ensure that the Connect Device to
Computer dialog Computer dialog does not appear during the installation of a
device driver if a device matching the driver is not connected
to a computer.
Do not create Add or Remove If you select this check box, the installation creates an Add
Programs entry for device or Remove Programs entry for the device driver only; the
driver installation does not create an additional entry for the
installation itself.
DIFxApp does not support this feature on Windows Vista.
Install unsigned driver files and By default, DIFxApp does not install unsigned driver
drivers with missing files packages or driver packages that have missing files. To
override this default behavior, select this check box.
Selecting this check box enables you to fully test drivers
more easily before shipping final signed versions.
Remove binary files associated By default, when DIFxApp uninstalls a driver package,
with driver during uninstall DIFxApp does not remove the binary files that were copied to
the system when it installed the driver. To override this
default behavior, select this check box.
If you select this check box, DIFxApp removes a binary file
from the system only if the binary file is identical to the
corresponding binary file in the driver store.
Options Description
Include all localized installation When this check box is selected, the installation uses a
runtime dialogs custom action runtime .dll that includes dialogs and text for
the following languages:
• Arabic (Saudi Arabia)
• Chinese (People’s ROC)
• Chinese (Taiwan)
• Czech (Czech Republic)
• Danish (Denmark)
• Dutch (Netherlands)
• English (United States)
• Finnish (Finland)
• French (France)
• German (Germany)
• Greek (Greece)
• Hebrew (Israel)
• Hungarian (Hungary)
• Italian (Italy)
• Japanese (Japan)
• Korean (Korea)
• Norwegian (Bokmål) (Norway)
• Polish (Poland)
• Portuguese (Brazil)
• Portuguese (Portugal)
• Russian (Russia)
• Spanish - Modern Sort (Spain)
• Swedish (Sweden)
• Turkish (Turkey)
If you clear this check box, the installation uses runtime
dialogs for English only. The English runtime .dll file is
smaller than the localized .dll file, so if space is an issue and
you do not need the extra language runtime dialogs, clear
this check box.
Device driver machine This area has several options. Select the appropriate option.
architecture
• Device driver targets 32 bit machines
• Device driver targets Itanium 64 bit machines
• Device driver targets AMD 64 bit machines
Installing Assemblies
Note: The recommended way to add a .NET assembly to your installation project is to add an assembly as a component’s
key file and set the component’s .NET Scan at Build property.
In the Assembly section of a component’s Advanced Settings, you can add a private or global Win32
assembly or .NET assembly to be registered when the current component is installed. Using assemblies
helps you install products that are self-contained, without affecting other applications on the system.
Note that a component can contain only one assembly.
Adding Assemblies
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Right-click Assembly and then click New Win32 Assembly or New .NET Assembly.
5. Click the assembly and then configure the Manifest, File Application, and related properties.
Data you enter in the Assembly editor is written to the MsiAssembly and MsiAssemblyName tables of
your .msi database. You can view and edit these tables using the Direct Editor.
Deleting Assemblies
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Right-click the assembly and click Delete.
Project: This information does not apply to InstallScript or InstallScript Object projects.
The recommended method for installing NT services is to use the Component Wizard. In general, you
need to modify only the advanced settings to make changes later.
1. Ensure that a single executable file has been added to the component. For more information, see
Adding Files to Components. The file must be an .exe file, since Windows Installer does not support
driver services.
2. Make the executable file that contains this component’s services the component’s key file. For more
information, see Component Key Files.
3. Double-click the component’s Advanced Settings folder to view all of the advanced settings.
4. Click Install NT Services.
5. Right-click the NT Services explorer and then click New. InstallShield adds a new service.
6. Type a new name for the service now, or click it and then press F2 later to rename it.
7. Click a service to set its installation properties.
Repeat the process for each service in this component’s key file.
Windows Installer passes these values to the Windows API function CreateService() to install each
service onto the target system and register it with the Service Control Manager.
More help is available in the help pane in InstallShield when you click each NT service property. You
must be familiar with the technical details of your service before you can set its properties.
InstallShield provides functionality for controlling this NT service or others on the target system. For
more information, see Controlling NT Services.
Follow the instructions below to modify a component’s advanced settings to control an NT service when
the component is installed or uninstalled. Note that the service that you are controlling can either be
present on the target system during installation or uninstallation, or it can be installed with this
installation.
1. Open the Setup Design view (for installation projects only) or the Components view.
2. In the explorer, expand the component.
3. Click the Advanced Settings item to expand it.
4. Click Control NT Services. The Control NT Services explorer opens.
5. Right-click he Control NT Services explorer and click New Service. InstallShield adds a new
service, as well as an event under that service.
6. Type a new name for the service. This is the name that InstallShield, Windows Installer, and the
Service Control Manager use to identify a service, not its display name.
7. Right-click the event and click Rename. Type a unique name for the event.
8. Click the event to set its properties and specify how you want to control the service during
installation and uninstallation. More help is available in the help pane in InstallShield when you
click each event property.
You can place all of your control options in a single event. However, you might need to create additional
events if, for example, you want to pass different arguments during installation and uninstallation.
Renaming Drivers
The ODBC Resource advanced setting displays the name of the driver, translator, or DSN that is
installed with this component, along with its attributes. Right-click a resource to rename it.
Other Data
The Other Data node for a component is available in the Components view (and the in the Setup Design
view of installation projects only) for Windows Installer–based projects.
• Click the Other Data node to view a list of Windows Installer tables that are related to the
component. The list also includes the name of any SQL script files associated with a component. In
addition, the Other Data node lists the number of records found in the Complus, DuplicateFile,
Environment, IniFile, MoveFile, RemoveIniFile, RemoveRegistry, and ReserveCost tables.
• To go to a table in the Direct Editor, click the table name.
File Types
Project: This information does not apply to InstallScript or InstallScript Object projects.
If your application manipulates files with a unique file extension, you can register your file type in the
File Types view, which is available as an advanced setting within the Components view and the Setup
Design view (for installation projects only). For example, if your application manipulates files with the
.xyz extension, registering the file type instructs the operating system to open the file with your
application when the user double-clicks its icon.
This advanced setting registers the following information about a file type on the target system when the
component is installed or advertised:
File Extensions You can associate file extensions (such as .doc and .txt) with
the component’s key file.
Verbs You can register command verbs (such as Open and Print)
that appear in the context menu that Windows Explorer
displays when an end user right-clicks a file with the current
extension.
MIME Type You can also register multipurpose Internet mail extension
(MIME) types, also known as media types or content types,
for the component’s key file. You can also associate a MIME
type with a class ID.
Note: On Windows NT 4 and Windows 9x systems, file association information is stored under the root
HKEY_CLASSES_ROOT. On systems running Windows 2000 or later, file associations are stored in both
HKLM\SOFTWARE\Classes and HKCU\SOFTWARE\Classes; you can see a merged view of the data under
HKEY_CLASSES_ROOT. It is recommended that you use the File Types editor instead of writing directly to the registry to
support Windows Installer advertisement features.
Note also that Windows Installer writes file-extension advertisement information to the registry, which appears to be a
string of random characters. This behavior is normal.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component that should have the new componentID, and under
Advanced Settings, select Publishing. The Publishing explorer appears in a separate pane.
3. Right-click the Publishing explorer and then click New ComponentID. InstallShield adds a
unique componentID and a corresponding qualifier.
Removing ComponentIDs
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select Publishing. The
Publishing explorer appears in a separate pane.
3. In the Publishing explorer, right-click the componentID and click Delete.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select Publishing. The
Publishing explorer appears in a separate pane.
3. In the Publishing explorer, right-click the componentID and click New Qualifier. InstallShield
creates a new qualifier with the default name New Qualifier-n, where n is a unique number.
4. Type a name for the qualifier.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select Publishing. The
Publishing explorer appears in a separate pane.
3. In the Publishing explorer, right-click the qualifier and click Delete.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select Publishing. The
Publishing explorer appears in a separate pane.
3. In the Publishing explorer, click the qualifier and configure its value in the property grid.
Tip: When you type a value for the property, you are actually creating a string table entry and setting its value for the
current language. You can also select an existing entry by clicking the String Table tab and editing entries.
Important: The recommended method for installing a COM server is to have Windows Installer register its classes,
ProgIDs, type libraries, and so on. Calling self-registration functions violates Setup Best Practices.
The easiest way to populate the COM Registration advanced setting is to have the Component Wizard
extract the necessary information or extract COM data for a key file. (You can also have it extracted
dynamically at build time, in which case you do not need to use this advanced setting.) It is
recommended that you modify the COM Registration advanced setting or create COM entries in the
component’s Registry explorer only if you are familiar with the technical details behind your file’s
registration.
Task To install a COM server solely through editing the component’s advanced settings:
1. Ensure that a single COM server is added to the component. The file must be a single portable
executable file (such as an .exe, .dll, or .ocx file), according to Setup Best Practices.
2. Make the COM server the component’s key file.
3. Set the component’s COM Extract at Build property to No.
4. Expand the component’s Advanced Settings item to view all of the advanced settings.
5. Click COM Registration to configure COM server information.
Right-click one of the items in the COM Registration explorer to modify or to create registration
information for your COM server. Right-click and item and click Rename to rename the new item.
Note: The PATH system variable on the build machine must be set to include the directories of all of the .dll files to which
the COM server links; otherwise, the file will fail to register and COM information will not be extracted.
Set the properties for each registration item or subitem that you create. More help is available in the help
pane in InstallShield when you click each registration property.
COM Classes
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select COM
Registration. The COM Registration explorer appears in a separate pane.
3. In the COM Registration explorer, right-click COM Classes and click New COM Class.
4. Type a new name for the COM class if needed. The name that you give the COM class will be
registered as the default value under HKEY_CLASSES_ROOT\CLSID\<GUID>. To give the class a
new name, right-click it and click Rename.
5. Click the new COM class to set its properties.
6. Specify a context type for this class. The following list tells you which server context is appropriate
for which type of COM server:
ProgIDs
A progID is a string used to identify a class in the format Component.Class.N.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select COM
Registration. The COM Registration explorer appears in a separate pane.
3. In the COM Registration explorer, right-click ProgIDs and click New ProgID.
4. Type a new name for the ProgID. Use the format Component.Class.N. To give the class a new name,
right-click it and click Rename.
5. Click the new ProgID to set its properties.
Version-Independent ProgIDs
A version-independent progID is a string used to identify a class in the format Component.Class, which is
constant for all versions of a class.
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select COM
Registration. The COM Registration explorer appears in a separate pane.
3. In the COM Registration explorer, right-click Version-Independent ProgIDs and click New
ProgID.
4. Type a new name for the ProgID. Use the format Component.Class. To give the class a new name,
right-click it and click Rename.
Type Libraries
1. Open the Setup Design view (in installation projects only) or the Components view.
2. In the explorer, expand the component, and under Advanced Settings, select COM
Registration. The COM Registration explorer appears in a separate pane.
3. In the COM Registration explorer, right-click Type Libraries and click New Type Library.
4. Type a new name for the type library, or libID, referenced by this COM server. The name that you
give the type library item is registered as the default value under
HKEY_CLASSES_ROOT\TYPELIB\<libID>\<version>. Use the format Component.Class. To give
the class a new name, right-click it and click Rename.
5. Click on the type library to configure its settings.
Defining Features
A feature is a building block of an application from the end user’s perspective. It represents a specific
capability of your product—such as its help files or a part of a product suite that can be installed or
uninstalled based on the end user’s selections. Your entire application should be divided into features
that perform a specific purpose. You can define features in the Features view.
Subfeatures
Subfeatures are further divisions of a feature. Because features should be self-contained elements of an
application or application suite that a user can selectively install, it might make sense for you to organize
portions of your application as subfeatures of a parent feature. If all features are visible, your end user
can then select which portions of a feature to install in the custom setup type dialog that corresponds to
your project type.
• For Basic MSI projects—Custom Setup Dialog Options
Tip: Although you can create many levels of subfeatures, you should keep the design as simple as possible for
organizational purposes.
Creating Features
Creating Features or Subfeatures
1. In the View List under Organization, click Setup Design (in installation projects only) or the
Features view.
2. Right-click the top-level item in the explorer and click New Feature. InstallShield adds a new
feature with the default name New Feature_n (where n is a successive number).
3. Enter a new name, or right-click it later and click Rename to give it a new name.
Project: In Basic MSI, InstallScript MSI and Merge Module projects, feature names must contain only letters, digits,
underscores (_), and periods (.), and they must begin with a letter or an underscore.
In InstallScript and InstallScript Object projects, the following characters are invalid in feature names:
\/:*?"’<>|
Tip: You can create multiple nested features at one time by creating a new key and typing Feature 1\Feature
2\Feature 3 in the feature’s name. InstallShield creates a nested feature structure where Feature 3 is a subfeature of
Feature 2, which is a subfeature of Feature 1.
Next Steps
After you have created all of your application’s features and subfeatures, you need to create components
and then associate them with your features.
Feature Properties
The following table provides a description for each feature property.
Display Name All A feature’s display name is what the end user
sees in the Custom Setup dialog box. If you do
not specify a display name, InstallShield displays
the name provided in the Features explorer when
you created or renamed the feature.
Remote Installation Windows Installer Indicates whether this feature’s files are installed
based, InstallScript MSI on the target system or run from the source
medium, such as a CD-ROM or network server.
For more information, see Setting a Feature’s
Remote Installation Property.
Display Windows Installer Indicates how you want the feature presented to
based, InstallScript MSI the end user in the Custom Setup dialog. For
more information, see Displaying Features to End
Users.
Release Flags Windows Installer Release flags enable you to create different
based, InstallScript MSI versions of your product without having to create
more than one installation project.
Condition Windows Installer Allows you to enter a statement that the installer
based, InstallScript MSI evaluates before determining whether to install
the feature on the target system. For more
information, see Conditionally Installing Features.
FTP Location InstallScript, Lets you associate an FTP location with the
InstallScript Object, selected feature. The location that you enter can
InstallScript MSI be accessed from the script using the
FeatureGetData function.
Enter the FTP location in the format
ftp.domain.com.
HTTP Location InstallScript, Lets you associate an HTTP location with the
InstallScript Object, selected feature. The location you enter can be
InstallScript MSI accessed from the script using the
FeatureGetData function.
Enter the HTTP location in the format http://
www.domain.com.
Miscellaneous InstallScript, Lets you associate a text string with the selected
InstallScript Object, feature. The text you enter can be accessed from
InstallScript MSI the script using the FeatureGetData function.
Status Text InstallScript, Specify the status text for the feature. Your end
InstallScript Object users will see this text in the progress indicator
box during the transfer of this feature to the
target system. When you enter a value for this
property, you are actually creating a string table
entry and setting its value for the current
language.
Include In Build InstallScript, If the Use the ‘Include in Build’ property option is
InstallScript Object selected in the Release property sheet’s Features
property, the Include in Build property lets you
specify whether the feature should be included in
your distribution media.
Password InstallScript, Enter a password for the feature. You can specify
InstallScript Object a different password for each different feature.
You can also specify a password for the entire
installation in the Release property sheet’s Media
Password property.
Encryption InstallScript, Specify whether the files for the feature will be
InstallScript Object encrypted. Encrypted files can be read only by
the InstallScript engine (or by an expert code-
breaker).
CD-ROM Folder InstallScript, Specify the folder in the disk image in which the
InstallScript Object feature is placed if the feature’s check box is
selected in the Custom Media Layout panel of the
Release Wizard. If no folder is specified and the
feature’s check box is selected, the feature is
placed in the root of the disk image or, if it is a
subfeature, in the same folder as its parent
feature.
Advertising Features
Project: The feature’s Advertisement property is not available for InstallScript or InstallScript MSI projects.
By setting a feature’s Advertisement property, you can selectively enable or disable a feature for
advertisement. Advertised features are not installed immediately during the installation process.
Instead, they are installed when requested. If the feature is assigned, the feature appears to be already
installed, although it is not installed until the end user requests it. (Assigned features have their
shortcuts installed, and they can be installed from Add or Remove Programs in the Control Panel.
However, an assigned feature is advertised until a user requests it.) A published feature does not appear
on the target system until it is requested from the installer. (Published features lack any end user–
interface elements. They are installed programmatically or through an associated MIME type.)
You can set this property in the Features view.
This property’s options include:
Table 11-16: Options that Are Available for the Advertisement Property
Option Description
Favor Advertise The feature is advertised by default. End users can change
the advertisement option for a feature in Custom Setup
dialog.
Disallow Advertise Advertising is not allowed for this feature. End users cannot
elect to have the feature advertised in the Custom Setup
dialog.
Table 11-16: Options that Are Available for the Advertisement Property (cont.)
Option Description
Disable Advertise if Not Advertisement works only on systems with Internet Explorer
Supported 4.01 or later. If the target system does not meet this
criterion, advertising is not allowed. If the target system can
support advertisement, advertising is allowed.
When you allow feature advertisement, the feature is advertised, regardless of the mode in which the
installation is running, as long as no other factors prevent it from being advertised. In the Custom Setup
dialog, the end user can control which features are immediately installed and which are available later.
Advertisement usually requires support from the application. For example, your product’s spell checker
can be advertised. The application interface offers use of the spell checker through a menu command or
toolbar button. You must write to check the feature’s installation state and install it when the customer
clicks the Spell Check command or button.
Project: The feature’s Condition property is not available for InstallScript or InstallScript Object projects.
1. Click the last row in the Level column and type the Install Level value to be used if the condition
evaluates to true.
2. Click the Condition column to enable the Properties and Operators lists.
3. Type the condition directly into the Condition box, or build the condition by doing the following:
a. In the Properties list, select a property and click Add. InstallShield adds the property to the
Condition box.
b. In the Operators list, select the operator and click Add. InstallShield adds the operator to the
Condition box.
c. In the Condition(s) box, type a value to complete the condition.
4. Click OK.
Caution: No validation is made during design time. Use valid syntax and double-check to ensure that your statement
evaluates to the expected outcome. For more information and for example conditions, see Building Conditional
Statements.
For example, if you have a feature that you want to be selected (by default) only if the user has
administrative privileges, you can give the feature a condition of Not AdminUser and an alternative install
level of 200. If the end user does not have administrative privileges, the condition succeeds, and the
feature will be given the install level 200. Because 200 is greater than the default product install level
(100), the feature will not be selected.
Tip: You can conditionally hide a feature by giving the feature a condition that sets the install level to the special value 0. If
the condition succeeds, the feature will be deselected and will not be displayed in the Custom Setup dialog.
Project: This information does not apply to InstallScript or InstallScript Object projects.
Each feature and subfeature can have a different destination location for its files. By default, a new
feature’s Destination property is INSTALLDIR, initialized to [ProgramFilesFolder]Company
Name\Product Name in the product’s Destination Folder property.
Windows Logo Guideline: According to Windows logo requirements, the default destination of your application’s files
must be a subfolder of the user’s Program Files folder. If you use INSTALLDIR or ProgramFilesFolder as the parent
folder for your feature’s Destination property, your files will be installed to the correct location.
1. Open the Features view or the Setup Design view (in installation projects only).
2. Select the feature. Its property sheet is displayed in the right pane.
3. Click the Destination property to display a list of available destinations.
4. In the Destination list, select a Windows Installer folder property (in square brackets) or select
Browse, create, or modify a directory entry to display the Browse for Directory dialog. Only
uppercase directory identifiers are allowed.
The changes that you make are reflected in the property sheet.
Note: If the component’s destination is set to something other than INSTALLDIR, the components are installed to the
destination specified for each component and changing INSTALLDIR has no effect on the components’ destinations.
An installer folder property such as INSTALLDIR specifies a default value. An end user can change this value by setting a
property when launching Msiexec.exe at the command line or by selecting a new destination folder for a feature in the
Custom Setup dialog.
Project: The feature’s Display property is not available for InstallScript or InstallScript Object projects.
A feature’s Display property indicates how you want the feature presented to the end user in the Custom
Setup dialog.
Following is a list of the Display property options and descriptions:
Table 11-17: Options that Are Available for the Display Property
Option Description
Visible and Collapsed The feature is displayed in the Custom Setup dialog with its
subfeatures collapsed by default.
Visible and Expanded The feature is displayed in the Custom Setup dialog with its
subfeatures expanded by default.
Not Visible The feature and subfeatures are not displayed in the Custom
Setup dialog.
Note: Selecting Not Visible for this property does not have any direct impact on whether or not a feature is installed. A
feature is not automatically installed if it is invisible—it just cannot be deselected if it would otherwise be installed, or
selected if it should not be installed.
Project: The feature’s Install Level property is not available for InstallScript or InstallScript Object projects.
For InstallScript MSI projects, this property is used only if there are no setup types defined for the project.
The install level feature attribute is compared against the INSTALLLEVEL property at run time to
determine which features are available for installation. You can use this attribute to create specific
feature configurations.
Unless the end user deselects features in the Custom Setup dialog, all features with an install level less
than or equal to the value of the package’s INSTALLLEVEL property are installed to the target system.
Note: You can change the package’s INSTALLLEVEL property in the Property Manager.
1. Open the Features view or the Setup Design view (in installation projects only).
2. Select the feature. Its property sheet is displayed in the right pane.
3. For the Install Level property, type an integer for this feature’s install level. The recommended
value is 100.
Project: Release flags are not available for InstallScript or InstallScript Object projects.
Release flags enable you to create different versions of your product without having to create more than
one project. There are two steps for filtering features according to release flags: assigning release flags
and specifying which flags to include in the release.
Project: Release flags are not available for InstallScript or InstallScript Object projects.
Release flags must be set on features that you want to exclude from certain builds. For example, if you
have a feature called Add-ons that should be included only in a special edition of your product, you can
flag that feature and include it only when needed.
1. Open the Features view or the Setup Design view (in installation projects only).
2. Select the feature. Its property sheet is displayed in the right pane.
3. For the Release Flags property, type a string. The string can be any combination of letters or
numbers. To have more than one flag on a feature, use a comma to separate the flags.
To learn how to filter features based on release flags, see Release Flags.
Project: Release flags are not available for InstallScript or InstallScript Object projects.
1. Open the Features view or the Setup Design view (in installation projects only).
2. Select the feature. Its property sheet is displayed in the right pane.
3. Delete the value in the Release Flags property.
Project: The feature’s Remote Installation property is not available for InstallScript or InstallScript Object projects.
The Remote Installation feature property determines whether the feature’s files are installed on the
target system or run from the source medium, such as a CD-ROM or network server. The default value
for a new feature is Favor Local, which means that the files in the selected features are installed on the
target system.
Task To change the Remote Installation property so that the feature’s files run only from the source medium:
1. Open the Features view or the Setup Design view (in installation projects only).
2. Select the feature. Its property sheet is displayed in the right pane.
3. Click the Remote Installation property to display a list of available options.
4. In the Remote Installation list, select Favor Source. Selecting Favor Parent gives a
subfeature the Remote Installation property of its parent feature.
The changes you make are reflected in the property grid.
Caution: Set the Remote Installation property to Favor Local if any of the feature’s components contains an NT service.
Although an end user could change the installation state through the Custom Setup dialog, the Windows Installer cannot
install a service remotely.
Project: The Required Features property is available in the following project types:
• InstallScript
• InstallScript Object
• InstallScript MSI
The Required Features property enables to you specify features required by the current feature. For
example, you might have an installation program with two features—ProgramFiles and HelpFiles. If
it is necessary that end users install ProgramFiles whenever the HelpFiles feature is selected, you
need to use the Required Features property.
3. Click the Required Features property and then click the ellipsis button (...). The Required
Features dialog box opens.
4. Select the ProgramFiles check box.
5. Click OK.
At run time, if the user selects a Custom setup type, feature-selection dialogs such as SdFeatureTree will
not allow the user to deselect the ProgramFiles feature if the HelpFiles feature is selected.
Feature Advertisement
Project: This information does not apply to InstallScript or InstallScript Object projects.
When you set a feature’s Required property to Yes, the end user cannot deselect it in the Custom Setup
dialog (for Basic MSI projects), or the SdFeatureDialog2, SdFeatureMult, or SdFeatureTree dialogs (for
InstallScript MSI projects). The feature will be installed to the target system.
For InstallScript MSI projects, this property pertains only to root-level features. To ensure that a
subfeature is installed to the target system, use the Required Features property to make the subfeature a
required feature of the parent feature. The parent feature’s Required property must be set to Yes.
If the Required property is set to No, the feature is installed by default, but the end user can deselect it.
You can set this property in the Features view.
Reordering Features
When your end users install your product, the Custom Setup dialog displays the features in the same
order that they are displayed in the Features view in InstallShield. You can change the order in which the
features are displayed.
1. Open the Features view or the Setup Design view (in installation projects only).
2. Right-click the feature that you want to move and click Move Up or Move Down. You can also
move a feature left or right, thereby making it a subfeature of another feature or a top-level feature.
Tip: You can also reorder your features by dragging and dropping. Any feature or subfeature can be moved in this way.
Task For example, to deselect a feature if the end user does not have administrator privileges:
1. Open the Features view or the Setup Design view (in installation projects only).
2. Select the feature. Its property sheet is displayed in the right pane.
3. Click the Condition property, and then click the ellipsis button (...). The Feature Condition
Builder opens.
4. Add a new row with 200 in the Level column and Not AdminUser in the Condition column.
5. Click OK.
At run time, if the end user does not have administrator privileges (that is, if the condition succeeds), the
Install Level property for the feature is set to 200. Because the default INSTALLLEVEL property for a
project is 100, the feature is deselected.
Note: You can change the INSTALLLEVEL property in the Property Manager.
Task For example, to hide a feature if the end user running your installation does not have administrative
privileges:
1. Open the Features view or the Setup Design view (in installation projects only).
2. Select the feature. Its property sheet is displayed in the right pane.
3. Click the Condition property, and then click the ellipsis button (...). The Feature Condition
Builder opens.
4. Add a new row with 0 in the Level column and Not AdminUser in the Condition column.
5. Click OK.
After rebuilding your project and running the installation, the feature will not be displayed or installed if
the end user does not have administrative privileges.
Note: Hiding a feature does not automatically deselect it. To deselect the feature so that its data is not installed, call
FeatureSelectItem(MEDIA, "FeatureName", FALSE);.
Project: Setup types are available in InstallScript and InstallScript MSI projects.
Setup types enable you to provide different versions of your installation to your end users. For example,
the default setup types are Complete and Custom for an InstallScript project and Minimal, Typical, and
Custom for an InstallScript MSI project. The Complete and Typical setup types install all of the files
included in your installation. Minimal installs only those files necessary for your application to run. Such
things as multimedia demos are not installed in order to preserve hard disk space. The Custom setup
type lets the end user select which features are installed.
Setup types are based on features. You select the features you would like to associate with each setup
type. Then, when an end user selects a certain setup type, only those features that you associated with
that setup type are installed.
By default, each project that you create contains predefined setup types. In the Setup Types view, you
can add or remove setup types, rename existing setup types, and change which features are associated
with each one.
Project: Setup types are available in InstallScript and InstallScript MSI projects.
Project: Setup types are available in InstallScript and InstallScript MSI projects.
Note: The SetupType function displays only the standard setup types—Typical, Compact, and Custom—with fixed
description text for each. If you want greater flexibility, call SdSetupTypeEx in your script instead. (The default code for
the OnFirstUIBefore event handler includes a call to the SetupType function.)
Tip: To provide an accelerator key for your setup type, include an ampersand (&) before a letter in the name. For example,
the name Cu&stom becomes the label Custom, and the end user can select it during installation by pressing the S key.
Project: Setup types are available in InstallScript and InstallScript MSI projects.
Project: Setup types are available in InstallScript and InstallScript MSI projects.
Project: Setup types are available in InstallScript and InstallScript MSI projects.
Setup types use the following properties:
Property Description
Comment Type comments about the setup type. The comments are for
your use only and do not appear in the installation.
Property Description
Display Name Type the name of the setup type. This is the name that is
displayed to end users when they run your installation.
Merge Modules
A merge module (or .msm file) contains all of the logic and files needed to install distinct pieces of
functionality. For example, many applications require Microsoft Visual Basic run-time .dll files. Instead
of having to include the file in a component and figure out its installation requirements, you can simply
attach the Visual Basic Virtual Machine merge module to one of your project’s features.
Note: Many of the merge modules included in the Redistributables view are authored by Microsoft or another third party.
InstallShield distributes these modules as a courtesy to assist you in creating your installation project. However,
InstallShield cannot modify or fix any problems that may exist within third party-authored modules. You are encouraged to
contact the vendor regarding issues with specific third party-authored modules.
Objects
Like merge modules, objects contain logic and files needed to install distinct pieces of functionality.
Some objects, such as the Microsoft Access object included with InstallShield, require customization
through a wizard. As soon as you add such an object to your installation, its customization wizard opens.
You can either customize your object at the time you add it, or cancel the wizard and customize your
object later by right-clicking the object and selecting Change Objects Settings.
Project: Merge modules that are added to a feature in an InstallScript-based project appear in the Features pane as
subitems of the Merge Module Holder object. This object requires the Windows Installer engine, so you must add the MSI
2.0 Engine object above the Merge Module Holder object.
Tip: To see information about an object or merge module, such as files it installs and other actions it performs, select the
object or merge module name. The information is displayed in the pane on the right.
Note: The BDE module is available only if a Borland tool was present on the system when you installed InstallShield.
3. Right-click the BDE module and select Configure merge module to launch the wizard.
Note: When you add the BDE merge module to an installation, a single-file installation cannot be created. You need to use
a utility like PackageForTheWeb to compress and package your installation into a single, self-extracting executable file.
Tip: The DirectX object is not installed with InstallShield; you need to download it. To include the DirectX object in Basic
MSI or InstallScript MSI projects, obtain the MSI object download. To include the DirectX object in InstallScript projects,
obtain the InstallScript object download. To learn more, see Obtaining Updates for InstallShield.
Redistributable Files
The DirectX objects install all DirectX 9.0c core and optional components, including 32-bit- and 64-bit-
specific components.
Including the DirectX Object in Basic MSI and InstallScript MSI Projects
When you add the DirectX object to a Basic MSI or InstallScript MSI project, InstallShield launches the
DirectX Object Wizard.
You can use the DirectX object in compressed or uncompressed installations; the DirectX Object Wizard
lets you specify whether the DirectX files should be in a folder in the Disk1 folder, or they should be
streamed into the .msi file:
• If you specify that the files should be in a folder in the Disk1 folder, InstallShield creates a DirectX
folder for your installation at build time and places it in the Disk1 folder of your release.
InstallShield lists the DirectX folder in the Disk1 area of the Support Files view (in Basic MSI
projects) or the Support Files/Billboards view (in InstallScript MSI projects).
• If you specify that the files should not be in the Disk1 folder, InstallShield embeds the files in your
installation’s .msi file. InstallShield lists these files in the Language Independent area of the Support
Files view (in Basic MSI projects) or the Support Files/Billboards view (in InstallScript MSI
projects).
Note: The custom action that launches the DirectX installation is sequenced in the Execute sequence and run in deferred
system context so that it can be run with elevated privileges on Windows Vista systems.
Updating the DirectX Object Files for Basic MSI and InstallScript MSI Projects
If you obtain updates for any of the DirectX files and you want to include them in your DirectX object,
place them in the appropriate InstallShield Program Files subfolder with the other DirectX files. The
default location is:
C:\Program Files\Macrovision\IS2008\Objects\DirectX9c\Redist
You can also remove files from that folder if your product does not require them and you do not need to
include them in your installation. For more information about the DirectX redistributable files,
including details about any updates that Microsoft may have released since the current version of
InstallShield was released, see the latest DirectX SDK or Microsoft’s Web site (http://
msdn.microsoft.com/directx).
At build time, InstallShield uses whatever redistributable files are in that DirectX folder to build your
release.
The DirectX 8.0a object contains a merge module that has the logic required to install DirectX 8.0a. It
does so by launching a redistributable .exe file.
The object performs a configuration step that does not require user intervention. When the object
performs the configuration step, it adds the required redistributable .exe files to the to the Disk1 in the
Support Files view. As a result, the build engine copies these files to your disk image at build time. From
this location on the disk image, the merge module attempts to run the DirectX 8.0a installation.
Tip: To change the text of the warning message, you can set a Windows Installer property called
DIRECTX8_NT4_MESSAGE to the text you want to display. If you want the installation to exit instead of continuing
normally, you can set the DIRECTX8_NT4_ISERROR property to any value such as Yes.
• ISINSTALL_MDAC_SKIP
Note: MDAC 2.5 SP1 has been updated to install MDAC 2.5 SP2.
Task To use the InstallShield MSDE 2000 Object for NT Platforms in an InstallScript MSI project:
1. Place the following three function declarations in the function prototypes section of your script
(below the line #include "ifx.h"):
prototype int Msi.MsiGetPropertyA(int, byval string, byref string, byref int);
prototype InstallMSDE();
prototype UninstallMSDE();
2. Place function definitions like the following examples at the end of your script. Be sure to replace
YourMSDEFeatureName in the call to FeatureIsItemSelected with the name of the feature with which the
MDSE object is associated. You can customize the following code to meet your particular needs.
function InstallMSDE()
string szPropVal, svResult;
number nBuffer, nResult, nvResult;
BOOL bFeatVal;
begin
nBuffer = MAX_PATH;
bFeatVal = FeatureIsItemSelected ( MEDIA , "YourMSDEFeatureName" );
MsiDoAction(ISMSI_HANDLE,
"CheckInstance.DEAEC3E7_8F5C_4115_ABD3_E5742E47D469");
nResult = Msi.MsiGetPropertyA(ISMSI_HANDLE,"INSTANCEFOUND",szPropVal,nBuffer);
GetSystemInfo (OS, nvResult, svResult);
if ((szPropVal="")&&(bFeatVal=TRUE)) then
if (nvResult=IS_WINDOWS9X) then
MessageBox("Cannot install MSDE on Windows 9X machines. " +
"Please contact your setup provider for more information. " +
"Setup will now exit.", WARNING);
abort;
else
MessageBox("Preparing the MSDE 2000 setup. " +
"This may take a few minutes...", INFORMATION);
nResult = MsiDoAction(ISMSI_HANDLE,
"InstallMSDE.DEAEC3E7_8F5C_4115_ABD3_E5742E47D469");
if (nResult!=0) then
MessageBox("MSDE 2000 Installation failed. " +
"Setup will now stop.", WARNING);
abort;
else
nResult = Msi.MsiGetPropertyA(ISMSI_HANDLE,
"REBOOTISMSDE2000",szPropVal,nBuffer);
if (szPropVal="") then
MsiDoAction(ISMSI_HANDLE,
"SetReboot.DEAEC3E7_8F5C_4115_ABD3_E5742E47D469");
endif;
endif;
endif;
endif;
end;
function UninstallMSDE()
string szUninstKey, svUninstVal, svRemMSDE, szProdCode;
number BufSize, nvType, nResult;
begin
nvType = REGDB_STRING;
BufSize = MAX_PATH;
nResult = Msi.MsiGetPropertyA(ISMSI_HANDLE,"ProductCode",szProdCode,BufSize);
szUninstKey = "SOFTWARE\\InstallShield\\ObjectRuntime\\ISMSDE2000\\" + szProdCode;
RegDBSetDefaultRoot ( HKEY_LOCAL_MACHINE );
RegDBGetKeyValueEx ( szUninstKey, "UninstallKey" , nvType, svUninstVal , BufSize);
nResult = Msi.MsiGetPropertyA(ISMSI_HANDLE,"REMOVEMSDE",svRemMSDE,BufSize);
if ((svRemMSDE!="")&&(svUninstVal!="")) then
MsiDoAction(ISMSI_HANDLE,
"UninstallMSDE.DEAEC3E7_8F5C_4115_ABD3_E5742E47D469");
endif;
end;
3. Call InstallMSDE in the OnFirstUIBefore event handler function just before or after the line
Enable(STATUSEX);.
4. Call UninstallMSDE in the OnMaintUIBefore event handler function just before the Dlg_Start block’s
endif statement, so that UninstallMSDE is called only if the end user selects and confirms
uninstallation.
Note: If Needs to be downloaded is specified in the Location column for the setup prerequisite that you added to
your project, that prerequisite is not installed on your computer. You can download the prerequisite from the Internet to
your computer if you would like to include it in your project. If you build a release without first downloading one or more
required prerequisites, and if you specify that the prerequisites should be extracted from Setup.exe or copied from the
source media (instead of being downloaded from the Web to the end user’s computer), one or more build errors may be
generated. To eliminate the build errors, remove the prerequisite from your project, download it to your computer, or
change the setup prerequisites location for the release to the download option; then rebuild the release.
Project: This information applies to Basic MSI and InstallScript MSI projects.
InstallShield includes setup prerequisites for some versions of the .NET Framework and the .NET
Framework language packs. You can include these setup prerequisites in Basic MSI and InstallScript
MSI projects if you want to redistribute these versions of the .NET Framework and the language packs.
Following is a list of the .NET Framework redistributables that are available as setup prerequisites. The
associated language pack setup prerequisites are included if available.
• Microsoft .NET Framework 3.0
The setup prerequisite installations determine if the corresponding version of the .NET Framework is
already installed on the target machine by checking the Install value for a particular
HKEY_LOCAL_MACHINE key. For more details, you can open any setup prerequisite in the Setup
Prerequisite Editor and note the conditions that are set.
You can include in your installation a setup prerequisite that installs MySQL Connector/ODBC 3.51. It
enables end users to connect to a MySQL database server that uses ODBC. Before you can add this setup
prerequisite to your projects, you must download the MySQL Connector/ODBC driver and configure the
setup prerequisite on your system.
Task To add the MySQL Connector ODBC 3.51 setup prerequisite to your system so that you can add it to your
projects:
1. Open Windows Explorer and browse for the setup prerequisite template folder. The default location
is:
C:\Program Files\Macrovision\IS2008\SetupPrerequisites\Templates
2. Copy the MySQL Connector ODBC 3.51.prq file that is in the Templates folder, and paste it in the setup
prerequisite folder. The default location is:
C:\Program Files\Macrovision\IS2008\SetupPrerequisites
The next time that you launch InstallShield, the MySQL Connector ODBC setup prerequisite is available
in the Redistributables view.
If you want to change the location on your machine where you store the installer for the MySQL
Connector/ODBC 3.51 driver, you can do so by opening the MySQL Connector ODBC 3.51.prq file in the
Setup Prerequisite Editor. To open the Setup Prerequisite Editor, click Prerequisite Editor on the Tools
menu. For more information, see Specifying Files for a Prerequisite.
• InstallScript MSI
If you want to install the Oracle 10g Instant Client before your installation is run, you can include the
Oracle 10g Instant Client setup prerequisite in your project. Before you can add this setup prerequisite to
your projects, you must download Oracle Instant Client and create an .msi package on your system. For
more information, see Connecting to an Instance of Oracle and Running SQL Scripts.
Windows Installer, This merge module is not installed on your computer but it is
InstallScript available for download.
Windows Installer This setup prerequisite is not installed on your computer but
it is available for download.
Project: If you add to your Windows Installer project a redistributable that is not installed on your computer, one or more
build errors are generated when you build a release. To eliminate the build errors, either remove the redistributable from
your project or download it before rebuilding the release. If a redistributable is not installed on your computer, Needs to be
downloaded is specified in the Location column for that redistributable.
InstallShield does not permit you to add a redistributable to your InstallScript project if it is not installed on your computer.
Merge Modules
Merge modules are available from a variety of sources. Although InstallShield includes many
redistributable modules, new versions may be available or other software developers may have released
a module that you need. In addition, InstallShield enables you to create your own merge modules and
add them to your redistributables gallery.
The source of the merge module files listed in the Redistributables view is the folder or folders specified
on the Merge Modules tab of the Options dialog box. To access the Options dialog box, on the Tools
menu, click Options.
The following directory is the default location for the modules that come with InstallShield:
InstallShield Program Files Folder\Modules\i386
Objects
InstallShield provides many redistributable objects and lets you create your own for inclusion in your
installations. Furthermore, you may want to add to your projects the objects that other developers
created with InstallShield.
The default location for the objects that come with InstallShield is:
InstallShield Program Files Folder\Objects
The objects that are included in the above location are listed in the Redistributables view.
Setup Prerequisites
Several setup prerequisites are available in InstallShield. In addition, the Setup Prerequisite Editor in
InstallShield enables you to modify these prerequisites and create your own. All setup prerequisite (.prq)
files are stored in the following location:
InstallShield Program Files Folder\SetupPrerequisites
Task To download all of the merge modules, objects, and setup prerequisites that are needed for your installation
project:
4. Launch InstallShield.
The modifications made are reflected in the Redistributables view.
1. Close InstallShield.
2. Using Windows Explorer, locate and delete the merge module that you want to remove from the
gallery. Ensure that you search each directory specified on the Merge Modules tab of the Options
dialog box.
3. Launch InstallShield.
The modifications made are reflected in the Redistributables view.
Note: If you delete a merge module that is currently associated with your installation, the message [Merge Module Not
Found] is displayed to inform you that the module cannot be included in your installation.
1. Close InstallShield.
2. Using Windows Explorer, locate and delete the setup prerequisite that you want to remove from the
gallery. Setup prerequisites are located in the following directory:
3. Launch InstallShield.
The modifications made are reflected in the Redistributables view.
Module Dependencies
When a module is created, dependencies are set for it. This means that a module will not work if you do
not include its dependencies as well. InstallShield automatically associates a module’s dependencies
with your installation project if they are stored in your local redistributables gallery. If those modules
cannot be found, you need to obtain a copy of each and associate them with your installation project in
the Redistributables view.
Module Exclusions
Some modules do not operate correctly in the presence of certain other modules. If this is the case, the
module’s author should list them as exclusions and they should appear in the description window of the
Redistributables view. If your newly associated module has exclusions, and those excluded modules
have already been associated with your installation, InstallShield silently removes any reference to them
in your installation.
Caution: Any excluded modules that are added to the installation after the excluding module has been added will not be
removed; in addition, you will not receive any warning that they are incompatible.
If you are creating a completely new dependency, see Adding Dependencies to Merge Modules for more
information.
Note: This procedure redirects only the TARGETDIR directory in the merge module, or directories that derive directly
from TARGETDIR. If the merge module is configured to send files to a predefined folder (for example, SystemFolder), you
cannot override the module’s destination.
Setup Prerequisites
Project: Setup prerequisites can be included in Windows Installer and ClickOnce projects.
InstallShield provides several third-party redistributables that you can incorporate into your project as
setup prerequisites. A setup prerequisite is a base application or component that must be installed on
the target machine before your application can be installed. If you include more than one setup
prerequisite in an installation, you can specify the order in which the prerequisites should be installed.
Some examples of setup prerequisites are Java Runtime Environment (JRE), Jet 4.0, and SQL Server
2005 Express Edition.
Including setup prerequisites in your project enables you to chain multiple .msi files together into a
single Setup.exe file, bypassing the Windows Installer limitation that enables only one .msi file to be
executed at a time. The Redistributables view is where you add setup prerequisites to a Windows
Installer–based project. The Installation Requirements page is where you add setup prerequisites to a
ClickOnce project.
When InstallShield builds a Setup.exe file for a project that does not include any prerequisites, it starts
with the base Setup.exe file stored in the following location:
InstallShield Program Files Folder\redist\Language Independent\i386
However, when InstallShield builds a Setup.exe file for a project that includes prerequisites, the
aforementioned Setup.exe file cannot be used as the base because it does not have the capability of
including prerequisites. A slightly larger file called SetupPrereq.exe is used instead. This base
SetupPrereq.exe file is located in the same directory as the base Setup.exe file. Since two different base
files—Setup.exe and SetupPrereq.exe—are used, only installation authors who are actually including
prerequisites in their projects incur the additional size overhead in the final, built Setup.exe file that is
distributed to end users.
• Compress the setup prerequisite files into Setup.exe, to be extracted at run time, as needed.
• If needed, your installation can download the setup prerequisite files included in your project from
the URL specified in the setup prerequisite (.prq) file for each prerequisite.
You can specify different methods for each setup prerequisite in your project. To learn more, see
Specifying a Location for a Specific Setup Prerequisite.
You can also override individual methods at the release level if you want all of the prerequisites in a
release to be available through the same method. For more information, see Specifying the Location for
Setup Prerequisites at the Release Level.
You can configure a setup prerequisite so that it is installed either before or after any installation of the
Windows Installer engine and the .NET Framework. For more information, see Specifying Parameters
for Installing a Prerequisite.
Project: Setup prerequisites can be included in Windows Installer and ClickOnce projects.
When you include setup prerequisites in an installation, the Setup.exe setup launcher checks the target
machine to determine whether one or more of the setup prerequisites must be installed. If the full user
interface of a prerequisite installation is displayed, Windows Installer displays a message box that lists
all of the prerequisites that must be installed. If the end user clicks Cancel, the installation stops. If the
end user clicks Install, the prerequisites are installed and the installation continues.
Project: Setup prerequisites can be included in Windows Installer and ClickOnce projects.
Your installation may consist of your application plus one or more setup prerequisites. If end users
uninstall your application through Add or Remove Programs in Control Panel, the setup prerequisites
are still installed on their machines. They need to uninstall each setup prerequisite individually in Add
or Remove Programs if they want to remove them from their machines.
Although Windows Installer is built into Windows 2000, Windows Me, Windows XP, and Windows
Vista, other Windows platforms require that the Windows Installer be installed before any Windows
Installer installations can run on those systems. In addition, your installation may depend on certain
functionality that is available in only the latest versions of Windows Installer. InstallShield gives you the
option of including with your installation a Windows Installer redistributable in a self-extracting
executable file called Setup.exe.
For a list of the minimum operating system requirements for each version of Windows Installer, see
Target System Requirements. For a list of which versions of Windows Installer were released with which
versions of Windows, see Released Versions of Windows Installer in the Windows Installer Help
Library.
Note that Windows Installer 4.0 is not available as a redistributable.
Note: InstallScript MSI installation projects require Setup.exe because Setup.exe initiates the external user interface
for Windows Installer.
If you plan to distribute your installation in more than one language, Setup.exe is required if you want to
provide end users the option of selecting which language version of the installation they would like to
run.
Tip: If an end user installs your installation on a Windows 2000 (or later) system that has an earlier version of Windows
Installer than what your installation provides, Setup.exe may display a warning. If you want to suppress this warning, set
the Suppress Launcher Warning property in the Releases view to Yes.
• For .NET Framework 2.0, 1.1, or 1.0 redistributables (32 bit)—Configure the .NET settings for the
release in the Releases view. As an alternative, you can select the appropriate options through the
Release Wizard.
To test whether the .NET Framework is already installed on the target system, you can use the built-in
MsiNetAssemblySupport property. It is set to the version of a particular .NET DLL (fusion.dll) if
the .NET Framework is installed, and it is not set if the .NET Framework is not installed.
InstallScript Projects
If you want to include one or more versions of the .NET Framework in an InstallScript project, use the
Objects view to add the Microsoft .NET Framework object to your installation. This object also enables
you to add one or more language packs to an InstallScript project. To learn more, see Microsoft .NET
Object Wizard.
To determine whether a particular version of the .NET Framework or a language pack is installed, use
the Is function and pass the DOTNETFRAMEWORKINSTALLED predefined constant.
• (Windows Installer projects only) In the Redistributables view, clear the check box in front of the
redistributable.
• (InstallScript projects only) In the Objects view, right-click the redistributable in the Features
window and click Delete from project.
Any dependencies associated with the redistributable are automatically removed.
Tip: If a setup prerequisite is included in your installation as a dependency of another setup prerequisite but you want to
remove that dependency prerequisite from the installation, you must remove the corresponding dependency from the
prerequisite. For more information, see Removing a Dependency from a Prerequisite.
Note: This method will work only for the Access 97, ODBC 3.51, and DCOM Deployment objects. You cannot and need
not use script-defined variables with other objects.
Task To specify a different location for each setup prerequisite in your installation:
Task To add a release flag to a setup prerequisite that you have added to your installation project:
Task To specify the order in which the setup prerequisites should be installed on the target machine:
1. In the Redistributables view, add the necessary setup prerequisites to your project if you have not
already done so.
2. Right-click any redistributable and click Set Setup Prerequisite Order. The Setup
Prerequisite Installation Order dialog box opens.
3. Select a prerequisite in the list and then click the up or down arrow to move it up or down in the
order for installation.
Tip: If the Windows Installer engine or the .NET Framework must be installed before a setup prerequisite is installed, you
can open the setup prerequisite in the Setup Prerequisite Editor and configure it as necessary. For more information, see
Specifying Parameters for Installing a Prerequisite.
Task To locate the correct merge module file, you need to browse to the correct file:
• Copy the merge module you want into one of the folders that is already listed in the Merge Module
Locations box.
• Remove the default folders from the search path so that you are referencing only the shared
location.
Task To publish a merge module to a repository when you are working on a Windows Installer–based installation:
Merge modules are built into an installation at build time. If you make a change to a repository merge
module and then republish it to the repository, any project that has the old version of the repository
merge module will be updated the next time that a release of the project’s installation is rebuilt.
Perform Static Scanning The Static Scanning Wizard looks at many of the files that
you have in your installation and checks for any
dependencies that they may require.
Perform Dynamic Scanning The Dynamic Scanning Wizard monitors your system while
an executable file is running. It then adds to your project any
.dll or .ocx files that are required by the application.
Import Visual Basic Project The Visual Basic Wizard scans your Visual Basic project for
all dependencies and adds them to your installation project.
Any files that are added to a Windows Installer–based installation through one of these scanners are
added in accordance with Setup Best Practices.
To include all files needed by a .NET solution, open your project from within Microsoft Visual Studio
and drag project outputs from your .NET project to the InstallShield project.
Task To launch the Visual Basic Wizard in InstallShield, do one of the following:
The file must remain in this location after you edit it to ensure that the scanners work properly.
Tip: You can also use the Filters.xml file to control which registry items should be excluded during COM extraction. For
more information, see Filtering Registry Changes for COM Extraction.
Excluding Files
The <Exclude> element in the Filters.xml file is where you add subelements for each of the files that
you want the scanners to exclude. Any files that are listed here will not be added to your installation
project by the scanners.
By default, the <Exclude> element has subelements for common system files that are present on all
Windows–based machines.
Including Files
The <Include> element in the Filters.xml file gives you the ability to override individual files that are
subelements of the <Exclude> element. Any files that are listed in subelements of the <Include>
element will be added to your installation project by the scanners, even if the files are also listed in
subelements of the <Exclude> element.
Note: The following vital operating system files are never recognized by the scanner, even if you add them as
subelements of the <Include> element:
• kernel32.dll
• ntdll.dll
• user32.dll
• gdi32.dll
• advapi32.dll
• shell32.dll
• ole32.dll
Attribute Description
name This attribute must be lowercase. The value of this attribute (for example,
myfile.dll in the above example) indicates the name of the file that you want to
include or exclude.
path This attribute is optional. The value of this attribute (for example,
[SystemFolder] in the above example) indicates the path of the file.
Any other attributes are optional and are not recognized by the scanners. You may want to add
additional attributes—such as the We attribute in the example above and the corresponding
"needthis" value—to identify why an item is being excluded or included.
Important: Ensure that your XML code is well formed; if its not well formed, all of the filters fail. In most cases, you can
identify improperly formed XML code by opening the Filters.xml file in Internet Explorer. You should be able to expand
and contract the <Filters>, <Include>, and <Exclude> elements; if you cannot, check the code for errors.
If you add subelements to the <Exclude> or <Include> elements, be sure that you do not place them within the
commented-out section, since InstallShield ignores that area of the Filters.xml file.
The following sample XML code shows the format of the Filters.xml file:
<Filters>
<Include>
<!--Instructions on how to add files to this element.
-->
<File name="mfc42.dll" We="needthis"/>
</Include>
<Exclude>
<!--Instructions on how to add files to this element.
-->
<Registry key="HKEY_CLASSES_ROOT\Interface\{00020404-0000-0000-C000-000000000046}"/>
<File name="12520437.cpx" path="[SystemFolder]" W2kSp4="WPF" WxpSp2="WPF" W2k3Sp1="WPF"
WinMe="WPF"/>
<File name="12520850.cpx" path="[SystemFolder]" W2kSp4="WPF" WxpSp2="WPF" W2k3Sp1="WPF"
WinMe="WPF"/>
</Exclude>
</Filters>
Since each component should have only one portable executable file, the assumption is that all of the
registration information belongs to a single file, marked as the key file of its component.
You can also manually add COM information to a component in the component’s advanced settings.
InstallShield employs a special technique to find all COM information on a COM server without actually
registering it. Therefore, COM extraction does not affect the system registry. However, some COM
servers’ registration processes depend on existing registry entry values. Although InstallShield has
developed an algorithm to avoid this scenario, it may not be foolproof in some extreme cases.
Caution: Some applications, like WinRunner, insert hook .dll files into the COM extraction engine. This causes COM
extraction to fail and displays the following message: "ISRegSpy detects following module %1 hooked into this process,
which causes ISRegSpy to malfunction. You need to shut the application down and restart COM extraction." If you
encounter this message, shut down the application and restart COM extraction, as the dialog box instructs.
Do not select the self-registering property for .exe files that are not self-registering. To self-register an .exe file, you need
to launch the .exe file with the /regserver command. However, if the .exe file does not support the command line switch,
the .exe file will be launched during extraction at build time.
You can also set the COM Extract at Build property for the component to No. Use this method if you
want InstallShield to register the file according to the information statically contained in the
component’s COM Registration advanced setting. This advanced setting stores information about the
file’s COM classes, ProgIDs, and so on, that were either extracted in the Component Wizard or entered
in the advanced setting.
Note: The definitions of the COM-related Windows Installer tables prevent a COM server from being placed in more than
one feature. If a COM server needs to be placed in more than one feature, the following are two available options:
• Make the second feature that requires the COM server a child of the first, and place the file in the parent feature.
• Use self-registration on the COM server instead of using the COM-related Windows Installer database tables.
The file must remain in this location after you edit it to ensure that COM extraction works properly.
Tip: You can also use the Filters.xml file to control which files should be included or excluded during dependency
scanning. For more information, see Filtering Files in Dependency Scanners.
By default, the <Exclude> element has subelements for common system registry keys that are required.
Following is a sample of a properly formatted registry subelement that blocks changes to only the default
value of an InprocServer32 registry key:
<Registry key="HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{00000231-0000-0010-8000-
00AA006D2EA4}\InprocServer32" value=""/>
Following is a sample of a properly formatted registry subelement that blocks changes to only the
ThreadingModel value name for an InprocServer32 registry key:
<Registry key="HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{00000231-0000-0010-8000-
00AA006D2EA4}\InprocServer32" value="ThreadingModel"/>
Attribute Description
key This attribute must be lowercase. The value of this attribute (for example,
HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{00000231-0000-0010-
8000-00AA006D2EA4}\InprocServer32 in the above examples) indicates the
name of the registry key that you want to filter.
Any other attributes for the <Registry> subelement are optional and are not recognized by the COM
extraction process. You may want to add additional attributes to identify why an item is being excluded.
Important: Ensure that your XML code is well formed; if its not well formed, all of the filters fail. In most cases, you can
identify improperly formed XML code by opening the Filters.xml file in Internet Explorer. You should be able to expand
and contract the <Filters>, <Include>, and <Exclude> elements; if you cannot, check the code for errors.
If you add subelements to the <Exclude> or <Include> elements, be sure that you do not place them within the
commented-out section, since InstallShield ignores that area of the Filters.xml file.
The following sample XML code shows the format of the Filters.xml file:
<Filters>
<Include>
<!--Instructions on how to add files to this element.
-->
</Include>
<Exclude>
<!--Instructions on how to add files to this element.
-->
<Registry key="HKEY_CLASSES_ROOT\Interface\{00020404-0000-0000-C000-000000000046}"/>
<File name="12520437.cpx" path="[SystemFolder]" W2kSp4="WPF" WxpSp2="WPF" W2k3Sp1="WPF"
WinMe="WPF"/>
<File name="12520850.cpx" path="[SystemFolder]" W2kSp4="WPF" WxpSp2="WPF" W2k3Sp1="WPF"
WinMe="WPF"/>
</Exclude>
</Filters>
Tip: If the self-registering file is part of a 64-bit component, 64-bit self-registration occurs on the target machine. For more
information, see Targeting 64-Bit Operating Systems.
When you mark a COM server .dll or .ocx file as self-registering, the file’s own registration function
(DllRegisterServer) is called during installation to register it with the target system, and its unregistration
function (DllUnregisterServer) is called during uninstallation to unregister the file.
Registering a file with DllRegisterServer has several limitations:
• COM information registered with DllRegisterServer cannot be advertised.
• Because DllRegisterServer is .dll code, its effects cannot reliably be rolled back during a failed
installation.
• DllRegisterServer cannot distinguish between per-user and per-machine COM information on
systems running Windows 2000 and later.
• Self-registration may require COM servers to be registered in a particular order. InstallShield self-
registration (ISSelfReg) enables you to overcome this limitation.
• DllRegisterServer generally does not register a file with a relative path, as needed by systems that
support side-by-side sharing.
When you mark one or more files as self-registering, InstallShield adds data to a table of your .msi
database, and adds some custom actions related to self-registration to your installation Execute
sequence. For details, see Self-Registration Methods and InstallShield Self-Registration (ISSelfReg).
On systems running Windows 2000 and later, per-machine self-registration information is stored in the
registry key HKLM\SOFTWARE\Classes\CLSID, and per-user self-registration information is stored in
HKCU\SOFTWARE\Classes\CLSID; a merged view of the data is available under HKCR\CLSID. On
systems running Windows NT 4 and Windows 9x, COM registration information is stored in
HKCR\CLSID.
Self-Registration Methods
On the Preferences tab of the Options dialog, you can select whether you want to use the InstallShield
self-registration method (ISSelfReg) or the Windows Installer self-registration method (SelfReg).
InstallShield Self-Registration
InstallShield self-registration does the following:
• Can register .exe, .tlb, .dll, and .ocx files.
• Uses batch mode registration to handle any registration dependencies at run time.
Note: With InstallShield self-registration, you can specify the order in which the files are registered at run time. You can set
the order in the ISSelfReg table (Order column) in the Direct Editor.
In addition, if your project contains any files (or dynamic links) marked as self-registered, InstallShield
adds the following custom actions to the Execute sequence of your installation.
Table 11-23: Custom Actions Added to Projects that Have Self-Registering COM Servers
Action Description
• A component is not suitable for Reg-Free COM if it is a system component or part of the operating
system. In addition, it is not suitable if it is a data access component such as Microsoft Data Access
Components (MDAC). These types of components should not be isolated. Some of these
components, such as MDAC, can be included in an installation as a redistributable.
• A COM component can be isolated only once per application. Consider grouping COM components
in a single class library as a workaround to this limitation.
On a Windows XP system, the presence of the manifest file enables the application to use methods from
the COM library without the libraries having been registered in the target system’s registry. Windows XP
uses the COM libraries in the current directory before using any other versions of the libraries that may
be registered on the target system.
Traditionally, release engineers have been fully responsible for interacting with software developers and
creating installations for software deployment. With the InstallShield Collaboration model, software
developers can directly participate in the installation design. They can communicate all their installation
requirements in an XML-structured text file that is authored alongside other source code that makes up
a software module. These files are Developer Installation Manifest (.dim) files and can be authored using
InstallShield Collaboration or InstallAnywhere Collaboration and edited in any text editor.
Once the .dim files have been created, they can be referenced in a Basic MSI or Merge Module project in
InstallShield. When a project that contains .dim files is built, all DIM references are automatically
consumed in the process.
Project: In Basic MSI projects, DIM references must be associated with a feature.
Merge Module projects do not contain features. If you add a merge module that contains DIM references to an installation
project, InstallShield associates the DIM references with the feature in the installation project that contains the merge
module.
Currently, you can reference .dim files in the following InstallShield views:
• Setup Design (Basic MSI projects)
Tip: You can also add a new DIM references to a Basic MSI project by adding it to a feature. For more information, see
Adding a New DIM Reference to a Feature.
Project: In Basic MSI projects, DIM references must be associated with a feature.
Merge Module projects do not contain features. If you add a merge module that contains DIM references to an installation
project, InstallShield associates the DIM references with the feature in the installation project that contains the merge
module.
You can associate a DIM reference with one or more features in a Basic MSI project.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, right-click a Web site, and click Insert DIM Virtual Directories. The
Associate DIM References dialog box opens.
3. Select the .dim file that you want to associate with the Web site, and click OK.
InstallShield adds the DIM reference to the IIS Web site.
Project: This information does not apply to the Smart Device projects. In addition, certain portions do not apply to certain
types of project, as noted.
Every installation changes the target system in some way. The simplest installations might only copy
files. More in-depth installations make registry changes, edit .ini files, create shortcuts, configure ODBC
resources, use environment variables, and modify XML files. For more information on how to configure
the target system, refer to the “Configuring the Target System” section.
Shortcut Locations
The Shortcuts view has a set of predefined folders under which you can create shortcuts and subfolders.
You can access additional folders by right-clicking the top item in the Shortcuts explorer, pointing to
Show Folder, and then clicking the appropriate predefined folder.
Shortcut
Destination Description
Programs The first two destinations—Programs Menu and Startup—are located on the
Menu and Start menu. The Programs folder is the industry standard and Microsoft’s
Startup suggested method. The Startup folder should contain shortcuts to items that
need to be launched whenever Windows starts.
Send To Folder The Send To folder is accessed when a user right-clicks a file. The context
menu contains a command called Send To. If you create a shortcut for your
program in this folder, an end-user can click any file and send it to your
program.
For example, you might want your end user to be able to open an HTML page in
Notepad. If you created a shortcut to Notepad in the Send To menu in the
Shortcuts explorer, the end user could right-click an HTML file and click
Notepad from your Send To menu. The source file for that page opens in
Notepad.
Desktop The final shortcut location is the end user’s desktop. When you create a
shortcut in the desktop folder, your program’s icon is displayed on the end
user’s desktop.
Note: The desktop is the most visible place to put a shortcut, but too many
shortcut icons can clutter the end user’s desktop.
Types of Shortcuts
InstallShield offers several types of shortcuts:
New Shortcut Creates a new shortcut to a file that exists in your installation
project.
New Advertised
Shortcut
Project: This type of shortcut is available in Windows Installer–
based projects.
Creates an advertised shortcut. The component’s files are not
installed to the target system until the end user launches the
shortcut.
New Shortcut to Creates a shortcut to a file that already exists on the target
Preexisting File system.
New Folder Creates a program folder. You can create a program folder if you
want to your shortcut to appear under your company name, for
example.
Creating Shortcuts
Before you create a shortcut, you should create at least one feature and component. If you have not
created a component when you create your first shortcut, InstallShield creates a component for you. You
can change the component to which the shortcut belongs by setting the shortcut’s Component property.
You can use the Shortcuts view to add shortcuts to your project. As an alternative, you can also use the
Components view or—in installation projects only—the Setup Design view. If you use either the
Components view or the Setup Design view, click the Shortcuts item in the explorer; a separate
Shortcuts explorer opens in a new pane.
3. Enter a new name, or right-click it later and click Rename to give it a new name.
4. Define the shortcut’s properties.
Note: You can create a program folder if you want your shortcut to appear under your company name, for example. When
you have created a folder for your shortcut, you can create the shortcut by right-clicking your new folder and then clicking
New Shortcut.
Renaming Shortcuts
When you create a shortcut, your shortcut appears with a default internal name. This name is not
displayed to end users, but you can change it to something that is relevant to your project.
InstallShield changes the icon that is displayed for the shortcut in the Shortcuts explorer to the one that
you specified, unless either of the following conditions is true:
• The project type is InstallScript.
InstallShield also uses this icon for a shortcut in the Shortcuts explorer if the file that is selected in the
Icon File setting does not contain an icon.
Project: For Basic MSI, InstallScript MSI, and merge module projects: Since Windows Installer requires a separate icon
when the component is advertised, InstallShield extracts the icon from any executable file that you specify.
Tip: For Basic MSI, InstallScript MSI, and merge module projects: You can also right-click the icon in the Shortcuts view
and then click Change Shortcut icon to specify a different shortcut icon. InstallShield updates the value in the Icon File and
Icon Index settings with the values that you specify using this method.
Windows Logo Guideline: According to current Microsoft Certified for Windows Vista guidelines, best practice is to not
place shortcuts to remove the application in the Start menu. An uninstallation shortcut is unnecessary because your
application’s uninstaller is in Add or Remove Programs.
You can create an uninstallation shortcut to make it easier for end users to uninstall your product from
their systems. When launched, the shortcut automatically starts the uninstallation process.
Msiexec.exe is the command-line engine for the Windows Installer service. The /x argument
instructs the Windows Installer service to uninstall the product referenced by the product code.
5. Set the Advertised field to No.
6. In the Target field, select [SystemFolder], and then append msiexec.exe to this location.
7. In the Component field, select the component with which you want this shortcut associated. To
ensure that the shortcut is always installed, associate it with the component containing your
application’s main executable file.
Note: You may not want to create an uninstallation shortcut. An uninstallation shortcut is unnecessary because your
application’s uninstaller is in Add or Remove Programs.
You can create an uninstallation shortcut to make it easier for end users to uninstall your product from
their systems. When end users launch the shortcut, the uninstallation process automatically starts.
It is necessary to use the UNINSTALL_STRING variable/text substitution to ensure compatibility with
future releases and to guarantee that the shortcut matches the uninstall string in Add or Remove
Programs. Although it is possible to do this through the Shortcuts view, the UNINSTALL_STRING must
be parsed and quotation marks must be used. Therefore, since you need to use InstallScript even if you
use the Shortcuts view, it is easier to use the AddFolderIcon function than to use the Shortcuts view.
The following InstallScript code creates a shortcut called Uninstall Application on the desktop after
file transfer. Launching this shortcut runs your installation in maintenance mode. This code works for
both InstallScript and InstallScript MSI projects.
function OnMoved()
string szApp, szCmdLine;
number nDelimiter;
begin
// Create shortcut.
AddFolderIcon( FOLDER_DESKTOP, "Uninstall Application", szApp + szCmdLine, "", "", 0, "",
REPLACE );
endif;
end;
URL=http://www.MySite.com
InstallScript Project
The AddFolderIcon function creates a shortcut to a folder if you pass the path to the folder in the third
(szCommandLine) parameter.
For example, this code creates a shortcut to the Common Files folder in the end user’s Programs folder:
ProgDefGroupType(COMMON)
szFolder = TARGETDIR;
LongPathToQuote(szFolder, TRUE);
AddFolderIcon(
ProgramMenuFolder, // where shortcut will appear
Shortcut Properties
After creating a shortcut, you need to set its properties. Shortcut properties allow you to link the shortcut
to a file, provide a description of the shortcut, or pass arguments.
Property Description
Display Name The name of the shortcut as it appears on the target machine. Type a new
name in this field, which is then automatically added to the string table (to allow
for easier translation), or select an existing string table entry by clicking the
String Table tab at the bottom of the page.
The shortcut display name is of the Windows Installer Filename data type. If the
display name is longer than eight characters, the Short Name | Long Name
format is used in the property grid. Windows Installer requires the Short Name |
Long Name format for file names that are not already in the 8.3 format.
Note: The Display Name property is required. If there is no value in this field, an
error occurs at build time.
Property Description
Description
Advertised
Target The target file for the shortcut. The file can be part of your installation project,
or it can be a file that you know is on the target system. The target property
contains the path to the file—on the end user’s system—that this shortcut will
launch.
Component The component (or, in InstallScript projects, components) to which you want
this shortcut to belong. Click the ellipsis button (...) to display the Browse for a
Component dialog box.
Features
Property Description
Icon File Specify the file that contains the icon for the shortcut that you are creating. You
must specify an .ico file or the executable file (.dll or .exe) that contains the icon
resource. The method that you use to specify the file depends on the type of
project that you are using.
Project: For InstallScript projects: Type the fully qualified path to the file on the
target system that contains the icon.
For Basic MSI, InstallScript MSI, or merge module projects: You can either type
the fully qualified path to the file that contains the icon, or click the ellipsis (...)
button to browse to it. Note that because Windows Installer requires a separate
icon file, InstallShield extracts the first icon in the executable file unless an icon
index is specified. If you leave this property blank, the key file of this
component is automatically set as the shortcut’s icon.
Icon Index If the icon file that you specify contains more than one icon resource, enter the
index in the Icon Index setting.
• A nonnegative integer refers to the order of the icon resources in the
executable file. For example, 0 refers to the first icon in the file, 1 refers to
the second icon, and 2 refers to the third icon.
• Use a negative number to refer to a specific resource ID. For example, the
icon index -12 points to the icon with a resource ID of 12.
Run Select a run command to specify how the program is launched when the
shortcut is double-clicked:
• Normal Window—Launches the program in a standard-sized window.
• Maximized Window—Launches the program in full-screen view.
• Minimized Window—Launches the program in a minimized window,
visible only on the taskbar.
Arguments Enter the command-line arguments for the shortcut. The arguments are added
to the Target value of the shortcut’s property sheet. These arguments work in
the same way as any other command-line arguments. For example, you can link
a file to an executable file or cause an executable file to run silently by passing
command-line arguments.
Note: Verify that the syntax is correct because InstallShield does not do this.
Tip: Use %1 in the argument for the selected file name. For example, if the end
user right-clicks the file C:\File.ext and -p %1 is the argument for this
shortcut, the command-line argument becomes -p C:\File.ext. In some
cases, it is necessary to enclose the %1 argument in quotation marks—as in
"%1"—to correctly handle file names that contain spaces.
Property Description
Working The working directory is the directory that common Open and Save dialog
Directory boxes default to. Enter the path to the directory that you would like to specify
as the working directory for this shortcut, or select a property from the list and
customize it to your needs.
Hot Key Enter the decimal value of the accelerator key combination for your shortcut.
For example, if your key combination is CTRL+ALT+A, enter 1601. This number
is obtained by combining the hex value of CTRL (200) and the hex value of ALT
(400) with the logical Or operator. Then, add that number (600) to the hex value
for A (41) and convert it to decimal value. Therefore, the number you are
converting to decimal is 641. After the conversion, it is 1601. For more
information, see Shortcut Accelerator Keys.
Key Name
Property Description
Display
Resource DLL
Project: This property is available in Windows Installer–based projects.
If you are preparing an installation for a multilingual application and Windows
Installer 4.0 will be running the installation, specify the full path to the language-
neutral file that contains the multilingual user interface (MUI) manifest. This
enables you to separate language-neutral portable executable files from .mui
files, which contain all of the language-dependent resources, and later add
resources for additional languages without having to recompile or relink the
application.
If this setting contains a value, the value for the Display Name setting is
ignored. If you leave this setting blank, Windows Installer uses the value for the
Display Name setting.
Note: If you enter a value in the Display Resource DLL, you must also enter a
value for the Display Resource ID setting.
This setting applies to installations that are run with Windows Installer 4.0 on
Windows Vista systems. Earlier versions of Windows Installer ignore this
setting.
Display
Resource ID
Project: This property is available in Windows Installer–based projects.
If you are preparing an installation for a multilingual application and Windows
Installer 4.0 will be running the installation, specify the display name index for
the shortcut. This must be a non-negative number.
Note: If you enter a value for the Display Resource ID setting, you must also
enter a value for the Display Resource DLL setting.
This setting applies to installations that are run with Windows Installer 4.0 on
Windows Vista systems. Earlier versions of Windows Installer ignore this
setting.
Property Description
Description
Resource DLL
Project: This property is available in Windows Installer–based projects.
If you are preparing an installation for a multilingual application and Windows
Installer 4.0 will be running the installation, specify the full path to the language-
neutral file that contains the multilingual user interface (MUI) manifest. This
enables you to separate language-neutral portable executable files from .mui
files, which contain all of the language-dependent resources, and later add
resources for additional languages without having to recompile or relink the
application.
If this setting contains a value, the value for the Description setting is ignored. If
you leave this setting blank, Windows Installer uses the value for the Description
setting.
Note: If you enter a value in the Description Resource DLL, you must also enter
a value for the Description Resource ID setting.
This setting applies to installations that are run with Windows Installer 4.0 on
Windows Vista systems. Earlier versions of Windows Installer ignore this
setting.
Description
Resource ID
Project: This property is available in Windows Installer–based projects.
If you are preparing an installation for a multilingual application and Windows
Installer 4.0 will be running the installation, specify the description name index
for the shortcut. This must be a non-negative number.
Note: If you enter a value for the Description Resource ID setting, you must also
enter a value for the Description Resource DLL setting.
This setting applies to installations that are run with Windows Installer 4.0 on
Windows Vista systems. Earlier versions of Windows Installer ignore this
setting.
Comments Enter comments for this shortcut. Comments are saved in the project file for
your reference and are not used in the installation.
Uninstall
Property Description
Replace
existing (if
found)
Project: This property is available in InstallScript projects.
Select whether the shortcut should replace an already existing shortcut with the
same display name in the same location on the target system.
Internet
Shortcut
Project: This property is available in InstallScript projects.
Select whether the shortcut is an Internet shortcut that points to the URL
specified in the shortcut’s Target property.
VS .NET
Project Output
Project: This property is available in InstallScript projects.
Select whether the shortcut points to a Visual Studio project output.
Type
4. Click the ellipsis button (...). The Hot Key dialog box opens.
5. Press the hot key combination that you want to use for this shortcut.
After you enter the hot key combination, the dialog box closes and a decimal value representing the
combination appears in the Hot Key property field.
Note: Shortcut hot keys do not work on Windows 95 and NT 4.0 when using Active Desktop. They also do not work on
Windows 98 platforms.
Caution: Microsoft recommends that you do not set this value because it may conflict with existing hot key combinations
on the target machine.
• Uninstallation information that enables end users to uninstall the application easily without
interfering with other applications on the system
• System-wide file associations for documents created by an application
• License information
• HKEY_USERS
• HKEY_CURRENT_USER
• HKEY_CLASSES_ROOT
A key is a named location in the registry. A key can contain a subkey, a value name and value pair, and a
default (unnamed) value. A value name and value pair is a two-part data structure under a key. The
value name identifies a value for storage under a key, and the value is the actual data associated with a
value name. When a value name is unspecified for a value, that value is the default value for that key.
Each key can have only one default (unnamed) value.
Note that the terms key and subkey are relative. In the registry, a key that is below another key can be
referred to as a subkey or as a key, depending on how you want to refer to it relative to another key in the
registry hierarchy.
Caution: It is important not to modify or delete registry keys indiscriminately because the registry is a vital part of the
Windows operating system, and the system may fail to function if vital registry keys are altered.
Project: For installation projects: The installer automatically creates certain registry entries based on values that you
provide for your project and product properties.
For merge module projects: The installer automatically creates certain registry entries based on values that you provide
for your merge module properties.
Windows Logo Guideline: These “informational keys” are required if you want to meet Windows logo guidelines.
Also, all of a component’s advanced settings are used to register files on the target system.
Note: You can modify, rename, or delete registry keys and values while filtering the view by All Application Data.
When you click a registry key in the Destination computer’s Registry view pane of the Registry view,
InstallShield displays all of the registry data for that key in the lower-right pane of the Registry view. The
Component column shows the component with which the registry data is associated. If the same value
exists for more than one component, the last component that was associated with the registry data is
displayed.
If you have not set a value for a key, no registry data is displayed for that key when you select All
Application Data in the View Filter.
Press F12.
Task To specify a registry key to be created on the target system when a component is installed:
InstallScript projects: In the Destination computer’s Registry view pane, open an existing
registry set or create one by right-clicking the Destination Computer folder. Associate the
registry set with one or more components by clicking the registry set and selecting the desired
components in the Registry Set Install Conditions pane.
3. In the Destination computer’s Registry view pane, right-click a registry hive or key, point to
New, and then click Key. InstallShield adds a new key with the name New Key-n (where n is a
successive number).
4. Enter a meaningful name to rename the key, or right-click the key and click Rename to give it a
new name later.
InstallShield adds your new key with an empty default string value.
By default, all keys that you create are set for automatic installation and uninstallation. This means that
they are installed if the component they belong to is installed, and they are uninstalled when that
component in uninstalled. For more information on registry key flags, see Registry Flags.
Tip: You can create multiple nested keys at one time by creating a new key and typing, for example, Key 1\Key 2\Key
3 in the key’s name. InstallShield creates a nested key structure where Key 3 is a subkey of Key 2, which is a subkey of
Key 1.
Table 12-4: Commands Available from the Registry Entry Context Menu
Option Description
All keys & values Adds all selected keys, subkeys, and values.
Key and its values only Adds only the selected key and the key’s values. No subkeys are
added.
Only this key Adds only the selected key, not any of its subkeys or values.
Cancel Ends the drag and drop operation without making any changes.
Option Description
DWORD Value Data represented by a number that is four bytes (32 bits) long.
Expandable String Value The value is interpreted and stored as an expandable string.
According to the Microsoft Developer Network (MSDN), an
expandable string registry value is a null-terminated string that
contains unexpanded references to environment variables (for
example, %PATH%).
InstallShield adds a new value with the name New Value n (where n is a successive number). Enter a
meaningful name now to rename the value, or right-click the value name and then click Rename to give
it a new name later.
Project: In Windows Installer projects, any registry value can serve as the component’s key path.
Task To modify the data for a registry value to be created on the target system:
Project: In Windows Installer projects: To add value data that contains square brackets ([]), you must precede each
bracket with a backslash (\) and surround it with an opening and closing bracket. Otherwise, Windows Installer treats the
value as a property. For example, if you wanted to write [stuff] to the registry, you would use [\[]stuff[\]] as the
value data.
Registry Flags
Registry flags enable you to control the installation of your registry entries. By default, your registry
entries are installed if the component to which they belong is installed. They are then uninstalled when
that component is removed. If you would like your registry entries to remain on the target system even
after the product has been uninstalled, or if you want to create registry entries only if they do not already
exist, you need to set the installation flag for that key.
Right-click a key to change its installation flag. Select from any of the choices listed below.
Registry keys that have special installation flags can be identified by the folder icon. Below is a list of the
icons, and the type of installation flags to which they correspond.
Automatic This is the default option for all registry keys. The key is installed if not
already present.
Shared among
several
applications (+)
Project: This registry key is available in InstallScript projects.
When the component to which this key belongs is uninstalled, if the key
has any subkeys or values, the key is not removed from the system.
(Note that a value created by your installation will have already been
uninstalled unless you unset its Remove during uninstall flag.) If the
key does not have any subkeys or values, the key is removed from the
system regardless of whether it was created by the installation, that is,
whether it already existed at the time of installation.
Uninstall entire
key (–)
Project: This registry key is available in Windows Installer projects.
During uninstallation, the key and all its subkeys and values will be
removed.
Install if absent,
Uninstall if
present (*)
Project: This registry key is available in Windows Installer projects.
This option is similar to the default behavior, with one exception. By
default, if the key already exists during installation, the installation does
not remove it during uninstallation. Setting your registry key’s installation
flag to this option forces the key to be removed during uninstallation if it
is present, no matter who put the key there.
Task To search for a registry entry within a certain component (in Windows Installer projects) or registry set (in
InstallScript projects):
3. Right-click a registry entry and click Find. The Find dialog box opens.
4. Enter the string that you are searching for.
5. Click Find to start the search.
In a Windows Installer project, InstallShield searches only the registry entries for the current
component, not all the registry data for the project.
The search starts from the top item and works its way down, regardless of which item is selected. It stops
at the first match, highlighting this key. To continue the search, right-click and select Find Next, or press
F3. The Find Next feature finds the next match, moving down the explorer.
Syntax
When creating registry entries of this type, you need to begin the entry with a pound sign followed by a
percent sign (#%). Then, you can enter your environment variable, complete with the beginning and
ending percent sign. Therefore, if you enter #%%TEMP% in the Registry view in InstallShield, it
appears as %TEMP% when written to the registry.
In the Windows 2000 (or later) registry, the Type field for this entry appears as REG_EXPAND_SZ, and
the Data field is %TEMP%.
Note: Windows 95, Windows 98, and Windows NT machines do not have the Type field in the registry.
• Export Selected Branch exports only the current registry key and any subkeys.
Right-click a key’s value name to specify that value as the key path for the component.
The value’s string, binary, or DWORD icon is replaced with a key icon.
Note: A component can have either one key path or one key file. If you have already set a key file or a key path for a
component, you will get a warning prompt if you try to set another key path. Click Yes in the dialog box to replace the
existing key file or key path with the new key path.
Note: Because file and folder permissions require an NTFS partition, they work only on Windows NT, Windows 2000, or
Windows XP systems.
Names
From the Names grid, you can enter any combination of domains and user names.
To add an entry, right-click the grid and click New. You can modify or delete entries using the same
context menu.
You can enter [%USERDOMAIN] in the Domain field to represent the current user’s domain, and
[LogonUser] (or any other property name in square brackets) in the User field to represent the user
running the installation.
Permissions
In this section, select the permissions that you want to set for registry key. These permissions are the
same ones that appear in the Windows OS when setting permissions. Once you make a selection, you can
click Advanced to specify other permissions associated with the high level one that you initially select.
For more information on the lock permissions table, see LockPermissions Table in the Windows
Installer Help Library.
Windows Installer requires a unique primary key for each registry key and value that you add to the
Registry table. To enable you to create registry entries in a completely visual environment,
InstallShield assigns a unique name to every entry in the database’s Registry table at build time.
You may need to know the entry’s primary key when authoring a custom action. InstallShield supports
specifying a primary key on a registry key or value in the Registry Data explorer in the Setup Design view
or the Components view. Note that it is not possible to assign the key or value a primary key in the
Registry view.
1. Right-click the key or value and click MSI Value. The MSI Value dialog box opens.
2. Enter the name of the key. Since the primary key must be a Windows Installer identifier, the name
may contain only letters, numbers, underscores (_) and periods (.), and it must begin with a letter or
underscore.
To view or modify the primary key, right-click the registry key or value and click MSI Value again.
If you do not specify a value, InstallShield generates a unique primary key for this entry in the Registry
table.
1. Right-click the registry key to which you want to add the multi-line value, point to New, and click
Multi-String Value. The Multi-Line String Value dialog box opens.
2. Select how you want to modify the registry value, and then enter a line for each null-delimited string.
3. Click OK.
Note: Strings can contain just spaces, but they cannot be empty or [~], which is the delimiter for the strings.
Note: Windows NT–based systems do not allow a new key to be created directly under HKEY_LOCAL_MACHINE. For this
reason, any information that you create under HKEY_USER_SELECTABLE must be placed under the SOFTWARE subkey,
which is the only subkey common to HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER.
For example, creating the key HKEY_USER_SELECTABLE\SOFTWARE\MyCompany is valid, but creating
HKEY_USER_SELECTABLE\MyCompany is not.
Note: The Windows 95 registry does not support multi-line strings. If you use the multi-line string option under Windows
95, a binary value will be placed in or read from the registry.
if (RegDBKeyExist("Software\\ThisCo\\ThisApp") = 1) then
MessageBox("ThisApp is on the system.", INFORMATION);
endif;
To learn more about the built-in registry functions available with InstallScript, see the following:
• Registry Functions
Signature_ registry_sig
Root 2 HKEY_LOCAL_MACHINE
Name RegisteredOwner
After the AppSearch action runs, the REGISTERED_OWNER property will contain the data read
from the registry. If the value is not found, the property will be undefined (empty).
For more information regarding the AppSearch and RegLocator tables, see the Windows Installer
Help Library.
For Windows Installer-based projects, you can use the System Search Wizard to find data.
RegDBGetKeyValueEx(
"Software\\Microsoft\\Windows NT\\CurrentVersion",
"RegisteredOwner",
nvType,
svRegisteredOwner,
nvSize);
MessageBox(
"Registered owner is: " + svRegisteredOwner,
INFORMATION);
end;
You can set a Windows Installer property equal to the value you read using the MsiSetProperty function.
Property Description
Display Name Enter the name of the .ini file, including the file extension, that you would like to
edit—INIFile.ini, for example. The value that you enter into this field is added
to the string table of your default language. For more information, see Using
String Table Entries in InstallShield.
Note: The display name is of the Windows Installer Filename data type. If the
display name is longer than eight characters long, the Short Name | Long
Name format is used in the property grid. Windows Installer requires the Short
Name | Long Name format for file names that are not already in the 8.3 format.
Component Select the component with which you want to associate this .ini file. Click the
Browse button to display a list of all the components in your installation. If no
components exist when you create your .ini file, a new component is added to
your installation and your .ini file is associated with this component.
Target Enter the path to the folder where the .ini file that you want to edit is stored, or
click the Browse button to navigate to this directory. Rather than hard-coding a
path, you can choose one of the Windows Installer folders properties from the
list. Separate further levels of subfolders with a backslash—
[ProgramFilesFolder]MyCompany.
Keyword Properties
Keywords have the following properties, which must be set in order for your .ini file change to occur.
Property Description
Display Name Enter the name of the keyword that you would like to edit, exactly as it should
appear in the target .ini file. This value is stored in the string table for your
installation, allowing for easier globalization.
Action Select the action that you would like to perform. These define how you will be
editing the .ini file.
• Replace Old Value—Select this option if you would like your new value to
replace the existing value. If no value previously existed, your new value
will be added.
• Do Not Overwrite—Your value will be added to the .ini file if the keyword
does not already exist. No changes will be made if the keyword is already
present in the .ini file.
• Append Tag—Select this option if you would like to add an additional tag
to an .ini value. Tags are comma separated. If the keyword to which you
would like to append a tag does not exist, no changes will be made.
• Remove Whole Value—Select this option if you would like to remove an
entire keyword and its value. If the specified keyword does not exist, no
changes will be made. No entry is required in the value field if this option is
selected.
• Remove Tag—Only the tag that you specify in the Value field will be
removed from this .ini entry.
Property Description
Data Value Enter the value for the keyword. If you are adding or appending a value, enter
the new value here. If you are removing a tag, enter the tag that you would like
to remove.
You can use Windows Installer properties in your keyword’s value. To do this,
surround the property with square brackets—[INSTALLDIR], for example.
Assuming the .ini file is called Test.ini, and contains the following:
[ProductSettings]
Key1=One
Key2=2
Key3=III
Key4=....
[OtherSettings]
Key1=Value1
Key2=Value2
*/
function OnBegin( )
STRING svKey1Value; // filled in by GetProfString
begin
GetProfString(
end;
listKeyNames = ListCreate(STRINGLIST);
// if desired, you can loop over the key names in the list and read each
key's value...
ListDestroy(listKeyNames);
end;
Modifying System.ini
System.ini is a system-level file that controls properties in the operating system. It is used primarily on
machines running Microsoft Windows 9x operating systems. In Windows NT–based operating systems,
the information that was stored in System.ini is stored in the registry.
All of the ODBC drivers, data source names (DSNs), and translators registered on your system are
displayed in the ODBC Resources view. DSNs are shown as children of their associated driver. Expand
the explorer to view all of the existing ODBC resources.
To include an ODBC resource in your installation, select the check box next to its name in the ODBC
Resources pane in the upper-left corner of the view. In installation projects, the resource must then be
associated with at least one feature so that it can be installed. Then, you can set the attributes for the
selected resource.
You can also install ODBC resources not listed in the explorer. Where you add them depends on the type
of resource.
Task To add a driver that is not listed in the ODBC Resources explorer in the ODBC Resources view:
1. In the ODBC Resources explorer, right-click Drivers and DSNs and click New Driver.
2. Enter a new name for the driver, or press the F2 key later to rename it.
3. Select the check box next to the new driver to include it in your installation.
Task To add a data source that is not listed in the ODBC Resources explorer in the ODBC Resources view:
1. In the ODBC Resources explorer, right-click a driver and click New DSN.
2. Enter a new name for the DSN, or press the F2 key later to rename it.
3. Select the check box next to the new DSN to include it in your installation.
Note: You cannot add a translator to the list. Instead, you must install it on the development system and then select it.
Like most of the data in your project, ODBC resources must be associated with a feature. When the
feature is installed to the target system, the ODBC resource is installed as a part of the feature.
After you choose to install a driver, DSN, or translator for installation, the Features list is enabled on the
right side of the ODBC Resources explorer. Select all of the features to which the ODBC resource
belongs. InstallShield creates a new component and associates it with each selected feature. The
resource will be installed only once even if it is associated with multiple features, but the resource cannot
be installed if none of its features is installed.
In an InstallScript MSI project, if no other feature exists, the resource is added to the DefaultFeature. In
a Basic MSI project, if a feature does not exist when you add an ODBC resource to your installation, the
Create a New Feature dialog box is displayed. This dialog box prompts you to create a feature. If only one
feature is associated with an ODBC resource, it cannot be deselected until you select at least one
additional feature.
When an ODBC resource is registered on the development system, its current attributes are displayed in
the Properties list of the ODBC Resources view. You can edit the attributes in the Properties pane after
you have selected the driver, data source name (DSN), or translator.
There is no universal list of attributes and their possible values. Check with the file’s vendor or author if
you are unsure about what to specify for its installation. Some attributes are common to each type of
ODBC resource, as described below:
Drivers
In addition to the required attributes below, the driver must have a name in the tree. This name is
registered as the driver’s description. The driver’s name cannot be localized, which means that it does
not appear in your string table. Because of this, the same value is used regardless of the system’s
language.
Driver The complete path to the file on the development system that serves as the
ODBC driver. Enter the value, or click the ellipsis button (...) to browse to the .dll
file.
Setup The complete path to the installation .dll file for this driver. Enter the value, or
click the ellipsis button (...) to browse to the .dll file. You can leave this property
empty if the driver file is also the installation.dll file.
Data Sources
In addition to the required attributes below, the DSN must have a name in the tree. This name is
registered as the DSN’s description. The DSN’s name cannot be localized, which means that it does not
appear in your string table. Because of this, the same value is used regardless of the system’s language.
Translators
In addition to the required attributes below, the translator must have a name in the tree. This name is
registered as the translator’s description. The translator’s name cannot be localized, which means that it
does not appear in your string table. Because of this, the same value is used regardless of the system’s
language.
Translator The complete path to the file on the development system that serves as the
ODBC translator. Enter the value, or click the ellipsis button (...) to browse to
the file.
Setup The complete path to the installation .dll file for this translator. Enter the value,
or click the ellipsis button (...) to browse to the .dll file. You can leave this
property empty if the translator file is also the installation .dll file.
Environment variables are name and value pairs that can be set on the target system with your
installation and can be accessed by your application and by other running programs.
In the Environment Variables view, you can create, set (or modify), and remove environment variables
on the target system through your installation. You can also specify environment variable properties in
this view.
Note: For target systems running Microsoft Windows 95 or 98, the environment variables are modified in, created in, or
removed from Autoexec.bat. Environment variables are stored in the registry on systems running Windows NT 4.0 or
Windows 2000 and later.
Task To create a new environment variable or modify the value of an existing environment variable:
Property Description
Component Select the component with which you want to associate this environment
variable. If the selected component is installed or uninstalled, the environment
variable is created, modified, or removed from the target system—depending
on the values that you provide for the other environment variable properties.
Click the ellipsis button (...) in the field to launch the Browse for a Component
dialog box.
Value Enter the path or value for this environment variable. You can use a predefined
folder as part of this value—such as [INSTALLDIR]Bin.
To enter multiple paths, separate the paths with a semicolon.
Note: If the On Install property is set to Remove, the Value property is cleared
and becomes read only.
On Install Indicates the action that you want to take place when the associated feature is
installed to the target system. Select one of the following options:
• Set—In conjunction with the Placement property, sets the value of an
existing environment variable. This option creates the environment variable
if it does not already exist on the target system, and then sets it during
installation. If the environment variable exists on the target system, it is set
during the installation.
• Create—Creates the specified environment variable on the target
system—if it does not already exist—and sets the variable’s value.
• Remove—Removes the specified environment variable from the target
system.
Property Description
Placement Indicates the placement of the value in the Value field relative to the specified
environment variable’s existing value. Select one of the following options:
• Append—This option appends the value indicated in the Value property to
the end of the specified environment variable’s existing value.
• Prefix—This option adds the value indicated in the Value property to the
beginning of the specified environment variable’s existing value.
• Replace—;This option replaces the value of the specified environment
variable with the value indicated in the Value property.
Note: If you select Create for the On Install property and the specified
environment variable already exists on the target system, the Placement
property value indicates how the new value should be added to the existing
environment variable’s value or if it should replace the existing environment
variable’s value. However, if—in this scenario—the specified environment
variable does not exist on the target system, it is created and the Placement
value is ignored.
On Uninstall Indicates whether or not this environment variable should be removed from the
target system when the associated feature is uninstalled. Select one of the
following options:
• Remove—This option removes the environment variable or the its
appended value from the target system if the associated feature is
uninstalled. If the On Install property is set to Create, Remove removes the
entire environment variable. If the On Install property is set to Set, Remove
removes only the value that was appended to the variable’s value.
• Leave—This option leaves the environment variable or its appended value
on the target system if the associated feature is uninstalled.
Type For target systems that are running Microsoft Windows NT or Windows 2000
and later, this property indicates whether the environment variable name refers
to a system or user environment variable. If the target system is running
Microsoft Windows 9x, this property is ignored. Select one of the following
options:
• System—Creates, modifies, or removes the system environment variable
specified.
• User—Creates, modifies, or removes the environment variable from the
user’s environment. The environment variable specified is available only to
the end user who is logged on at the time of installation.
*
* NOTE: This code is only for InstallShield running on Windows NT.
* Also, the current user must have administrator privileges for this
* code to work.
\********************************************************************/
begin
/********************************************************************\
* The following code creates an environment variable under Windows NT
* for the current user. You can modify the OnEnd event handler
* function block (or any other function block) to include this example
* code.
*
* NOTE: This script is only for InstallShield running on Windows NT.
* Also, the current user must have administrator privileges for this
* code to work.
\********************************************************************/
NUMBER nResult;
STRING szKey, szEnv;
POINTER pEnv;
begin
szKey="Environment";
RegDBSetDefaultRoot(HKEY_CURRENT_USER);
nResult=RegDBSetKeyValueEx(szKey,"Fame",REGDB_STRING,"C:\\test",-1);
if (nResult < 0) then
MessageBox("Failed to Set Environment Variable",WARNING);
else
MessageBox("Successfully Set Environment Variable",INFORMATION);
// Flush the NT registry to all applications.
szEnv = "Environment";
pEnv = &szEnv;
SendMessage (HWND_BROADCAST, WM_WININICHANGE, 0, pEnv );
endif;
//RebootDialog("","",SYS_BOOTMACHINE);
end;
You may need to modify .xml files that store settings related to your product, or you may need to modify
standard configuration files such as web.config and machine.config. InstallShield includes support for
modifying XML files on the target system at run time. The XML files can be part of your installation, or
they can be files that are already present on target systems.
For instructions on how to modify an XML file during installation, consult this section of the help.
For background information about XML, see the following Web sites:
• World Wide Web Consortium (http://www.w3.org)
• W3 Schools (http://w3schools.com)
Tip: Support for XML files extends into other areas of InstallShield product functionality. The System Search feature in
InstallShield enables you to search for an attribute value, contents, or existence of the element in the XML file that you
specify. For more information, see Searching for XML Data.
Run-Time Behavior
The XML File Changes view enables you to configure run-time behavior such as the following:
• Add a namespace mapping to an XML file, and add namespace prefixes to elements.
• Modify only the first element in the XML file that matches the specified XPath expression, or modify
all matching instances.
• Remove an element during uninstallation.
• Append a string to an existing attribute value during installation, during uninstallation, or both.
• For Basic MSI and InstallScript MSI projects: Replace Windows Installer properties in elements,
attributes, attribute values, and element content with the appropriate values at run time.
• For InstallScript projects: Substitute InstallScript string variables for elements, attributes, attribute
values, and element content with the appropriate values at run time.
When an installation that contains XML file changes runs on a target system, MSXML parses the XML
file and executes the XPath expressions that are associated with the changes that you configured. The
Advanced tab in the XML File Changes view for an XML file shows the XPath expressions that are
executed on target systems.
When MSXML finds an area of the XML file that matches the XPath expression, the changes that were
configured in the XML File Changes view are made.
For examples of how to create some basic XPath expressions, see Using XPath Expressions to Find XML
Data in an XML File.
Note: If the XML file does not exist on the target system at run time and the Always create XML file if it doesn’t
already exist check box is selected on the Advanced tab for the XML file, the XML file is created with the XML data that
is configured in the XML File Changes view.
InstallShield includes redistributables for different versions of MSXML. If it is possible that target
systems may not have MSXML, or they may not have the appropriate version of MSXML, you can add
the appropriate MSXML redistributable to your project in either the Redistributables view (for Basic
MSI and InstallScript MSI projects) or the Objects view (for InstallScript projects).
For detailed information about MSXML, see the MSDN Library.
Important: The XML File Changes view is not designed to list a node for every node in an XML file. To improve
performance, the XML File Changes view should show only the settings that differ from the base XML file:
• If the XML file that you are modifying is part of your installation, the XML File Changes view should list only the nodes
and node sets that should be added, changed, or deleted after the XML file is installed at run time.
• If the XML file that you are modifying is a file that is already present on the target system, the XML File Changes view
should list only the nodes and node sets that need to be added, changed, or deleted at run time.
Therefore, when you are importing a file, import only the nodes in the XML file that you want to modify at run time.
Note that the XML File Changes view does not enable you to specify the order in which new elements should be listed in
the XML file. Therefore, importing only the nodes that you want to modify at run time helps to avoid issues that may occur
if your product requires that the elements be listed in a particular order.
Task To import an XML file into the XML File Changes view:
1. In the View List under System Configuration, click XML File Changes.
2. Right-click the XML Files explorer and then click Import. The Import XML Settings Wizard
opens.
3. Complete the panels in the wizard, selecting only the XML file nodes that you want to change.
4. Click Import.
InstallShield adds a new node for the XML file that you imported. The XML file node contains each of
the nodes that you selected in the wizard. Each node represents an XPath query that occurs at run time.
InstallShield also adds a new component for the XML file that you have imported through the XML File
Changes view.
Now you can configure the XML file’s settings and specify any element, attribute, and content changes
for it.
Tip: You can also add an XML file by right-clicking the XML Files explorer and then clicking New File. However, in most
cases, you may want to create your XML file in a third-party XML editor or text editor. Next, add this file to your project
through the Files and Folders view. Then, import the file, as described in the aforementioned procedure, and configure the
changes that should be made to the file at run time.
Task To specify the location of the XML file on the target system:
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, click the XML file whose location you want to specify.
3. Click the General tab.
4. In the XML File Destination area, click the Browse button. The Browse for Directory dialog
box opens.
5. In the Destination Directories box, select the location.
6. Click OK.
InstallShield adds the destination that you specified to the Specify the location of the XML file on
the target machine box.
Note: If your project does not contain any features when you add an XML file reference, InstallShield displays the Create a
New Feature dialog box, which lets you to create a new feature.
Task To associate an XML file change reference with a feature in your project:
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, click the file whose component you want to associate with a feature.
3. Click the General tab.
4. In the Select Features the XML file belongs to box, select the check box of any feature that
should contain the selected XML file change reference. This may be the same feature that contains
the base XML file that you added to your project through the Files and Folders view, or it may be a
different feature.
If an end user chooses to install the feature that contains the XML file changes, the XML file changes are
performed at run time.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, click the file whose encoding you want to configure.
3. Click the Advanced tab.
4. In the Encoding list, select the appropriate type of encoding.
At run time, the installation uses the selected encoding type as the value of the encoding attribute in the
XML file.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the XML file to which you want to add a new root element
and click New Root Element.
InstallShield adds the new root element. Use the tabs that are displayed in the right pane to configure its
settings.
Tip: To add a root element and one or more levels of subelements in one step, type the name of the root element plus the
subelements, with each separated by a slash. For example, to add a root element called Root, a Sub element under the
Root element, and a Sub2 element under the Sub element, type the following:
Root/Sub/Sub2
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the XML file to which you want to add a new element and
click New Element.
InstallShield adds the new element. Rename it as appropriate, and use the tabs that are displayed in the
right pane to configure its settings.
Tip: When you are adding elements and subelements under the root element in the XML File Changes view, you can type
the full XPath expression for the name of the element, and it will automatically expand in the explorer.
To add a root element and one or more levels of subelements in one step, type the name of the root element plus the
subelements, with each separated by a slash. For example, to add a root element called Root, a Sub element under the
Root element, and a Sub2 element under the Sub element, type the following:
Root/Sub/Sub2
InstallShield automatically expands it in the explorer so that each element has its own node.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the XML file to which you want to add a configuration
element, click Add Predefined Element, point to .NET Configuration Files, point to Web
Configuration File, point to a given set of settings, and click the appropriate command.
InstallShield adds the new element in the explorer.
For detailed reference information about the different elements and attributes in .NET configuration
files, see Configuration File Schema on the MSDN Web site.
If an attribute that you add already exists in the XML file on the target machine but the attribute has a
different value than the one that you specified in the XML File Changes view, the installation updates the
value at run time.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, click the XML file to which you want to add an attribute.
3. Click the General tab.
4. In the attribute table, click a row to add a new attribute to the table.
InstallShield adds a new row, with default values for the Attribute, Value, Operation, and Scheduling
columns. Change any of the settings as needed. To learn more about each of the columns, see General
Tab for an XML Element.
Tip: If you configure your installation so that the XML file remains on the target system when its component is uninstalled,
you may want to create installation/uninstallation attribute pairs in the attribute table.
For example, to add a key attribute during installation and remove that same key attribute during uninstallation, add two
rows with the key attribute to the attribute table; schedule one row for installation, and the other for uninstallation.
Task To add content to one of the elements listed in the XML File Changes view:
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, select the element to which you want to add content.
3. Select the Advanced tab.
4. Select the Set element content check box.
• W3 Schools (http://w3schools.com)
The following sections show examples of how to create some basic XPath expressions.
To add those elements, the following XPath expressions are added under the Biographies node in the
XML File Changes view:
Book[@Author="John Smith"]
Book[@Author="Bill Smith"]
The following screen shots show the settings in the XML File Changes view.
Figure 12-2: Settings for the Biographies Node, which Contains the Child Nodes to Be Added
Figure 12-3: General Settings for One of the Child Nodes to Be Added
Figure 12-4: Advanced Settings for One of the Child Nodes to Be Added
Figure 12-5: General Settings for One of the Child Nodes to Be Added
Figure 12-6: Advanced Settings for One of the Child Nodes to Be Added
The following screen shot shows the settings in the XML File Changes view.
</Books>
To update the value, the following XPath expression is added under the Biographies node in the XML
File Changes view:
Book[@Copyright="2006"]
The following screen shot shows the settings in the XML File Changes view.
For Basic MSI and InstallScript MSI projects, you can use a Windows Installer property to specify an
XML element, an attribute, an attribute value, or an element’s content. At run time, Windows Installer
uses MsiFormatRecord to resolve the property value, and it uses that value as the data in your XML file.
This enables you to use data that end users enter in dialogs, or other configuration information that is
determined during the installation, in your product’s XML files.
For example, your installation may include the SQL Login dialog, which lets end users select a SQL
Server. The name of the server that they select is typically stored in the IS_SQLSERVER_SERVER
property. If you want an XML file to contain the name of the SQL server that an end user selects, you can
use this property, surrounded by brackets (that is, [IS_SQLSERVER_SERVER]), when you
configure your XML file changes in the XML File Changes view. Then at run time, Windows Installer
automatically replaces the property with its associated value.
Tip: Use a Windows Installer property for an element, an attribute, or element content only if the value of the property
would make a well-formed XML document. If a property value would lead to syntax errors in the XML document, your
product or installation may not behave as expected.
For example, if you set the name of an element to [INSTALLDIR]—a Windows Installer property whose value is a path on
the target system—the result at run time is an element name that contains backslashes. Element names cannot contain
backslashes, and XML documents that contain element names with backslashes are not valid.
Note: If test your XML file from within the XML File Changes view, any Windows Installer properties that are used for XML
data are not replaced with the appropriate values during testing. For more information about testing, see Testing
Installation Changes to an XML File or Testing Uninstallation Changes to an XML File.
Example
The following procedure demonstrates how to use the name of the SQL Server that an end user selects in
the SQL Login dialog as the content for one of the elements in your XML file. Note that you can
substitute a hard-coded value with a property for any of the elements, attributes, attribute values, or
element content in the XML File Changes view. The property that you specify in this view must be
enclosed within square brackets, and the property name must be in all uppercase letters; for example,
[MYPROPERTY].
Task To use the name of the SQL Server that end users select as the content for an XML element:
1. Configure the SQL connection and any associated SQL scripts if you have not already done so, and
determine the name of the server property name:
a. In the View List under Server Configuration, click SQL Scripts.
b. Add a SQL connection and SQL scripts as needed. For instructions, see Configuring SQL
Support.
c. In the SQL Scripts explorer, click the SQL connection.
d. Click the Advanced tab.
e. Note the name that is selected for the Target Server Property Name setting. The default
value is typically IS_SQLSERVER_SERVER.
2. In the View List under System Configuration, click XML File Changes.
3. In the XML Files explorer, select the element to which you want to add content.
4. Select the Advanced tab.
5. Select the Set element content check box.
6. In the Content box, type the name that is selected in step 1e, and enclose it within brackets. For
example:
[IS_SQLSERVER_SERVER]
Tip: Use text substitution for an element, an attribute, or element content only if the value of the property would make a
well-formed XML document. If a property value would lead to syntax errors in the XML document, your product or
installation may not behave as expected.
For example, if you set the name of an element to a text substitution string variable that will be replaced with text that
includes one or more spaces, end users may have problems with your product or your installation. Element names cannot
contain spaces, and XML documents that contain element names with spaces are not valid.
Note: If test your XML file from within the XML File Changes view, any text substitution string variables that are used for
XML data are not replaced with the appropriate values during testing. For more information about testing, see Testing
Installation Changes to an XML File or Testing Uninstallation Changes to an XML File.
Example
The following procedure demonstrates how to use the name of the SQL Server that an end user selects in
the SQL Login dialog as the content for one of the elements in your XML file. Note that you can
substitute a hard-coded value with a text substitution string variable for any of the elements, attributes,
attribute values, or element content in the XML File Changes view. The string variable that you specify
in this view must be enclosed within angle brackets; for example, <MYPROPERTY>. The string
variable that you specify is case-sensitive.
Task To use the name of the SQL Server that end users select as the content for an XML element:
1. Configure the SQL connection and any associated SQL scripts if you have not already done so:
a. In the View List under Server Configuration, click SQL Scripts.
b. Add a SQL connection and SQL scripts as needed. For instructions, see Configuring SQL
Support.
2. In the View List under System Configuration, click XML File Changes.
3. In the XML Files explorer, select the element to which you want to add content.
4. Select the Advanced tab.
Using Reserved Characters (<, >, &, ', and ") Inside Elements
If you use a reserved character such as a less than symbol (<) inside an XML element, the MSXML
parser converts it at run time on target systems to its predefined entity (<). Using the less than symbol
instead of its entity would generate an error because XML parsers would interpret it as the start of a new
element, and it would result in invalid XML code. Note that if you open the resulting XML file in a
browser such as Internet Explorer, the character—not its entity—is displayed inside the XML element.
The following table lists the reserved XML characters and their entity equivalents. The table also
indicates whether each reserved character is replaced by its entity at run time.
< < Less than This character cannot be used as content in an XML element
because it is reserved to be used to indicate the start of an XML
element.
This character is automatically replaced by its entity at run time.
> > Greater than This character is automatically replaced by its entity at run time.
& & And This character cannot be used as content in an XML element
unless it indicates the start of an entity.
If this character is used as content in an XML element but it
does not indicate the start of an entity, it is automatically
replaced by its entity at run time.
’ ' Apostrophe This character is not automatically replaced by its entity at run
time.
" " Quotation mark This character is not automatically replaced by its entity at run
time.
Tip: If you use the Import XML Settings Wizard to import an XML file into the XML File Changes view, InstallShield imports
any namespaces that are declared for the file.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, click the XML file that should contain the namespace.
3. Click the Namespace tab.
4. Click a row in the table to add a new namespace.
5. In the Prefix column, type the prefix that should be used for any elements that are associated with
the corresponding namespace.
6. In the URI column, type a URL or a string of characters that identifies the Internet resource.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the element to which you want to add a prefix and then do
one of the following:
• To add a prefix to only the selected element, point to Namespace Prefix, and then click to the
appropriate namespace mapping.
• To add a prefix to the element and all of its subelements, point to Namespace Prefix
(include all sub elements), and then click to the appropriate namespace mapping.
InstallShield adds the prefix to the element (and all of its subelements, if appropriate) in the XML Files
explorer.
Tip: You can also add a namespace prefix by right-clicking an element, clicking Rename, and adding the prefix and the
colon (:) before the element name.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the element whose prefix you want to remove, and then do
one of the following:
• To remove the prefix from only the selected element, point to Namespace Prefix, and then
click <None>.
• To remove the prefix from the element and all of its subelements, point to Namespace Prefix
(include all sub elements), and then click <None>.
InstallShield removes the prefix from the element (and all of its subelements, if appropriate) in the XML
Files explorer.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, click the XML file that contains the namespace that you want to remove.
3. Click the Namespace tab.
4. Click the row that contains the namespace mapping that you want to remove, and then click the
Delete button.
InstallShield removes the namespace from the table.
Note: If your XML file changes include Windows Installer properties or InstallScript text substitutions, they are not
replaced with the appropriate values during testing.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the XML file that you want to test and then click Test XML
File Install Changes. The Select Test XML File dialog box opens.
3. In the File name box, select the target file to which you want the installation changes applied, or
specify a new target file name and location:
• If you are modifying an XML file that is installed as part of your installation, select a copy of that
file. (Do not select the actual file in your installation because testing the XML installation
changes would modify it.)
• If you are modifying an XML file that already exists on the target system, select a copy of that
file.
• To test what happens if the XML file does not exist at run time and it is not installed as part of
your installation, specify a new file name and location.
The default file name is the name of the test file that you right-clicked in step 2.
4. Click Open.
If the target file already exists, InstallShield applies the changes from the test file to the target file. If the
target file that you specified does not exist and the Always create XML file if it doesn’t already
exist check box is selected on the Advanced tab for the XML file, InstallShield creates the file and
applies the changes from the test file.
InstallShield displays details about the installation test on the Results tab of the Output window. The
details include a hyperlink to the test file.
Tip: If the target file is open in a browser window when you perform the testing, you may need to refresh the browser to
see the test changes.
Note: If your XML file changes include Windows Installer properties or InstallScript text substitutions, they are not
replaced with the appropriate values during testing.
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the XML file that you want to test and then click Test XML
File Uninstall Changes. The Select Test XML File dialog box opens.
3. In the File name box, select the target file to which you want the uninstallation changes applied.
The default value is the name of the file whose installation changes you last tested.
4. Click Open.
InstallShield applies the uninstallation changes that are configured in the XML File Changes view to the
test file.
InstallShield displays details about the uninstallation test on the Results tab of the Output window. The
details include a hyperlink to the test file. Note that if you have configured the XML file to be removed
during uninstallation, the hyperlink may not work, since the file may no longer be present.
Tip: If the target file is open in a browser window when you perform the testing, you may need to refresh the browser
window to see the test changes.
Task To remove an element or an XML file from the XML File Changes view:
1. In the View List under System Configuration, click XML File Changes.
2. In the XML Files explorer, right-click the XML file or XML element that you want to remove and
click Delete.
If you delete an XML file, InstallShield displays a message that explains that the component associated
with the XML file will be deleted along with the file itself.
• Basic MSI
• InstallScript MSI
The Windows Installer property ALLUSERS and the current user’s privileges determine where the
configuration information such as your product’s shortcuts and registry entries are stored on a target
machine: to the All Users profile or the current user’s profile.
You can set the ALLUSERS property for your project through the Property Manager. You can also set
this property using the following methods:
• At the command line
Note: If you upgrade a Basic MSI project that was created with InstallShield 12 or earlier to InstallShield 2008,
InstallShield does not automatically change the value of the ALLUSERS property or add this property if it was not defined
in the earlier project.
Task To display the radio button group that lets end users set ALLUSERS from the Customer Information dialog in a
Basic MSI project:
Note: If you upgrade a Basic MSI project that was created with InstallShield 12 or earlier to InstallShield 2008,
InstallShield does not automatically change the Customer Information dialog.
An important aspect of creating an installation is customizing it for your end users’ needs. The help
topics in the “Customizing Installation Behavior” section of the help library discuss various features of
InstallShield that help you extend the functionality of your installation. For example, you may find it
useful to create custom actions to add support for something not directly supported by Windows
Installer. Furthermore, you may set up custom actions to call any script that you write in the
InstallScript view’s script editor. Refer to this section of the help for more information on how you can
customize the installation behavior in your project.
Using InstallScript
You can leverage the power and ease of InstallScript to extend the functionality of your installation
package. The InstallScript view includes a script editor pane for you to author your InstallScript code.
Project: You must have a file named Setup.rul in your project if you are using InstallScript. InstallScript MSI projects
contain a Setup.rul file by default. You must add a Setup.rul file in a Basic MSI project if you want to use InstallScript
custom actions.
1. Add a blank Setup.rul to your project in the InstallScript view if it does not already exist.
2. Write an entry-point function. Note that you cannot call an entry-point function in the User
Interface sequence for an InstallScript MSI installation project.
3. Compile the script.
4. Create a custom action that calls your InstallScript function.
5. Invoke the InstallScript custom action by either including it in a sequence (InstallScript MSI, Basic
MSI, and merge module projects) or executing it as a control event (Basic MSI and merge module
projects).
6. Debug if necessary.
Note: As with other custom actions, changes made to the system through InstallScript custom actions are not
automatically restored when the package is uninstalled. Because InstallScript custom actions are not logged and removed
by the uninstaller, you must write a corresponding custom action to uninstall any changes that your custom action makes.
Overview of ISSetup.dll
ISSetup.dll is a C++ MSI DLL that contains the full InstallScript scripting run-time engine. For
InstallScript MSI, Basic MSI, and merge module installations, ISSetup.dll executes InstallScript custom
actions. For InstallScript projects, ISSetup.dll must be in the Disk1 folder.
Your installation always uses the InstallScript scripting run-time engine with which it was built, even if
more a more recent version is installed on a target machine by another installation.
Editor Functionality
InstallShield includes a full-featured text editor that is activated automatically when you select a script
file while using the InstallScript view. The InstallShield script editor pane operates much like other
standard Windows-based editors.
The script editor pane includes the following functionality:
Functionality Description
Keystroke edit commands You can assign more than 120 different edit commands to
specified keystrokes.
Drag and drop text manipulation Highlighted text can be dragged and dropped between any
window supporting OLE text drag-and-drop functionality. Text
can be copied or moved.
Unlimited undo/redo All edit actions are fully undoable and redoable. You can set
a limit on the number of edit actions that can be undone.
Auto indentation As you enter code, the script editor automatically indents
lines according to the scoping rules of the selected
language.
Column selection and Columns of text can be selected and manipulated. You can
manipulation select empty columns (columns with a width of zero
characters) to cause subsequent typing and deletion to
occur over multiple lines at the same time.
IntelliScript
IntelliScript technology assists you as you work in the script editor pane by automatically completing
function names and providing function parameter information.
1. Enter a function name in your script by typing it or using automatic function name completion, as
described earlier.
2. Type a left parenthesis—(—after the function name. InstallShield displays a tooltip that shows a
complete call to the function, including all of its parameters. The first parameter appears in bold.
3. Type the parameters as indicated by the tooltip. Each time that you type a comma, the next
parameter in the function syntax appears in bold.
4. To close the tooltip, type the right parenthesis—). Or, press ESC or click in the script editor pane
outside the tooltip.
Syntax Coloring
The script editor pane displays InstallScript source files with color attributes that identify keywords,
comments, strings, and other script elements (listed in the table below). The elements in each category
are displayed in the same color so that you can easily identify them.
This functionality—called syntax coloring—is designed to help you avoid errors caused, for example,
when you attempt to use a reserved word as a user-defined identifier. It can also help you locate other
errors in your script, such as misspelled keywords, missing quotation marks at the end of a string, and
missing comment characters.
Note: Syntax coloring occurs only with files that have the extension .rul (script files) or .h (header files).
The following table shows the default color that is applied to each script element. You can change the
color attribute of a category.
Bookmarks Teal
Comments Green
Keywords Blue
Numbers Teal
Operators Red
To make the best use of this functionality, keep the following points in mind:
• Files with an extension other than .rul or .h (for example, log or report files) are not displayed with
syntax coloring.
• Misspelled reserved words are not recognized by the editor and are not displayed with syntax
coloring. If you see in your script a “reserved word” that is not displayed with indicating attributes, it
is probably misspelled.
• Coloring of string literals includes both the opening and closing quotation marks. If the closing
quotation mark is missing, string coloring will extend to the end of the line; in that case, text that
should have followed the quotation will be displayed as though it were part of the string literal.
• Syntax coloring makes it easy to identify comments that open with /* and are not closed properly
with */. In that case, all of the text that follows the comment is displayed with the comment color
attribute.
• In lines that include comments starting with two slashes (//), all text from the comment character to
the end of the line is recognized as a comment.
Function Wizard
The Function Wizard automates the process of adding function calls to your scripts. Instead of looking
up a function in the online help; deciphering parameter descriptions; and copying, pasting, and editing
the function call, you can launch the Function Wizard to insert a function at the insertion point.
Task To move the insertion point to a specific line number in your script:
1. On the Edit menu, click Go To. The Go To Line dialog box opens.
2. In the Line box, type the number of the line where you want to move the insertion point.
3. Click OK.
Bookmarks
Bookmarks are markers that let you jump to specific lines within your script with a minimum of
keystrokes. They are visible in the left margin when the margin is displayed. Note that bookmarks are
deleted when a file is saved.
Setting Bookmarks
Task To mark all lines that contain specific text (such as a specific keyword or function name):
1. On the Edit menu, click Find. The Find dialog box opens.
2. In the What box, type the text that must appear in the lines that you want to mark.
3. Click Mark All.
InstallShield adds a bookmark to each line that contains the text string. Lines with matching text that
are already marked remain marked.
Clearing Bookmarks
Press the keyboard shortcut for BookmarkClearAll. By default, no shortcut is assigned to this command.
For instructions on assigning a shortcut, see Changing the Keyboard Shortcut Assigned to a Command.
Task To enable or disable the vertical or horizontal scroll bar in the script editor pane:
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Misc tab.
3. To change the state of the vertical scroll bar, select or clear the Show vertical scrollbar check box.
InstallShield displays a vertical scroll bar on the right side of the script editor pane when this check
box is selected.
To change the state of the horizontal scroll bar, select or clear the Show horizontal scrollbar
check box. InstallShield displays a horizontal scroll bar at the bottom of the script editor pane when
this check box is selected.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Misc tab.
3. To enable column selection, select the Allow column selection check box.
To disable column selection, clear the Allow column selection check box.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
Task To enable or disable the left margin in the script editor pane:
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Misc tab.
3. To include the left margin, select the Show left margin check box.
To disable hide the left margin, clear the Show left margin check box.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Misc tab.
3. To enable drag-and-drop text editing, select the Allow drag and drop check box.
To disable drag-and-drop text editing, clear the Allow drag and drop check box.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Language/Tabs tab.
3. In the Tab Size box, enter the size—as a multiple of the character space size—that you want for tabs
in your scripts. InstallShield inserts a tab either as a tab character (ASCII 09) or as spaces,
depending on whether the Convert tabs to spaces while typing check box is selected.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Misc tab.
3. In the Max undoable actions area, do one of the following:
• To specify a maximum number, select the Limited to option and type a number in the box.
Selecting this option can save memory by limiting the size of the undo buffer.
• To enable an unlimited number of undo and redo actions, select the Unlimited option.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Language/Tabs tab.
3. To insert tabs as space characters, select the Convert tabs to spaces while typing check box.
The number of spaces inserted when you press the TAB key depends on the number specified in the
Tab size box.
To insert tabs as tab characters, clear the Convert tabs to spaces while typing check box.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Language/Tabs tab.
3. In the Auto indentation style area, select the appropriate option:
• Off—Select this option to disable auto indentation. When you press ENTER in the script editor
pane, the insertion point appears on a new line in the first column.
• Follow language scoping—Select this option if auto indentation should be performed
according to the scoping rules of the language selected in the Language list. If <none> is
selected in this list, no auto indentation is performed.
• Copy from previous line—Select this option if the indentation should be copied from the
previous line. When you press ENTER in the script editor pane, the insertion point appears on a
new line positioned directly beneath the first character of the previous line.
To insert tabs as tab characters, clear the Convert tabs to spaces while typing check box.
4. Click Apply.
5. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Color/Font tab.
3. In the Item box, select the script element whose color you want to change.
4. In the Color list, select the appropriate color.
5. If the Background list is available for the selected type of script element, select the appropriate
color.
6. Click Apply.
7. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Keyboard tab.
3. In the Command list, select the command for which you want to create a keyboard shortcut. Note
that the current keyboard shortcuts (if any) for the selected command are displayed in the Key
Assignments box.
4. Place the insertion point in the New key assignment box.
5. Press the key combination that you want to assign as a shortcut to the selected command. Note that
if your shortcut is already assigned to a command, InstallShield will display a message beneath the
New key assignment box to inform you about the conflict.
6. Click Assign. InstallShield adds the keyboard shortcut to the Key Assignments box.
7. Click Apply.
8. Click OK to close the Window Properties dialog box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Keyboard tab.
3. In the Command list, select the command whose keyboard shortcut you want to change.
Note that the command names for macros are listed as PlayMacroN, where N is a successive number.
4. In the Key Assignments list, click the keyboard short cut that you want to change.
5. Click Remove. InstallShield removes the keyboard shortcut from the Key Assignments box.
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Keyboard tab.
3. In the Command list, select the command whose keyboard shortcut you want to remove.
Note that the command names for macros are listed as PlayMacroN, where N is a successive number.
4. In the Key Assignments list, click the keyboard short cut that you want to remove.
5. Click Remove. InstallShield removes the keyboard shortcut from the Key Assignments box.
6. Click Apply.
7. Click OK to close the Window Properties dialog box.
Changing the Font that Is Used to Display Text in the Script Editor
Task To change the font, font style, or font size that is used to display text in the script editor:
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Color/Font tab.
3. In the Font area, click Change. The Font dialog box opens.
4. Specify the font changes as needed.
5. Click OK. The Font dialog box closes.
6. Click Apply.
7. Click OK to close the Window Properties dialog box.
1. Press the keyboard shortcut for the RecordMacro command. (By default, the shortcut is
CTRL+SHIFT+R.) The Record Macro dialog box opens, and the insertion point changes.
2. Type the keystrokes that you want to record.
3. In the Record Macro dialog box, click the End Recording button. The Record Macro dialog box
closes and the Save Macro dialog box opens.
4. Place the insertion point in the Press new shortcut key box.
5. Press the key combination that you want to assign as the shortcut to the macro.
6. In the Save As list, select an unassigned macro number.
7. Click OK.
Running a Macro
Press the keystroke shortcut that you entered for the macro.
To learn how to change the keyboard shortcut assigned to a macro, see Changing the Keyboard Shortcut
Assigned to a Command.
Task To display characters property in the script editor on non-English operating system platforms:
1. Right-click in the script editor pane and click Properties. The Window Properties dialog box
opens.
2. Click the Color/Font tab.
3. In the Font area, click Change. The Font dialog box opens.
4. In the Font and Script boxes, select the appropriate settings.
5. Click OK. The Font dialog box closes.
6. Click Apply.
7. Click OK to close the Window Properties dialog box.
Task To undo an action that you performed in the script editor pane, do one of the following:
• Press CTRL+Z.
• Right-click in the script editor pane and click Undo.
Task To redo an action that you performed in the script editor pane, do one of the following:
• Press CTRL+Y.
• Right-click in the script editor pane and click Redo.
Moving Text
Copying Text
Task To copy selected text using the drag and drop method:
• With the insertion point in the script editor pane, press CTRL+M.
• On the View menu, click Maximize.
Script Files
#include "FeatureEvents.rul"
Project: You must have a file named Setup.rul in your project if you are using InstallScript. InstallScript MSI projects
contain a Setup.rul file by default. You must add a Setup.rul file in a Basic MSI project or a merge module project if
you want to use InstallScript custom actions.
Task To open a script file in your project so that you can edit it:
• In the Repository Items box, click the InstallScript file (.rul) or InstallScript header file (.h)
that you want to add to your project.
• If the script file that you want to import is not stored in the repository, click the Browse button
to select it.
4. Click OK.
1. Press ALT and then drag your mouse vertically to select a zero-character width column. When you
release the ALT key, a vertical line appears in the script editor pane.
2. Type the characters that you want to include on each line (for example, #include).
Compiling Scripts
You must compile your script before your InstallScript code can be called in your installation.
InstallShield searches only for a file named Setup.rul when compiling the script. You can include files
with different names, but they must be included in Setup.rul or in an include file with the #include
preprocessor statement.
Debugging Scripts
The InstallScript Debugger is useful for stepping through your InstallScript code and checking the
progress of your code.
Before you can debug your script, you must first compile it, execute it as a custom action (if your project
is Basic MSI), and build a release.
Task To debug your script directly from within InstallShield, do one of the following:
1. Wherever you want to insert a debug statement in the script, start with the following #ifdef
directive:
#ifdef DEBUG
The InstallScript Debugger enables you to trace program execution and inspect variables as your
installation executes.
Note: Your installation must contain a source file named Setup.rul; that file is the main compilation unit of an installation
script. If your installation does not include a script file with that name, InstallShield will report error C8503 when you
compile your installation.
String identifiers must follow an at symbol (@) in your script. The Select String dialog box will let you
browse and modify the string table for the default language before inserting the selected string ID into
your script.
For example, assuming you have an entry in your string table for MSG_ACTION_SUCCEEDED, you
could display its value in a message box as demonstrated below:
szMsg = @MSG_ACTION_SUCCEEDED;
nType = INFORMATION;
MessageBox (szMsg, nType);
Caution: You cannot rename a file to the name of an existing file under the project location, even if the script file has been
removed through the above procedure. For example, assume you have a script file called Setup.rul in your project.
Next, remove that file and add a new script file, called Script1.rul by default. You cannot rename Script1.rul to
Setup.rul, because doing so would overwrite the first Setup.rul. To avoid this, you should move your original
Setup.rul out of your project folder, rename it, or delete it through Windows Explorer.
Task To create a library file for functions that you have defined:
1. Create one or more .rul files containing the definitions of your functions.
2. At the command line, for each of your .rul files, run Compile.exe with the -c switch to compile the
file without linking it to any existing library file. This will create an .obs file (rather than the .inx file
created by compiling without the -c switch). For example, enter the following command line to
create the file MyFunc.obs in the current folder.
Compile MyFunc.rul -c
To create an .obs file with a different name or location, use the -o switch.
3. Run Compile.exe with the -l switch, and one or more .obs files as parameters, to create the library
file. For example, enter the following command line to create the file MyFunc.obl in the current
folder.
Compile MyFunc.obs -l
Entering the following command line creates the file MyFunc1.obl in the current folder.
Compile MyFunc1.obs MyFunc2.obs -l
To create an .obs file with a different name or location, use the -o switch.
Tip: If you have many .obs files, you can shorten the command line by using a command file as in the following example:
Compile @MyObsFiles.txt -l
To quickly create the command file, you can use the MS-DOS command DIR with its /b (bare format) switch and redirect
the output to a file. For example:
DIR *.obs /b > MyObsFiles.txt
To compile an installation script using your library file, specify the library file on the command line or—
when compiling within InstallShield—in the Libraries (obl) box on the Compile/Link Tab of the Settings
dialog box.
Task To print the file that is displayed in the active script editor pane:
1. On the File menu, click Print. Note that this command is enabled only if the insertion point is in
the script editor pane. The Print dialog box opens.
2. Specify the options that you prefer.
3. Click OK.
Printing Settings
InstallShield uses the following settings when printing scripts:
• Left margin: 5/8 inch; top margin: 5/8 inch; bottom margin 1 inch; right margin: ¾ inch.
• Header contains the full path and file name of the file in bold.
• Footer contains the page number.
• Font is Courier.
InstallScript Lists
Lists are used to store related information, such as strings or numbers. InstallScript lists are very similar
to single-linked lists in the C language. InstallScript list functions are very flexible, enabling you to
return information in an order different from the order in which it was stored and access and use that
information in a variety of ways.
List Functions
InstallShield provides a number of functions for creating and manipulating lists. There are three types of
InstallScript list functions:
• Functions ending in -String that work with string lists only
List Structure
Lists are used to store related information—either strings or numbers. All the information in a list must
be of the same data type, and the number of elements is limited only by the available memory.
An InstallScript list has two parts. The first part is the head, which InstallShield uses internally. The
head of the list contains general information about the list, such as whether it contains strings or
numbers. The head also contains pointers to the beginning and end of the list.
The second part of the list is the list body. The list body contains the actual strings or numbers. You can
have as many strings or numbers in a list as the memory in the system will allow.
Remember that lists cannot contain both numbers and strings. A list must have only strings or only
numbers.
Variables representing lists can be declared as type LIST or type LONG. Lists exist only in memory,
meaning they are destroyed when the installation is complete. If a list is local to a function, the list is
destroyed when the function returns control to the calling code.
–or–
// This builds the list head for a number (item) list.
listID2 = ListCreate (NUMBERLIST);
ListCreate automatically builds the head of the list and returns its ID number. The ID is used in all
subsequent functions that operate on the list. Therefore, you must always create a list using ListCreate
before you use any other list function. You must store the return value from ListCreate in a variable of
type LIST or type LONG.
This fragment creates a number list and then a string list. It also tests each one to make sure that the lists
were created successfully.
// This creates an empty list for strings.
listID1 = ListCreate (STRINGLIST);
When you are finished using a list, you will typically want to destroy the list to free the memory for other
uses. ListDestroy destroys the list and its contents. This example creates a list referenced by listID, adds a
string to the list, and then destroys the entire list.
listID = ListCreate (STRINGLIST);
If you do not destroy a list using ListDestroy, the list will be destroyed when the installation is complete.
If the list is local to a function, the list is destroyed when the function returns control to the calling code.
Function Description
ListAddString and ListAddItem add a single element to the list that you specify. Remember that, regardless
of where you place the new string in the list, it becomes the current string. Use the options BEFORE and
AFTER to indicate where you want to place the new element in the list relative to the current element. If
you are working with a newly created list, using either BEFORE or AFTER will add the string to the first
element position in the list.
Adding elements to a list and the resulting effects on the list order and the element in the current
position are most easily explained by example. The examples below use string lists and ListAddString, but
the same principles and steps apply to using ListAddItem and number lists. Consider these scenarios:
• Adding an element to an empty list
Figure 13-4: String 1 is added. Then String 2 is added before String 1. Last, String 3 is added after String 2.
In the example above, if String 3 were added before the current string, the result would be as shown
below, with String 3 becoming the current string. This code segment is shown below:
// Create the empty list of strings.
listID = ListCreate (STRINGLIST);
Figure 13-5: String 1 is added. Then String 2 is added before String 1. Last, String 3 is added before String 2.
Note that since ListDeleteString and ListDeleteItem delete the current element, you must reset the current
element to the element that you want deleted. After deletion, the next element in the list becomes the
current element. You reset the element by any of the methods described in Traversing Lists.
The example below illustrates the use of several list functions, including ListDeleteString. The
ListDeleteItem function is used in the same manner, except that the list is a number list and the variables
are number variables.
// Create the empty list of strings.
listID = ListCreate (STRINGLIST);
nItem = 1;
ListAddItem (listID, nItem, AFTER);
ListDestroy (listID);
Note: The ListFindString and ListFindItem functions look for only the first instance of the specified string or number at
or after the current element.
The ListSetIndex function works on both string and number lists. After you set the indexed element as the
current element, call either the ListCurrentItem function or the ListCurrentString function to return the
value of the indexed item.
This example demonstrates traversing a list non-incrementally using ListSetIndex.
listID = ListCreate (STRINGLIST);
GetGroupNameList (listID);
nCheck = ListSetIndex (listID, LISTFIRST);
ListDestroy (listID);
The ListCount function tells you how many elements are in a list. The ListCount function is used mainly
for general information purposes, although it can be used to establish an upper index value in
conjunction with ListSetIndex. For example, you can call ListCount to get the number of elements in a list,
and use that value with ListSetIndex to traverse a list. The above example, which uses a while loop, is
rewritten below using an InstallScript for loop based on the number of elements in the list.
listID = ListCreate (STRINGLIST);
GetGroupNameList (listID);
ListDestroy (listID);
Traversing Lists
InstallShield provides these functions for traversing lists incrementally and non-incrementally:
Function Description
Function Description
ListGetNextItem Retrieves the element after the current element from a number list.
ListGetNextString Retrieves the element after the current element from a string list.
InstallShield uses single-linked lists, which means that unless you use functions that set indices or
search for specific elements in lists, you can traverse lists incrementally in one direction only: from the
first element to the last.
InstallShield allows you to traverse lists in non-incremental fashion by means of indices and by
searching for particular elements in lists. Refer to the individual function descriptions for more details.
Most list traversing and list access operations are carried out relative to the current list element.
Furthermore, most of the functions used to traverse and access lists establish a current element as a
result of their action. Therefore, making an element the current element in a list is not an isolated action;
it is a byproduct of another action.
If a list is empty, adding an element to the list will establish a current element. If a list is not empty, then
making an element the current element is best accomplished by traversing the list or searching for a
particular element in the list.
Tip: Lists are often processed within while loops, usually checking for END_OF_LIST. An infinite loop can result if the list is
not valid. If you are processing lists in a while loop, make sure that you have created the list with the ListCreate function,
and that you have not destroyed the list with the ListDestroy function.
Function Description
All open files are saved automatically when you click Save on the File menu.
System Restore
Note: Installation actions (for example, registry changes and file modifications) that take place before file transfer cannot
be undone by System Restore.
Your installations are System Restore compatible by default. You can disable System Restore
compatibility by placing the following code in your script’s OnBegin event handler:
Disable( PCRESTORE );
If the file Wininit.ini exists in the target machine’s Windows folder, the installation cannot set a restore
point. To handle Wininit.ini, put code like the following in the OnFirstUIBefore and OnMaintUIBefore
event handler functions:
/* Look for Wininit.ini in the Windows folder. If it is found ... */
if FindFile( WINDIR, "Wininit.ini", svResult )=0 then
bRebootForSystemRestore = TRUE;
/* ... get its size. */
GetFileInfo( WINDIR ^ "Wininit.ini", FILE_SIZE, nvSize, svResult );
/* If its size is zero bytes ... */
if nvSize=0 then
/* ... delete Wininit.ini. */
if DeleteFile( WINDIR ^ "Wininit.ini" )=0 then
bRebootForSystemRestore = FALSE;
endif;
endif;
/* If Wininit.ini has a non-zero size or could not be deleted, notify the end user and allow
a reboot. */
if bRebootForSystemRestore then
szQuestion = "Windows System Restore lets you undo " +
"changes to your computer. If you want to be able " +
"to use System Restore to undo this installation, " +
"you must reboot your computer now.\n\n" +
"Do you want to reboot your computer now?"
if AskYesNo( szQuestion, YES )=YES then
System( SYS_BOOTMACHINE );
endif;
endif;
endif;
Note: Note that the MsiGetProperty and MsiSetProperty properties cannot be used for deferred InstallScript custom
actions, which do not have access to the active .msi database and do not recognize any Windows Installer properties.
They can access only the information that has been written into the execution script.
The following example retrieves the user name from the Windows Installer setup package, confirms the
value, gives the user the opportunity to change it, and then writes the new value back into the database:
// Include header file for built-in functions
#include "isrt.h"
// Include header file for MSI API functions and constants
#include "iswi.h"
function Func1(hMSI)
STRING svName;
NUMBER nvSize, nResponse;
begin
// Retrieve the user's name from the MSI database
nvSize = 256;
MsiGetProperty (hMSI, "USERNAME", svName, nvSize);
if nResponse = NO then
AskText ("Enter the name that will be registered for " +
"this product.", svName, svName);
MsiSetProperty(hMSI, "USERNAME", svName);
endif;
end;
Note that 0x00000003 is not a valid bit flag, since this value corresponds to two bits in the number
being set to 1.
All bits other than the rightmost bit are set to 0 by the & operation; the rightmost bit is 1 since it is 1 in
both the constant BITFLAG_TEST_1 and nFlags.
The following expression evaluates to FALSE since the third bit of nFlags is 0 and all other bits are set to
0 by the & operation:
String Comparisons
When InstallShield compares two strings, it starts by comparing the initial character in the first string
with the initial character in the second string. If those characters are equal, InstallShield then compares
the characters in the next position of each string. If those characters are also equal, it moves on to the
characters in the next position, continuing in sequence until it encounters one of the following
conditions:
• Two characters in the same relative position in the two strings do not match. In this case,
InstallShield bases its resolution on the comparison of those two characters. If the character in
string one has a greater value than the character in the corresponding position of string two, then
string one is greater; otherwise string two is greater.
• The end of one string is encountered without finding unequal characters in corresponding positions.
In this case, the strings are of unequal length and therefore they are not equal.
• The end of both strings is reached without finding unequal characters in corresponding positions. In
this case, the strings are equal in length and all characters match; therefore the strings are equal.
Consider the following example:
svString1 = "trusting";
svString2 = "TRUTHFUL";
String comparisons are not case-sensitive. Because an uppercase character is equal to its lowercase
counterpart, InstallShield finds that the first three characters of trusting and the first three characters
of TRUTHFUL are equivalent. The comparison ends with the test of the characters in the fourth
position of each string. Since s is lower than t in the ASCII character table, svString1 does not equal
svString2. The remaining characters are not compared and the else branch is executed.
Note: The value of each character is based on its ASCII value. For information about the ASCII values of specific
characters and symbols, refer to a basic programming manual.
STRING szString[1024];
Do not use autosizing; the installation engine expects autosized strings to not include null characters
within the string.
• Do not try to create arrays of null-delimited strings; since array elements must always be autosized,
string arrays do not currently support this type of string.
• The specified size of a null-delimited string should be at least the number of characters to be stored
plus two for the two terminating null characters.
• Since strings are automatically initialized to all null characters, you do not need to explicitly set the
second-to-last character to null (though this will not cause any adverse effects) unless you have
previously set the second-to-last character to something other than null.
• The best way to determine the length of a null-delimited string is to call the CharReplace function to
replace the null characters and then call the StrLengthChars function to determine the size of the
resulting string.
• The StrGetTokens and StrPutTokens functions may be useful when working with null-delimited
strings.
• Most InstallScript functions other than the ones noted above do not work with multiple null-
delimited strings. If you want to use a multiple null-delimited string with a built-in function, use the
CharReplace function first to replace the null characters with another character, such as an
underscore (_).
Relative Path
A relative path includes all of the information necessary to locate a file by starting at the current folder
on the current drive, for example, IS2008\Support. That folder can be located along that relative path
only if it exists in the current directory.
Absolute Path
Building Functions
Typically, functions are declared at the top of the file, and the body is defined at the bottom of the file.
After you declare a function prototype, you need to define the function itself in the function block. Each
function block contains only one function.
4. To the right of the function name, type the names of the arguments that you are using in
parentheses. The arguments must correspond in data type to the parameters that you declared in
the declare block.
Note: InstallScript functions do not allow you to pass an assignment statement as a parameter. In addition, you
cannot use the && or || operators within an argument to a function.
Steps 1 and 2 create the function header. Function headers do not end with a semicolon in
InstallScript.
5. Declare any local variables that you will use in the function. Then type the keyword begin on a line
by itself, without punctuation.
6. After the begin line, add whichever statements you need in order to accomplish your particular task.
You can also use a return statement, particularly if you want to return a specific value from the
function. See below for information on returning values from a function.
7. End your function with the keyword end.
A sample function block is shown below:
function GetPathParts(szFullPath, svDrv, svPath, svName)
LONG lResult;
begin
lResult = ParsePath(svDrv, szFullPath, DISK);
if (lResult = 0) then
lResult = ParsePath(svPath, szFullPath, DIRECTORY);
endif;
if (lResult = 0) then
lResult = ParsePath(svName, szFullPath, FILENAME);
endif;
return lResult;
end;
Note: User-defined functions can return a value with a return statement. Other types of data can be returned in parameters
that have been declared with the BYREF operator.
Calling Functions
All functions—whether user-defined, built-in, Sd, or external—are called in the same way. Type the
name of the function, followed by the parameters that you want to pass to the function. For example:
MyFunction (MyAge, MyHeight, MyWeight);
Note: InstallScript functions do not allow you to pass an assignment statement as a parameter. In addition, you cannot use
the && or || operators within an argument to a function.
An autosized string variable that is passed by reference to a function is not autosized within the called function. If the
function attempts to assign a value whose length is greater than the current size of that parameter, run-time error 401
occurs. To avoid this error, declare strings with a specific size when they are to be passed by reference to a function.
1. Add the .dll file to your project as a support file if you have not already done so. For more
information, see Adding Support Files.
2. Open the InstallScript view.
3. In the InstallScript explorer, click the InstallScript file (.rul) that should call the .dll function.
4. At the beginning of the script, prototype the function using the following syntax:
prototype [CallingConvention] [ReturnType] DLLName.FunctionName( ParamType1, ParamType2,
... );
For example:
prototype BOOL MyDLL.MyFunction( INT, INT, INT );
You can specify the calling convention to be cdecl or stdcall. If you do not specify a calling
convention, InstallShield uses stdcall.
Note that the .dll file name is case-sensitive; for example, the script compiler treats
MyDLL.MyFunction and mydll.MyFunction as different functions. When prototyping functions from
User.exe, User32.dll, Gdi.exe, Gdi32.dll, Krnl386.exe, Krnl286.exe, or Kernel32.dll, you may use
the keywords USER, GDI, and KERNEL in place of the .dll file name.
You can specify the return type to be any InstallScript data type except LIST. If you are declaring a
.dll file function call in which a wide-character string argument is expected, use the wstring data
type. If you do not specify a return type, the installation assumes that the .dll file function returns a
4-byte value.
5. Load the .dll file by calling the UseDLL function. For example:
UseDLL( SUPPORTDIR ^ "MyDLL.dll" );
Note: You do not have to load _isuser.dll, _isres.dll, or Windows API .dll files, such as User.exe,
User32.dll, Gdi.exe, Gdi32.dll, Krnl386.exe, Krnl286.exe, and Kernel32.dll. Do not call UseDLL and
UnUseDLL to load and unload these .dll files.
6. Call the function as you would call any other function. For example:
bResult = MyDLL.MyFunction( nInt1, nInt2, nInt3 );
It is recommended that you include the .dll file name in the function call, as in the preceding
example. If your script declares functions with the same name from different .dll files, calling the
function without including the .dll file name results in a compiler error.
If the installation does not find the called function in the .dll file, the installation raises an exception,
which you can handle by using a try...catch...endcatch block.
7. After all script calls to the .dll have been made, unload the .dll file by calling UnUseDLL. For example:
UnUseDLL( SUPPORTDIR ^ "MyDLL.dll" );
Declaring Functions
The first step in creating a user-defined function is to declare the function. The keyword prototype tells
the InstallShield script compiler that the line contains a function definition.
When you are declaring .dll functions, use the format <DLL file name>.<function name> for the name
of the .dll file function. For example:
The above declaration signals to the InstallScript compiler that the program will call a function named
MyFunction, with two INT parameters, in a file named Mydll.dll.
You can also optionally declare a calling convention, either cdecl or stdcall, when declaring a .dll file
function. For example:
prototype cdecl MyDLL.MyFunction(INT, INT);
If you do not explicitly declare a calling convention, InstallShield uses stdcall. If you explicitly declare
both a calling convention and a return type, place the calling convention before the return type.
Note: Most Windows API functions use the stdcall calling convention, but some C or C++ development environments build
.dll file functions with the cdecl calling convention unless you prototype your C or C++ function with the __stdcall modifier.
For more information, consult your compiler documentation.
In InstallScript projects, many Windows API functions are declared in the header files WinAPI.h and Winproto.h, which
are automatically included when you include Ifx.h in your script. (You can prevent the automatic inclusion of WinAPI.h in
Ifx.h by placing the preprocessor constant ISINCLUDE_NO_WINAPI_H in the Preprocessor Defines box on the Compile/
Link tab of the Settings dialog box.)
The keyword return can be followed by a constant, a variable, a numeric or string expression, or a
function call. In the example below, RectangleArea has been modified to eliminate the assignment
statement; the arithmetic expression follows the keyword return:
function RectangleArea (nLength, nWidth)
begin
return (nLength * nWidth);
end;
The value returned by a function can be ignored by the calling program or function, tested in a
conditional expression, or assigned to a variable. In the following example, the return value from
RectangleArea is assigned to the variable nArea:
To return more than one value or non-numeric values, use the BYREF operator to define parameters
that are passed by reference.
Unsupported Functions
Some of the functions that were available in InstallShield Professional and InstallShield—Windows
Installer Edition are not supported in InstallShield.
Component Functions
In InstallShield, features are the top-most level of project organization from the end user’s perspective.
Because of this, component functions are now feature functions. For example, ComponentDialog is now
FeatureDialog. Nearly all of the component functions are available to you as feature functions in
InstallShield.
Project: Feature functions are available for use in InstallScript and InstallScript MSI project types. If you have a Basic MSI
project, you must convert your project to the InstallScript MSI project type in order to use feature functions in your
installation.
When Windows Installer executes an InstallScript custom action, InstallShield calls the function that
you specified when you created the custom action. Every InstallScript custom action must have an
exported, user-defined function as an entry point into the script.
// Include Iswi.h for Windows Installer API function prototypes and constants.
#include "iswi.h"
function MyFunction(hMSI)
STRING szKey, svValue, svPath;
NUMBER nvType, nvSize, nReturn;
begin
RegDBSetDefaultRoot (HKEY_LOCAL_MACHINE);
// The App Paths key contains the folder where InstallShield was
// installed, followed by a semicolon.
StrSub (svPath, svValue, 0, StrFind(svValue, ";"));
if nReturn = 0 then
MessageBox ("InstallShield is installed to " + svPath, INFORMATION);
return ERROR_SUCCESS;
else
MessageBox ("Cannot determine where InstallShield is installed.", SEVERE);
return ERROR_INSTALL_FAILURE;
endif;
end;
• If you are creating a script that needs to be compatible in both InstallShield 2008 and versions of
InstallShield Professional earlier than 7, surround your declaration with code such as the following:
#if _ISCRIPT_VER < 0x700prototype ...#endif
Note: If you put parentheses in a feature’s name, event handler functions with names of the default form <feature
name>_<event name> will not compile properly.
function OnBegin()
// Declare local variable
STRING svResult;
begin
GetSystemInfo (WINMAJOR, nvResult, svResult);
end;
function MyFn(hMSI)
begin
if nvResult > 4 then
// Code for version of Windows later than 4.0
else
// Code for Windows 4.0
endif;
end;
Important: Global variables share state across all event handlers. However, if you create an InstallScript custom action for
your project, global variables will not share state from the InstallScript custom action to the event-driven InstallScript code,
or vice versa. Thus, if you declare a global variable in your event-driven InstallScript code, that variable would not be
available to your InstallScript custom action. Similarly, if you declare a variable in your InstallScript custom action, that
variable would not be available to your event-driven InstallScript code.
device=votc.386
device=*vmpcd
device=*vmp32
device=votc.386
device=*vmpcd
If another installation had added a value to the existing line, only the value from the installation that is
being uninstalled will be removed. The original keyname and the new value will be left in the file. For
example, if you had added the line Test Values=votc.386 in Test.ini under the [Test] section:
[Test]
Test Values=votc.386
Continuous Test=No
and another installation had added a new value to Test Values after your installation had run:
[Test]
Test Values=votc.386,pctcp.386
Continuous Test=No
when your application is uninstalled, votc.386 will be removed and TestValues=pctcp.386 will be left in
the file:
[Test]
Test Values=pctcp.386
Continuous Test=No
device=votc.386
device=*vmpcd
device=*vmp32
device=votc.386
device=*vmpcd
Important: Do not confuse COM objects with InstallShield objects. They are two separate features.
Instead of using DLLs or other executable files, you can extend your installation with COM objects. COM
objects can be integrated into your installation fairly easily. Use the following procedure to assign COM
objects in your script.
2. Get a reference to your COM object and assign it to the variable by using the set keyword. For
example:
set oMyCOMObject = CreateObject ( szMyProgID );
The value of szMyProgID is a valid program ID for your COM object. If you leave the set keyword out,
the script engine attempts to set the default property of oMyCOMObject to szProgID. Because there is no
default property, since oMyCOMObject does not contain a reference to your COM object yet, the script
will fail.
Important: By default, once a COM object is loaded by the installation using CoCreateObject, CoCreateObjectDotNet,
CoGetObject, or DotNetCoCreateObject, it remains loaded until the installation is finished. The COM object remains
unloaded regardless of whether the COM object variable goes out of scope or is set to NOTHING.
Consequently, the library referenced by the COM object is also not released until the installation is finished. However, it is
possible to unload library referenced by the COM object by calling the Windows API, CoFreeLibrary. CoFreeLibrary
unloads the library regardless of whether any object variables still reference it. Therefore, you should only call
CoFreeLibrary after all objects referencing the library have gone out of scope or are set to NOTHING. See the following
example code:
prototype void ole32.CoFreeLibrary( byval int );
int hModule;
program
else
endif;
endprogram
CoFreeUnusedLibraries can also be used to unload the library. However, by default, the system waits 10 minutes before
unloading the library, and in most cases, the installation requires the library to be unloaded immediately. If your installation
will run on Windows XP and later only, you can call CoFreeUnusedLibrariesEx, which includes the option of unloading the
library immediately.
Below is an example COM object that validates a serial number. It has one method, Validate, and one
property, IsEval.
function OnFirstUIBefore()
OBJECT oObj;
STRING szProgID, szMsg, szTitle, svName, svCompany, svSerial;
BOOL bValidSerialNumber, bEval, bValidate;
NUMBER nResult;
begin
szProgID = "MySerialValidation";
set oObj = CreateObject( szProgID );
if ( !IsObject( oObj ) ) then
MessageBox( "Object " + szProgID + " is invalid!", SEVERE );
return ISERR_GEN_FAILURE;
endif;
bValidSerialNumber = FALSE;
while (!bValidSerialNumber)
szMsg = "Please enter your name, company name, and product serial number.";
szTitle = "Enter info";
nResult = SdRegisterUserEx( szTitle, szMsg, svName, svCompany, svSerial );
if ( nResult < 0 ) then
MessageBox( "Failed to display dialog box.", INFORMATION );
return ISERR_GEN_FAILURE;
endif;
return ISERR_SUCCESS;
end;
Note: You can pass a data structure to your COM object as long as it has the members that your COM object expects. The
following is an example of passing a data structure:
#define PERSON_NAME_SIZE 1024
typedef PERSON
begin
STRING Name[PERSON_NAME_SIZE];
NUMBER Age;
end;
function OnBegin()
PERSON pPerson;
NUMBER nPhoneNumber;
OBJECT oMyCOMObject;
STRING szMyProgID;
begin
/* Assign a value to szMyProgID in this line. */
set oMyCOMObject = CreateObject ( szMyProgID );
if ( !IsObject( oMyCOMObject ) ) then
MessageBox( "Object " + szMyProgID + " is invalid!", SEVERE );
return ISERR_GEN_FAILURE;
endif;
nPhoneNumber = oMyCOMObject.GetPhoneNumber( pPerson );
return ISERR_SUCCESS;
end;
Note: The standard COM return value HRESULT is not visible to an automation client such as InstallScript. To return a value
from your COM object method, you should have an [out,retval] parameter in your method’s parameter list, as illustrated in
the following code samples.
IDL:
interface IMyInterface : IDispatch
{
[id(1)] HRESULT DoSomeWork([in] long nInputValue, [out,retval] long *pReturnValue);
}
C++:
STDMETHODIMP MyInterfaceImpl::DoSomeWork(long nInputValue, long *pReturnValue)
{
// your implementation code
*pReturnValue = 1; //return a value to client
return S_OK;
}
InstallScript:
function OnBegin()
NUMBER nObjReturn;
begin
set oMyCOMObject = CreateObject("MyProgID");
if (IsObject(oMyCOMObject) then
nObjReturn = oMyCOMObject.DoSomething(10);
/*nObjReturn will contain the value 1, returned from your implementation*/
endif;
end;
1. At the beginning of the script, prototype the function using the following syntax:
prototype ReturnType DLLName.FunctionName( ParamType1, ParamType2, ... )
For example:
prototype INT User.LoadString( INT, SHORT, BYREF STRING, INT );
Use Dumpbin.exe with the /EXPORTS option to determine which functions reside in any of the
Windows API DLLs Kernel32.dll, User32.dll, and GDI32.dll. Consult a Windows programming
reference such as the Microsoft Development Library (MSDL) to determine the return type and
parameter types for a function.
Note: You can specify the return type to be one of the following InstallScript data types: BOOL, CHAR, HWND, INT,
LONG, LPSTR, NUMBER, POINTER, or SHORT. If a return type is not specified, InstallShield assumes that the DLL
function returns a 4-byte value.
2. Call the function as you would call any other function. For example:
nResult = LoadString( iInstance, nStringID, szMyString, MAX_SIZE );
3. To get extended error information if the function fails, check the value of the Err object’s
LastDllError property. (It is not possible to call the Windows API function GetLastError to get
extended error information, since the setup itself changes this value before returning control to the
script.)
This table provides an overview of what functions are called for each scenario.
Table 13-6: Determining Which Functions Are Appropriate for Common Custom Transfer File Operations
FeatureMoveData None
These procedures include step-by-step information about how to use custom file transfer operations for
each scenario.
Task To install additional files during the standard file transfer operation using XCopyFile or CopyFile:
1. Before file transfer, determine the size of the files to be installed, taking into account the cluster size
on the target folder for the files. You can accomplish this using the GetAndAddFileCost,
CalculateAndAddFileCost, and/or GetAndAddAllFilesCost functions.
2. Using the FeatureAddCost function, add the cost determined in Step 1 to the cost for the feature that
these files are associated with. Note that all cost must be associated with a particular feature.
Therefore, if the files to be installed are not associated with an existing feature, you must create a
dummy feature or use an existing feature.
3. During file transfer, call the XCopyFile function to install the files. Typically, this would be done
during the Installing event of the feature associated with the additional files or in the OnMoving or
OnMoved events. The progress bar is updated smoothly and appropriately during the call. Note that
you should disable the Cancel button in the status dialog during the XCopyFile operation. See the
description for the XCopyFile function for more information.
Note: There is no additional action required for the uninstallation. The files are uninstalled while the uninstallation progress
is updated appropriately.
Task To call an external installation that installs additional files during the standard file transfer operation:
1. Before file transfer, determine the size and number of the files to be installed (or other operations)
by the external installation by examining the external installation and taking note of what
operations occur.
2. Using the FeatureAddCost function, add the cost determined in Step 1 to the cost for the feature that
this installation is associated with. Note that all cost must be associated with a particular feature.
Therefore, if the files to be installed are not associated with an existing feature, you must create a
dummy feature or use an existing feature. Review the two scenarios below.
3. If the external installation is called during uninstallation, add the number of operations and size of
the operations to the uninstallation cost using FeatureAddUninstallCost.
4. During file transfer, use the LaunchAppAndWait event to launch the installation, typically in silent
mode. Typically, this would be done during the Installing event of the feature associated with the
additional files or in the OnMoving or OnMoved events. Use the LAAW_USE_CALLBACK option so
that your script regains control periodically during the installation and uninstallation.
5. Override the OnLaunchAppAndWaitCallback event, and add code to poll the running installation to
determine its progress. Then call the FeatureSpendCost (Installation) function or the
FeatureSpendUninstallCost (Uninstallation) function to spend the appropriate amount of cost that the
installation has completed. Repeat this process while the external installation is running. The
progress bar is updated smoothly and appropriately during the call. Note that you might have to
adjust the LAAW_PARAMETERS.nCallbackInterval so that the OnLaunchAppAndWaitCallback event
is called often enough to keep the progress updated smoothly.
Note: Note that convention differs from the unsigned high/low value pairs used by Windows in which the lower value
stores the lower 32 bits of data and the high value stores the upper 32 bits of data. The
ConvertWinHighLowSizeToISHighLowSize function is provided for easy conversion of data returned by Windows API
functions.
• GetFileInfo
• GetAndAddFileCost
• CalculateAndAddFileCost
• GetAndAddAllFilesCost
• FeatureFileInfo
• FeatureGetCostEx
• FeatureAddCost
• FeatureSpendCost
• ConvertWinHighLowSizeToISHighLowSize
• ConvertSizeToUnits
Project: This information applies to InstallScript projects. Installing device drivers is supported in InstallScript MSI projects
using the DIFx Windows Installer functionality. For information on configuring device drivers using the Windows Installer,
see Configuring Device Driver Settings.
function VersionExample(hMSI)
BOOL bIsShellExplorer, bIsWindowsNT4, bIsWindowsNT351;
BOOL bIsWindows95, bIsWindows98;
NUMBER nvResult; STRING svResult;
begin
// Initialize variables.
bIsShellExplorer = FALSE;
bIsWindowsNT4 = FALSE;
bIsWindowsNT351 = FALSE;
bIsWindows95 = FALSE;
bIsWindows98 = FALSE;
endif;
endif;
bIsShellExplorer = TRUE;
endif;
end;
Calling DoInstall
The preferred way to launch an installation created with InstallShield is to call the DoInstall function, as
described below:
1. Create a complete installation project for the child (launched) installation; all the files generated by
InstallShield are necessary for the child installation to run properly.
2. In the parent (launching) installation project, place all the files for the child installation in one of the
following locations:
• A subfolder of the main installation’s source location (SRCDIR)
• A file group that is installed to a temporary location; for example, a subfolder of the main
installation’s support folder (SUPPORTDIR)
3. In the parent installation script, call DoInstall as in the following example if the child installation’s
files are in a subfolder of the main installation’s source location:
DoInstall (SRCDIR ^ "Child\\Setup.inx", "", LAAW_OPTION_WAIT);
Perform the following if the child installation’s files are installed by a file group to a subfolder of the
main setup’s support folder.
DoInstall (SUPPORTDIR ^ "Child\\Setup.inx", "", LAAW_OPTION_WAIT);
Calling LaunchAppAndWait
You can also launch a complete installation by calling the LaunchApp or the LaunchAppAndWait function.
For example, if you left the child setup’s files on a CD-ROM, you would call LaunchAppAndWait as follows:
Alternatively, you could insert links to the child installation’s files into your file groups, install the files
onto the target system, and then launch the installation from the target location. (Of course, this method
will leave the installation files on the target system until the parent installation is uninstalled.)
On systems operating in 256-color mode, there is one 256-color palette for displaying all available
colors; in 16-color mode, there is a 16-color palette, regardless of the number of colors that the video
driver supports. Systems operating in high-color or true-color mode do not use a color palette of any
type. The colors are displayed directly, so color distortion should not occur on these systems. On systems
using a color palette, entries are allocated and used as needed when an object—such as a bitmap—is
displayed.
Once the current color palette has been allocated, to display a new color Windows attempts to use a color
similar to one that was already allocated. Therefore, distortion may result on a 256-color system if
multiple objects that contain several different colors are displayed simultaneously.
Also, Windows allocates 16 static colors (VGA colors) and four additional shades of gray during startup.
These colors are used by the system to display 16-color images and are never de-allocated by Windows.
See the Windows platform SDK for more information on color palette handling.
Use the tips below to minimize any color distortion related to color palette shifts. Color palette tips apply
to all images that you display during installation, including the background color, .avi files, metafiles,
and bitmaps.
standard 16 static colors in your metafile, because these colors will be available, regardless of the
current color palette’s availability.
• Verify that the system’s video driver supports 256 or more colors. If the video driver does not
support 256 colors, the bitmap will not display properly, even if your video card and monitor
support 256 colors.
• If a monitor is not capable of displaying 256-color bitmaps, only the 16 static colors are used. This
can cause severe distortion problems. If you are using 256-color images in your installation, it is
recommended that you require end users to run it on systems that support 256 colors.
Task InstallShield divides the task of creating and implementing custom actions into the following steps:
1. Create a custom action in the Custom Actions and Sequences view (or the Custom Actions view) or
by using the Custom Action Wizard.
2. Decide when your custom action should run.
3. Launch a custom action by inserting it into a sequence or placing it as the result of a dialog’s control
event (Basic MSI projects).
For details about each of the InstallShield custom actions that are added automatically to InstallShield
projects to support different functionality, see InstallShield Custom Action Reference.
Project: Merge module projects only: You can control the launch of custom actions in a merge module by modifying the
ModuleInstallExecuteSequence table in the Direct Editor. When you add the merge module to your installation project,
all custom actions and dialogs included in the merge module are available for you to insert in the installation’s sequences
via the Custom Actions and Sequences view.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. Right-click the Custom Actions explorer and click Custom Action Wizard. The Custom Action
Wizard launches.
Project: The Custom Actions and Sequences view is available in the following project types:
• Basic MSI
• InstallScript MSI
• MSI Database
• Transform
• Web
The view is called the Custom Actions view in the following project types:
• Merge Module
• MSM Database
The recommended way to create a custom action is with the Custom Action Wizard. The wizard walks
you through all the required steps to create a custom action and prompts for information. You can also
create your custom action in the Custom Actions and Sequences view (or the Custom Actions view)—
without using this wizard—by configuring all of its settings directly in the view.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. Right-click the Custom Actions explorer and then click the type of custom action that you want to
add.
3. Rename the new custom action by selecting it, pressing the F2 key, and typing the new name.
4. Configure the custom action’s settings.
For more information about these settings, see CustomAction Table in the Windows Installer Help
Library.
Property Description
DLL Filename Enter the path to the .dll file that you would like to use in your custom action. As
an alternative, you can select it from the list of available .dll files in your Binary
table, or select Browse for file to find it.
The .dll file must comply with the required Windows Installer function signature.
Function Name Enter the name of the function that you would like to call.
Return Specify how the custom action thread should be processed. Valid options are:
Processing
• Asynchronous (No wait for completion)
• Asynchronous (Wait for exit code)
• Synchronous (Check exit code)
• Synchronous (Ignores exit code)
These flags are used to specify that the main and custom action threads run
synchronously (the installer waits for the custom action thread to complete
before resuming the main installation thread) or asynchronously (the installer
runs the custom action simultaneously as the main installation continues).
Note that some options are not applicable to some types of custom actions.
Only options that pertain to the selected type of custom action are available in
this list.
In-Script Select which iteration of the sequence will trigger your action. For details about
Execution each option, see In-Script Execution.
These options copy the action code into the execution, rollback, or commit
script. If you select a Terminal Server Aware option, the custom action
impersonates the user during per-machine installations on terminal server
machines.
Source If you chose to launch an executable file (.exe file), call a function in a Windows
Installer .dll file, or execute a VBScript or JScript file, this property can contain
the name of the table entry from tables such as the Binary table or the
Property table. If you chose to set a property or directory, enter the property
or directory name from the associated table entry. For more information on this
property, see the Windows Installer Programmer’s Reference for the action type
that you are calling.
Property Description
Target Depending on the type of custom action that you are creating, the Target
property can be a command-line argument, a function name, or a formatted
text string. For executable files, this property will be a command-line argument,
such as -s to run the executable file in silent mode. If you are calling a function
from a Windows Installer .dll file or running JScript or VBScript code, this
property should contain a function name. Enter a formatted text string that will
evaluate to the new value of a property if you are setting a property or
directory. Standard .dll files must have the function name, parameters, and
return type in a specially formatted string.
Type Enter the numeric value for the type of action that you want to create.
In addition to the native Windows Installer custom action types, InstallShield
supports custom action types for InstallScript custom actions and for calling a
function in a standard .dll file.
Comments Type comments about this action into the Comments field. These comments
are for internal use and are never displayed to the end user.
Help File Path Click the ellipsis button (...) to browse to the file that describes the behavior of
the custom action. The file should be a text-based file such as a .txt, .htm, or
.rtf file.
At build time for Basic MSI, InstallScript MSI, and merge module projects,
InstallShield streams the contents of this file into the Description column of the
ISCustomActionReference table.
If you are working on a project in Direct Edit mode, InstallShield streams the
contents of the file that you select into the Description column of the
ISCustomActionReference table as soon as you select the help file. In
addition, InstallShield makes this setting read-only and displays [Text Data] as
the value for this setting.
Windows Logo Guideline: The intended behavior of each custom action must be
documented for the Certified for Windows Vista program. This is especially
helpful if system administrators deploy your product to enterprise
environments; they sometimes need to know what the custom actions do. If you
validate your installation package but you have not specified a value for the
Help File Path setting, InstallShield generates validation error ISICE10. For more
information, see ISICE10.
For any built-in InstallShield custom actions, InstallShield makes this setting
read-only and displays InstallShield Custom Action as the value.
Project: You should not use an InstallScript custom action in the User Interface sequence of an InstallScript MSI project.
You can use the script to provide the user interface in an InstallScript MSI project.
If you are authoring an InstallScript custom action, your entry-point function can return either
ERROR_SUCCESS or ERROR_INSTALL_FAILURE. These constants are defined for you when you
include Iswi.h in your script. The InstallShield script engine reports any of the other exceptions to
Windows Installer.
In-Script Execution
When you create a custom action, one property that must be set is the In-Script Execution property on
the Respond Options panel of the Custom Action Wizard. Actions are executed in the order in which
they appear in a sequence. However, the sequences are run many times during a typical installation. The
In-Script Execution property enables you to select which iteration of the sequence will trigger your
action.
Immediate Execution
As its name implies, Immediate Execution runs when the internal Windows Installer installation script
is being compiled. When an .msi file is launched, the Windows Installer service converts all the tables in
the installation database into an internal script. (This internal script is not the same as InstallScript
code.) This script is built by cycling through all the actions in the installation in the order in which they
appear. The building of this script is immediate execution. When an action is encountered whose In-
Script Execution property is set to Immediate Execution, that action is executed. Therefore, this action
launches before any file transfers are encountered, possibly even before the end-user interface for the
installation is fully loaded.
As a rule, custom actions scheduled for immediate execution do not modify the target system, but only
set properties and query the target system (for example, to see if the target system meets your product’s
system requirements). Custom actions that set Windows Installer properties must be scheduled for
immediate execution, and custom actions that occur in the User Interface sequence must be scheduled
for immediate execution.
Because actions of this type run before any changes have been made to the system, they cannot rely on
files that are being installed by the installation.
Deferred Execution
Deferred Execution takes place when the internal script generated during Immediate Execution is
executed by the Windows Installer service. After that script has been fully generated, the Windows
Installer service runs the newly compiled script. The script runs through all of the actions in your
sequences and executes them in order. However, if an action is scheduled for immediate execution, the
action does not run again during Deferred Execution.
Actions that launch during Deferred Execution have access to files being installed as part of the system.
As a result, you can call a custom action that calls a function from a .dll file installed with your product
during this phase of the installation. However, Deferred Execution custom actions must take place
between InstallInitialize and InstallFinalize in order to work properly.
Custom actions that rely on a file being installed to the target system, or that rely on other system
changes to have already been performed, must be scheduled for deferred execution.
Rollback Execution
Rollback occurs when an error is encountered by the installation or the end user cancels the installation
before it has a chance to complete. The Rollback Execution option allows you to set your action to
execute only during rollback. Therefore, any actions that are enabled for Rollback Execution are written
to the installation script, as are Deferred Execution actions. Unlike Deferred Execution actions, Rollback
Execution actions launch only during rollback. (Rollback custom actions run only if the installation fails
during deferred execution.)
Any custom actions that make changes to the target system during an installation should be undone with
a Rollback Execution custom action in the event of rollback. For example, if you have a custom action
that creates a file, you should create a second custom action that deletes the file, and schedule the second
action for rollback execution. (A rollback custom action should be scheduled before the custom action it
reverses.)
Commit Execution
Commit Execution actions do not run until the InstallFinalize action completes successfully. This means
that they wait until the installation has completed transferring files, registering COM servers, and
creating shortcuts and registry entries. Then, any actions that are set to Commit Execution launch in the
order in which they appear in the sequence.
For example, if you have a custom action that creates a temporary file, you should create a second
custom action that deletes the file, and schedule it for commit execution.
Windows Logo Guideline: The intended behavior of each custom action must be documented for the Certified for
Windows Vista program. This is especially helpful if system administrators deploy your product to enterprise
environments; they sometimes need to know what the custom actions do. If you validate your installation package but you
have not specified a value for the Help File Path setting, InstallShield generates validation error ISICE10. For more
information, see ISICE10.
1. Create a file that describes the intended behavior of the custom action. The file should be a text-
based file such as a .txt, .htm, or .rtf file. Note that each custom action should have its own
document.
2. In the View List under Behavior and Logic, click Custom Actions.
3. In the Custom Actions explorer, click the action that you are documenting.
4. For the Help File Path setting, click the ellipsis button (...) to browse to the file that describes the
behavior of the custom action.
Tip: You can specify whether InstallShield should stream the contents of each of the custom action help files into the .msi
file at build time. For more information, see the description of the Include Custom Action Help setting for a product
configuration in the Releases view.
• Custom actions that change system state during installation must remove or restore the system state
during uninstallation. In addition, custom actions that change system state must be written as a
deferred and rollback custom action pair.
• This does not apply to custom action types 19 (displays an error, returns failure, and ends the
installation), 35 (sets the installation directory), or 51 (sets a property)
• The intended behavior of each custom action in your installation must be documented. This does
not apply to custom action types 19 (displays an error, returns failure, and ends the installation), 35
(sets the installation directory), or 51 (sets a property). For more information, see Documenting the
Behavior of Custom Actions.
For information about all of the InstallShield custom actions that are added automatically to
InstallShield projects to support different functionality, see InstallShield Custom Action Reference.
Nested Installations
Important: Nested installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft Corporation
recommends that you avoid using nested installations and nested-installation custom actions to install products that are
intended to be released to the public. To learn more, see Concurrent Installations on the MSDN Web site.
A nested installation is a type of custom action that installs or removes another .msi package (sometimes
called the child product) from within a running installation (called the parent product).
Note: Before using nested-installation custom actions, you should be aware of the following restrictions:
• Nested installations do not display a user interface.
• A child product generally does not appear in Add or Remove Programs in Control Panel on the end user’s system, and
it is not automatically uninstalled when the parent product is uninstalled.
Important: Nested installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft Corporation
recommends that you avoid using nested installations and nested-installation custom actions to install products that are
intended to be released to the public. To learn more, see Concurrent Installations on the MSDN Web site.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. Right-click the Custom Actions explorer and click Custom Action Wizard. The Custom
Action Wizard opens.
3. On Basic Information panel, specify a name and comment for your custom action and click Next.
4. On the Action Type panel, in the Type list, select Launch another .msi package. In the
Location list, select Included within your main setup.
5. On the Action Parameters panel, browse for the location of the .msi file that you are launching.
(For simplicity, assume that the child product is packaged with all files compressed into the .msi
package.) The Target box enables you to specify command-line switches to pass to the child
installation. For example, to install all of the features of the child installation with their default
settings, and to use the same value for the ALLUSERS property used by the parent installation,
type the following in the Target box:
ARPSYSTEMCOMPONENT=1 ADDDEFAULT=ALL ALLUSERS=[ALLUSERS]
You can use similar expressions to use the same value of INSTALLDIR in the child as in the parent.
6. Accept the default options on the Additional Options panel and click Next until you finish the
wizard.
Important: Nested installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft Corporation
recommends that you avoid using nested installations and nested-installation custom actions to install products that are
intended to be released to the public. To learn more, see Concurrent Installations on the MSDN Web site.
After you have created the custom action, you need to insert it into a sequence.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. In the Sequences explorer, under the Installation sequence, expand the User Interface item.
The actions and dialogs that are scheduled for this sequence are listed.
3. Right-click CostFinalize and click Insert. The Insert Action dialog box opens.
4. Select the new custom action.
5. In the Condition box, select Not Installed to ensure that the nested installation is performed only
the first time that the parent product is installed.
6. Click OK.
Important: Nested installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft Corporation
recommends that you avoid using nested installations and nested-installation custom actions to install products that are
intended to be released to the public. To learn more, see Concurrent Installations on the MSDN Web site.
A child product is not automatically removed when the parent product is removed. However, you can
create a second nested-installation custom action that does this.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. Right-click the Custom Actions explorer and click Custom Action Wizard. The Custom
Action Wizard opens.
3. On the Basic Information panel, specify a name and comment for your custom action and click
Next.
4. On the Action Type panel, in the Type list, select Launch another .msi package. In the
Location list, select An application that is advertised or already installed.
5. On the Action Parameters panel, browse for the location of the .msi file that you want to remove.
In the Target box, leave the default properties:
ALLUSERS=[ALLUSERS] REMOVE=ALL
6. Accept the default options on the Additional Options panel and click Next until you finish the
wizard.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. In the Sequences explorer, under the Installation sequence, expand the Execute item. The
actions and dialogs that are scheduled for this sequence are listed.
3. Right-click InstallValidate and click Insert. The Insert Action dialog box opens.
4. Select the new custom action.
5. In the Condition box, type the following:
REMOVE="ALL"
6. Click OK.
This custom action will uninstall the child product when the parent product is uninstalled.
Note: When you are creating a nested-installation custom action of type Launch another .msi package with the Location
setting set to Stored on the source media, be aware of the following:
• The child installation must not be compressed inside a Setup.exe installation launcher.
• If the child installation’s files are not compressed inside the child .msi database, you must manually copy the child
installation’s files to the Disk1 folder of the parent installation’s release folder.
Calling MsiGetProperty
A more robust way to set a condition on your custom action based on release flags is to author a call to
MsiGetProperty within the custom action. In addition to determining if the action should launch, you can
also indicate what code is executed by the action. For example, you can use one function from a .dll file
for all scenarios, yet provide different functionality for each scenario through conditional logic within
your function.
The drawback to conditionally launching your custom action in this way is that you can use only a script
or .dll custom action. Additionally, your custom action still launches behind the scenes. When the
custom action launches, it can check if a specified release flag has been included in the build. If that flag
exists, the custom action continues. If the flag is not there, the action exits.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. In the Custom Actions explorer, right-click the custom action that you want to clone and click
Clone.
InstallShield adds a copy of the cloned custom action to the Custom Actions explorer. The name of the
custom action is the same name as the cloned custom action, except that the copy has a 1 at the end of
the name.
Task To call the Windows API function MessageBoxA() in a custom action to display a message box:
NUMBER Constant 1
In the Value list for the HWND type, select MsiWindowHandle. Setting the HWND type to this
value ensures that your message box will not hide behind the installation window. The properties
MESSAGEPROP and CAPTIONPROP are not available in the list. When you enter these names
in the Value list, they are added to the Property Manager.
3. In the Return Type list, select void. (Although MessageBoxA() does return a number, checking that
value in a property is outside the scope of this example.)
4. Click Next to proceed to the Action Parameters panel.
Project: Because a merge module does not have any sequences of its own, you must first build the module and include it
in an installation project before continuing with this example.
Follow the steps below to insert CA_Example into the Installation sequence of the installation project:
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. In the Sequences explorer, under the Installation sequence, expand the User Interface item.
The actions and dialogs that are scheduled for this sequence are listed.
3. Right-click the MigrateFeatureStates action (the action right before the InstallWelcome dialog)
and click Insert. The Insert Action dialog box opens.
4. In the list at the top of the dialog box, select Merge Module Custom Actions (for Merge Module
projects) or Custom Actions (for installation projects).
5. In the list of custom actions, select CA_Example.
6. Click OK.
CA_Example is added to the Installation sequence directly after MigrateFeatureStates.
Note: If you call a function in a standard .dll file that is installed with the product and the action is scheduled as deferred
(for the In-Script Execution property), the .dll file that you are calling must be the component’s key file.
A custom action that calls a function in a standard .dll file stored in the Binary table cannot be scheduled for deferred
execution.
DataType1=[PropertyName1]
DataType1 is of type void, STRING, BOOL, NUMBER, HWND, HANDLE, or POINTER. PropertyName1 is
the name of a property from the Property Manager.
If the return type is void, =[PropertyName1] is omitted.
DllName
Specify the name of the .dll file, without the dot or file extension.
FuncName
Enter the name of the function that you are calling.
in DataType2="Value"
This is the format for an argument that is a constant. DataType1 is of type STRING, BOOL, NUMBER,
HWND, HANDLE, or POINTER. Value is the data that you want to pass for this argument. The
constant’s data type is always preceded by in.
Direction DataType3=[PropertyName2]
This is the format for an argument that references a Windows Installer property’s value. Direction can
be in, inout, or out. For a discussion of these property types, see the Function Definition panel under the
argument’s source.
DataType3 can be of type STRING, BOOL, NUMBER, HWND, HANDLE, or POINTER. PropertyName2 is
the name of a property whose value will be passed to or set by the function, depending on the value of
Direction.
Example
For the custom action created in Example: Calling MessageBoxA in an Installation, the Target value
reads:
void User32::MessageBoxA(in HWND=0, in STRING=[MESSAGEPROP], in STRING=[CAPTIONPROP], in
NUMBER=1)
In this example, the data type is void, in HWND=0 represents a numeric value of 0, and MESSAGEPROP is a
property that contains a string that will be passed to the function MessageBoxA in User32.dll.
You specify that your custom action resides in a Windows Installer .dll file (custom action types 1 and 17)
by selecting Call a function in a Windows Installer dynamic-link library in the Custom Action
Wizard’s Action Type panel.
An alternative is to select Call a function in a standard dynamic link library in the Action Type
panel. In this case, InstallShield allows you to specify the function’s parameters.
Task There are three major steps involved in passing a parameter to a function in a .dll file written for Windows
Installer:
MessageBox(GetForegroundWindow( ),
szValue,
TEXT("Value of MYPROPERTY"), MB_OK | MB_ICONINFORMATION);
return ERROR_SUCCESS;
}
For more information, see MsiGetProperty in the Windows Installer Help Library.
If you use a C++ compiler to build your .dll file, ensure that the compiler does not change the function
names exported from the .dll file. With Microsoft Visual C++, for example, you can create a .def file that
specifies the function names to be exported from your .dll file. A typical .def (called MyActions.def) file
looks like the following:
LIBRARY MyActions
EXPORTS
MyActionName
For more information about function name decoration, see your compiler documentation.
1. In the View List under Behavior and Logic, click Property Manager.
2. Scroll to the bottom of the property grid and click the last row to add a new property.
3. In the Name column, type the name of the property that you would like to retrieve with
MsiGetProperty (MYPROPERTY, in this example).
4. In the Value column, type the value that you want to pass. For example, if you want to pass the URL
to your Web site, type http://www.mycompany.com.
1. In the Custom Wizard’s Action Type panel, select Call a function in a standard dynamic-link
library.
2. In the Function Definition panel, specify the parameters that you want InstallShield to pass to
the function.
Table 13-11: Settings for the Basic Information Panel in the Custom Action Wizard
Name Provide a meaningful name for your custom action. This name is used internally
in your product and is for identification purposes only.
Action Type
Table 13-12: Settings for the Action Type Panel in the Custom Action Wizard
Type Select the type of custom action that you want to create. For this example,
select Launch an executable.
Location The selection that you make depends on where the target executable file will be
during the installation. Because Notepad is on everyone’s machine, it is the
target for this custom action. Because Notepad is practically guaranteed to be
present in the target machine’s Windows or WINNT folder, you can point to it
using the Directory table. Therefore, select Stored in the Directory table.
Action Parameters
Table 13-13: Settings for the Action Parameters Panel in the Custom Action Wizard
Source Since you choose to launch an executable file stored in the Directory table,
you are given a list of choices that reflect all of your current entries in the
Directory table. One of these options is WindowsFolder. Choose this option
to point to Notepad without having to hard-code a path.
Target For this option, you need to enter the target file within the specified directory
from the Source option. Enter Notepad.exe and click the Next button to
continue.
Additional Options
Table 13-14: Settings for the Additional Options Panel in the Custom Action Wizard
Wait for the Select this option if you would like the installation to pause until the action has
action to finish completed. In the context of this example, the installation will remained paused
executing until Notepad is closed.
Table 13-14: Settings for the Additional Options Panel in the Custom Action Wizard (cont.)
Ignore custom If you do not want to retrieve a return code from the custom action—such as
action return success or failure—you can choose to ignore it.
code
Execution Select Always execute to ensure that your custom action launches every time
Scheduling that it is encountered.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. Right-click the Custom Actions explorer and click Custom Action Wizard. The Custom
Action Wizard opens.
3. On the Basic Information panel, specify a name and comment for your custom action and click
Next.
4. On the Action Type panel, in the Type list, select Launch an executable. In the Location list,
select Stored in the Directory table. The Directory table allows you to choose from predefined
folders, such as SystemFolder, which is where Msiexec.exe is located.
5. On the Action Parameters panel, browse for the executable file (Msiexec.exe) of that you are
launching. The Target box enables you to specify the name of the executable file that you would like
to launch, as well as any command-line parameters that you would like to pass to it. For example:
msiexec.exe /i "[SOURCEDIR]AnotherSetup\SecondSetup.msi" /qb
The first part of this entry, msiexec.exe, is the name of the executable file that you would like to
launch. The next section, /i "[SOURCEDIR]AnotherSetup\SecondSetup.msi", tells
Msiexec.exe which package to run. In this case, it is pointing to a file one folder below that of the
source folder of the initial installation. Finally, /qb tells the Windows Installer service to run the
installation with minimal user interface. Only a progress bar is displayed.
6. On the Additional Options panel, select the default options and click Next until you finish the
wizard.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. In the Sequences explorer, under the Installation sequence, expand the User Interface item.
The actions and dialogs that are scheduled for this sequence are listed.
3. Right-click CostFinalize and click Insert. The Insert Action dialog box opens.
4. Select the new custom action.
5. Click OK.
Next, verify that the installation package that you want to launch is located in the folder that you
specified in the Action Parameters panel, build your installation, and run it.
Note: A custom action that launches Msiexec.exe must be placed in the User Interface sequence, which means that the
custom action will not run if the end user runs the installation silently.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. In the Custom Actions explorer, right-click your custom action and click Export. The Export
into dialog box opens.
3. Browse to the location of an existing InstallShield project file (.ism file). It can be either an
installation project or a merge module project, but the file cannot be open in another instance of
InstallShield.
4. Click Open.
A copy of this custom action is added to the specified .ism file. If the other .ism file already has a custom
action of that name with different properties, the Resolve Conflict dialog box opens to offer you options
for resolving the conflicts.
Signature findme_sig
FileName FindMe.exe
Note that other fields in the Signature table enable you to specify optional version, size, date, and
language information.
There are four locator tables in which you can specify where Windows Installer should begin searching
for the file: CompLocator, RegLocator, IniLocator, and DrLocator. To search for a file in a
specific directory, use the DrLocator table. For example, to search for FindMe.exe in the user’s
Program Files directory, we add the following record to the DrLocator table.
Signature findme_sig
Parent
Path [ProgramFilesFolder]
Depth 2
After the AppSearch action runs, the public property LOCATION_OF_FINDME will contain the full
path to FindMe.exe on the end user’s system if it exists; if the file is not located, this property will be
undefined.
STRING svFoundFile;
begin
end;
The LaunchApp and LaunchAppAndWait functions launch an executable file. For example, the following
code launches a copy of Program.exe in the end user’s INSTALLDIR folder, returning execution to the
script when the end user closes the program’s window.
LaunchAppAndWait(INSTALLDIR ^ "Program.exe", "", WAIT);
Note: Deferred, commit, and rollback custom actions in Basic MSI and InstallScript MSI installations have access to only
some of the built-in Windows Installer properties: CustomActionData, ProductCode, and UserSID. If you want a custom
action to access any other properties (such as SUPPORTDIR) during deferred, commit, or rollback execution, you need
to pass them as CustomActionData. To learn more, see Accessing or Setting Windows Installer Properties Through
Deferred, Commit, and Rollback Custom Actions.
Project: Note that the value of the Windows Installer property SUPPORTDIR is not the same as the value of the
InstallScript system variable SUPPORTDIR.
nLength = MAX_PATH + 1;
MsiGetProperty(hMSI, "MYFILE", szMyFile, nLength);
In this example, the name of the support file that is being used is stored in the MYFILE property.
C++
In C++, you could use the following code:
UINT __stdcall ShowSupportdir(MSIHANDLE hInstall)
{
TCHAR szSupportDir[MAX_PATH + 1] = {'\0'};
DWORD dwBuff = sizeof(szSupportDir);
MsiGetProperty(hInstall,"SUPPORTDIR",szSupportDir,&dwBuff);
MessageBox(NULL,szSupportDir,"SUPPORTDIR is ...",MB_OK);
}
VBScript
In VBScript, you could use the following code:
dim strSupportDir
strSupportDir = Session.Property("SUPPORTDIR")
Deferred, commit, and rollback custom actions in Basic MSI and InstallScript MSI installations have
access to only some of the built-in Windows Installer properties: CustomActionData, ProductCode,
and UserSID. If you want a custom action to access any other properties during deferred, commit, or
rollback execution, you can pass them as CustomActionData. You can do so by scheduling an
immediate set-a-property type of custom action to set a property that matches the name of the custom
action. The value of this property is then available in the CustomActionData property within the
deferred, commit, or rollback custom action.
1. In the Custom Actions and Sequences view, create a set-a-property custom action (type 51)
called GetSUPPORTDIR . Configure the Property Name, Property Value, and Install Exec
Sequence settings for the custom action as follows, and leave all of the other settings blank.
• Property Name: DisplaySupportDir
• Property Value: [SUPPORTDIR]
• Install Exec Sequence: After InstallInitialize
2. In the InstallScript view, create a new function called DisplaySupportDir.
3. Add the following code to display a message box containing the value of SUPPORTDIR:
function DisplaySupportDir(hMSI)
STRING supportDirPath;
NUMBER supportDirPathBuffer;
begin
supportDirPathBuffer = MAX_PATH;
if(MsiGetProperty(hMSI, "CustomActionData", supportDirPath, supportDirPathBuffer) ==
ERROR_SUCCESS) then
SprintfBox(INFORMATION,"Deferred Execution","The value of SUPPORTDIR is
%s",supportDirPath);
SprintfBox(INFORMATION,"Deferred Execution","The value of InstallScript's SUPPORTDIR
is %s",SUPPORTDIR);
endif;
end;
4. In the Custom Actions and Sequences view, create an InstallScript custom action called
DisplaySupportDir. Configure the Function Name, In-Script Execution, and Install Exec
Sequence settings for the custom action as follows, and leave all of the other settings blank.
• Function Name: DisplaySupportDir
• In-Script Execution: Deferred Execution in System Context
• Install Exec Sequence: After GetSUPPORTDIR
SetupType = PropArray(2)
'Now do something with these variables...
An InstallScript entry-point function that returns the value ERROR_INSTALL_FAILURE will cause the
installation to exit.
• Set the property value before the OnMoving event, preferably in OnFirstUIBefore. After that, it is too late because the
installer has already built up its internal script information, which cannot be modified.
• Use all uppercase letters for your property name.
• If SYSTEM_DB_DIR exists in the Directory table, omit the backslash (\) after the right bracket (]) when making your
ODBC attribute settings. If you have defined it in the Property Manager, the backslash must be included.
For more information, see Session Object in the Windows Installer Help Library.
Defining Sequences
Project: In Basic MSI, transform, and Web projects, sequences also specify the order in which the dialogs are displayed.
In InstallScript MSI projects, the user-interface dialogs are defined in the InstallScript code, and the InstallScript engine
controls the user interface part of the installation.
The Custom Actions and Sequences view in InstallShield is where you define the sequences of your
project. The Sequences explorer in this view lists all of the actions and dialogs in your project in
chronological order, according to when they are launched during the applicable sequence. Each action
and dialog is given a number in the sequence, and Windows Installer runs the sequence from the lowest
number to the highest number.
Rather than having to manually provide a numeric value for every custom action and dialog that you add
to your project, you can use the Custom Actions and Sequences view to insert actions or dialogs into a
sequence or edit the sequence timeline. Refer to this section of the help for information about sequences.
Project: If you create a custom action or a custom dialog in a merge module, you need to first import that module into an
installation project and then add it to a sequence through the Custom Actions and Sequences view.
Installation Sequence
The installation sequence is the series of actions that are executed when the installation runs in the
default installation mode, such as when an end user double-clicks a new .msi file. These actions are
broken down into two types:
• User Interface
• Execute
Project: The User Interface dialogs described below are those for a Basic MSI project. For an InstallScript MSI project,
your InstallScript code performs the user interface of the installation.
An InstallScript MSI project automatically includes the ISVerifyScriptingRuntime custom action. For details, see
ISVerifyScriptingRuntime.
User Interface
The User Interface sequence contains all of the actions and dialogs needed to support a full user
interface. This sequence is skipped if an installation is run in silent mode.
For complete technical details about each standard action, see the Standard Actions Reference in the
Windows Installer Help Library.
ISSetupFilesExtract Custom action This custom action extracts any files that
you have added in the Support Files view.
For more information, see Using Support
Files.
Table 13-18: User-Interface Actions and Dialogs in the Installation Sequence (cont.)
Table 13-18: User-Interface Actions and Dialogs in the Installation Sequence (cont.)
ResolveSource Standard action Finds the location of the source and sets
the SourceDir property.
Table 13-18: User-Interface Actions and Dialogs in the Installation Sequence (cont.)
MaintenanceWelcome Dialog This dialog opens when the end user tries
to change a program’s installed features,
remove the program, reinstall the
program, run an installation for the second
time, or select the current product in Add
or Remove Programs.
ISSetupFilesCleanup Custom action This custom action appears when you add
a file in the Support Files view. For more
information, see Using Support Files.
Execute
The Execute sequence contains all of the actions that can change the machine’s state and do not rely
upon the user interface in order to function properly. These actions include file transfer, publishing
components and features, and registering COM servers. Most of the Execute sequence is skipped when
you run your installation in test mode, except for custom actions that have been inserted into the
sequence.
ISSetupFilesExtract Custom action This custom action extracts any files that
you have added in the Support Files view.
For more information, see Using Support
Files.
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
AllocateRegistrySpace Standard action The installer makes sure that the system
has at least as much free registry space
available as specified in the
AVAILABLEFREEREG property when it
performs this action.
StopServices Standard action The installer stops all services that you
specified in your Control NT Services
component. For more information, see
Controlling NT Services.
DeleteServices Standard action The installer removes all services that you
specified in your Control NT Services
component. For more information, see
Controlling NT Services.
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
UnregisterMIMEInfo Standard action This action queries the MIME table of the
current feature that is being uninstalled,
and unregisters the MIME information for
the servers found therein. This information
is created through the File Types
advanced setting.
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
CreateShortcuts Standard action This action creates the shortcuts that you
specified in the Shortcuts explorer in the
Shortcut view or the Setup Design view.
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
RegisterClassInfo Standard action This action registers all of the COM class
info that you specified in the COM
Registration advanced setting, or which
was extracted by the Component Wizard
or a component’s COM Extract at Build
setting.
RegisterMIMEInfo Standard action This action registers all of the MIME types
that you defined in the File Types
advanced setting that are linked to class
servers or extension servers marked for
installation.
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
StartServices Standard action The installer starts all services that you
specified your Control NT Services
component. For more information, see
Controlling NT Services.
RegisterProduct Standard action This action registers the product with the
installer and saves the installer database
on the target machine.
RemoveExistingProducts Standard action This action loops through all the product
codes listed in the Upgrade table and
removes those products.
Table 13-19: Execute Actions and Dialogs in the Installation Sequence (cont.)
ISSetupFilesCleanup Custom action This custom action appears when you add
a file in the Support Files view. For more
information, see Using Support Files.
Advertisement Sequence
The Advertisement sequence is the list of actions that occur when an end user launches your installation
with the /j command-line option for MsiExec.exe. The built-in actions in this sequence are described in
the table below.
User Interface
Validation rule ICE78 requires the Advertisement User Interface sequence to be empty.
Execute
The Execute sequence contains all the actions that do not rely upon the user interface in order to
function properly. These actions include file transfer, publishing components and features, and
registering COM servers.
For complete technical details about each standard action, see the Standard Actions Reference in the
Windows Installer Help Library.
RegisterMIMEInfo Standard action Registers all of the MIME types that are
defined in the File Types advanced setting
if its component is being advertised.
Administration Sequence
The Administration sequence is the list of actions that execute when a user launches your setup program
with the /a command-line option. The built-in actions and dialogs for this sequence are defined in the
tables below.
User Interface
The User Interface sequence contains all of the actions and dialogs needed to support a full user
interface. This sequence is skipped if an installation is run in silent mode.
Project: The User Interface actions described below are those for a Basic MSI project. For an InstallScript MSI project,
your InstallScript code performs the user interface of the installation.
For complete technical details about each standard action, see the Standard Actions Reference in the
Windows Installer Help Library.
Execute
The Execute sequence contains all the actions that do not rely upon the user interface in order to
function properly. These actions include file transfer, publishing components and features, and
registering COM servers.
InstallFiles Standard action The InstallFiles action copies all of the files
to the target machine if the feature that
those files belong to is slated for
installation. Only files that are associated
with components that are to be installed
locally will be copied to the target
machine.
Project: InstallScript custom actions are not supported in the User Interface sequence for InstallScript MSI projects.
Execute Sequence
The Execute sequence is executed after the User Interface sequence, unless your installation is run in
silent mode. The Execute sequence contains all the standard and custom actions that change the target
system. For example, file transfer is handled during the Execute sequence. Typically, this sequence is the
part of the installation where changes are made to the target machine.
Each sequence (Installation, Advertisement, and Administration) has different actions that occur in the
Execute sequence. This discrepancy is due to the fact that each of those sequences achieves different
goals. For example, the Installation sequence installs the product on the target machine. The
Advertisement sequence installs the product’s advertised shortcuts, file-type information, and COM-
server data on the target machine, but it does not transfer the product’s files until the end user selects
the shortcut, opens a registered document, or invokes an advertised COM server. As can be gathered
from the name of the sequence, the product is advertised.
Note: InstallShield does not provide any validation on your sequences. If an action is placed in a sequence where it cannot
function properly, an error will not occur until the installation is run.
Inserting an Action
1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. In the Sequences explorer, right-click the action or dialog that you want your action to follow and
click Insert. The Insert Action dialog box opens, providing a list of all the actions and dialogs that
can be added to the sequence.
3. In the list at the top of the dialog box, select the type of action that you want to insert.
4. In the box that shows a list of actions, select the action that you want to insert.
5. Click OK.
InstallShield also includes drag-and-drop support that enables you to drag and drop custom actions
from the Custom Actions explorer to a sequence in the Sequences explorer.
Task To insert a custom action into a sequence using the drag-and-drop method:
1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. Drag the custom action from the Custom Actions explorer to the appropriate location in a
sequence under the Sequences explorer. When you drop it, drop it onto the item that should be
directly before it in the sequence.
Note: A custom action cannot be called twice in the same sequence, since the custom action name is the key in the
CustomAction table. Therefore, you cannot insert a custom action to a sequence that already contains that custom
action.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. In the Sequences explorer, find the action that you want to copy.
3. Press and hold CTRL while dragging the custom action from one sequence to another sequence, and
drop it onto the action or dialog that should be directly before it.
Note: A custom action cannot be called twice in the same sequence, since the custom action name is the key in the
CustomAction table. Therefore, you cannot move or copy a custom action to a sequence that already contains that
custom action.
Dialogs and standard actions cannot be moved to a different type of sequence through a drag-and-drop operation.
Reordering a Sequence
The actions and dialogs in the Sequences explorer in the Custom Actions and Sequences view are
organized by chronological order, according to when they are launched. Each action and item also has a
number that identifies its location in the sequence in relation to other items’ sequence numbers. The
items are launched in order from the lowest number to the highest number.
When you add a dialog (to Basic MSI, MSI Database, Transform, or Web projects) or a custom action to
your project, you can specify when it should be launched by adding it to the appropriate place in a
sequence.
Task To change the order in which actions and dialogs in a sequence execute:
1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. Do one of the following:
• To sequence a new custom action, drag it from the Custom Actions explorer to the
appropriate location in a sequence under the Sequences explorer. When you drop it, drop it
onto the item that should be directly before it in the sequence.
• To move an action or a dialog to a different point in a sequence (or from one sequence to
another), drag it from the old location and drop it onto the item that should be directly before it
in the sequence.
Note: A custom action cannot be called twice in the same sequence, since the custom action name is the key in the
CustomAction table. Therefore, you cannot move or copy a custom action to a sequence that already contains that
custom action.
Dialogs and standard actions cannot be moved to a different type of sequence through a drag-and-drop operation.
If you change a custom action after adding it to a sequence, you do not need to reassociate it with that sequence. The
action that you put in the sequence is a pointer to the real action, and it is dynamically updated whenever you make
changes to the action in the Custom Actions and Sequences view.
Tip: You can also move actions and dialogs in the Sequences explorer using any of the following methods:
• Right-click the action or dialog and click Move Up or Move Down.
• Click the action or dialog and then press CTRL+SHIFT+UP ARROW or CTRL+SHIFT+DOWN ARROW.
• Change the position of the action or dialog by editing its Sequence Number setting, which is displayed in the grid on
the right when you click the action or dialog. To move a an action or dialog to an earlier point in a sequence, give it a
lower sequence number. To move it to a later point in the sequence, give it a higher sequence number.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. In the Sequences explorer, expand the sequence that contains the action that you want to remove.
3. Right-click the action and click Remove.
The action is removed from that sequence only, not from all sequences or from the project. You can
permanently remove an action from an installation project through the Custom Actions explorer in the
Custom Actions and Sequences view.
• A rollback can occur only during the Execute sequence and not at any point during the User
Interface sequence. Therefore, the rollback action must be placed after InstallInitialize and before
InstallFinalize in the Execute sequence.
• The rollback custom action must be sequenced before the action it rolls back. In all other instances,
the Windows Installer service runs through sequences from top to bottom—the lower the sequence
number, the sooner the action launches. In the rollback script, however, the service runs in the
opposite direction. Therefore, to ensure that your rollback action launches when needed, it should
be placed earlier in the sequence than the action it rolls back.
Table 13-23: Settings for Actions that Launch an .exe File in the .msi Package
Table 13-24: Settings for Actions that Launch an Installed .exe File
Table 13-25: Settings for Actions that Launch an .exe File that Is Already Installed
Table 13-26: Settings for Actions that Call a Function in a .dll File that is stored in the .msi Package
Table 13-27: Settings for Actions that Call a Function in a .dll File that Is Found in the System’s Path
Table 13-28: Settings for Actions that Call a Function in a .dll File that Is Already Installed
Table 13-29: Settings for Actions that Call a VBScript or JScript File that Is Installed with the Product
Table 13-30: Settings for Actions that Call a VBScript or JScript File that Is Stored in the Binary Table
Table 13-31:
InstallScript Code
InstallScript custom actions differ from JScript or VBScript custom actions because the source files for
InstallScript actions are always streamed into the .msi package. Therefore, the custom action can be
inserted into a sequence anywhere after the action that has 2 as its sequence number. This limitation
occurs because the script engine launches during sequence number 2. Therefore, if you call your script
before the script engine launches, the system is not able to process it.
If your custom action contains feature functions or setup type dialog functions, you must insert the
custom action after the CostInitialize, FileCost, and CostFinalize actions.
• Validation rule ICE12 requires any type-35 custom action (called Set a directory in the Custom
Action Wizard) to be sequenced after the standard CostFinalize action in the sequences.
• Similarly, ICE12 requires any type-51 custom action (called Set a property in the Custom Action
Wizard) that sets the value of a property found in the Directory table to be scheduled before the
standard CostFinalize action.
• Any custom action that sets a property should be scheduled for immediate execution.
Important: Nested installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft Corporation
recommends that you avoid using nested installations and nested-installation custom actions to install products that are
intended to be released to the public. To learn more, see Concurrent Installations on the MSDN Web site.
When you are sequencing a nested-installation custom action (called Launch another .msi package
in the Custom Action Wizard), you must place the action in the Execute sequence after the standard
CostFinalize action.
Additionally, ensure that the custom action launches before any of the files contained within the
installation are needed by your main installation, if applicable. For example, if you later want to launch
an executable file that is installed as part of the second .msi file, ensure that the package is installed
before you try to launch the executable file.
Note: If no matching product is installed on the target system, ISSetAllUsers does nothing.
1. Open the Support Files view (Basic MSI projects) or the Support Files/Billboards view
(InstallScript projects and InstallScript MSI projects).
2. In the Support Files explorer, click the item that should contain the support file that you are
adding.
3. Right-click anywhere in the Files pane and then click Insert Files. The Open dialog box opens.
4. Browse to the file that you want to include. To select multiple files, hold down the CTRL key while
clicking files.
5. Click OK.
InstallShield adds the file to the Files pane.
Tip: You can also drag files from Windows Explorer and drop them into the Files pane.
1. Add the file under the appropriate language item. (For more information, see Adding Support Files.)
If the file is to be associated with all project languages, add the file under the Language
Independent item.
2. Call the file in the szLicenseFile parameter in the SdLicense function in your script (for an
InstallScript MSI project) or in an InstallScript custom action (for a Basic MSI project).
1. Open the Support Files view (Basic MSI projects) or the Support Files/Billboards view
(InstallScript projects and InstallScript MSI projects).
2. In the Support Files explorer, click Disk1.
3. Right-click anywhere in the Files pane and then click Insert Files. The Open dialog box opens.
4. Browse to the file that you want to include. To select multiple files, hold down the CTRL key while
clicking files.
5. Click OK.
InstallShield adds the file to the Files pane.
1. Open the Support Files view (Basic MSI projects) or the Support Files/Billboards view
(InstallScript projects and InstallScript MSI projects).
2. In the Support Files explorer, click Disk1.
3. In the Files pane, right-click the file or folder and then click Delete.
For example, you might include a large redistributable file with your application. You may want end
users to be able to access the redistributable, but you do not want to include in the application
installation. If this is the case, this file can be placed in the last disk folder.
Task To remove a file or folder from the last disk image folder:
Tip: To specify the disk, run the Release Wizard; in the General Options panel, click the Other Disk Files button.
1. Open the Support Files view (Basic MSI projects) or the Support Files/Billboards view
(InstallScript projects and InstallScript MSI projects).
2. In the Support Files explorer, click the item that contains the support file that you want to delete.
3. In the Files pane, right-click the file or folder and then click Delete.
This section covers different features of InstallShield that enable you to define different aspects of the
end-user interface. Some of the topics in the “Defining the End-User Interface” section discuss how to
create and work with dialogs for the end-user interface of your installation. Others discuss topics such as
string tables, which let you localize your installation.
Common Operations
Some of the dialog operations are common to Basic MSI, InstallScript, and InstallScript MSI projects.
• Using the Dialog Wizard to Create a New Dialog
InstallScript For InstallScript projects, the specified user name, password, and group
information entered by the end user in the LogonInformation dialogs are stored in
the following global variables:
• IFX_NETAPI_USER_ACCOUNT
• IFX_NETAPI_PASSWORD
• IFX_NETAPI_GROUP
Basic MSI For Basic MSI projects, the specified user name, password, and group
information entered in the LogonInformation dialogs are stored in the following
properties:
• IS_NET_API_LOGON_USERNAME
• IS_NET_API_LOGON_GROUP
• IS_NET_API_LOGON_PASSWORD
InstallScript MSI For InstallScript MSI projects, the specified user account, group, and password
are stored in the following global variables and properties:
• IFX_NETAPI_USER_ACCOUNT
• IFX_NETAPI_GROUP
• IFX_NETAPI_PASSWORD
• IS_NET_API_LOGON_USERNAME
• IS_NET_API_LOGON_GROUP
• IS_NET_API_LOGON_PASSWORD
Task To add support for the LogonInformation dialogs in either an InstallScript or InstallScript MSI project:
1. Navigate to the location in your InstallScript code where you want to insert the LogonInformation
dialog set. In most situations, you will add it within OnFirstUIBefore. For example:
Dlg_SdLogon:
SdLogonUserInformation(szTitle, szMsg, szAccount, szPassword);
if (nResult = BACK) goto Dlg_SdWelcome;
2. In InstallScript MSI projects, add the following function so that the Windows Installer properties
are set to the same value as the InstallScript global variables. You can add it after calling
SdLogonUserInformation.
OnLogonUserSetMsiProperties();
3. On the Build menu, click Settings. The Settings dialog box opens.
4. Click the Compile/Link tab and enter the following path to your new library file (*.obl):
<ISProductFolder>Script\ISRT\lib\NetApiRT.obl
Note: You should enter the path to the new library file before the path to isrt.obl.
Once you have added the InstallScript code, build and run your installation. When the script is executed,
the appropriate dialogs are displayed.
If you are adding a static text field containing a placeholder, give the static text field a unique (to that
dialog) ID in the range of 701 through 799. IDs in the 701 through 799 range instruct InstallShield to
scan the static text field for the existence of the placeholders. If a placeholder is found, InstallShield
replaces it with the value of the corresponding system variables.
• In the Repository Items box, click the dialog that you want to add to your project.
• If the file for the dialog box (.isd file) that you want to import is not stored in the repository, click
the Browse button to select it.
4. Click OK.
InstallShield adds a copy for each supported language to your project.
Note: When you import a dialog, make sure that any string identifiers, properties, and actions referenced by the dialog
are present in the new installation project.
Resolving Conflicts
When you import a dialog, InstallShield checks to make sure that the name of the dialog and its controls
are unique—as required by Windows Installer. You cannot import a dialog with the same name as an
existing dialog because InstallShield assumes that you are trying to import an identical dialog.
If you try to import an .isd file that uses the names of controls or string identifiers that already exist in
your installation project, InstallShield asks how you want to resolve those conflicts. You can either
overwrite the existing values or skip the imported values in order to leave the existing ones.
Every attempt is made to preserve each dialog’s layout as much as possible. However, since some
information in the Dialog Editor has no counterpart in a resource editor, InstallShield exports the
resources as they appear in the Dialog Editor with the following exceptions:
Exception Description
String table entries All strings entries are resolved to the value of the default language.
Paths The paths, including any path variables, to any resources, such as text files or
bitmaps, are preserved to make it easier to import the dialog at a later point.
Selection trees A Windows Installer selection tree becomes a standard tree control in the .rc file.
Text style While the Dialog Editor maintains separate properties for font information (base
text style and text style) and maximum character length, these properties are
grouped together as they are in the Windows Installer tables.
Behavior Unlike .isd files, which contain complete copies of the dialog’s layout and
behavior, .rc files store only the resources.
Task Assuming again that you use Visual Studio, follow the steps below to build MyProject.rc into MyProject.dll:
1. Use the Resource Compiler (Rc.exe) to compile MyProject.rc into MyProject with the following
command-line statement:
rc MyProject.rc
2. Run the Incremental Linker (Link.exe) to build a .dll file with the following command:
link /DLL /NOENTRY /NODEFAULTLIB /MACHINE:iX86 /OUT:MyProject.dll MyProject.res
4. Click Open.
InstallShield adds each dialog to your project. Naming conflicts are resolved by adding a number to the
imported dialog to make it unique.
If an imported control displays text that is already found in the string table, InstallShield uses the
existing string table entry for the control’s Text property.
Note: When you are importing a dialog, ensure that any properties referenced by the dialog are present in the new
installation project.
Adding a dialog to a project does not mean that the dialog will be displayed during the installation run
time. For information on inserting the dialog into one or more of the installation’s sequences, see
Displaying Dialogs During Basic MSI Installations.
Even though dialogs can be exported to an .rc file, you must build the resources into a .dll file before you
can import them into InstallShield. For more information, see Exporting All Dialogs to an .rc File.
Note: Right-clicking a dialog in the Custom Actions and Sequences view and clicking Remove does not delete the dialog
from your project. It only removes it from that sequence.
In the above example, 12005 is the ISResourceId of this custom dialog, as specified in the Dialog table.
Custom dialog functions can then be called to manipulate the custom dialog to your needs. These
functions are documented in the InstallScript Language Reference.
Undoing Changes
• Press CTRL+Z.
Task To place an undone change back into effect, do one of the following:
• Press CTRL+Y.
Note: You cannot undo changes made to a string table entry through the Dialog Editor.
Task The first step in creating a custom dialog box is to lay out the controls used on the dialog:
You can use the Dialog Editor to edit a selected dialog’s controls. The InstallShield Dialog Editor
functions much in the same way as other resource editors.
Note: When an end user runs your installation on a Windows platform that uses a desktop display theme, the theme is
used to display your installation’s end-user dialogs.
• In the Dialogs view, click a dialog and then click Edit dialog layout in the dialog preview pane on
the right.
• In the Dialogs view, right-click a dialog and click Edit.
Note: For projects created in Microsoft Visual Studio, you can use the Toolbox to add controls.
• Check Box
• Push Button
• Edit Field
• Combo Box
• Text Area
• List Box
• Radio Button
• Bitmap
• Group Box
• Line
• Selection Tree
• Progress Bar
• List View
• Icon
• Custom
• The value for the Tab Index property of the bitmap must be lower than the value for the Tab
Index property of any controls that are to be placed on top of the bitmap. The easiest way to ensure
this is to set the bitmap control’s Tab Index property to 0.
• All controls—including the bitmap—must have their Tab Stop properties set to True.
1. On the Tools menu, click Options. The Options dialog box opens.
2. Click the Resources tab.
The Resources tab lists the locations of the compiler and linker.
Task To replace the resource compiler or resource linker with one that is already on your system:
1. On the Tools menu, click Options. The Options dialog box opens.
2. Click the Resources tab.
3. Click the Browse button next to the Resource compiler location box or the Resource linker
location box to navigate to the program file.
Before you edit a dialog’s behavior, you must first add it to your script to ensure that it is displayed to the
end user during the user interface portion of the installation. To edit the dialog’s behavior, modify the
dialog function’s parameters according to how you want the dialog to function during the user interface.
Refer to the specific help topic about the dialog function to learn about the function parameters. See the
following topic to view a list of available dialog functions for the predefined dialogs.
• Sd Dialog Box Functions
Selecting and editing an InstallScript project dialog in the Dialog Editor does not automatically place the
dialog in the end-user interface. Only the dialogs that are a part of the OnFirstUIBefore and OnFirstUIAfter
event handlers are included in the default script and displayed to end users.
Task To display a dialog to the end user as part of the installation’s user interface:
You can create a custom dialog in an InstallScript project by using both the Dialog Editor and the Script
Editor.
Task The general steps to add a custom dialog to your project are the following:
The next step in creating a custom dialog is to write an InstallScript function that processes the end
user’s interaction with the dialog controls.
1. Begin by creating a new InstallScript source file to contain the custom dialog code. Name the file
CustomDialog.rul.
Tip: To be able to use the dialog script in other projects, copy the .rul file to another location. In your other projects,
open the InstallScript view, right-click the Files item in the InstallScript explorer, and click Insert Script Files.
2. Inside CustomDialog.rul, place the prototype and implementation for your custom dialog function.
Add the following code to CustomDialog.rul.
prototype NUMBER CustomDialog( );
function NUMBER CustomDialog( )
begin
end;
3. When you compile your script, ensure that the main script Setup.rul includes the code for your
CustomDialog function, by inserting the following line near the top of Setup.rul:
#include "CustomDialog.rul"
4. In the CustomDialog.rul script, define the constants that store the numeric IDs of the controls that
you added to the dialog. If you copied the Back, Next, and Cancel buttons from a standard dialog,
you can add the following lines near the top of CustomDialog.rul:
// control identifiers
#define BUTTON_NEXT 1
#define BUTTON_BACK 12
#define BUTTON_CANCEL 9
In general, the numeric ID of a control on a dialog is the number listed in the control’s Control
Identifier property, displayed in the property list when you select the control in the Dialog Editor.
You need to define additional constants for every other control (for example, check box, edit field, or
list box) with which the end user can interact.
5. Your CustomDialog function loads the custom dialog into memory using the EzDefineDialog
function:
EzDefineDialog(
"CustomDialog", // nickname for dialog
ISUSER, // DLL containing the dialog’s resources
"CustomDialog", // name of dialog in Dialogs view
0); // numeric resource ID for dialog; not used here
Tip: The resource ID of a dialog is the dialog’s name, as it appears in the Dialog Editor. If you need to specify a
numeric resource ID, you can add a numeric ID to the ISResourceId column in the Dialog table for the custom dialog.
You can access the Dialog table in the Direct Editor.
6. Create a message loop in your script for the custom dialog. The message loop repeatedly calls the
function WaitOnDialog, which returns the numeric control ID for the control with which user
interacts with. A typical message loop appears as follows.
// repeatedly call WaitOnDialog until the user exits the dialog
// box with the Next, Back, or Cancel button
while (!bDone)
case CONTROL1:
// do something when user clicks CONTROL1
case CONTROL2:
// do something when user clicks CONTROL2
endswitch;
endwhile;
For example, CustomDialog currently contains Next, Back, and Cancel buttons. Its message loop
might appear as follows:
while (!bDone)
nControl = WaitOnDialog("CustomDialog");
switch (nControl)
case BUTTON_BACK:
// user clicked Back
nReturn = BUTTON_BACK;
bDone = TRUE;
case BUTTON_NEXT:
// user clicked Next
nReturn = BUTTON_NEXT;
bDone = TRUE;
case BUTTON_CANCEL:
// user clicked Cancel; ask user to verify cancellation
Do(EXIT);
endswitch;
endwhile;
7. When the end user exits the dialog by clicking Back or Next, you should remove the dialog from the
screen and from memory using EndDialog and ReleaseDialog:
EndDialog("CustomDialog");
ReleaseDialog("CustomDialog");
To use the dialog in the main script, add a call to the CustomDialog function in, for example, the
OnFirstUIBefore event handler of Setup.rul.
Dlg_SdWelcome:
szTitle = "";
szMsg = "";
nResult = SdWelcome(szTitle, szMsg);
Dlg_CustomDlg:
nResult = CustomDialog( );
if (nResult = BUTTON_BACK) goto Dlg_SdWelcome;
// etc.
If the end user clicks Back or Next, the script displays the previous or following dialog. If the user
clicks Cancel, the standard confirmation dialog (handled by the OnCanceling event handler) is
displayed.
Note: For information on implementing dialog control functionality, see Using InstallScript to Process Dialog Controls.
Special Messages
In addition to returning control identifiers, the WaitOnDialog function returns some special messages.
• Immediately before the dialog is displayed on the screen, WaitOnDialog returns the message constant
DLG_INIT. In the DLG_INIT case statement, you can set the default states of check boxes and radio
buttons, populate and set the current selection in a list box or combo box control, or set the initial
text of an edit field.
• If an error occurs, WaitOnDialog returns the constant DLG_ERR.
In InstallScript and InstallScript MSI installation projects, you use InstallScript to process the controls
that you add to your custom dialogs.
Note: InstallShield has a standard dialog called AskOptions. This dialog displays up to nine check boxes or radio buttons,
and therefore it is not necessary to create a custom dialog to display only check boxes to the end user.
As with push buttons, for each check box control that you add to a dialog, you generally add a #define
statement to your script that assigns a symbolic name to the numeric control ID. For example, if you add
a check box control to a custom dialog, the control’s numeric ID will appear in the Control Identifier
property of the control. If the numeric ID is 1302, you would add the following line to your script.
For most types of controls, InstallScript defines CtrlGet and CtrlSet functions with which you can get or
set the current state or data for a control. For example, you can get and set the current state of a check
box control using CtrlGetState and CtrlSetState. In the DLG_INIT case of your dialog’s message loop, you
can call CtrlSetState to set the initial selection state of the check box. The following code causes the check
box to appear initially selected.
case DLG_INIT:
CtrlSetState("CustomDialog", MYCHECKBOX1, BUTTON_CHECKED);
Similarly, you can add the following code outside the dialog’s message loop to detect the final selection
state of the check box.
nState = CtrlGetState("CustomDialog", MYCHECKBOX1);
if (nState = BUTTON_CHECKED) then
// check box selected
else
// check box unselected
endif;
Similarly, you can set the initial text stored in an Edit control (in the DLG_INIT block of the message-
loop’s switch statement) with CtrlSetText.
Tip: You can use the Password attribute of an edit control to hide the characters that the end user types into the edit
field. You can use the Number attribute to allow the end user to enter only numbers in the edit field.
STRING svDrive;
begin
nReturn = EzDefineDialog("CustomDialog", ISUSER, "CustomDialog", 0);
bDone = FALSE;
while (!bDone)
nControl = WaitOnDialog("CustomDialog");
switch (nControl)
case DLG_INIT:
CtrlSetState("CustomDialog", MYCHECKBOX1, BUTTON_CHECKED);
// associate the list with the combo box
CtrlSetList("CustomDialog", MYCOMBOBOX1, listDrives);
// get the first drive letter from the list...
ListGetFirstString(listDrives, svDrive);
// ...and make it the current selection
CtrlSetCurSel("CustomDialog", MYCOMBOBOX1, svDrive);
endswitch;
endwhile;
EndDialog("CustomDialog");
ReleaseDialog("CustomDialog");
return nReturn;
end;
List box and combo box controls have a Sorted property, which you can set to Yes to sort the contents of
the list controls by the items’ display names.
Tip: To use the same layout for the standard dialog banner and title, and for the Back, Next, and Cancel buttons, you can
copy these controls from another dialog and paste them onto your custom dialog.
Dialog Sampler
The Dialog Sampler is an InstallShield wizard that displays samples of all built-in dialogs as well as
dialogs called by script dialog (sd) functions in InstallScript and InstallScript MSI projects. You can
launch two different varieties of the Dialog Sampler.
On the Tools menu, point to InstallScript, and then click either Standard Dialog Sampler or
Skinned Dialog Sampler.
You can also launch these samplers using the shortcut in the InstallShield program folder on the
Programs menu.
Dialog Skins
Overview
Dialog skins enable you to display end-user dialogs with a different look and color scheme. Skinned
dialogs are slightly larger than standard dialogs, and the controls are located differently. For skinned
dialogs to display properly, the desktop area on the target machine must be at least 800 by 600 pixels
(or if large fonts are used, 1024 by 768 pixels), and the system must display at least 16-bit color.
Limitations
There are limitations when using dialog skins in your project:
• The location of the standard navigation buttons (Next, Cancel, Back, Finish) are the same for all
skins. The .skin file controls their position. Moving them in the Dialog Editor has no effect on the
run-time positioning. There are also some Browse buttons on a few dialogs (for example,
SdAskDestPath) that cannot be repositioned.
• If you add custom dialogs to your project, the new dialogs should be the same size as the other end-
user dialogs. If the custom dialogs are a different size, they may not be displayed correctly; for
example, the navigation buttons might not be visible to the end user during run time, due to the
positioning issue described above.
Note: If you want to specify a dialog skin for a custom dialog, you must set the skin before creating the custom dialog in
the Dialog Editor in order for the skin to appear properly.
You can use a dialog skin to change the look of the end-user dialogs in your installation. You can specify
one skin per installation project. All of the dialogs in your project are displayed using the selected skin.
Note: If you want to specify a dialog skin for a custom dialog, you must set the skin before creating the custom dialog in
the Dialog Editor in order for the skin to appear properly.
4. To select a displayed skin, click Select in the preview pane. A red check mark appears on the
selected skin’s icon in the Dialogs explorer.
All of the dialog skins use .gif files for the fade graphic, with the exception of the Blue skin. The Blue skin
uses a .bmp file, which results in a larger file size. The Blue skin’s appearance on a 16-bit color system is
not as clean as the other colors when a .gif file is used. If you want to use a Blue skin that supports 16-bit
color systems and file size is not an issue, select the Blue option. For a smaller file size, select the BlueTC
(True Color) option, which uses a .gif file for the graphic.
Task The process of creating a new dialog and displaying it in your installation can be broken down into the
following tasks:
Project: When you create a dialog in a merge module, you cannot insert it into a sequence until you associate that module
with an installation project.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. In the Sequences explorer, expand one of the two high-level sequences in which dialogs are usually
displayed—Installation, Advertisement, or Administration—to view its User Interface
sequence.
3. Expand the User Interface sequence to see how the existing actions, dialogs, and custom actions
are ordered.
4. Right-click the existing action or dialog that you want your dialog to follow in the sequence, and then
click Insert. The Insert Action dialog box opens.
5. In the list, select Dialogs.
6. Select your new dialog from the list of dialogs.
7. Click OK.
When your installation runs with a full user interface (determined by the /q command-line parameter)
and all conditions are met for this dialog, it will be displayed within the selected sequences.
While InstallShield lets you insert a dialog into an Execute sequence, doing so violates ICE13.
Task For example, to display a WelcomeBitmap dialog after the WelcomeInstallation dialog:
8. Type 1 for the condition to ensure that the dialog is created under any circumstance.
Note: If the WelcomeInstallation dialog had launched a different dialog from the Next button, you would repeat the above
procedure for the WelcomeBitmap’s Next button to show the next dialog.
To learn about viewing your new dialog in the Custom Actions and Sequences view, see Viewing End-
User Dialog Order in the Custom Actions and Sequences view (Basic MSI Projects).
AddLocal String specifying the name of a feature Sets the specified feature to be run
or ALL to specify all features. locally.
AddSource String specifying the name of a feature Sets the specified feature to be run
or ALL to specify all features. from the source medium.
CheckExistingTargetPath Name of the property that contains the Verifies that the specified path can be
path. You can either select this written to. If the path is not writable,
property from the list or enter the the installer automatically blocks any
name manually. If the property is other control events associated with
indirect, square brackets are required. the current control.
CheckTargetPath Property name containing the desired Causes the installer to verify the
path. specified path. If the path is not
writable, the installer automatically
blocks any other control events
associated with the current control.
DoAction String name of the custom action you Causes a custom action to launch
would like to call. The Argument when the selected control is activated.
property contains a list of all the
custom actions in your project.
EnableRollback Boolean: True enables rollback, False Used to turn rollback capabilities off
disables it. and on.
NewDialog String name of the dialog you would Closes the current dialog box, and
like to launch. The Argument property opens the dialog box specified in the
contains a list of all dialogs associated Argument property.
with your installation. You can choose
one of these dialogs, or type in the
name of a yet-to-be-created dialog.
Reinstall String specifying the name of a feature Forces the installer to reinstall the
or ALL to specify all features. specified feature or features.
Remove String specifying the name of a feature The installer is notified of features
or ALL to specify all features. marked for removal. The current
dialog is still displayed.
SelectionBrowse Name of dialog to be spawned. The Causes the current dialog to close and
Argument property contains a list of all opens the dialog specified in the
dialogs associated with your Argument property. This information is
installation. You can choose one of published by the SelectionTree
these dialogs, or type in the name of a control.
yet-to-be-created dialog.
SetTargetPath Property name containing the desired Causes the installer to set and check
path. the selected path. If the path is not
writable, the installer stops further
control events associated with the
current control.
SpawnDialog String name of the dialog that you Launches the dialog specified in the
would like to spawn. The Argument Argument property as a modal dialog,
property contains a list of all dialogs without closing the current dialog.
associated with your installation. You
can choose one of these dialogs, or
type in the name of a yet-to-be-created
dialog.
SpawnWaitDialog String name of the dialog you would Launches the dialog specified in the
like to display. The Argument property Argument property.
contains a list of all dialogs associated
with your installation. You can choose
one of these dialogs, or type in the
name of a yet-to-be-created dialog.
Subscriptions
The Windows Installer service provides volumes of information to the installation during the run time.
One of the most useful ways to gather information during installation is to use subscriptions. To
subscribe to something is commonly defined as entering one’s name for a publication or service. In
Windows Installer terms, actions generally publish information, and dialog controls generally subscribe
to information.
Progress Bars
The best example of this relationship centers around progress bars. The InstallFiles action publishes
information on the percentage of files moved and the percentage remaining to be moved. When a
progress bar subscribes to this information, it is able to accurately display the progress of the
installation’s file transfer process.
The Windows Installer service tracks progress through what are called ticks. When your progress bar
subscribes to this information, it is passed the ticksSoFar and totalTicks values. The progress bar
uses this information to display the total progress of the installation.
Other Uses
Subscriptions are not used only for progress bars. You might have a custom action that validates a serial
number as part of your installation. This action could publish the failure or success of validation. On a
dialog, you could have a Next button that subscribes to this information. If the action publishes the
failure of the validation, the button remains disabled. If the action publishes success, the button is
enabled.
Tip: You can also add a dialog by importing one from another project.
Note: When an end user runs your installation on a Windows platform that uses a desktop display theme, the theme is
used to display your installation’s end-user dialogs.
The Dialogs view manages versions of the dialog for each of your project’s supported languages. You
must select a language-specific version in order to edit the layout. These versions remain identical
except for changes you make to a control’s size. For more information, see Modifying Dialogs for Each
Language.
• Select the language-specific version of the dialog under the dialog’s name in the Dialogs view.
• Select the dialog’s name in the Dialogs view. In the pane to the right under the Action Items
heading, select a language from the list and click the Edit this dialog layout link.
• In the Custom Actions and Sequences view, right-click the dialog and click Edit layout.
• In the Custom Actions and Sequences view, click the name of the dialog whose behavior you
want to modify. Then, click the Edit dialog layout link in the Action Items section of the right
pane. If you have written your installation to run in more than one language, you must select the
language you want to edit from the list.
The Dialog Editor opens in the right pane of the Dialogs view. If you need more space, you can move the
property sheet so that it is no longer docked inside the editor.
Tip: For projects created in Microsoft Visual Studio, you can use the Toolbox to add controls.
• Dialog
• Check Box
• Push Button
• Edit Field
• Combo Box
• Text Area
• List Box
• Radio Button
• Bitmap
• Group Box
• Billboard
• Line
• Selection Tree
• Progress Bar
• List View
• Scrollable Text
• Icon
• Directory List
• Directory Combo
• Masked Edit
• Path Edit
• The value for the Tab Index property of the bitmap must be lower than the value for the Tab
Index property of any controls that are to be placed on top of the bitmap. The easiest way to ensure
this is to set the bitmap control’s Tab Index property to 0.
• All controls—including the bitmap—must have their Tab Stop properties set to True.
• In the Dialogs view, click the name of the dialog whose behavior you want to modify. Then, click
the Edit dialog behavior link in the Action Items section of the right pane.
• Double-click the dialog in the Dialogs view to expose its Behavior and language-specific items.
Click the Behavior item.
• In the Custom Actions and Sequences view, right-click the dialog and click Edit behavior.
• In the Custom Actions and Sequences view, click the name of the dialog whose behavior you
want to modify. Then, click the Edit dialog behavior link in the Action Items section of the right
pane.
The first thing to do when you use the Behavior Editor is to select a control. All of the properties that you
set in the editor apply to the selected control.
A dialog’s behavior includes the following three areas:
• Events that an end user interacting with the control will trigger
Examples
The control event below dismisses the present dialog and shows the Welcome dialog only when the
product is first installed:
Table 14-4: Sample Settings for a Control Event that Shows the Welcome Dialog Under Certain Circumstances
The following event launches an InstallScript custom action every time that the control is clicked:
Table 14-5: Sample Settings for a Control Event that Launches an InstallScript Custom Action Each Time that the Control
Is Clicked
DoAction MyScriptCustomAction 1
5. Click the Argument column. Many of the events have a corresponding argument list that is
populated with likely values. For example, if your event was NewDialog, the Arguments field will
contain a list of all of the dialogs in your project. Select the appropriate argument. If your event was
a property name, specify the value you want to assign to the property. Empty curly braces {} give it a
null value.
6. Specify any condition that you want to check before the event is triggered. Set the condition to 1 if
you want to have the installer trigger the event under any circumstance.
Task To do this:
3. Place a new push button on this dialog. Provide a name and display text for the push button.
4. Select the Behavior view for this dialog. In this view, you can define what happens when your new
button is pushed.
5. In the list of controls, select your new button. The button’s events are listed in the right pane.
6. In the Action field, select DoAction.
7. In the Argument field, select the custom action.
8. Add a condition, if necessary.
Build and test your installation to ensure that it works as you planned.
Viewing End-User Dialog Order in the Custom Actions and Sequences view
(Basic MSI Projects)
Project: This information applies to Basic MSI projects. To view the order of your end-user dialogs in an InstallScript
project or an InstallScript MSI project, use the InstallScript view to review your script.
In the Custom Actions and Sequences view, you can view primary and next dialogs in the order in which
they appear to the end user during the run time of your installation. Primary dialogs are top-level dialogs
that have been inserted into the installation sequence. You can change the order of a primary dialog
within the Custom Actions and Sequences view.
Next dialogs are dialogs that are triggered by the action of a previous dialog’s Next button control events.
Although you can view next dialogs in the Custom Actions and Sequences view, they are not a part of the
installation sequence, and you cannot change their order in the Custom Actions and Sequences view. To
change the order of a next dialog, you must edit the dialog’s behavior in the Behavior editor.
Refresh
After you have edited a next dialog’s behavior or layout and returned to the Custom Actions and
Sequences view, you can select Refresh from the context menu to refresh the dialog sequence view. This
option is available only for primary dialogs.
Edit Behavior
Task To move to the Dialog Behavior Editor from within the Sequences explorer in the Custom Actions and
Sequences view, do either of the following:
• Right-click the next dialog that you want to edit and click Edit Behavior.
• Click the name of the dialog that you want to edit. Then, in the Action Items section of the right
pane, click Edit dialog behavior.
For more information, see Editing Dialog Behavior in Basic MSI Projects.
Edit Layout
Task To move to the Dialog Layout Editor from within the Sequences explorer in the Custom Actions and
Sequences view, do either of the following:
• Right-click the next dialog that you want to edit and click Edit Layout.
• Click the name of the dialog that you want to edit. Then, in the Action Items section of the right
pane, click Edit dialog layout.If you have written your installation in more than one language, you
must select the appropriate language in the list.
For more information, see Editing Dialog Layout in Basic MSI Projects.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The Custom Setup dialog has a sophisticated end-user interface that is tightly integrated with
information about the target system, the features in your installation, and Windows Installer installation
options. It provides the end user with the most control over the installation.
Many of the options and information it offers are determined by the feature properties that you set in
your setup design, as described below.
Advertisement Option
Feature advertisement enables files to be installed on demand after the installation has initially run. In
the Custom Setup dialog, when end users click a feature, they can specify that they want it installed later
by selecting the Will be installed when required option.
However, that default option is present only if the you chose None or Favor Advertise for the feature’s
Advertisement property. You can disable the option to advertise by setting the property to Disallow
Advertise.
Hiding Features
When you set a feature’s Display property to Not Visible, the end user cannot see the feature or its
subfeatures in the Custom Setup dialog and therefore cannot change any of its installation options.
Option Description
Visible and Collapsed The feature is displayed in the Custom Setup dialog with its subfeatures collapsed
by default.
Visible and Expanded The feature is displayed in the Custom Setup dialog with its subfeatures expanded
by default.
For a complete discussion of the factors that affect where a feature is installed, see Setting a Destination
Folder for the Feature’s Files.
Naming Features
Specify a different name to appear in the Custom Setup dialog by setting its Display Name.
Dialog Themes
Note: InstallShield does not currently let you create your own dialog themes. However, InstallShield includes many
themes. For more information, see Available Themes and Corresponding Dialog Sizes.
Task To preview how a dialog in your project looks with the selected theme:
Tip: If you switch from one of the wide-style themes to a standard-width theme, the positions of any controls that are
placed along the far left or far right sides of the dialog may change.
If you want to change the theme for your project and you also want to add a custom exterior dialog, change the theme
first, and then add the custom exterior dialog. Otherwise, the dialog may not appear properly.
Tip: You can also change the theme by clicking a button: In the Dialogs explorer, click the theme that you want to use.
Then, in the right pane, click the Select button.
Task To change the theme after you have added a custom exterior dialog to your project:
1. Close InstallShield.
2. In the InstallShield Program Files folder, find the .theme file for the theme that you want your
dialogs to use. The default location is:
C:\Program Files\Macrovision\IS2008\Support\Themes
3. Open the .theme file in a text editor such as Notepad. For example, if you want to use the Global
theme, open the Global.theme file.
4. In the <Include> and <Exclude> sections of the file, add the following line:
<Name>NameOfDialog</Name>
• InstallWelcome
• MaintenanceWelcome
• PatchWelcome
• SetupCompleteError
• SetupCompleteSuccess
• SetupInitialization
• SetupInterrupted
• SetupResume
• SplashBitmap
Project: Some of the themes are available in both the Premier and Professional editions of InstallShield, and some are
available in only the Premier edition.
Some of the themes set the size of the dialogs to a standard width and height: 374×266. The wide themes
set the dialog size to 584×274. The following table shows the size of each dialog, plus which editions of
InstallShield contain the theme.
Figure 14-2: Sample Exterior Dialog with the Circle Theme (Wide)
Figure 14-3: Sample Interior Dialog with the Circle Theme (Wide)
To learn how to add your company or product logo to the exterior dialogs, see Adding a Logo or Other
Image to the Exterior Dialogs.
Classic Theme
Following are sample exterior and interior dialogs with the Classic Theme.
Following are sample exterior and interior dialogs with the Cooperation Theme (Wide).
Figure 14-6: Sample Exterior Dialog with the Cooperation Theme (Wide)
Figure 14-7: Sample Interior Dialog with the Cooperation Theme (Wide)
Following are sample exterior and interior dialogs with the Filmstrip Theme (Wide).
Figure 14-8: Sample Exterior Dialog with the Filmstrip Theme (Wide)
Figure 14-9: Sample Interior Dialog with the Filmstrip Theme (Wide)
Global Theme
Following are sample exterior and interior dialogs with the Global Theme.
Figure 14-12: Sample Exterior Dialog with the InstallShield Blue Theme
Figure 14-13: Sample Interior Dialog with the InstallShield Blue Theme
Figure 14-14: Sample Exterior Dialog with the InstallShield Blue Theme (Wide)
Figure 14-15: Sample Interior Dialog with the InstallShield Blue Theme (Wide)
Following are sample exterior and interior dialogs with the InstallShield Silver Theme.
Figure 14-16: Sample Exterior Dialog with the InstallShield Silver Theme
Figure 14-17: Sample Interior Dialog with the InstallShield Silver Theme
Monitor Theme
Following are sample exterior and interior dialogs with the Monitor Theme.
To learn how to add your company or product logo to the exterior dialogs, see Adding a Logo or Other
Image to the Exterior Dialogs.
Following are sample exterior and interior dialogs with the Pastel Wheat Theme.
Figure 14-20: Sample Exterior Dialog with the Pastel Wheat Theme
Figure 14-21: Sample Interior Dialog with the Pastel Wheat Theme
Following are sample exterior and interior dialogs with the Theater Theme (Wide).
Figure 14-22: Sample Exterior Dialog with the Theater Theme (Wide)
Figure 14-23: Sample Interior Dialog with the Theater Theme (Wide)
To learn how to add your company or product logo to the exterior dialogs, see Adding a Logo or Other
Image to the Exterior Dialogs.
• Pressing PAGE DOWN when the scrollable EULA control has focus.
• Pressing CTRL+PAGE DOWN when the scrollable EULA control has focus.
• Pressing the DOWN ARROW key when the scrollable EULA control has focus.
Task To require end users to reach the end of the EULA text in the scrollable EULA control:
1. Add to your project a new MSI DLL custom action called WatchScroll:
a. In the View List under Behavior and Logic, click Custom Actions and Sequences.
b. Right-click the Custom Actions explorer, point to New MSI DLL, and then click Stored in
Binary table. InstallShield adds a new custom action called NewCustomActionN, where N is a
successive number.
c. Change the name of the custom action to WatchScroll.
d. In the pane on the right, configure the following settings for this custom action:
• Event: DoAction
• Argument: WatchScroll
1. Create a button control in the dialog and optionally set its Text property to &Print. For details, see
Editing Dialog Layout in Basic MSI Projects.
2. Add a DoAction event to the Print button, and in the event’s Argument field, select ISPrint. For
details, see Triggering Control Events in Basic MSI Dialogs.
3. Modify the value of IS_PRINT_DIALOG from the events of the Back and Next buttons of the
dialog and its next and previous dialogs:
a. Determine which dialog is displayed before the dialog to which you are adding a Print button.
You can do this by either checking the argument of the NewDialog event for the dialog’s Back
button, or viewing next dialog order in the expanded Custom Actions and Sequences view.
b. Add an [IS_PRINT_DIALOG] event to that previous dialog’s Next button, and set its argument
as the name of the dialog to which you are adding a Print button.
c. If a Print button is included on any dialog that is displayed after the dialog to which you are
adding a Print button, do the following:
i. Determine which dialog is displayed after the dialog to which you are adding a Print button.
You can do this by either checking the argument of the NewDialog event for the dialog’s
Next button, or viewing the next dialog order in the expanded Custom Actions and
Sequences view.
ii. Add an [IS_PRINT_DIALOG] event to that next dialog’s Back button, and set its
argument to the name of the dialog to which you are adding a Print button.
If the next dialog does not have a Print button, or if it is the LicenseAgreement dialog, add an
[IS_PRINT_DIALOG] event to the Next button of the dialog to which you are adding a Print
button, and set the event’s argument to LicenseAgreement.
d. If a Print button is included on any dialog that is displayed before the dialog to which you are
adding a Print button, and the previous dialog does not have a Print button or it is the
LicenseAgreement dialog, add an [IS_PRINT_DIALOG] event to the Back button of the
dialog to which you are adding a Print button, and set the event’s argument to
LicenseAgreement.
Task To add a Print button to an existing project that was created with InstallShield DevStudio 9.0 or earlier:
d. In the Action Parameters panel, click the Browse button and browse to the file
SetAllUsers.dll in the InstallShield folder’s Redist\Language Independent\i386 subfolder. Click
Open. The Path Variable Recommendation dialog box opens.
e. Select the Use the following path variable-based folder representation for the
source folder option, and then in the list, select
<ISProductFolder>\redist\language independent\i386. Click OK.
Note: If the ISPrint custom action is executed by a control event, the custom action’s logging information cannot be
recorded to the installer log in the usual manner (because of a Windows Installer limitation); the information is logged to
the values of properties that have the form ISPrintLogmNoten.
Windows Logo Guideline: Restarting the system after an installation is inconvenient for end users. One of the Certified for
Windows Vista program requirements is that all installations must contain an option that enables end users to
automatically close applications and attempt to restart them after the installation is complete.
To support this requirement, all Basic MSI projects include the MsiRMFilesInUse dialog by default. An
installation displays the MsiRMFilesInUse dialog on a Windows Vista system if one or more files that
need to be updated are currently in use during the installation. The dialog contains two options to allow
end users to specify how to proceed:
• End users can choose to have the installation close the applications that are using those files and
then attempt to restart the applications after the installation is complete.
• End users can avoid closing the applications. A reboot will be required at the end of the installation.
For the best end-user experience, your application should be instrumented to use the Restart Manager
API; doing so allows the Restart Manager to effectively pause and resume your application exactly where
the end user left it. For detailed information, see About Restart Manager and the other Restart Manager
documentation on the MSDN Web site.
Dialog Controls
Whether your dialog is part of a Basic MSI or InstallScript MSI installation project, you can use many of
the same controls to modify the layout of your predefined and user-defined dialogs.
• Check Box
• Combo Box
• Dialog
• Edit Field
• Group Box
• Icon
• Line
• List Box
• List View
• Progress Bar
• Push Button
• Radio Button
• Selection Tree
• Text Area
• Directory Combo
• Directory List
• Masked Edit
• Path Edit
• Scrollable Text
Billboard Properties
Project: Billboard controls are available for use only in Basic MSI installation projects. The Billboard properties described
below do not refer to the properties of billboards that can be displayed in InstallScript and InstallScript MSI installations; to
learn more about this type of billboard, see Displaying Billboards.
A billboard is used to display data that can be updated in response to control events. Billboards can
contain other controls for displaying this information, but they must be static controls—including text,
bitmaps, and icons—that are not linked to a Windows Installer property. You can use a billboard, for
example, to display the progress of a protracted custom action.
Billboards are not fully supported in the Dialog Editor. You must go into the Direct Editor and modify
the Billboard and BBControl tables to have the billboard interact with Windows Installer actions and
display other controls.
Each billboard control has the following properties to specify how it is displayed.
Property Description
Name Enter a name for this billboard. The name must be unique among all of the
controls in your project.
Base Text Style This font style is used for the billboard’s label if you specify nothing for the Text
Style property.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the
cancel control has the same effect as pressing the ESC key or clicking the Close
button on the title bar. The Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help This property is reserved for future use. Windows Installer does not currently
support launching context-sensitive help topics from the installation.
Control Identifier This field contains a numeric identifier for the control that is unique within the
dialog. This identifier is the same as a resource identifier in Visual C++. You
should not change the control identifiers for any of the controls included with a
dialog by default.
Default Select True if this is the only control on the dialog that you want to be the default
control, which means that it will be activated when the end user presses the Enter
key. The Next or OK button is usually the default control.
Enabled True means that this control is available (the end user can interact with it). False
means that it is not available (grayed out).
Height Height of the billboard in installer units, which are defined as 1/12 of the height of
the system font.
Left Distance from the left edge of the dialog to the start of the billboard in installer
units.
Property Description
Sunken Set this property to True to give the billboard’s edges a recessed, three-
dimensional appearance. If this property is False, this control appears as a typical
control field.
Tab Index Provide an integer, starting with 0 (zero) that—along with the other controls on
this dialog and excluding controls such as static text—determines the order in
which each control area will receive focus when the end user presses the TAB key.
Tab Stop The tab stop indicates whether this control area will receive focus within the tab
order.
Text This property holds the text that will be used for the initial value of the billboard’s
control (see the BBControl table). Since the text is language specific, this value is
always associated with a string ID. Editing the value in the property sheet changes
the string ID’s value for the current language.
When you click the Text value to edit it, an ellipsis button (...) appears to allow you
to select a string ID and edit the default language’s string table.
If the billboard’s control contains a bitmap or icon, then this value must be a
foreign key into the Binary table to the file that is initially displayed on the control.
Text Style Select the font style, size, and color (if available) in which you want the billboard’s
label to be displayed. Leaving the value as <Default> displays the font contained
in the DefaultUIFont property.
Tooltip This property holds the text that will be displayed when the mouse hovers over the
control. Since the text is language specific, this value is always associated with a
string ID. Editing the value in the property sheet changes the string ID’s value for
the current language.
Top Distance from the top of the dialog to the top of the billboard in installer units.
Visible True means that the billboard control is visible, and False means that it is hidden.
You can also make the billboard visible by editing its condition in the Behavior
editor.
Bitmap Properties
Each bitmap control has the following properties to specify how it is displayed.
Name Basic MSI, Enter a name for this bitmap. The name must be unique among all of the
InstallScript, controls in your project.
InstallScript MSI,
InstallScript Object
Cancel Basic MSI, Select True if this is the only control on the dialog that will dismiss it.
InstallScript, Clicking the cancel control has the same effect as pressing the ESC key or
InstallScript MSI, clicking the Close button on the title bar. The Cancel or Finish button is
InstallScript Object usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript, the dialog. This identifier is the same as a resource identifier in Visual C++.
InstallScript MSI, You should not change the control identifiers for any of the controls
InstallScript Object included with a dialog by default.
Default Basic MSI, Select True if this is the only control on the dialog that you want to be the
InstallScript, default control, which means that it will be activated when the end user
InstallScript MSI, presses the Enter key. The Next or OK button is usually the default control.
InstallScript Object
Enabled Basic MSI True means that this control is available (the end user can interact with it).
False means that it is not available (grayed out).
File Name Basic MSI, The icon or bitmap file must be stored as a binary resource inside the
InstallScript, Windows Installer package. Enter the path to this file so that InstallShield
InstallScript MSI, can include it in your release.
InstallScript Object
Once you click the File Name value to edit it, an ellipsis button (...) appears
to allow you either to browse to the file or to select the string ID that
contains the path and file name. In fact, the value for File Name is always
stored in a string table entry so that you can easily make language-specific
changes to the dialog.
Height Basic MSI, Height of the control area in nstaller units, which are defined as 1/12 of the
InstallScript, height of the system font.
InstallScript MSI,
InstallScript Object
Left Basic MSI, Distance from the left edge of the dialog to the start of the control area in
InstallScript, installer units.
InstallScript MSI,
InstallScript Object
Other Window Basic MSI, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript,
InstallScript MSI,
InstallScript Object
Stretch to Fit Basic MSI Selecting True causes the image to be resized to fill the area of the control.
A value of False makes the bitmap centered if smaller than the control or
cropped if larger.
Sunken Basic MSI, False leaves this control looking like a typical bitmap image. Set this
InstallScript, property to True to give the control area’s edges a recessed, three-
InstallScript MSI, dimensional appearance.
InstallScript Object
Tab Index Basic MSI, Provide an integer, starting with 0 (zero) that, along with the other controls
InstallScript, on this dialog, excluding controls such as static text, determines the order
InstallScript MSI, in which each one will receive focus when the end user presses the Tab
InstallScript Object button.
Tab Stop Basic MSI, The tab stop indicates whether this control area will receive focus within the
InstallScript, tab order.
InstallScript MSI,
InstallScript Object
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet changes
the string ID’s value for the current language.
Top Basic MSI, Distance from the top of the dialog to the top of the control area in installer
InstallScript, units.
InstallScript MSI,
InstallScript Object
Visible Basic MSI, True means that the bitmap control is visible, and False that it is hidden. You
InstallScript, can also make it visible by editing its condition in the Behavior editor.
InstallScript MSI,
InstallScript Object
Project: (Windows Installer based projects only) When you first draw a check box onto a dialog, InstallShield prompts for
the name of a single Windows Installer property. The name that you enter is used as the value for Property, below, which
contains the value entered into the edit field by the end user.
Name Basic MSI, InstallScript, Enter a name for this check box. The name must be unique among all of the
InstallScript MSI, controls in your project.
InstallScript Object
Base Text Basic MSI This font style is used for the check box label if you specify nothing for the
Style Text Style property.
This property has no effect on a check box with an image for a label. If it is
read-only, then you must select Text for the Control Style property before
specifying the style.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key or
InstallScript Object clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual C++.
InstallScript Object You should not change the control identifiers for any of the controls
included with a dialog by default.
Control Style Basic MSI, InstallScript, Specify whether this check box will be marked with a text label, an icon, or
InstallScript MSI, a bitmap.
InstallScript Object
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default control.
Enabled Basic MSI, InstallScript, True means that this control is available (the end user can interact with it).
InstallScript MSI, False means that it is not available (grayed out).
InstallScript Object
File Name Basic MSI, InstallScript, Check boxes that display an icon or a bitmap file must have the file stored
InstallScript MSI, as a binary resource inside the Windows Installer package. Enter the path
InstallScript Object to this file so that InstallShield can include it in your release.
Once you click the File Name value to edit it, an ellipsis button (...) appears
to allow you either to browse to the file or to select the string ID that
contains the path and file name. In fact, the value for File Name is always
stored in a string table entry so that you can easily make language-specific
changes to the dialog.
This property has no effect on a check box with a text label. If it is read-
only, then you must select either Bitmap or Icon for the Control Style
property before browsing to the file.
Height Basic MSI, InstallScript, Height of the check box in installer units, which are defined as 1/12 of the
InstallScript MSI, height of the system font.
InstallScript Object
Icon Size Basic MSI, InstallScript, Assuming that your icon file has more than one resource, specify the size
InstallScript MSI, of the image that you want to use for the push button. The Use first image
InstallScript Object option causes the first image in the file to be displayed and makes it stretch
to fit the size of the control, regardless of what you specify for the Stretch
to Fit property.
This property has no effect on a check box with a text label. If it is read-
only, then you must select either Bitmap or Icon for the Control Style
property before selecting a size.
Indirect Basic MSI, InstallScript, Set this value to True if this control’s Installer property (see Property)
Property InstallScript MSI, references another Installer property.
InstallScript Object
When an indirect property is set to True, Windows Installer will resolve the
referenced property at run time. For example, this check box might use the
property _BROWSE, whose value is INSTALLDIR. As long as you set Indirect
Property to True, the value of _BROWSE will be the current value of
INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the check box in
InstallScript MSI, installer units.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript MSI,
InstallScript Object
Property Basic MSI Enter the name of a property that will be set when this check box is clicked.
This property can be unique to this combo box; it need not be present in
the Property Manager.
To set a default value for this check box, make the property public by typing
it in all capital letters, go to the Property Manager and add the public
property, and then assign to it the Value property (below).
Property Is Basic MSI, InstallScript, Select True from the list if the property for this control (above) has an
Integer InstallScript MSI, integer value. The property’s value is assumed to be a string when Property
InstallScript Object Is Integer is False.
Push Button Basic MSI, InstallScript, Set this property to True to turn this check box into a push button control.
InstallScript MSI,
InstallScript Object
Right-Aligned Basic MSI, InstallScript, The default value of False aligns the text to the left of the control. Set it to
InstallScript MSI, True to align the text to the right.
InstallScript Object
Right-to-Left Basic MSI, InstallScript, Select False for English and other languages that are written from left to
InstallScript MSI, right. Select True for Hebrew and those languages read from right to left.
InstallScript Object
Stretch to Fit Basic MSI Selecting True causes an icon to be resized to fill the area of the button’s
face. A value of False makes the icon centered if smaller than the button or
cropped if larger. False is ignored if you do not set the Icon Size property.
This property has no effect on a check box with a text label. If it is read-
only, then you must select either Bitmap or Icon for the Control Style
property before changing the Stretch to Fit value.
Sunken Basic MSI, InstallScript, Set this property to True to give this check box a recessed, three-
InstallScript MSI, dimensional appearance. Otherwise, it will have a flat, box-like appearance.
InstallScript Object
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other controls
InstallScript MSI, on this dialog, excluding controls such as static text, determines the order
InstallScript Object in which each one will receive focus when the end user presses the Tab
button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this check box will receive focus within the
InstallScript MSI, tab order.
InstallScript Object
Text Basic MSI, InstallScript, This property holds the text that will be used for the control’s label. Since
InstallScript MSI, the text is language specific, this value is always associated with a string
InstallScript Object ID. Editing the value in the property sheet changes the string ID’s value for
the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
This property has no effect on a check box with an image for a label. If it is
read-only, then you must select Text for the Control Style property before
editing the text.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the check
box label to be displayed in. Leaving the value as <Default> displays the
font contained in the DefaultUIFont property.
This property has no effect on a check box with an image for a label. If it is
read-only, then you must select Text for the Control Style property before
specifying the style.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet changes
the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the check box in installer
InstallScript MSI, units.
InstallScript Object
Value Basic MSI When the check box is selected, the property above will be set to this
value.
Visible Basic MSI, InstallScript, True means that the check box is visible, and False that it is hidden. You can
InstallScript MSI, also make it visible by editing its condition in the Behavior editor.
InstallScript Object
Width Basic MSI, InstallScript, Width of the check box and label in installer units.
InstallScript MSI,
InstallScript Object
Project: (Windows Installer based projects only) When you first draw a combo box onto a dialog, InstallShield prompts for
the name of a single Windows Installer property that identifies all of the items that belong to this combo box. The name
that you enter is used as the value for Property, below, which will contain the selected or entered value from the combo
box. (Note that Windows Installer combo boxes allow the user to select only a single item.
Be sure to set the Height property to a “large” number, which specifies the height of the drop-down list portion of the
combo box control.
Name Basic MSI, InstallScript, Enter a name for this combo box. The name must be unique among all of
InstallScript MSI, the controls in your project.
InstallScript Object
Base Text Style Basic MSI This font style is used for the combo-box label if you specify nothing for
the Text Style property.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key
InstallScript Object or clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to
True.
Code Page Basic MSI Set this property to Database to have the combo box use fonts from the
package’s database, or User’s System to use fonts from the system’s
default code page.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default
control.
Drop-Down List Basic MSI, InstallScript, Select False to have this control be an editable combo box, or True to
InstallScript MSI, have it work like a drop-down list.
InstallScript Object
Enabled Basic MSI, InstallScript, True means that this control is available (the end user can interact with
InstallScript MSI, it). False means that it is not available (grayed out).
InstallScript Object
Height Basic MSI, InstallScript, Height of the combo box in installer units.
InstallScript MSI,
InstallScript Object
Indirect Basic MSI, InstallScript, Set this value to True if this control’s Installer property (see Property,
Property InstallScript MSI, below) references another Installer property.
InstallScript Object
When an indirect property is set to True, Windows Installer will resolve the
referenced property at run time. For example, this combo box might use
the property _BROWSE, whose value is INSTALLDIR. As long as you set
Indirect Property to True, the value of _BROWSE will be the current value
of INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Items Basic MSI Once you click the Items value to edit it, an ellipsis button (...) appears to
let you edit the combo-box items in the List Items dialog.
To add a new item to the list, click the Add button. For each item, you
must enter text, which is the item that will be displayed in the combo box,
and a value, which is the value that will be assigned to the property if this
item is selected.
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the combo box in
InstallScript MSI, installer units, which are defined as 1/12 of the height of the system
InstallScript Object font.
Left Scrollbar Basic MSI, InstallScript, Set this property to True to have the arrow and vertical scrollbar
InstallScript MSI, displayed on the left side of the combo box. This property should be set
InstallScript Object only when the Right-to-Left property is true.
Max. Length Basic MSI Specify how many characters the end user can enter into the combo
box.
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog
Styles InstallScript MSI, box.
InstallScript Object
Property Basic MSI Enter the name of a property that will be set when the end user enters a
value into or selects one from this combo box. This property can be
unique to this combo box; it need not be present in the Property
Manager.
To set a default value for this combo box, make the property is a public
property by giving it a name containing only uppercase letters (for
example, COMBOPROPERTY), go to the Property Manager and add the
public property, and then assign to it the value of the default selection
(see Items, above).
Property Is Basic MSI, InstallScript, Select True if the property for this control (above) has an integer value.
Integer InstallScript MSI, The property’s value is assumed to be a string when Property Is Integer
InstallScript Object is False. Make sure that all of the values in the Item property (above) are
either integers or strings, depending on the value you select here.
Right-Aligned Basic MSI, InstallScript, The default value of False aligns the text to the left of the control. Set it
InstallScript MSI, to True to align the text to the right.
InstallScript Object
Right-to-Left Basic MSI, InstallScript, Select False for English and other languages that are written from left to
InstallScript MSI, right. Select True for Hebrew and those languages read from right to left.
InstallScript Object
Sorted Basic MSI, InstallScript, Selecting True causes the items in the combo box to be sorted
InstallScript MSI, alphabetically. A value of False makes them retain the order that you set
InstallScript Object for each item in the List Items dialog.
Sunken Basic MSI, InstallScript, Set this property to True to give the combo box a recessed, three-
InstallScript MSI, dimensional appearance, as combo boxes usually look. False gives it a
InstallScript Object flat appearance.
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript MSI, controls on this dialog, excluding controls such as static text, determines
InstallScript Object the order in which each one will receive focus when the end user presses
the Tab key.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this combo box will receive focus within
InstallScript MSI, the tab order.
InstallScript Object
Text Basic MSI This property holds the text that will be used for the control’s label.
Although you cannot see the label, it will be available for screen readers.
Since the text is language specific, this value is always associated with a
string ID. Editing the value in the property sheet changes the string ID’s
value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the
combo-box label to be displayed in. Leaving the value as <Default>
displays the font contained in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over this control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet
changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the combo box in
InstallScript MSI, installer units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the combo box is visible, and False that it is hidden. You
InstallScript MSI, can also make it visible by editing its condition in the Behavior editor.
InstallScript Object
Width Basic MSI, InstallScript, Width of the combo box in installer units.
InstallScript MSI,
InstallScript Object
Custom Properties
Project: Custom controls are available only for dialogs in InstallScript MSI projects.
Each custom control has the following properties available for specifying how it is displayed.
Property Description
Name Enter a name for this custom control. The name must be unique among all of the
controls in your project.
Property Description
Control Identifier This field contains a numeric identifier for the control that is unique within the
dialog. This identifier is the same as a resource identifier in Visual C++. You
should not change the control identifiers for any of the controls included with a
dialog by default.
Enabled True means that this control is available (the end user can interact with it). False
means that it is not available (grayed out).
Height Height of the control in installer units, which are defined as 1/12 of the height of
the system font.
Left Distance from the left edge of the dialog to the start of the control in installer
units.
Other Window Styles Click the ellipsis button (...) to display the Other Window Styles dialog box.
Tab Index Provide an integer, starting with 0 (zero) that, along with the other controls on this
dialog, excluding controls such as static text, determines the order in which each
one will receive focus when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this control will receive focus within the tab order.
Top Distance from the top of the dialog to the top of the control in installer units.
Visible True means that the custom control is visible, and False that it is hidden.
Dialog Properties
Each dialog has the following properties to specify how it is displayed.
Unlike its controls, you cannot change the name of a dialog in the Dialog Editor. To change the name,
right-click on the dialog in the Dialogs view and click Rename.
Caption Basic MSI A name that will become the title for the dialog box. Since the text is
language specific, this value is always associated with a string ID.
Editing the value in the property sheet changes the string ID’s value for
the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string
table.
Comment Basic MSI Enter comments for the dialog. Your comments are saved in the project
file for your reference and are not used in the installation at any time.
Custom Palette Basic MSI A custom palette is necessary only if the dialog will contain images
using a color palette different from the default one created by Windows
Installer for the dialog. Otherwise, leave this value as False.
ErrorDialog Basic MSI Set this value to True if this dialog serves as an error dialog, one of the
dialogs required by Windows Installer.
Height Basic MSI, InstallScript, The height of the dialog box, excluding the title bar. Give the value in
InstallScript MSI, installer units, which are defined as 1/12 of the height of the system
InstallScript Object font.
Keep Modeless Basic MSI When this value is set to True and this dialog is spawned through a
DoAction event, all other dialogs remain. If the Keep Modeless property
is False, they will be destroyed.
Left Basic MSI, InstallScript, Give the percentage from the left edge of the screen where you want the
InstallScript MSI, dialog to be placed. A value of 50 centers the dialog horizontally.
InstallScript Object
This value is ignored if this dialog is part of an installation wizard, and
the previous dialog was in a different location or was moved by the end
user.
Left Scrollbar Basic MSI, InstallScript, Select True to set the scroll bar, if present, at the left side of the dialog.
InstallScript MSI, The default value, False, keeps it at the right side.
InstallScript Object
Minimize Basic MSI, InstallScript, True means that the end user can minimize this dialog. False means that
InstallScript MSI, the option is not present on the title bar.
InstallScript Object
Modal Basic MSI, InstallScript, Select True if this dialog is part of the installation wizard and no other
InstallScript MSI, dialogs should be placed on top of it.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog
Styles InstallScript MSI, box.
InstallScript Object
Right-Aligned Basic MSI, InstallScript, Set this property to True to align the caption to the right of the dialog.
InstallScript MSI,
InstallScript Object
Right-to-Left Basic MSI, InstallScript, Select False for English and other languages that are written from left to
InstallScript MSI, right. Select True for Hebrew and those languages read from right to
InstallScript Object left.
Text Style InstallScript MSI Specify a font to be used for the dialog by selecting from the drop-down
menu.
Top Basic MSI, InstallScript, Give the percentage from the top of the screen where you want the
InstallScript MSI, dialog to be placed. A value of 50 centers the dialog vertically.
InstallScript Object
This value is ignored if this dialog is part of an installation wizard, and
the previous dialog was in a different location or was moved by the end
user.
Track Disk Basic MSI Select True if this dialog has a control that alerts the end user that a
Space drive is out of space or that checks the value of the OutOfDiskSpace
property before performing some action.
Visible Basic MSI, InstallScript, True means that the dialog is visible, and False means that it is hidden.
InstallScript MSI,
InstallScript Object
Width Basic MSI, InstallScript, The width of the dialog box in installer units.
InstallScript MSI,
InstallScript Object
Project: Directory combo controls are available only for use in Basic MSI projects
A directory combo is used in conjunction with a directory list and a path edit control to create a browse
dialog. The directory combo displays the list of drives mapped on the current system.
When you first draw a directory combo onto a dialog, InstallShield prompts for the name of a single
Windows Installer property. This property should be the same for the accompanying directory list and
path edit. It will contain the path selected by the end user.
Each directory combo control has the following properties to specify how it is displayed.
Property Description
Name Enter a name for this directory combo. The name must be unique among all of the
controls in your project.
Base Text Style This font style is used for the directory combo’s text if you specify nothing for the Text
Style property.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the cancel
control has the same effect as pressing the Esc key or clicking the Close button on the
title bar. The Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help This property is reserved for future use. Windows Installer does not currently support
launching context-sensitive help topics from the installation.
Property Description
Control Identifier This field contains a numeric identifier for the control that is unique within the dialog. This
identifier is the same as a resource identifier in Visual C++. You should not change the
control identifiers for any of the controls included with a dialog by default.
Default Select True if this is the only control on the dialog that you want to be the default control,
which means that it will be activated when the end user presses the Enter key. The Next
or OK button is usually the default control.
Enabled True means that this control is available (the end user can interact with it). False means
that it is not available (grayed out).
Height Height of the directory combo in installer units, which are defined as 1/12 of the height of
the system font.
Indirect Property Set this value to True if this control’s Installer property (see Property, below) references
another Installer property.
When an indirect property is set to True, Windows Installer resolves the referenced
property at run time. For example, this directory combo might use the property
_BROWSE, whose value is INSTALLDIR. As long as you set Indirect Property to True, the
value of _BROWSE will be the current value of INSTALLDIR; otherwise, _BROWSE will
contain the string INSTALLDIR.
Left Distance from the left edge of the dialog to the start of the directory combo in installer
units.
Left Scrollbar Set this property to True to have the arrow and vertical scrollbar displayed on the left side
of the directory combo. This property should be set only when the Right-to-Left property is
true.
Other Window Styles Click the ellipsis button (...) to display the Other Window Styles dialog box.
Property Enter the name of a property that will be set when the end user selects a value from this
directory combo. This control populates the first part of the path that is displayed in the
directory list, so you must use the same property for the directory combo, the directory
list, and path edit when using them together in a browse dialog. This property can be
unique to the browse dialog; it need not be present in the Property Manager.
To set a default value for this directory combo, make the property public by typing it in all
capital letters, go to the Property Manager and add the public property, and then assign
to it the value of the default selection.
Right-Aligned The default value of False aligns the text to the left of the control. Set it to True to align
the text to the right.
Right-to-Left Select False for English and other languages that are written from left to right. Select True
for Hebrew and those languages read from right to left.
Show CD-ROM Select True to display CD-ROM volumes in the directory combo.
Show Fixed Select True to display hard drives in the directory combo.
Show Floppy Select True to display floppy drives in the directory combo.
Property Description
Show RAMDisk Select True to display RAM volumes in the directory combo.
Show Remote Select True to display mapped network drives in the directory combo.
Show Removable Select True to display removable drives in the directory combo.
Sunken Set this property to True to give the directory combo a recessed, three-dimensional
appearance, as directory combos usually look. False gives it a flat appearance.
Tab Index Provide an integer, starting with 0 (zero) that, along with the other controls on this dialog,
excluding controls such as static text, determines the order in which each one will receive
focus when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this directory combo will receive focus within the tab
order.
Text Style Select the font style, size, and color, if available, that you want the directory combo’s
label to be displayed in. Leaving the value as <Default> displays the font contained in the
DefaultUIFont property.
Tooltip This property holds the text that will be displayed when the mouse hovers over this
control. Since the text is language specific, this value is always associated with a string
ID. Editing the value in the property sheet changes the string ID’s value for the current
language.
Top Distance from the top of the dialog to the top of the directory combo in installer units.
Visible True means that the directory combo is visible, and False that it is hidden. You can also
make it visible by editing its condition in the Behavior editor.
Project: Directory list controls are available only for use in Basic MSI projects.
A directory list is used in conjunction with a directory combo and a path edit control to create a browse
dialog. The directory list displays the folders below the drive selected in the directory combo control and
populates the value of the path edit control.
When you first draw a directory list onto a dialog, InstallShield prompts for the name of a single
Windows Installer property. This property should be the same for the accompanying directory combo
and path edit. It will contain the path selected by the end user.
Each directory list control has the following properties to specify how it is displayed.
Property Description
Name Enter a name for this directory list. The name must be unique among all of the controls in
your project.
Base Text Style This font style is used for the text in the directory list if you specify nothing for the Text
Style property.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the cancel
control has the same effect as pressing the Esc key or clicking the Close button on the
title bar. The Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help This property is reserved for future use. Windows Installer does not currently support
launching context-sensitive help topics from the installation.
Control Identifier This field contains a numeric identifier for the control that is unique within the dialog. This
identifier is the same as a resource identifier in Visual C++. You should not change the
control identifiers for any of the controls included with a dialog by default.
Default Select True if this is the only control on the dialog that you want to be the default control,
which means that it will be activated when the end user presses the Enter key. The Next or
OK button is usually the default control.
Enabled True means that this control is available (the end user can interact with it). False means
that it is not available (grayed out).
Height Height of the directory list in installer units, which are defined as 1/12 of the height of the
system font.
Indirect Property Set this value to True if this control’s Installer property (see Property, below) references
another Installer property.
When an indirect property is set to True, Windows Installer resolves the referenced
property at run time. For example, this directory list might use the property _BROWSE,
whose value is INSTALLDIR. As long as you set Indirect Property to True, the value of
_BROWSE will be the current value of INSTALLDIR; otherwise, _BROWSE will contain the
string INSTALLDIR.
Left Distance from the left edge of the dialog to the start of the directory list in installer units.
Left Scrollbar Set this property to True to have the vertical scrollbar displayed on the left side of the
directory list. This property should be set only when the Right-to-Left property is true.
Other Window Styles Click the ellipsis button (...) to display the Other Window Styles dialog box.
Property Description
Property Enter the name of a property that will be set when the end user selects a value from this
directory list. This control populates the path that is displayed in the path edit and changes
depending on the selection in the directory combo, so you must use the same property for
all three controls when using them together in a browse dialog. This property can be
unique to the browse dialog; it need not be present in the Property Manager.
To set a default value for this directory list, make the property public by typing it in all
capital letters, go to the Property Manager and add the public property, and then assign to
it the value of the default selection.
Right-Aligned The default value of False aligns the text to the left of the control. Set it to True to align the
text to the right.
Right-to-Left Select False for English and other languages that are written from left to right. Select True
for Hebrew and those languages read from right to left.
Sunken Set this property to True to give this directory list’s border a recessed, three-dimensional
appearance. Otherwise, it will have a flat, box-like appearance.
Tab Index Provide an integer, starting with 0 (zero) that, along with the other controls on this dialog,
excluding controls such as static text, determines the order in which each one will receive
focus when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this edit field will receive focus within the tab order.
Text Style Select the font style, size, and color, if available, that you want the directory list’s text to
be displayed in. Leaving the value as <Default> displays the font contained in the
DefaultUIFont property.
Tooltip This property holds the text that will be displayed when the mouse hovers over the control.
Since the text is language specific, this value is always associated with a string ID. Editing
the value in the property sheet changes the string ID’s value for the current language.
Top Distance from the top of the dialog to the top of the directory list in installer units.
Visible True means that the directory list is visible, and False that it is hidden. You can also make
it visible by editing its condition in the Behavior editor.
Project: (Windows Installer–based projects only) When you first draw an edit field onto a dialog, InstallShield prompts you
for the name of a single Windows Installer property. The name you enter is used as the value for Property, below, which
will contain the value entered into the edit field by the end user.
Name Basic MSI, Enter a name for this edit field. The name must be unique among all of
InstallScript, the controls in your project.
InstallScript MSI,
InstallScript Object
Base Text Style Basic MSI This font style is used for the edit field’s text if you specify nothing for
the Text Style property.
Cancel Basic MSI, Select True if this is the only control on the dialog that will dismiss it.
InstallScript, Clicking the cancel control has the same effect as pressing the Esc key
InstallScript MSI, or clicking the Close button on the title bar. The Cancel or Finish button
InstallScript Object is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to
True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Identifier Basic MSI, This field contains a numeric identifier for the control that is unique within
InstallScript, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript MSI, C++. You should not change the control identifiers for any of the
InstallScript Object controls included with a dialog by default.
Default Basic MSI, Select True if this is the only control on the dialog that you want to be the
InstallScript, default control, which means that it will be activated when the end user
InstallScript MSI, presses the Enter key. The Next or OK button is usually the default
InstallScript Object control.
Enabled Basic MSI, True means that this control is available (the end user can interact with
InstallScript, it). False means that it is not available (grayed out).
InstallScript MSI,
InstallScript Object
Indirect Property Basic MSI Set this value to True if this control’s Installer property (see Property,
below) references another Installer property.
When an indirect property is set to True, Windows Installer resolves the
referenced property at run time. For example, this edit field might use
the property _BROWSE, whose value is INSTALLDIR. As long as you set
Indirect Property to True, the value of _BROWSE will be the current value
of INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Left Basic MSI, Distance from the left edge of the dialog to the start of the edit field in
InstallScript, installer units, which are defined as 1/12 of the height of the system
InstallScript MSI, font.
InstallScript Object
Left Scrollbar Basic MSI, Set this property to True to have the vertical scrollbar displayed on the
InstallScript, left side of the edit field. This property should be set only when both the
InstallScript MSI, Multi-Line and Right-to-Left properties are true.
InstallScript Object
Max. Length Basic MSI Specify how many characters the end user can enter into this edit field.
MultiLine Basic MSI, Set this property to True to turn this control into a multiline edit field.
InstallScript,
InstallScript MSI,
InstallScript Object
Other Window Basic MSI, Click the ellipsis button (...) to display the Other Window Styles dialog
Styles InstallScript, box.
InstallScript MSI,
InstallScript Object
Password Basic MSI, Select True to have this edit box behave like a password control, only
InstallScript, showing asterisks (*) when input is entered into it. Select false to have it
InstallScript MSI, behave like a normal edit box.
InstallScript Object
Property Basic MSI Enter the name of a property that will be set with the value that the user
enters into the edit field. This property can be unique to this edit field; it
need not be present in the Property Manager.
To set a default value for this edit field, make the property public by
typing it in all capital letters, go to the Property Manager and add the
public property, and then give it the value of the default selection.
Right-Aligned Basic MSI, The default value of False aligns the text to the left of the control. Set it
InstallScript, to True to align the text to the right.
InstallScript MSI,
InstallScript Object
Right-to-Left Basic MSI, Select False for English and other languages that are written from left to
InstallScript, right. Select True for Hebrew and those languages read from right to
InstallScript MSI, left.
InstallScript Object
Sunken Basic MSI, Set this property to True to give this edit field a recessed, three-
InstallScript, dimensional appearance. Otherwise, it will have a flat, box-like
InstallScript MSI, appearance.
InstallScript Object
Tab Index Basic MSI, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript, controls on this dialog, excluding controls such as static text,
InstallScript MSI, determines the order in which each one will receive focus when the end
InstallScript Object user presses the Tab button.
Tab Stop Basic MSI, The tab stop indicates whether this edit field will receive focus within the
InstallScript, tab order.
InstallScript MSI,
InstallScript Object
Text Basic MSI This property holds the text that will be used for the control’s text. Since
the text is language specific, this value is always associated with a string
ID. Editing the value in the property sheet changes the string ID’s value
for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string
table.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the edit
field’s text to be displayed in. Leaving the value as <Default> displays
the font contained in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse
hovers over the control. Since the text is language specific, this value is
always associated with a string ID. Editing the value in the property
sheet changes the string ID’s value for the current language.
Top Basic MSI Distance from the top of the dialog to the top of the edit field in installer
units.
Visible Basic MSI True means that the edit field is visible, and False that it is hidden. You
can also make it visible by editing its condition in the Behavior editor.
Width Basic MSI Width of the check box and label in installer units.
Each group box control has the following properties available for specifying how it will be displayed.
Name Basic MSI, InstallScript, Enter a name for this group box. The name must be unique among all of
InstallScript MSI, the controls in your project.
InstallScript Object
Base Text Style Basic MSI This font style is used for the group box label if you specify nothing for
the Text Style property.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key
InstallScript Object or clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to
True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default
control.
Enabled Basic MSI, InstallScript, True means that this control is available (the end user can interact with
InstallScript MSI, it). False means that it is not available (grayed out).
InstallScript Object
Height Basic MSI, InstallScript, Height of the group box in installer units, which are defined as 1/12 of
InstallScript MSI, the height of the system font.
InstallScript Object
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the group box in
InstallScript MSI, installer units.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog
Styles InstallScript MSI, box.
InstallScript Object
Right-Aligned Basic MSI, InstallScript, The default value of False aligns the text to the left of the control. Set it
InstallScript MSI, to True to align the text to the right.
InstallScript Object
Right-to-Left Basic MSI, InstallScript, Select False for English and other languages that are written from left to
InstallScript MSI, right. Select True for Hebrew and those languages read from right to left.
InstallScript Object
Sunken Basic MSI, InstallScript, False leaves this control looking like a typical control field. Set this
InstallScript MSI, property to True to give the group box edges a recessed, three-
InstallScript Object dimensional appearance.
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript MSI, controls on this dialog, excluding controls such as static text,
InstallScript Object determines the order in which each one will receive focus when the end
user presses the Tab button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this control area will receive focus within
InstallScript MSI, the tab order.
InstallScript Object
Text Basic MSI, InstallScript, This property holds the text that will be used for the group box label.
InstallScript MSI, Since the text is language specific, this value is always associated with a
InstallScript Object string ID. Editing the value in the property sheet changes the string ID’s
value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the group
box label to be displayed in. Leaving the value as <Default> displays the
font contained in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse
hovers over the control. Since the text is language specific, this value is
always associated with a string ID. Editing the value in the property sheet
changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the group box in installer
InstallScript MSI, units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the group box control is visible, and False that it is
InstallScript MSI, hidden. You can also make it visible by editing its condition in the
InstallScript Object Behavior editor.
Width Basic MSI, InstallScript, Width of the group box in installer units.
InstallScript MSI,
InstallScript Object
Icon Properties
Each icon control has the following properties available for specifying how it will be displayed.
Name Basic MSI, InstallScript, Enter a name for this icon. The name must be unique among all of the
InstallScript MSI, controls in your project.
InstallScript Object
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key
InstallScript Object or clicking the Close button on the title bar. The Cancel or Finish button
is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to
True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Identifier Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique
InstallScript MSI, within the dialog. This identifier is the same as a resource identifier in
InstallScript Object Visual C++. You should not change the control identifiers for any of the
controls included with a dialog by default.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be
InstallScript MSI, the default control, which means that it will be activated when the end
InstallScript Object user presses the Enter key. The Next or OK button is usually the default
control.
Enabled Basic MSI True means that this control is available (the end user can interact with
it). False means that it is not available (grayed out).
File Name Basic MSI, InstallScript, The icon file must be stored as a binary resource inside the Windows
InstallScript MSI, Installer package. Enter the path to this file so InstallShield can include
InstallScript Object it in your release.
When you click the File Name value to edit it, an ellipsis button (...)
appears to allow you either to browse to the file or to select the string
ID that contains the path and file name. The value for File Name is
always stored in a string table entry so that you can easily make
language-specific changes to the dialog.
Height Basic MSI, InstallScript, Height of the control in installer units, which are defined as 1/12 of the
InstallScript MSI, height of the system font.
InstallScript Object
Icon Size Basic MSI, InstallScript, Assuming that your icon file has more than one resource, specify the
InstallScript MSI, size of the image that you want to use for this control. The default value
InstallScript Object for a new icon is 32x32.
The Use first image option causes the first image in the file to be
displayed and makes it stretch to fit the size of the control, regardless
of what you specify for the Stretch to Fit property.
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the control in
InstallScript MSI, installer units.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog
Styles InstallScript MSI, box.
InstallScript Object
Stretch to Fit Basic MSI Selecting True causes an icon to be resized to fill the height and width
that you select. A value of False makes the icon centered if smaller than
the area or cropped if larger. False is ignored if you do not set the Icon
Size property.
Sunken Basic MSI, InstallScript, Set this property to True to give the control’s edges a recessed, three-
InstallScript MSI, dimensional appearance.
InstallScript Object
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript MSI, controls on this dialog, excluding controls such as static text,
InstallScript Object determines the order in which each one will receive focus when the end
user presses the Tab button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this icon will receive focus within the tab
InstallScript MSI, order.
InstallScript Object
Tooltip Basic MSI This property holds the text that will be displayed when the mouse
hovers over this control or read by a screen reader. Since the text is
language specific, this value is always associated with a string ID.
Editing the value in the property sheet changes the string ID’s value for
the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the control in installer
InstallScript MSI, units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the icon is visible, and False that it is hidden. You can
InstallScript MSI, also make it visible by editing its condition in the Behavior Editor.
InstallScript Object
Line Properties
The Line control creates lines of adjustable length and thickness. Lines can be used to separate areas of
the dialog or add graphical touches.
Each Line control has the following properties available for specifying how it will be displayed.
Name Basic MSI, InstallScript, Enter a name for this line. The name must be unique among all of the
InstallScript MSI, controls in your project.
InstallScript Object
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key
InstallScript Object or clicking the Close button on the title bar. The Cancel or Finish button
is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to
True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique
Identifier InstallScript MSI, within the dialog. This identifier is the same as a resource identifier in
InstallScript Object Visual C++. You should not change the control identifiers for any of the
controls included with a dialog by default.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be
InstallScript MSI, the default control, which means that it will be activated when the end
InstallScript Object user presses the Enter key. The Next or OK button is usually the default
control.
Enabled Basic MSI True means that this control is available (the end user can interact with
it). False means that it is not available (grayed out).
Height Basic MSI, InstallScript, Vertical length of the line in installer units, which are defined as 1/12 of
InstallScript MSI, the height of the system font.
InstallScript Object
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the line in
InstallScript MSI, installer units.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog
Styles InstallScript MSI, box.
InstallScript Object
Sunken Basic MSI, InstallScript, False leaves this control looking like a flat line. Set this property to True
InstallScript MSI, to give the line’s edges a recessed, three-dimensional appearance.
InstallScript Object
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript MSI, controls on this dialog, excluding controls such as static text,
InstallScript Object determines the order in which each one will receive focus when the end
user presses the Tab button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this control area will receive focus within
InstallScript MSI, the tab order.
InstallScript Object
Tooltip Basic MSI This property holds the text that will be displayed when the mouse
hovers over the control. Since the text is language specific, this value is
always associated with a string ID. Editing the value in the property
sheet changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the line in installer units.
InstallScript MSI,
InstallScript Object
Visible Basic MSI, InstallScript, True means that the line control is visible, and False that it is hidden. You
InstallScript MSI, can also make it visible by editing its condition in the Behavior editor.
InstallScript Object
Width Basic MSI, InstallScript, Horizontal length of the line in installer units.
InstallScript MSI,
InstallScript Object
Project: (Windows Installer based projects only:) When you draw a list box onto a dialog, InstallShield prompts you for the
name of a single Windows Installer property that will identify all of the items that will be displayed in this list box. The name
you enter is used as the value for Property, below, which will later contain the value selected from the list box.
Name Basic MSI, InstallScript, Enter a name for this list box. The name must be unique among all of the
InstallScript MSI, controls in your project.
InstallScript Object
Base Text Style Basic MSI This font style is used for the text in the list box if you specify nothing for
the Text Style property.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key or
InstallScript Object clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Code Page Basic MSI Set this property to Database to have the list box use fonts from the
package’s database, or User’s System to use fonts from the system’s
default code page.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default
control.
Enabled Basic MSI, InstallScript, True means that this control is available (the end user can interact with it).
InstallScript MSI, False means that it is not available (grayed out).
InstallScript Object
Height Basic MSI, InstallScript, Height of the list box in installer units, which are defined as 1/12 of the
InstallScript MSI, height of the system font.
InstallScript Object
Indirect Basic MSI, InstallScript, Set this value to True if this control’s Installer property (see Property,
Property InstallScript MSI, below) references another Installer property.
InstallScript Object
When an indirect property is set to True, Windows Installer resolves the
referenced property at run time. For example, this list box might use the
property _BROWSE, whose value is INSTALLDIR. As long as you set
Indirect Property to True, the value of _BROWSE will be the current value
of INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Items Basic MSI Once you click the Items value to edit it, an ellipsis button (...) appears to
let you edit the List box items in the List Items dialog.
To add a new item to the list, click the Add button. For each item you must
enter text, which is the string that will be displayed in the list box, and a
value, which is the value that will be assigned to the property if this item is
selected. You can use the Move Up and Move Down buttons to specify the
order in which the items will be displayed in the list box.
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the list box in
InstallScript MSI, installer units.
InstallScript Object
Left Scrollbar Basic MSI, InstallScript, Set this property to True to have the vertical scrollbar displayed on the left
InstallScript MSI, side of the list box. This property should be set only when the Right-to-Left
InstallScript Object property is true.
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript MSI,
InstallScript Object
Property Basic MSI Enter the name of a property that will be set when the end user selects a
value from this list box. This property can be unique to this list box; it
need not be present in the Property Manager.
To set a default value for this list box, make the property public by typing
it in all capital letters, go to the Property Manager and add the public
property, and then assign to it the text of the default selection (see Items,
above).
Property Is Basic MSI, InstallScript, Select True if the property for this control (above) has an integer value.
Integer InstallScript MSI, The property’s value is assumed to be a string when Property Is Integer is
InstallScript Object False. Ensure that all of the values in the Item property (above) are either
integers or strings, depending on the value you select here.
Right-to-Left Basic MSI, InstallScript, Select False for English and other languages that are written from left to
InstallScript MSI, right. Select True for Hebrew and those languages read from right to left.
InstallScript Object
Sorted Basic MSI, InstallScript, Selecting True causes the items in the list box to be sorted alphabetically.
InstallScript MSI, A value of False makes them retain the order that you set for each item in
InstallScript Object the List Items dialog.
Sunken Basic MSI, InstallScript, Set this property to True to give this list box border a recessed, three-
InstallScript MSI, dimensional appearance. Otherwise, it will have a flat, box-like
InstallScript Object appearance.
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript MSI, controls on this dialog, excluding controls such as static text, determines
InstallScript Object the order in which each one will receive focus when the end user presses
the Tab button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this edit field will receive focus within the
InstallScript MSI, tab order.
InstallScript Object
Text Basic MSI This property holds the text for screen readers. Since the text is language
specific, this value is always associated with a string ID. Editing the value
in the property sheet changes the string ID’s value for the current
language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the list box
text to be displayed in. Leaving the value as <Default> displays the font
contained in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet
changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the list box in installer
InstallScript MSI, units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the list box is visible, and False that it is hidden. You can
InstallScript MSI, also make it visible by editing its condition in the Behavior editor.
InstallScript Object
Width Basic MSI, InstallScript, Width of the list box in installer units.
InstallScript MSI,
InstallScript Object
Project: (Windows Installer based projects only:) When you first draw a list view onto a dialog, InstallShield prompts you
for the name of a single property that identifies all of the items that are displayed in this list view. The name you enter is
used as the value for Property, below, which later contains the value selected from the list view.
Name Basic MSI, InstallScript, Enter a name for this list view. The name must be unique among all of the
InstallScript MSI, controls in your project.
InstallScript Object
Base Text Style Basic MSI This font style is used for the list view’s items if you specify nothing for the
Text Style property.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key or
InstallScript Object clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default
control.
Enabled Basic MSI, InstallScript, True means that this control is available (the end user can interact with it).
InstallScript MSI, False means that it is not available (grayed out).
InstallScript Object
Height Basic MSI, InstallScript, Height of the list view area in installer units, which are defined as 1/12 of
InstallScript MSI, the height of the system font.
InstallScript Object
Indirect Basic MSI, InstallScript, Set this value to True if this control’s Installer property (see Property,
Property InstallScript MSI, below) references another Installer property.
InstallScript Object
When an indirect property is set to True, Windows Installer will resolve the
referenced property at run time. For example, suppose this list view uses
the property _BROWSE, whose value is INSTALLDIR. As long as you set
Indirect Property to True, the value of _BROWSE will be the current value
of INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Items Basic MSI Once you click the Items value to edit it, a Browse button appears to let
you edit the list view’s items in the List Items dialog.
To add a new item to the list, click the Add button. For each item you must
enter text, which is the item that will be displayed in the list view, and a
value, which is the value that will be assigned to Property if this item is
selected. You can use the Move Up and Move Down buttons to specify the
order in which the items will be displayed in the list box.
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the list view area
InstallScript MSI, in installer units.
InstallScript Object
Left Scrollbar Basic MSI, InstallScript, Set this property to True to have the vertical scrollbar displayed on the left
InstallScript MSI, side of the list view. This property should be set only when the Right-to-
InstallScript Object Left property is true.
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript MSI,
InstallScript Object
Property Basic MSI Enter the name of a property that will be set when the end user selects a
value from this list view. This property can be unique to this list view; it
need not be present in the Property Manager.
To set a default value for this list view, make the property public by typing
it in all capital letters, go to the Property Manager and add the public
property, and then give it the value of the default item (see Items, above).
Property Is Basic MSI, InstallScript, Select True if the property for this control (above) has an integer value.
Integer InstallScript MSI, The property’s value is assumed to be a string when Property Is Integer is
InstallScript Object False. Make sure that all of the values in the Item property (above) are
either integers or strings, depending on the value you select here.
Right-Aligned Basic MSI, InstallScript, The default value of False aligns the text to the left of the control. Set it to
InstallScript MSI, True to align the text to the right.
InstallScript Object
Right-to-Left Basic MSI, InstallScript, Select False for English and other languages that are written from left to
InstallScript MSI, right. Select True for Hebrew and those languages read from right to left.
InstallScript Object
Sorted Basic MSI, InstallScript, Selecting True causes the items in the list view to be sorted
InstallScript MSI, alphabetically. A value of False makes them retain the order that you set
InstallScript Object for each item in the List Items dialog.
Sunken Basic MSI, InstallScript, Set this property to True to give this list view area a recessed, three-
InstallScript MSI, dimensional appearance. Otherwise, its edges will have a flat, box-like
InstallScript Object appearance.
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript MSI, controls on this dialog, excluding controls such as static text, determines
InstallScript Object the order in which each one will receive focus when the end user presses
the Tab button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this list view will receive focus within the
InstallScript MSI, tab order.
InstallScript Object
Text Style Basic MSI Select the font style, size, and color, if available, that you want the list
view’s text to be displayed in. Leaving the value as <Default> displays the
font contained in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet
changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the list view area in
InstallScript MSI, installer units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the list view is visible, and False that it is hidden. You can
InstallScript MSI, also make it visible by editing its condition in the Behavior editor.
InstallScript Object
Width Basic MSI, InstallScript, Width of the list view area in installer units.
InstallScript MSI,
InstallScript Object
Project: Masked edit controls are available only for use in Basic MSI projects.
A masked edit field is used for entering information of a specified format. Each masked edit control has
the following properties available for specifying how it will be displayed.
Property Description
Name Enter a name for this masked edit control. The name must be unique among all of the controls
in your project.
Base Text Style This font style is used for the masked edit’s text if you specify nothing for the Text Style
property.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the cancel control
has the same effect as pressing the Esc key or clicking the Close button on the title bar. The
Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help This property is reserved for future use. Windows Installer does not currently support launching
context-sensitive help topics from the installation.
Default Select True if this is the only control on the dialog that you want to be the default control, which
means that it will be activated when the end user presses the Enter key. The Next or OK button
is usually the default control.
Enabled True means that this control is available (the end user can interact with it). False means that it is
not available (grayed out).
Height Height of the check box in installer units, which are defined as 1/12 of the height of the system
font.
Property Description
Indirect Property Set this value to True if this control’s Installer property (see Property, below) references another
Installer property.
When an indirect property is set to True, Windows Installer resolves the referenced property at
run time. For example, this masked edit might use the property _BROWSE, whose value is
INSTALLDIR. As long as you set Indirect Property to True, the value of _BROWSE will be the
current value of INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Left Distance from the left edge of the dialog to the start of the masked edit in installer units.
Mask Specifies the formatting of the mask. See MaskedEdit Control in the Windows Installer Help
Library for more information.
Max. Length Specify how many characters the end user can enter into this masked edit.
Other Window Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles
Property Enter the name of a property that will be set with the value that the user enters into the masked
edit. This property can be unique to this combo box; it need not be present in the Property
Manager.
To set a default value for this masked edit, make the property public by typing it in all capital
letters, go to the Property Manager and add the public property, and then give it the value of
the default selection.
Right-to-Left Select False for English and other languages that are written from left to right. Select True for
Hebrew and those languages read from right to left.
Sunken Set this property to True to give this masked edit a recessed, three-dimensional appearance.
Otherwise, it will have a flat, box-like appearance.
Tab Index Provide an integer, starting with 0 (zero) that, along with the other controls on this dialog,
excluding controls such as static text, determines the order in which each one will receive focus
when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this masked edit will receive focus within the tab order.
Text Style Select the font style, size, and color, if available, that you want the masked edit’s text to be
displayed in. Leaving the value as <Default> displays the font contained in the DefaultUIFont
property.
Tooltip This property holds the text that will be displayed when the mouse hovers over the control.
Since the text is language specific, this value is always associated with a string ID. Editing the
value in the property sheet changes the string ID’s value for the current language.
Top Distance from the top of the dialog to the top of the masked edit in installer units.
Visible True means that the masked edit is visible, and False that it is hidden. You can also make it
visible by editing its condition in the Behavior editor.
Project: Path edit controls are available only for use in Basic MSI projects.
A path edit control is used in conjunction with a directory combo and a directory list control to create a
browse dialog. The path edit displays the complete path assembled from selections made in the directory
combo and directory list, along or instead of edits made by the end user.
Each path edit control has the following properties available for specifying how it will be displayed.
Property Description
Name Enter a name for this path edit control. The name must be unique among all of the
controls in your project.
Base Text Style This font style is used for the path edit’s text if you specify nothing for the Text
Style property.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the
cancel control has the same effect as pressing the Esc key or clicking the Close
button on the title bar. The Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help This property is reserved for future use. Windows Installer does not currently
support launching context-sensitive help topics from the installation.
Default Select True if this is the only control on the dialog that you want to be the default
control, which means that it will be activated when the end user presses the Enter
key. The Next or OK button is usually the default control.
Enabled True means that this control is available (the end user can interact with it). False
means that it is not available (grayed out).
Height Height of the check box in installer units, which are defined as 1/12 of the height
of the system font.
Indirect Property Set this value to True if this control’s Installer property (see Property, below)
references another Installer property.
When an indirect property is set to True, Windows Installer resolves the
referenced property at run time. For example, this path edit might use the
property _BROWSE, whose value is INSTALLDIR. As long as you set Indirect
Property to True, the value of _BROWSE will be the current value of INSTALLDIR;
otherwise, _BROWSE will contain the string INSTALLDIR.
Left Distance from the left edge of the dialog to the start of the path edit in installer
units.
Other Window Styles Click the ellipsis button (...) to display the Other Window Styles dialog box.
Property Description
Property Enter the name of a property that will be set when the end user enters a value into
this path edit or selects one from the directory list. Since this control is populated
from the directory list and directory combo, you must use the same property for
the directory combo, the directory list, and path edit when using them together in
a browse dialog. This property can be unique to the browse dialog; it need not be
present in the Property Manager.
To set a default value for this path edit, make the property public by typing it in all
capital letters, go to the Property Manager and add the public property, and then
assign to it the value of the default selection.
Right-Aligned The default value of False aligns the text to the left of the control. Set it to True to
align the text to the right.
Right-to-Left Select False for English and other languages that are written from left to right.
Select True for Hebrew and those languages read from right to left.
Sunken Set this property to True to give this path edit a recessed, three-dimensional
appearance. Otherwise, it will have a flat, box-like appearance.
Tab Index Provide an integer, starting with 0 (zero) that, along with the other controls on this
dialog, excluding controls such as static text, determines the order in which each
one will receive focus when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this path edit will receive focus within the tab
order.
Text This property holds the text that will be used for the control’s label. Since the text
is language specific, this value is always associated with a string ID. Editing the
value in the property sheet changes the string ID’s value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to allow you
to select a string ID and edit the default language’s string table.
Text Style Select the font style, size, and color, if available, that you want the path edit’s
label to be displayed in. Leaving the value as <Default> displays the font
contained in the DefaultUIFont property.
Tooltip This property holds the text that will be displayed when the mouse hovers over the
control. Since the text is language specific, this value is always associated with a
string ID. Editing the value in the property sheet changes the string ID’s value for
the current language.
Top Distance from the top of the dialog to the top of the path edit in installer units.
Visible True means that the path edit is visible, and False that it is hidden. You can also
make it visible by editing its condition in the Behavior editor.
Each progress bar control has the following properties available for specifying how it will be displayed.
Name Basic MSI, InstallScript, Enter a name for this progress bar. The name must be unique among all of
InstallScript MSI, the controls in your project.
InstallScript Object
Appearance Basic MSI, InstallScript, Select Continuous if you want the moving bar to appear as a uniform, blue
InstallScript MSI, bar. Otherwise it will proceed as a series of blue rectangles.
InstallScript Object
Base Text Style Basic MSI This color is used for the line if you specify nothing for the Text Style
property.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key or
InstallScript Object clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default control.
Enabled Basic MSI True means that this control is available (the end user can interact with it).
False means that it is not available (grayed out).
Height Basic MSI, InstallScript, Height of the progress bar in installer units, which are defined as 1/12 of
InstallScript MSI, the height of the system font.
InstallScript Object
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the control in
InstallScript MSI, installer units.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript MSI,
InstallScript Object
Sunken Basic MSI, InstallScript, Set this property to True to give the edges of this progress bar a
InstallScript MSI, recessed, three-dimensional appearance. Otherwise, they will have a flat,
InstallScript Object box-like appearance.
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other controls
InstallScript MSI, on this dialog, excluding controls such as static text, determines the order
InstallScript Object in which each one will receive focus when the end user presses the Tab
button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this progress bar will receive focus within
InstallScript MSI, the tab order.
InstallScript Object
Text Style Basic MSI Select the color that you want the progress bar to be displayed in. Leaving
the value as <Default> displays the font, and hence line color, contained in
the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet changes
the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the control in installer
InstallScript MSI, units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the progress bar is visible, and False that it is hidden. You
InstallScript MSI, can also make it visible by editing its condition in the Behavior editor.
InstallScript Object
Width Basic MSI, InstallScript, Width of the progress bar in installer units.
InstallScript MSI,
InstallScript Object
Name Basic MSI, InstallScript, Enter a name for this push button. The name must be unique among all of
InstallScript MSI, the controls in your project.
InstallScript Object
Base Text Basic MSI This font style is used for the push button’s label if you specify nothing for
Style the Text Style property.
This property has no effect on a push button with an image for a label. If it
is read-only, then you must select Text for the Control Style property
before specifying the style.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key or
InstallScript Object clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
Control Style Basic MSI, InstallScript, Specify whether this push button will be marked with a text label, an icon,
InstallScript MSI, or a bitmap.
InstallScript Object
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default control.
Enabled Basic MSI, InstallScript, True means that this control is available (the end user can interact with it).
InstallScript MSI, False means that it is not available (grayed out).
InstallScript Object
File Name Basic MSI, InstallScript, Push buttons that display an icon or a bitmap file must have the file stored
InstallScript MSI, as a binary resource inside the Windows Installer package. Enter the path
InstallScript Object to this file so that InstallShield can include it in your release.
Once you click the File Name value to edit it, an ellipsis button (...) appears
to allow you either to browse to the file or to select the string ID that
contains the path and file name. In fact, the value for File Name is always
stored in a string table entry so that you can easily make language-specific
changes to the dialog.
This property has no effect on a push button with a text label. If it is read-
only, then you must select either Bitmap or Icon for the Control Style
property before browsing to the file.
Height Basic MSI, InstallScript, Height of the push button in installer units, which are defined as 1/12 of
InstallScript MSI, the height of the system font.
InstallScript Object
Icon Size Basic MSI, InstallScript, Assuming that your icon file has more than one resource, specify the size
InstallScript MSI, of the image that you want to use for the push button. The Use first image
InstallScript Object option causes the first image in the file to be displayed and makes it
stretch to fit the size of the control, regardless of what you specify for the
Stretch to Fit property.
This property has no effect on a push button with a text label. If it is read-
only, then you must select either Bitmap or Icon for the Control Style
property before selecting a size.
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the push button in
InstallScript MSI, installer units.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript MSI,
InstallScript Object
Right-to-Left Basic MSI, InstallScript, Select False for English and other languages that are written from left to
InstallScript MSI, right. Select True for Hebrew and those languages read from right to left.
InstallScript Object
Stretch to Fit Basic MSI Selecting True causes an icon to be resized to fill the area of the button’s
face. A value of False makes the icon centered if smaller than the button
or cropped if larger. False is ignored if you do not set the Icon Size
property.
This property has no effect on a push button with a text label. If it is read-
only, then you must select either Bitmap or Icon for the Control Style
property before changing the Stretch to Fit value.
Sunken Basic MSI, InstallScript, False leaves this control looking like a typical push button. Set this
InstallScript MSI, property to True to give the button’s edges a recessed, three-dimensional
InstallScript Object appearance, in addition to its raised button look.
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other controls
InstallScript MSI, on this dialog, excluding controls such as static text, determines the order
InstallScript Object in which each one will receive focus when the end user presses the Tab
button.
Tab Stop Basic MSI, InstallScript, The tab stop indicates whether this push button will receive focus within
InstallScript MSI, the tab order.
InstallScript Object
Text Basic MSI, InstallScript, This property holds the text that will be used for the control’s label, if any.
InstallScript MSI, Since the text is language specific, this value is always associated with a
InstallScript Object string ID. Editing the value in the property sheet changes the string ID’s
value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
This property has no effect on a push button with an image for a label. If it
is read-only, then you must select Text for the Control Style property
before editing the text.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the push
button’s label to be displayed in. Leaving the value as <Default> displays
the font contained in the DefaultUIFont property.
This property has no effect on a push button with an image for a label. If it
is read-only, then you must select Text for the Control Style property
before specifying the style.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over this control or read by a screen reader in the case of an icon or
bitmap push button. Since the text is language specific, this value is
always associated with a string ID. Editing the value in the property sheet
changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the push button in installer
InstallScript MSI, units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the push button is visible, and False that it is hidden. You
InstallScript MSI, can also make it visible by editing its condition in the Behavior editor.
InstallScript Object
Width Basic MSI, InstallScript, Width of the push button in installer units.
InstallScript MSI,
InstallScript Object
Project: (Windows Installer based projects only:) When you first specify a radio button group area in a dialog, InstallShield
prompts you for the name of a single property that will identify all of the buttons that will be displayed in this radio button
group. The name you enter is used as the value for Property, below, which will later contain the selected value from the list
of radio buttons contained in this radio button group.
Name Basic MSI, InstallScript, Enter a name for this radio button group. The name must be unique
InstallScript MSI, among all of the controls in your project.
InstallScript Object
Base Text Style Basic MSI This font style is used for the radio button group’s label if you specify
nothing for the Text Style property.
This property has no effect on a radio button group with an image for a
label.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key or
InstallScript Object clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
The control identifier for the first radio button in a group is the control
identifier for the radio button group. The control for each subsequent
radio button is the radio button group identifier incremented by one.
Default Basic MSI, InstallScript, Select True if this is the only control on the dialog that you want to be the
InstallScript MSI, default control, which means that it will be activated when the end user
InstallScript Object presses the Enter key. The Next or OK button is usually the default
control.
Enabled Basic MSI, InstallScript, True means that this control is available (the end user can interact with it).
InstallScript MSI, False means that it is not available (grayed out).
InstallScript Object
Has Border Basic MSI, InstallScript, Set this property to True to display the a border around the radio button
InstallScript MSI, group. Otherwise the radio button group and label will appear without a
InstallScript Object border. The appearance of the border can be further altered by modifying
the Sunken property.
Height Basic MSI, InstallScript, Height of the radio button group area in installer units, which are defined
InstallScript MSI, as 1/12 of the height of the system font.
InstallScript Object
Indirect Basic MSI, InstallScript, Set this value to True if this control’s Installer property (see Property,
Property InstallScript MSI, below) references another Installer property.
InstallScript Object
When an indirect property is set to True, Windows Installer resolves the
referenced property at run time. For example, this radio button group
might use the property _BROWSE, whose value is INSTALLDIR. As long as
you set Indirect Property to True, the value of _BROWSE will be the
current value of INSTALLDIR; otherwise, _BROWSE will contain the string
INSTALLDIR.
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the radio button
InstallScript MSI, group field in installer units.
InstallScript Object
Other Window Basic MSI, InstallScript, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript MSI,
InstallScript Object
Property Basic MSI Enter the name of a property that will be set when the end user selects
one of the radio buttons. This property can be unique to this radio button
group; it need not be present in the Property Manager.
For information on using this property to set a default selection in the
radio buttons, see the radio button’s Value property.
Right-Aligned Basic MSI, InstallScript, The default value of False aligns the text to the left of the control. Set it to
InstallScript MSI, True to align the text to the right.
InstallScript Object
Sunken Basic MSI, InstallScript, Set this property to True to give this radio button group area a border with
InstallScript MSI, a recessed, three-dimensional appearance. Otherwise, the buttons will
InstallScript Object appear on their own with borders determined by their individual settings.
Tab Index Basic MSI, InstallScript, Provide an integer, starting with 0 (zero) that, along with the other
InstallScript MSI, controls on this dialog, excluding controls such as static text, determines
InstallScript Object the order in which each one will receive focus when the end user presses
the Tab button.
Tab Stop Basic MSI, InstallScript, The radio button group cannot receive focus unless one of its radio
InstallScript MSI, buttons is selected. To make one of the buttons selected by default, see
InstallScript Object above in Property.
Text Basic MSI This property holds the text that will be used for the radio button group’s
label. Since the text is language specific, this value is always associated
with a string ID. Editing the value in the property sheet changes the string
ID’s value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
This property has no effect on a radio button group with an image for a
label.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the radio
button group’s label to be displayed in. Leaving the value as <Default>
displays the font contained in the DefaultUIFont property.
This property has no effect on a radio button group with an image for a
label.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet
changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the radio button group
InstallScript MSI, area in installer units.
InstallScript Object
Visible Basic MSI, InstallScript, True means that the radio button group field is visible, and False that it is
InstallScript MSI, hidden. You can also make it visible by editing its condition in the Behavior
InstallScript Object editor.
Width Basic MSI, InstallScript, Width of the radio button group area and label in installer units.
InstallScript MSI,
InstallScript Object
Name Basic MSI, InstallScript, Enter a name for this radio button. The name must be unique among all of
InstallScript MSI, the controls in your project.
InstallScript Object
Base Text Style Basic MSI This font style is used for the radio button’s label if you specify nothing for
the Text Style property.
Cancel Basic MSI, InstallScript, Select True if this is the only control on the dialog that will dismiss it.
InstallScript MSI, Clicking the cancel control has the same effect as pressing the Esc key
InstallScript Object or clicking the Close button on the title bar. The Cancel or Finish button is
usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, InstallScript, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript MSI, the dialog. This identifier is the same as a resource identifier in Visual
InstallScript Object C++. You should not change the control identifiers for any of the controls
included with a dialog by default.
The control identifier for the first radio button in a group is the control
identifier for the radio button group. The control for each subsequent
radio button is the radio button group identifier incremented by one.
Height Basic MSI, InstallScript, Height of the rectangular radio button area in installer units, which are
InstallScript MSI, defined as 1/12 of the height of the system font.
InstallScript Object
Left Basic MSI, InstallScript, Distance from the left edge of the dialog to the start of the rectangular
InstallScript MSI, radio button field in installer units.
InstallScript Object
Order Basic MSI, InstallScript, The order in which this radio button is displayed in the radio button group.
InstallScript MSI, This property must contain a unique, positive integer, but it does not have
InstallScript Object to be consecutive with the Order property of the other radio buttons in
this group.
Other Window Basic MSI Click the ellipsis button (...) to display the Other Window Styles dialog
Styles box.
Text Basic MSI, InstallScript, This property holds the text that will be used for the radio button’s label.
InstallScript MSI, Since the text is language specific, this value is always associated with a
InstallScript Object string ID. Editing the value in the property sheet changes the string ID’s
value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the radio
button’s label to be displayed in. Leaving the value as <Default> displays
the font contained in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet
changes the string ID’s value for the current language.
Top Basic MSI, InstallScript, Distance from the top of the dialog to the top of the radio button in
InstallScript MSI, installer units.
InstallScript Object
Value Basic MSI, InstallScript, Enter the value that you want the radio button group’s property to have
InstallScript MSI, when this radio button is selected.
InstallScript Object
To make one of the buttons selected by default, enter the radio button
group’s Windows Installer property into the Property Manager.
Note: Type the property in all capital letters if you want it to be public in
scope.Then, specify the value of the button that you want to appear as
the default. For example, if one of your radio buttons has a value of 104
and the radio button group uses the property GRP_PROPERTY1, enter the
following information in the Property Manager to make this radio button
the default selection.
• Name: GRP_PROPERTY1
• Value: 104
Width Basic MSI, InstallScript, Width of the rectangular radio button area (button and label) in installer
InstallScript MSI, units.
InstallScript Object
Project: Scrollable text controls are available only for dialogs in Basic MSI projects.
Each scrollable text control has the following properties available for specifying how it will be displayed.
Unlike the text values for most controls, Windows Installer does not resolve property names or other
values within the Scrollable Text control. As a result, the text in the file will be displayed exactly as it is
written.
Property Description
Name Enter a name for this scrollable text. The name must be unique among all of the
controls in your project.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the
cancel control has the same effect as pressing the Esc key or clicking the Close
button on the title bar. The Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Property Description
Context Help This property is reserved for future use. Windows Installer does not currently
support launching context-sensitive help topics from the installation.
Default Select True if this is the only control on the dialog that you want to be the default
control, which means that it will be activated when the end user presses the Enter
key. The Next or OK button is usually the default control.
Enabled True means that this control is available (the end user can interact with it). False
means that it is not available (grayed out).
File Name The rich text file must be stored as a binary resource inside the Windows Installer
package. Enter the path to this file so that InstallShield can include it in your
release.
Once you click the File Name value to edit it, an ellipsis button (...) appears to
allow you either to browse to the file or to select the string ID that contains the
path and file name. In fact, the value for File Name is always stored in a string
table entry so that you can easily make language-specific changes to the dialog.
Height Height of the control area in installer units, which are defined as 1/12 of the
height of the system font.
Left Distance from the left edge of the dialog to the start of the control area in installer
units.
Left Scrollbar Set this property to True to have the vertical scrollbar displayed on the left side of
the scrollable text. This property should be set only when the Right-to-Left
property is true.
Other Window Styles Click the ellipsis button (...) to display the Other Window Styles dialog box.
Right-Aligned The default value of False aligns the text to the left of the control. Set it to True to
align the text to the right.
Right-to-Left Select False for English and other languages that are written from left to right.
Select True for Hebrew and those languages read from right to left.
Sunken False leaves this control looking like a flat scrollable text window. Set this property
to True to give the scrollable text window’s edges a recessed, three-dimensional
appearance.
Tab Index Provide an integer, starting with 0 (zero) that, along with the other controls on this
dialog, excluding controls such as static text, determines the order in which each
one will receive focus when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this control area will receive focus within the tab
order.
Tooltip This property holds the text that will be displayed when the mouse hovers over the
control. Since the text is language specific, this value is always associated with a
string ID. Editing the value in the property sheet changes the string ID’s value for
the current language.
Property Description
Top Distance from the top of the dialog to the top of the control area in installer units.
Visible True means that the scrollable text control is visible, and False that it is hidden.
You can also make it visible by editing its condition in the Behavior editor.
Name Basic MSI, Enter a name for this selection tree. The name must be unique among all of
InstallScript, the controls in your project.
InstallScript MSI,
InstallScript Object
Base Text Style Basic MSI This font style is used for the selection tree’s text if you specify nothing for
the Text Style property.
Cancel Basic MSI, Select True if this is the only control on the dialog that will dismiss it. Clicking
InstallScript, the cancel control has the same effect as pressing the Esc key or clicking
InstallScript MSI, the Close button on the title bar. The Cancel or Finish button is usually the
InstallScript Object cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not currently
support launching context-sensitive help topics from the installation.
Control Basic MSI, This field contains a numeric identifier for the control that is unique within the
Identifier InstallScript, dialog. This identifier is the same as a resource identifier in Visual C++. You
InstallScript MSI, should not change the control identifiers for any of the controls included with
InstallScript Object a dialog by default.
Default Basic MSI, Select True if this is the only control on the dialog that you want to be the
InstallScript, default control, which means that it will be activated when the end user
InstallScript MSI, presses the Enter key. The Next or OK button is usually the default control.
InstallScript Object
Enabled Basic MSI, True means that this control is available (the end user can interact with it).
InstallScript, False means that it is not available (grayed out).
InstallScript MSI,
InstallScript Object
Height Basic MSI, Height of the selection tree area in installer units, which are defined as 1/12
InstallScript, of the height of the system font.
InstallScript MSI,
InstallScript Object
Indirect Basic MSI, Set this value to True if this control’s Installer property (see Property, below)
Property InstallScript, references another Installer property.
InstallScript MSI,
When an indirect property is set to True, Windows Installer resolves the
InstallScript Object
referenced property at run time. For example, this selection tree might use
the property _BROWSE, whose value is INSTALLDIR. As long as you set
Indirect Property to True, the value of _BROWSE will be the current value of
INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Left Basic MSI, Distance from the left edge of the dialog to the start of the selection tree
InstallScript, area in installer units.
InstallScript MSI,
InstallScript Object
Left Scrollbar Basic MSI, Set this property to True to have the vertical scrollbar displayed on the left
InstallScript, side of the selection tree. This property should be set only when the Right-to-
InstallScript MSI, Left property is true.
InstallScript Object
Other Window Basic MSI, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript,
InstallScript MSI,
InstallScript Object
Property Basic MSI Enter the name of a property for the selection tree. The user can set the
property in a browse dialog (a dialog that uses a path edit, directory combo,
and directory list control).
Right-Aligned Basic MSI, The default value of False aligns the text to the left of the control. Set it to
InstallScript, True to align the text to the right.
InstallScript MSI,
InstallScript Object
Right-to-Left Basic MSI, Select False for English and other languages that are written from left to
InstallScript, right. Select True for Hebrew and those languages read from right to left.
InstallScript MSI,
InstallScript Object
Sunken Basic MSI, False leaves this control looking like a typical, flat control field. Set this
InstallScript, property to True to give the selection tree’s edges a recessed, three-
InstallScript MSI, dimensional appearance.
InstallScript Object
Tab Index Basic MSI, Provide an integer, starting with 0 (zero) that, along with the other controls
InstallScript, on this dialog, excluding controls such as static text, determines the order in
InstallScript MSI, which each one will receive focus when the end user presses the Tab button.
InstallScript Object
Tab Stop Basic MSI, The tab stop indicates whether this control will receive focus within the tab
InstallScript, order.
InstallScript MSI,
InstallScript Object
Text Basic MSI This property holds the text for screen readers. Since the text is language
specific, this value is always associated with a string ID. Editing the value in
the property sheet changes the string ID’s value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the selection
tree’s text to be displayed in. Leaving the value as <Default> displays the
font contained in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the control. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet changes
the string ID’s value for the current language.
Top Basic MSI, Distance from the top of the dialog to the top of the selection tree area in
InstallScript, installer units.
InstallScript MSI,
InstallScript Object
Visible Basic MSI, True means that the selection tree control is visible, and False that it is
InstallScript, hidden. You can also make it visible by editing its condition in the Behavior
InstallScript MSI, editor.
InstallScript Object
Width Basic MSI, Width of the selection tree area in installer units.
InstallScript,
InstallScript MSI,
InstallScript Object
Name Basic MSI, Enter a name for this text area. The name must be unique among all of the
InstallScript, controls in your project.
InstallScript MSI,
InstallScript Object
Base Text Style Basic MSI This font style is used for the text if you specify nothing for the Text Style
property.
Cancel Basic MSI, Select True if this is the only control on the dialog that will dismiss it.
InstallScript, Clicking the cancel control has the same effect as pressing the Esc key or
InstallScript MSI, clicking the Close button on the title bar. The Cancel or Finish button is
InstallScript Object usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Code Page Basic MSI Set this property to Database to have the text area use fonts from the
package’s database, or User’s System to use fonts from the system’s
default code page.
Context Help Basic MSI This property is reserved for future use. Windows Installer does not
currently support launching context-sensitive help topics from the
installation.
Control Basic MSI, This field contains a numeric identifier for the control that is unique within
Identifier InstallScript, the dialog. This identifier is the same as a resource identifier in Visual C++.
InstallScript MSI, You should not change the control identifiers for any of the controls
InstallScript Object included with a dialog by default.
Default Basic MSI, Select True if this is the only control on the dialog that you want to be the
InstallScript, default control, which means that it will be activated when the end user
InstallScript MSI, presses the Enter key. The Next or OK button is usually the default control.
InstallScript Object
Enabled Basic MSI, True means that this control is available (the end user can interact with it).
InstallScript, False means that it is not available (grayed out).
InstallScript MSI,
InstallScript Object
Format as Basic MSI If this property is true, the installer attempts to display the text in bytes. The
Bytes Text property must contain only a number, without the unit. Then, at run
time, it is divided by 512 and displayed as the correct number of KB, MB,
or GB, depending on the size.
Height Basic MSI, Height of the text area in installer units, which are defined as 1/12 of the
InstallScript, height of the system font.
InstallScript MSI,
InstallScript Object
Left Basic MSI, Distance from the left edge of the dialog to the start of the text area in
InstallScript, installer units.
InstallScript MSI,
InstallScript Object
Other Window Basic MSI, Click the ellipsis button (...) to display the Other Window Styles dialog box.
Styles InstallScript,
InstallScript MSI,
InstallScript Object
No Prefix Basic MSI, Select True if the ampersand character should be displayed as &, or False
InstallScript, to have it displayed underlining the following character—for example,
InstallScript MSI, &Click here would be displayed as Click here.
InstallScript Object
No Text Wrap Basic MSI, If you select True and the text expands beyond the width of the text area,
InstallScript, the end of the string is cut off and replaced with an ellipsis button (...).
InstallScript MSI, Otherwise, the text wraps and can extend beyond the height of the text
InstallScript Object area, if it is not long enough.
Property Basic MSI Enter the name of a property that can supply the initial value for the text.
This property can be unique to this text area; it need not be present in the
Property Manager.
Right-Aligned Basic MSI, The default value of False aligns the text to the left of the control. Set it to
InstallScript, True to align the text to the right.
InstallScript MSI,
InstallScript Object
Right-to-Left Basic MSI, Select False for English and other languages that are written from left to
InstallScript, right. Select True for Hebrew and those languages read from right to left.
InstallScript MSI,
InstallScript Object
Sunken Basic MSI, Set this property to True to give this text area a recessed, three-
InstallScript, dimensional appearance. Otherwise, it will have a flat, box-like appearance.
InstallScript MSI,
InstallScript Object
Tab Index Basic MSI, Provide an integer, starting with 0 (zero) that, along with the other controls
InstallScript, on this dialog, excluding controls such as static text, determines the order
InstallScript MSI, in which each one will receive focus when the end user presses the Tab
InstallScript Object button. Since static text does not typically receive focus, this value will be
ignored by Windows Installer.
Tab Stop Basic MSI, The tab stop indicates whether this text area will receive focus within the
InstallScript, tab order. Since static text does not typically receive focus, this value will
InstallScript MSI, be ignored by Windows Installer.
InstallScript Object
Text Basic MSI, This property holds the text that will be shown inside the control. Since the
InstallScript, text is language specific, this value is always associated with a string ID.
InstallScript MSI, Editing the value in the property sheet changes the string ID’s value for the
InstallScript Object current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to
allow you to select a string ID and edit the default language’s string table.
Text Style Basic MSI Select the font style, size, and color, if available, that you want the text to
be displayed in. Leaving the value as <Default> displays the font contained
in the DefaultUIFont property.
Tooltip Basic MSI This property holds the text that will be displayed when the mouse hovers
over the text area. Since the text is language specific, this value is always
associated with a string ID. Editing the value in the property sheet changes
the string ID’s value for the current language.
Top Basic MSI, Distance from the top of the dialog to the top of the text area in installer
InstallScript, units.
InstallScript MSI,
InstallScript Object
Transparent Basic MSI, Set this property to True to allow the background to show through the text
InstallScript, area. This property is especially useful if you display an image under the
InstallScript MSI, text area.
InstallScript Object
Visible Basic MSI, True means that the text area is visible, and False that it is hidden. You can
InstallScript, also make it visible by editing its condition in the Behavior editor.
InstallScript MSI,
InstallScript Object
Project: Volume select combo controls are available only for use in Basic MSI projects.
A volume select combo control presents the end user with a selection of volumes, or drives.
Each volume select combo control has the following properties available for specifying how it is
displayed.
Property Description
Name Enter a name for this volume select combo. The name must be unique among all of the
controls in your project.
Base Text Style This font style is used for the volume select combo’s text if you specify nothing for the Text
Style property.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the cancel
control has the same effect as pressing the Esc key or clicking the Close button on the title
bar. The Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Property Description
Context Help This property is reserved for future use. Windows Installer does not currently support
launching context-sensitive help topics from the installation.
Default Select True if this is the only control on the dialog that you want to be the default control, which
means that it will be activated when the end user presses the Enter key. The Next or OK button
is usually the default control.
Enabled True means that this control is available (the end user can interact with it). False means that it
is not available (grayed out).
Height Height of the volume select combo in installer units, which are defined as 1/12 of the height of
the system font.
Indirect Property Set this value to True if this control’s Installer property (see Property, below) references
another Installer property.
When an indirect property is set to True, Windows Installer resolves the referenced property at
run time. For example, this volume select combo might use the property _BROWSE, whose
value is INSTALLDIR. As long as you set Indirect Property to True, the value of _BROWSE will
be the current value of INSTALLDIR; otherwise, _BROWSE will contain the string INSTALLDIR.
Left Distance from the left edge of the dialog to the start of the volume select combo in installer
units.
Left Scrollbar Set this property to True to have the arrow and vertical scrollbar displayed on the left side of
the volume select combo. This property should be set only when the Right-to-Left property is
true.
Other Window Styles Click the ellipsis button (...) to display the Other Window Styles dialog box.
Property Enter the name of a property that will be set when the end user selects a value from this
volume select combo. This control populates the first part of the path that is displayed in the
directory list, so you must use the same property for the volume select combo, the directory
list, and path edit when using them together in a browse dialog. This property can be unique to
the browse dialog; it need not be present in the Property Manager.
To set a default value for this volume select combo, make the property public by typing it in all
capital letters, go to the Property Manager and add the public property, and then assign to it
the value of the default selection.
Right-Aligned The default value of False aligns the text to the left of the control. Set it to True to align the text
to the right.
Right-to-Left Select False for English and other languages that are written from left to right. Select True for
Hebrew and those languages read from right to left.
Show CD-ROM Select True to display CD-ROM volumes in the volume select combo.
Show Fixed Select True to display hard drives in the volume select combo.
Show Floppy Select True to display floppy drives in the volume select combo.
Show RAMDisk Select True to display RAM volumes in the volume select combo.
Property Description
Show Remote Select True to display mapped network drives in the volume select combo.
Show Removable Select True to display removable drives in the volume select combo.
Sunken Set this property to True to give the volume select combo a recessed, three-dimensional
appearance, as volume select combos usually look. False gives it a flat appearance.
Tab Index Provide an integer, starting with 0 (zero) that, along with the other controls on this dialog,
excluding controls such as static text, determines the order in which each one will receive
focus when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this volume select combo will receive focus within the tab
order.
Text Style Select the font style, size, and color, if available, that you want the volume select combo’s text
to be displayed in. Leaving the value as <Default> displays the font contained in the
DefaultUIFont property.
Tooltip This property holds the text that will be displayed when the mouse hovers over this control.
Since the text is language specific, this value is always associated with a string ID. Editing the
value in the property sheet changes the string ID’s value for the current language.
Top Distance from the top of the dialog to the top of the volume select combo in installer units.
Visible True means that the volume select combo is visible, and False that it is hidden. You can also
make it visible by editing its condition in the Behavior editor.
Project: Volume cost list controls are available only for use in Basic MSI projects.
A volume cost list displays the cost—or disk space requirements—of the installation, associated with
each volume or drive.
The list has five possible columns. The headings for each column come from the UIText table, which is
exposed only in the Direct Editor, which in turn points to the value of string table entries to provide
localized strings. The keys in the UIText table for each column are listed below, along with their default
English values:
• VolumeCostVolume—Volume
• VolumeCostSize—Disk Size
• VolumeCostAvailable—Available
• VolumeCostRequired—Required
• VolumeCostDifference—Differences
Each volume cost list control has the following properties available for specifying how it is displayed.
Property Description
Name Enter a name for this volume cost list. The name must be unique among all of the controls
in your project.
Available Col Width Specify the default width in installer units, which are defined as 1/12 of the height of the
system font, of the column labeled Available. This column is hidden if the value is 0 (zero)
or it is left blank.
Base Text Style This font style is used for the contents of the volume cost list if you specify nothing for the
Text Style property.
Cancel Select True if this is the only control on the dialog that will dismiss it. Clicking the cancel
control has the same effect as pressing the Esc key or clicking the Close button on the
title bar. The Cancel or Finish button is usually the cancel control.
This value is ignored if this dialog has its ErrorDialog property set to True.
Context Help This property is reserved for future use. Windows Installer does not currently support
launching context-sensitive help topics from the installation.
Default Select True if this is the only control on the dialog that you want to be the default control,
which means that it is activated when the end user presses the Enter key. The Next or OK
button is usually the default control.
Differences Col Width Specify the default width in installer units of the column labeled Differences. This column
is hidden if the value is 0 (zero) or it is left blank.
Disk Size Col Width Specify the default width in installer units of the column labeled Disk Size. This column is
hidden if the value is 0 (zero) or it is left blank.
Enabled True means that this control is enabled (the end user can interact with it), False that it is
disabled (grayed out).
Left Distance from the left edge of the dialog to the start of the volume cost list in installer
units.
Left Scrollbar Set this property to True to have the vertical scrollbar displayed on the left side of the
volume cost list. This property should be set only when the Right-to-Left property is true.
Other Window Styles Click the ellipsis button (...) to display the Other Window Styles dialog box.
Required Col Width Specify the default width in installer units of the column labeled Required. This column is
hidden if the value is 0 (zero) or it is left blank.
Right-Aligned The default value of False aligns the text to the left of the control. Set the property to True
to align the text to the right.
Right-to-Left Select False for English and other languages that are written from left to right. Select True
for Hebrew and those languages read from right to left.
Property Description
Show CD-ROM Select True to display CD-ROM volumes in the volume select combo.
Show Fixed Select True to display hard drives in the volume select combo.
Show Floppy Select True to display floppy drives in the volume select combo.
Show RAMDisk Select True to display RAM volumes in the volume select combo.
Show Remote Select True to display mapped network drives in the volume select combo.
Show Removable Select True to display removable drives in the volume select combo.
Sunken Set this property to True to give this volume cost list’s border a recessed, three-
dimensional appearance. Otherwise, it will have a flat, box-like appearance.
Tab Index Provide an integer, starting with 0 (zero) that—along with the other controls on this dialog
and excluding controls such as static text—determines the order in which each control
area will receive focus when the end user presses the Tab button.
Tab Stop The tab stop indicates whether this edit field will receive focus within the tab order.
Text This property holds the text that is used for the control’s label. Although you cannot see
the label, it will be available for screen readers. Since the text is language specific, this
value is always associated with a string ID. Editing the value in the property sheet changes
the string ID’s value for the current language.
Once you click the Text value to edit it, an ellipsis button (...) appears to allow you to
select a string ID and edit the default language’s string table.
Text Style Select the font style, size, and color (if available) in which you want the volume cost list’s
contents to be displayed. Leaving the value as <Default> displays the font contained in
the DefaultUIFont property.
Tooltip This property holds the text that will be displayed when the mouse hovers over the
control. Since the text is language specific, this value is always associated with a string
ID. Editing the value in the property sheet changes the string ID’s value for the current
language.
Top Distance from the top of the dialog to the top of the volume cost list in installer units.
Visible True means that the volume cost list is visible, and False that it is hidden. You can also
make it visible by editing its condition in the Behavior editor.
Volume Col Width Specify the default width in installer units of the column labeled Volume. This column is
hidden if the value is 0 (zero) or it is left blank.
Width Width of the volume cost list and label in installer units.
1. Open the layout for the dialog that contains the button you want to copy.
2. Select the push button and press CTRL+C.
3. Open the second dialog in the Dialog Editor and press CTRL+V to paste the control in the dialog.
The push button is pasted with the same relative size and position as the original. Its other properties are
also identical to the original’s. The copy of the push button is given a unique name based on the type of
control it is. However, you must edit the new control’s behavior, since that information is not copied
over (Basic MSI projects).
Note: Radio button groups are a special case. When you copy the group, all of its radio buttons are copied for you. You
cannot copy a radio button by itself.
1. Right-click the control and click Cut, or press CTRL+X. A Delete Control dialog box opens to
inform you that deleting the control also deletes any associated conditions and actions.
2. Click Yes to continue cutting the control from the current dialog.
3. Open the second dialog in the Dialog Editor and press CTRL+V to paste the control in the dialog.
When you are done pasting the control into the new location, specify the control’s properties and
behavior.
Project: For installation projects: you can add additional languages, and therefore additional string tables, in an
installation project’s Setup Languages property.
For Merge Module projects: you can add additional languages, and therefore additional string tables, in your project’s
Language property.
The String Tables view contains a string table for each language supported in your project.
Each string table must have identical string IDs:
• Adding an entry to any string table causes the same ID to be added to each string table.
• Any string tables added to the project will contain the same string IDs as the others.
The values that appear for string IDs while you are working in InstallShield come from the project’s
default language.
When you finish authoring your project, you can export the string table for each language to a text file to
send out for translation.
Property Sheets
When you are editing a property sheet and modifying a property that requires a string value that can be
presented to end users, you must use a string identifier.
Task To work with a property sheet and an associated string table entry:
1. In the open property sheet, click a property that accepts localizable text (such the feature
Description property).
2. Click the String Table tab below the property sheet.
3. Right-click the entry that you want to use for the property, and then click Select string.
If you do not select a value and just edit the property directly, InstallShield creates a new string ID and
assigns your text to the default language’s value.
Dialog Editor
Many of the controls in the Dialog Editor accept strings that are displayed to the end user. For example,
the Text and Tooltip properties always require localizable text.
Using a string table entry in the Dialog Editor is similar to selecting string IDs in property sheets.
Task To work with the Dialog Editor and a control’s property that uses localizable text, do one of the following:
• Click the property sheet and edit the string. Doing so changes the value of the string table entry for
the current language. When you enter a text value without first selecting a string, InstallShield
creates a new string ID in the string tables.
• When you click the Text value to edit it, an ellipsis button (...) appears inside the property sheet.
Click the button to view the string table for the current language.
The major difference between the property sheets and the dialog control properties is that the property
sheets always display the string table for the default language. When you edit a dialog’s layout, however,
you must first select the language of the dialog. Then, all strings displayed in the dialog and in the
property sheet are from the current language of the dialog that you are editing.
• Right-click anywhere in the String Table editor and click New. InstallShield adds the same ID to
each string table with an empty value and comment.
• Right-click in the string table editor and click Create & Set. Edit the new entry in the resulting
dialog, and click OK. InstallShield creates an entry in the string table for each language in your
installation project with the same value and comment that you provide.
Since you must use a string ID for properties that accept localizable text, InstallShield adds a new entry
to the string tables whenever you try typing a value into a property sheet without selecting an ID from
the string table. Your new string ID is named NEW_STRINGN, where N is a successive number.
Caution: Do not confuse editing an existing value for the default language in the property sheet with entering a new string
ID by entering text into the property sheet. Once you have selected a string ID for the property, deleting the text in the
property sheet merely deletes the current value; it does not replace the current string ID with a new one.
Properties that accept localizable text, such as the feature Display Name property, require that you use a
string ID. They present you with a string table for the default language.
• Open the General Information view. In the General Information explorer, click the language
whose string table you want to modify. Double-click a string ID, value, or comment in the String
Table editor to modify the entry.
• If you are editing a property from within one of the views in InstallShield, click the String Table
tab at the bottom of the InstallShield interface. Double-click a string ID, value, or comment in the
String Table editor to modify the entry.
Note that if you rename a string ID, it is renamed in every string table.
Windows Installer permits special formatting for many of its data types, such as using brackets to
reference the value of an installer property. For more information on data types, see Column Data Types
in the Windows Installer Help Library.
New and newly modified string table entries carry a time stamp in the Modified column. Default entries
provided by InstallShield do not. This column is useful for sorting installation project strings according
to the date that they were changed so that you can export selected strings and send them out for
translation.
Task To find all the occurrences of a particular string ID within your installation project:
Right-click the string table entry (in either the String Table view, property sheet, or Dialog Editor) and
click Find String ID in Project.
The results of your search are displayed in the Output window at the bottom of the InstallShield
interface.
Finding Strings
Replacing Strings
Displaying Billboards
Billboards are displayed only in installations that display a background window. A background window
is—by default—not displayed, and does not meet current standards for user interfaces.
You can use billboards to pass information to your customers during the installation process. Billboards
can be used to communicate, advertise, educate, and entertain the end user. Billboards offer
information—new features of the product being installed or other products from your company—to your
end users. Each billboard is a bitmap (.bmp) file that you can customize for complete control over the
look and feel of the file transfer.
The length of time that a billboard is displayed depends upon the number of billboards in your
installation project. The display time is equal to 1 divided by the number of billboards. For example, if
you have four billboards in your installation, each billboard is displayed for 25% of the installation time.
Billboards are displayed only in installations that display a background window. A background window
is by default not displayed, and does not meet current standards for user interfaces.
To display a background window, modify the script’s OnShowUI event handler function by removing the
double slashes from the beginnings of the following seven lines of code:
//if ( LoadStringFromStringTable( "TITLE_MAIN", szTitle ) < ISERR_SUCCESS ) then // Load the
title string.
// szTitle = IFX_SETUP_TITLE;
//endif;
//SetTitle( szTitle, 24, WHITE );
//Enable( FULLWINDOWMODE );
//Enable( BACKGROUND );
//SetColor( BACKGROUND, RGB( 0, 128, 128 ) );
The first step in adding billboards to your project is to create the bitmap (.bmp) files that serve as your
installation’s billboards. When your bitmap files are properly named, you can add your billboards to
your installation.
Billboard files must follow a designated naming convention. Each file name must begin with bbrd and
end with the sequential number of the billboard (from 1 through 99). For example, the billboard file that
you want displayed first should be named bbrd1.bmp, and the billboard file that you want displayed
second should be named bbrd2.bmp.
Adding Billboards
Billboards are displayed according to the numeric order of their file names. A billboard file named
bbrd2.bmp is displayed to the end user before a file named bbrd3.bmp, and after a file named bbrd1.bmp.
1. Remove the billboard files whose order should change. (For more information, see Removing
Billboards.)
2. Using Windows Explorer, rename the billboard files so that they are in the appropriate numeric
order.
3. Add the renamed files, as explained in Adding Billboards.
Caution: There cannot be any numbers missing from the file name sequence for your billboards. For example, if you
added bbrd1.bmp, bbrd2.bmp, and bbrd4.bmp to your installation project, then bbrd1.bmp and bbrd2.bmp are
displayed to the end user and bbrd4.bmp is not because bbrd3.bmp is missing from the sequence. If bbrd1.bmp is
missing from the sequence, none of the billboards is displayed.
Removing Billboards
The SetDisplayEffect function enables you to display your billboards with different special effects when
they first appear on the main installation window. Choose one of this function’s options before you
display a bitmap with PlaceBitmap or display billboards during file transfer.
By default, the installation displays billboards in the center of the main installation window. To specify a
different location, call the PlaceWindow function with the BILLBOARD option. For example, to place
your billboards 10 pixels from the upper-left corner of the screen, make the following call:
PlaceWindow (BILLBOARD, 10, 10, UPPER_LEFT);
Since billboards are displayed only during file transfer, ensure that you call PlaceWindow before you
begin file transfer.
function NetBrowse( )
STRING svSelectedDir[MAX_PATH + 1];
NUMBER nReturn;
begin
svSelectedDir = PROGRAMFILES;
FLEXnet Connect provides a mechanism that enables you to automatically notify your Web-connected
end users when patches, updates, and product information for your application are ready for release.
FLEXnet Connect helps you reduce the number of end users running old releases of your products and
to prevent them from installing the wrong updates from your Web site.
Initial Deployment
1. Use InstallShield to create the installation project for your application. FLEXnet Connect should be
enabled in this project. When you enable FLEXnet Connect, InstallShield includes the Software
Manager in your installation. This desktop tool ships with your application and provides a tool for
end users to view available updates.
2. Register your application with the FLEXnet Connect Publisher site, a Web-based management
portal.
3. Install your application and test it.
FLEXnet Connect includes a variety of options that can be purchased together for a complete solution,
or separately for a customized solution. To learn more, visit the Macrovision Web site. To access the
FLEXnet Connect documentation, see the FLEXnet Connect Help Library.
Caution: Enabling automatic update notifications in your project adds about 600 KB of files to your installation. These
files must be distributed with your application in order for FLEXnet Connect to work. If you cannot afford to include these
files in your installation because of bandwidth limitations or other reasons, you can select No to disable automatic update
notifications. However, FLEXnet Connect cannot be used to deploy an update unless automatic notification is enabled in
the original installation when you distribute it to your end users. Therefore, if you select No, you will not be able to later
take advantage of the automatic update notification features.
4. Assign your product a version number that is in packed DWORD format—for example, 2.01.345.
FLEXnet Connect works only with version numbers in packed DWORD format. For guidelines on
assigning a version number, see How FLEXnet Connect Identifies Products.
a. On the Project menu, click Settings. The Project Settings dialog box opens.
b. Click the Application tab.
c. In the Product Version box, specify the version number.
Note: If you pass a null string ("") as the second argument to UpdateServiceRegisterProduct (as is done in the default
code for the OnMoveData event handler function), only the first two parts of your packed DWORD format version
string—that is, major.minor—are registered as the version with the target machine’s FLEXnet Connect database. To
register the full version string—that is, major.minor.build—pass the system variable IFX_PRODUCT_VERSION as the
second argument to UpdateServiceRegisterProduct.
5. To register your product with FLEXnet Connect, select the Is Product/Version Registered
setting and follow the directions in the help pane.
Caution: Enabling automatic update notifications in your project adds about 600 KB of files to your installation. These
files must be distributed with your application in order for FLEXnet Connect to work. If you cannot afford to include these
files in your installation because of bandwidth limitations or other reasons, you can select No to disable automatic update
notifications. However, FLEXnet Connect cannot be used to deploy an update unless automatic notification is enabled in
the original installation when you distribute it to your end users. Therefore, if you select No, you will not be able to later
take advantage of the automatic update notification features.
Task To remove the check-for-updates check box from the Setup Complete dialog:
1. In the Shortcuts view, right-click one of the destination directories and select New Shortcut to
Preexisting file.
2. Use the following properties for the shortcut:
• Basic MSI
• InstallScript MSI
Task To add a check-for-updates check box to the Setup Complete dialog for a Windows Installer–based
installation:
Task To add a check-for-updates check box to the Setup Complete dialog for an InstallScript project:
function OnFirstUIAfter()
STRING szTitle, szMsg1, szMsg2, szOpt1, szOpt2;
NUMBER bvOpt1, bvOpt2;
NUMBER bShowUpdateServiceDlg;
begin
ShowObjWizardPages(NEXT);
szTitle = "";
szMsg1 = "";
szMsg2 = "";
szOpt1 = "";
szOpt2 = "";
bvOpt1 = FALSE;
bvOpt2 = FALSE;
// Set this to true if you have FLEXnet Connect enabled, and if you want to check for
updates.
// Note: Some FLEXnet Connect editions do not support checking for updates
programmatically.
bShowUpdateServiceDlg = TRUE;
//{{IS_SCRIPT_TAG(Dlg_SdDinishEx)
if ( BATCH_INSTALL ) then
SdFinishReboot ( szTitle , szMsg1 , SYS_BOOTMACHINE , szMsg2 , 0 );
else
endif;
else
SdFinish ( szTitle , szMsg1 , szMsg2 , szOpt1 , szOpt2 , bvOpt1 , bvOpt2 );
endif;
endif;
//}}IS_SCRIPT_TAG(Dlg_SdDinishEx)
end;
Note: The check box in the run-time dialog cannot be displayed for InstallShield Developer 7.02 Basic MSI projects or for
Express 3.53 projects that have been upgraded to InstallShield Developer 7.03.
When creating an installation, you may find it necessary to provide server side support for some
technology that will be installed on a target system. InstallShield makes it easy to configure server side
installations or manage COM+ server applications and application proxies. InstallShield provides
support for Internet Information Services, SQL, and component services which are discussed in this
section of the help library.
• Set required SQL server/script properties (server name, database name, authentication method,
etc.).
• Set SQL script for execution during installation or uninstallation.
Note: The import database functionality applies to the Microsoft SQL Server Database. Oracle users should refer to the
Oracle Web page on Oracle Database Utilities for information on utilities that may work in conjunction with InstallShield.
Microsoft SQL Query Analyzer is part of the Microsoft SQL Server installation. This tool can be run only on SQL Server
databases.
To run an installation project with SQL support on a Windows 95 or 98 machine, your system will need to support MDAC
setup prerequisites.
InstallShield lets you specify whether new SQL database connections that you add to your project should
share the same Windows Installer properties by default.
For example, if you want connections to share the same default Windows Installer properties, you could
add one connection to your project in the SQL Scripts view, and specify a catalog name of
MyConnection. If you add a second connection to your project, InstallShield uses the same catalog
name of MyConnection for that second connection. If you change the catalog name of either
connection, InstallShield automatically updates the catalog name of the other connection, since both are
based on the same Windows Installer property.
Task To specify whether SQL connections should share the same Windows Installer properties:
1. On the Tools menu, click Options. The Options dialog box opens.
2. Click the SQL Scripts tab.
3. Select or clear the Generate unique Windows Installer properties for new connections
check box:
• To share Windows Installer properties between any new connections that you add, clear this
check box.
• To use different Windows Installer properties for any new connections that you add, select this
check box.
If you select the check box and then add a second connection to your project, InstallShield creates a new
set of Windows Installer properties for the second connection.
If you clear the check box and then add a second connection, InstallShield uses the default Windows
Installer properties for the second connection. The default Windows Installer properties are the ones
that were added for the first connection that you added to your project.
Tip: If you want to override a Windows Installer property for an existing connection, add a new property in the Property
Manager. Then, in the SQL Scripts view, select the connection. On the Advanced tab, select the name of the new property
in the appropriate list.
Project: For Basic MSI projects, the built-in SQLLogin dialog is designed to work with the default Windows Installer
properties for the first SQL connection that was added to the project. If you select the Generate unique Windows
Installer property for new connections option, you need to duplicate the dialog for each connection to work with the
new Windows Installer properties.
The InstallScript language includes many built-in SQL run-time (SQLRT) functions that begin with a
prefix of SQLRT. Some of the functions are available only in InstallScript projects, some are available
only in InstallScript MSI projects, and some are available in both project types.
The SQLRT functions require that you configure SQL information through the SQL Scripts view; the
configuration information is written to the SQLRT.ini file so that the SQL run-time functions work
properly. For InstallScript projects, the SQLRT functions are in the SQLRT.obl file, and they call the
SQLRT.dll file. For InstallScript MSI projects, the SQLRT functions are in the SQLCONV.obl file, and they
call the ISSQLSRV.dll file. These support files are added automatically to your project when you use the
SQL Scripts view.
The SQLRTInitialize2 function initializes the SQL server run time. In InstallScript projects, the
SQLRTInitialize2 function is called automatically during the OnSQLServerInitialize event handler. In
InstallScript MSI projects, the SQLRTInitialize2 function is called automatically during the OnSQLLogin
event handler. If you need to call one of the SQLRT functions before the OnSQLServerInitialize or
OnSQLLogin events, you must first call the SQLRTInitialize2 function.
Note: In earlier versions of InstallShield, the SQLRTInitialize function was used to initialize the SQL server run time in
InstallScript projects. This function has been superseded by the SQLRTInitialize2 function.
Task To add a new SQL script once you have created a new SQL connection:
Tip: You can also add scripts to your project by importing or inserting them. For more information, see Inserting and
Importing SQL Scripts.
Note: Once you add a new script, you can open it in Microsoft SQL Query Analyzer to test, edit, and syntax-check the
script when you right-click the script file in the explorer. However, you must have this tool (isqlw.exe) installed on your
system for it to be available. This tool is installed by Microsoft SQL Server or the Microsoft SQL Server client tools.
• Importing a script file copies the script file to the folder containing the script files for your project.
The script files that you import can be stored somewhere on your system, or they can be stored in a
repository.
• In the Repository Items box, click the SQL script file (.sql) that you want to add to your
project.
• If the script file that you want to import is not stored in the repository, click the browse button to
select it.
5. Click OK.
When you insert or import a new script to your project, InstallShield adds a new component for the
script. You must associate the script with a feature. If one does not exist, the Create a New Feature dialog
box opens when you add the SQL script, prompting you to create a new feature. You can change the
script-feature association later by using the Select Features the SQL Script Belongs to area on the
General tab in the SQL Scripts view for the SQL script.
Task To import an existing Microsoft SQL Server database and then generate a script file from it:
Note: The import database functionality applies to the Microsoft SQL Server Database. The script generated by the
Database Import Wizard is not compatible with the MySQL database server.
Project: In an InstallScript project, if you are working on a script that had overridden OnFirstUIBefore before upgrading to
InstallShield and is not calling OnSQLServerInitialize, then you should add that code to your script file.
Note: You can open your script file in Microsoft SQL Query Analyzer to test, edit, and syntax-check the script when you
right-click the script file in the explorer. However, you must have this tool (isqlw.exe) installed on your system for it to be
available. This tool is installed by Microsoft SQL Server or the Microsoft SQL Server client tools.
Task To specify the schema version for your SQL script file:
Tip: When you specify a number for the Schema Version setting and InstallShield adds the custom InstallShield table for
storing the schema version number on the target database, the data is not automatically removed upon uninstallation.
Therefore, if you want the installation to be able to roll back the changes, you need to create a custom script upon
uninstallation to drop the InstallShield table.
Specifying the SQL Script Order in Basic MSI and InstallScript MSI Projects
The order in which a connection’s SQL scripts are listed in the SQL Scripts view is the order in which
Basic MSI and InstallScript MSI installations run the SQL scripts. For example, if you create a
connection in the SQL Scripts view and add two SQL scripts to that connection, the script that is listed
first under the SQL connection is the one that the installation runs first.
Task To change the order in which a connection’s SQL scripts are run:
Property Description
Property Description
IS_SQLSERVER_DO_NOT_USE_REG Specify not to use the stored SQL Server login information
written in the registry. Since the SQLLogin dialog is not
displayed in maintenance and uninstall modes, InstallShield
stores the login information specified during installation. If
you do not want this behavior, set the
IS_SQLSERVER_DO_NOT_USE_REG property.
IS_SQLSERVER_LOCAL_ONLY Specify to show only the local SQL Server in the SQL
Server browse combo box and list box controls. By
default, the SQL Server(s) on the network will be listed.
Project: For Windows Installer–based projects, all connections are linked to the standard SQL Login dialog. To display
multiple SQL Login dialogs, you can copy the SQL dialogs from the Dialogs view and modify their behavior and events
similar to the SQL default dialogs. Remember to create new properties, and set them in the connection’s Advanced tab of
the SQL Scripts view. You will use those new properties when you modify the copies of the SQL dialogs that you made.
Task To set up a database server type condition for a script that targets Microsoft SQL Server:
Task To set up a database server type condition for a script that targets MySQL:
You may want your installation to launch a SQL script only if certain conditions are met on the target
system. For example, your SQL script may require that the end user have administrator rights. If an end
user does not have administrator rights, the SQL script is not launched.
Tip: For information on conditions and on condition syntax, see Building Conditional Statements and Conditional
Statement Syntax.
• OnSQLComponentInstalled
OnSQLServerInitialize is called by OnFirstUIBefore, and OnSQLComponentInstalled is called during
file transfer, for each component installed.
Note: If you are working on a script that had overridden OnFirstUIBefore before upgrading to InstallShield and is not calling
OnSQLServerInitialize, then you should add that code to your script file.
endif;
else
//User does not have administrator rights, so we do not run scripts
endif;
end;
Note: You can configure the behavior for script failure in the InstallShield interface when you click a SQL script in the SQL
Scripts explorer, and then go to the Runtime tab. The Script Error Handling section lets you select one of the following
options:
• On Error, Go to Next Script
• On Error, Go to Next Statement
• On Error, Abort Installation
Ensuring that SQL Scripts Are Run Only Against a Full SQL
Server
Installations that include SQL script support allow end users to run the SQL scripts on Microsoft SQL
Server Desktop Engine (MSDE) and on SQL Server Express Edition, by default. If you want end users to
be able to run SQL scripts on only a full SQL Server, you can use the SQL Scripts view to configure that
for any database connection in your installation.
Task To ensure that your SQL script files are not run on MSDE or SQL Server Express Edition:
One way to ensure that your installation runs only on SQL Server machines is to perform a system
search for registry information, store the result in a property, and then use the property in a condition
that you will set. The following step-by-step instructions show how to do this.
Task To ensure that a Windows Installer–based installation runs only on SQL Server machines:
1. In the View List under Behavior and Logic, click System Search.
2. Right-click the grid and click Add. The System Search Wizard opens.
3. In the What do you want to find panel, click Registry entry and click Next.
4. In the How do you want to look for it panel, do the following:
a. In the Registry Root list, click HKEY_LOCAL_MACHINE.
b. In the Registry Key box, type the following text:
Software\Microsoft\Microsoft SQL Server
d. Click Next.
5. In the What do you want to do with the value panel, do the following:
a. In the Store the value in this property box, type the following:
SQLSERVERFOUND
b. In the Additional Options area, select the Store the value in the property and use the
property in an Install Condition option.
c. Click Finish. The Condition Builder opens.
6. Verify the condition, and type a message that you want end users to see if the registry entry is not
found on the system. For example, you can type the following message:
Microsoft SQL Server was not found on this machine. This installation was designed to run
only on the server machine.
7. Click OK.
InstallShield adds an entry to the System Search grid.
RegDBSetDefaultRoot( HKEY_LOCAL_MACHINE );
sKey = "Software\\Microsoft\\Microsoft SQL Server";
sValue = "InstalledInstances";
nResult = RegDBGetKeyValueEx( sKey, sValue, nType, sData, nSize );
abort;
endif;
end;
If you want to install and launch the MySQL ODBC driver before your Windows Installer–based
installation is run, you can include the MySQL Connector 3.51 setup prerequisite in your project.
Task To install and launch the MySQL ODBC driver before your Windows Installer–based installation is run:
Tip: The MySQL Connector ODBC 3.51 setup prerequisite is available only if you have downloaded the installer and added
the setup prerequisite to your system. For detailed instructions, see Including the MySQL Connector ODBC Setup
Prerequisite.
Important: In order to add support for the MySQL ODBC Driver to an InstallScript project, as explained in the following
procedure, you must already have the Microsoft Data Access Components (MDAC) 2.8 setup prerequisite files on your
system. To add these files, open a Basic MSI or InstallScript MSI project. In the Redistributables view, right-click the
Microsoft Data Access Components (MDAC) 2.8 setup prerequisite and click Download Selected Item. InstallShield
downloads the MDAC files and places them in the following location (which is need for step 4g below):
InstallShield Program Files Folder\SetupPrerequisites\Microsoft Data Access Components (MDAC)
2.8.5
Task To install and launch the MySQL ODBC driver before your InstallScript installation is run:
e. Click Open.
f. Right-click in the Files pane and click Insert Folder. The Browse for Folder dialog box
opens.
g. Browse for the following directory:
InstallShield Program Files Folder\SetupPrerequisites\Microsoft Data Access Components
(MDAC) 2.8.5
h. Click OK.
5. In the View List under Behavior and Logic, click InstallScript.
6. In the InstallScript explorer under the Files item, select your script file (.rul).
7. In the script editor pane, add the following sample InstallScript code:
function OnBegin()
STRING svResult;
NUMBER nvResult;
BOOL bIsWindows95, bInstallMDAC;
begin
Note: You cannot delete a database to which you are currently connected.
If you need to remove a SQL database during uninstallation, you can do so through your SQL script. The
following procedure demonstrates how to configure your project and SQL script to delete a Microsoft
SQL Server database.
Tip: As an alternative to the aforementioned procedure, you can perform the same operation completely in SQL script. To
do so, enter the following code in your SQL script:
USE Master
DROP DATABASE DatabaseName
GO
DatabaseName is the name of the database that you want to delete.
The latest Microsoft Data Access Components (MDAC) include support for the Microsoft ODBC for
Oracle drivers. However, the Microsoft ODBC for Oracle driver requires Oracle 10g Instant Client
software to communicate with Oracle database servers. Therefore, Macrovision recommends that you
include the Oracle 10g Instant Client setup prerequisite (for Basic MSI and InstallScript MSI
installations) or launch the Oracle 10g Instant Client .msi file (for InstallScript installations) to ensure
that the Oracle Instant Client is properly configured on the target machine upon installation.
Downloading the Oracle Instant Client and Creating an .msi Package for It
Before you can add Oracle 10g Instant Client support to your Basic MSI, InstallScript MSI, or
InstallScript installation, you must download the Oracle Instant Client from Oracle’s Web site. Oracle
does not provide an installer for the files, so you also need to create an .msi package; you can do so easily
by using the Oracle Instant Client installation project that is available in the InstallShield Program Files
folder.
Task To download the Oracle Instant Client and create an .msi package:
3. Open the Oracle Instant Client installation project in InstallShield. The path for the project is as
follows:
InstallShield Program Files Folder\Support\Oracle Instant Client\instantclient-win32-
10_2.ism
Macrovision created this project for the 10.2.0.2 version of the Oracle Instant Client; however, you
can use this same project for more-recent versions of the Oracle 10g Instant Client, such as 10.2.05,
for example.
4. The name that is displayed at run time during the Oracle 10g Instant Client installation is
Oracle10g Instant Client 10.2.0.2; this name is also used for the .msi file. If you want to change
this name to something else to reflect a different version number, such as 10.2.0.5 or 10.2.0.x, you
can do so:
a. In the View List under Installation Information, click General Information.
b. In the General Information explorer, click Product Properties.
c. In the Name setting, edit the existing text as needed.
5. If you are using a version that was released after 10.2.0.2 and it requires additional dependencies,
add the files or merge modules to the project. For example, Oracle 10g Instant Client 10.2.0.2
requires mfc71.dll, mfc71u.dll, and msvcr71.dll. Therefore, the project includes MFC7.1 and the
Microsoft C Runtime Library 7.1 merge modules.
6. On the toolbar, click the Build button.
InstallShield builds an Oracle 10g Instant Client .msi file and adds it to the following directory so that
you can include the Oracle 10g Instant Client in your InstallShield projects:
Tip: If you are using a version that was released after 10.2.0.2, open the Oracle 10g Instant Client 10.2.0.2 setup
prerequisite in the Setup Prerequisite Editor. Rename the prerequisite to reflect the appropriate version number. In
addition, update the conditions to reflect the appropriate version number.
For instructions on how to add the Oracle 10g Instant Client to Basic MSI or InstallScript MSI
installations, see Installing the Oracle 10g Instant Client from a Windows Installer-Based Installation.
For instructions on how to add the Oracle 10g Instant Client to InstallScript installations, see Installing
the Oracle 10g Instant Client from an InstallScript Installation.
If you want to install the Oracle 10g Instant Client before your installation is run, you can include the
Oracle 10g Instant Client setup prerequisite in your project.
Note that before you can include the setup prerequisite, you must download the Oracle Instant Client
and create an .msi package; for more information, see Connecting to an Instance of Oracle and Running
SQL Scripts.
Task To include the Oracle 10g Instant Client setup prerequisite in your project:
• Oci.dll is not found in all Windows search directories (PATH environment variable).
If you want to install the Oracle 10g Instant Client before your installation is run, you can launch the
Oracle 10g Instant Client .msi file in your installation.
Note that before you can include the Oracle 10g Instant Client .msi file, you must download the Oracle
Instant Client and create the .msi package; for more information, see Connecting to an Instance of
Oracle and Running SQL Scripts.
Task To include support for the Oracle 10g Instant Client in your project:
e. Click Open.
f. Right-click in the Files pane and click Insert Folder. The Browse for Folder dialog box
opens.
g. Browse for the following directory:
InstallShield Program Files Folder\SetupPrerequisites\Microsoft Data Access Components
(MDAC) 2.8.5
h. Click OK.
3. In the View List under Behavior and Logic, click InstallScript.
4. In the InstallScript explorer under the Files item, select your script file (.rul).
5. In the script editor pane, add the following sample InstallScript code. Note that the script example
uses Oracle10g Instant Client 10.2.0.2.msi as the name of the file that you added in step 2d. If
your .msi file has a different name, change the script accordingly.
function OnBegin()
STRING svResult;
NUMBER nvResult;
BOOL bIsWindows95, bInstallMDAC;
begin
end;
The following procedure demonstrates how to create an installation that creates a SQL Server database
through customized SQL script.
Task To create an installation that creates a SQL Server database on the target machine by running customized
SQL script:
b. In the SQL Scripts explorer, click the NewConnection1 item, and then click the General
tab.
c. In the Default Target Server Name (optional) box, type TESTSQLSERVER.
d. Clear the Create Catalog If Absent check box.
e. In the Connect using area, select the Server authentication using the Login ID and
password below option.
f. In the Login ID box, type sa. Leave the Password box blank.
g. Click the Requirements tab.
h. Ensure that the Microsoft SQL Server check box is selected and the MySQL and Oracle
check boxes are cleared.
6. Add and configure a new SQL script for NewConnection1:
a. In the SQL Scripts explorer, right-click NewConnection1 and click New Script.
b. Change the name of the script to NewScript1.
c. In the SQL Scripts explorer, click NewScript1, and then click the Script tab.
d. In the script editor pane, add the following script:
CREATE DATABASE [TestDB] ON (NAME = N' TestDB', FILENAME = N'C:\Program Files\Microsoft
SQL Server\MSSQL\data\testdb.mdf' , SIZE = 3, FILEGROWTH = 10%) LOG ON (NAME = N'
TestDB_log', FILENAME = N'C:\Program Files\Microsoft SQL Server\MSSQL\data\testdb.ldf' ,
SIZE = 1, FILEGROWTH = 10%)
COLLATE SQL_Latin1_General_CP1_CI_AS
The following procedure demonstrates how to create an installation that creates an Oracle schema
through customized SQL script.
Task To create an installation that creates an Oracle schema on the target machine by running customized SQL
script:
j. In the Connect using area, select the Server authentication using the Login ID and
password below option.
k. In the Login ID box, type TEST_USER.
l. In the Password box, type MYPSWD.
m. Click the Requirements tab.
n. Ensure that the Oracle check box is selected and the Microsoft SQL Server and MySQL
check boxes are cleared.
8. Add and configure a new SQL script for NewConnection2:
a. In the SQL Scripts explorer, right-click NewConnection2 and click New Script.
b. Change the name of the script to NewScript2.
c. In the SQL Scripts explorer, click NewScript2, and then click the Script tab.
d. In the script editor pane, add the following script:
CREATE TABLE TestTable (TestColumn1 CHAR NOT NULL PRIMARY KEY)
1. In the Component Services view, select the COM+ application that you would like to configure if
you have not already done so.
2. On the Installation property sheet, select the Server check box.
Note: You must select the Proxy check box, the Server check box, or both check boxes. Once you clear one of
these check boxes, the other check box remains selected but it is no longer available; this prevents you from clearing
both check boxes.
3. Select the Refresh the COM+ settings from the client machine at build check box if
appropriate.
4. If your installation does not include the COM+ application proxy support, clear the Proxy check
box
When you add a COM+ server application to your installation, a corresponding component is created
and added to all of the features that are associated with the proxy component. This component has the
COM+ application’s server .dll files.
Note: If the selected COM+ application includes both server and proxy installations, you can add installation conditions so
that the appropriate COM+ application is installed on the target machine. For more information, see Including a COM+
Application that Targets Servers and Client Machines.
1. In the Component Services view, select the COM+ application that you would like to configure if
you have not already done so.
2. On the Installation property sheet, clear the Server check box if your installation does not include
the COM+ server application.
3. Select the Proxy check box.
Note: You must select the Proxy check box, the Server check box, or both check boxes. Once you clear one of
these check boxes, the other check box remains selected but it is no longer available; this prevents you from clearing
both check boxes.
4. In the Remote Server Name box, specify the name of the remote server computer where the
application resides. You can type the exact name or use the default [REMOTESERVERNAME]
property, which is automatically created when you select the Proxy check box for a COM+
application in your installation.
Note: The default value for the [REMOTESERVERNAME] property is the name of the machine used to add the
COM+ application to the installation project in InstallShield. To change the value of the [REMOTESERVERNAME]
property, use the Property Manager view.
If you would like the end user to be able to specify the remote server, add a Remote Server edit field control to an
end-user dialog in the Dialogs view. Set the Property value of this control to REMOTESERVERNAME.
5. Select the Enable distributed COM on the client machine check box if appropriate. Clear this
check box if you know that distributed component object model (DCOM) is already enabled on all
client machines and you will not have administrative privileges on them.
If you select this check box, Y is written at installation time to the EnableDCOM entry of the
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Ole registry key to enable DCOM.
Note: End users can enable or disable DCOM on their machines using the Component Services administrative tool in
the Control Panel. However, the application proxy will not work on a client machine if DCOM is disabled on that
machine. For this reason, you may want to select the Enable distributed COM on the client machine check box.
If an end user uninstalls the application proxy support, the EnableDCOM registry entry is not changed, even if the
installation process involved changing this registry entry to Y on the target machine.
When you add a COM+ application proxy to your installation, a corresponding component is created
and added to all of the features that are associated with the server component. This component has the
COM+ application’s server .dll files. These server files are installed on the client machine for the type
libraries.
Note: If the selected COM+ application includes both server and proxy installations, you can add installation conditions so
that the appropriate COM+ application is installed on the target machine. For more information, see Including a COM+
Application that Targets Servers and Client Machines.
Task To include a COM+ application in an installation that targets both servers and client machines:
8. In the Condition box under the Proxy check box, type the following:
COMPLUSTYPE="Proxy"
Note: A Web site is not created on a target machine unless a virtual directory that is associated with it is installed. That is,
if you create a Web site in the Internet Information Services view but you do not add a virtual directory, the installation
does not create the Web site at run time.
• Web service extensions, application pools, and all of the associated properties are available only on
machines with IIS 6 or later.
On systems with IIS 7, Web service extensions require that the IIS Metabase and IIS 6 Configuration
Compatibility feature be installed. If it is not installed, the installation’s log file may show error
-2147467259 to inform you that this feature may be required.
For information on how to determine whether a Windows Vista or Windows Server “Longhorn”
system has the IIS Metabase and IIS 6 Configuration Compatibility feature installed, see
Determining Whether a Target System with IIS 7 Has the IIS 6 Metabase Compatibility Feature.
• Windows Vista and Windows Server “Longhorn” systems store settings for individual Web sites and
virtual directories in configuration files that are located at the physical path that you specify in your
installation project—in the Local Path setting or the Network Directory setting on the Home
Directory tab (for a Web site) or the Virtual Directory tab (for a virtual directory) in the Internet
Information Services view. Therefore, each Web site or virtual directory should have a unique
physical path. Otherwise, you may notice unexpected behavior, especially in testing environments, if
you have two different virtual directories with the same physical path.
For example, if you have two virtual directories that have the same physical path, and directory
browsing is enabled in one but not the other, the directory browsing setting for the second virtual
directory that is created overrides the setting for the first virtual directory.
• On systems that have Windows Server 2003, if IIS 6 is not installed, other IIS directories and sites
are still created. IIS 6-specific settings are skipped.
• IIS 5.1 for Windows XP Professional can service only one Web site at a time. This is a limitation of
IIS 5.1.
• InstallShield supports version 4 and later of IIS. It does not support the version of IIS that is
installed with the NT Option Pack on NT Workstation—only the version that is installed to the NT
server.
When you create a Web project or add a virtual directory to your project, an entry is added to the System
Search view to search for the version of IIS installed on the target system. The IIS_VERSION property is
set by entries in the RegLocator and AppSearch tables (available in the Direct Editor), which
determine the version of IIS that is installed.
The IIS_VERSION property contains the IIS version number. If you need to determine the IIS version
that is installed, check the value of this property.
• If the end user installs IIS and then chooses to retry, the installation checks for IIS again, and
continues with the installation. If the end user does not install IIS but still chooses to retry, the
installation checks for IIS again and then displays the dialog again.
• If the end user chooses to ignore, the installation continues, but IIS Web sites, virtual directories,
and other IIS elements are not configured.
Note: InstallShield does not support the creation of Web sites on target machines other than the one on which the
installation is running.
A Web site is not created on a target machine unless a virtual directory that is associated with it is installed. That is, if you
create a Web site in the Internet Information Services view but you do not add a virtual directory, the installation does not
create the Web site at run time.
Project: If you are creating an application pool in an InstallScript project that you want to be associated with a virtual
directory or Web site, you must create the application pool and the virtual directory or Web site within the same
component. This ensures that the application pool is created before the virtual directory or Web site is created. This is a
requirement of IIS 6 and is not a limitation for Basic MSI or InstallScript MSI projects.
Task To specify whether a Web server should allow the CMD command to be used for SSI #exec directives:
1. In the View List under Server Configuration, click Internet Information Services.
2. In the center pane, click the Web Sites explorer. InstallShield displays the Web server settings in
the right pane.
3. For the SSIEnableCmdDirective registry value setting, select the appropriate option:
• Ignore—Do not change the SSIEnableCmdDirective registry value on the target system. This is
the default option.
• FALSE (0)—Set the SSIEnableCmdDirective registry value on the target system to 0. This
prevents the #exec CMD directive of server-side includes to be used to execute shell commands.
Note that if you select this value and an IIS Web server has applications that rely on #exec CMD
directives, those applications may stop working properly after your installation project’s Web
site and virtual directory are installed.
• TRUE (1)—Set the SSIEnableCmdDirective registry value on the target system to 1. This allows
the #exec CMD directive of server-side includes to be used to execute shell commands.
If you select the FALSE or TRUE options, InstallShield stores the value—either 0 for FALSE or 1 for
TRUE—in the INSTALLSHIELD_SSI_PROP property.
If one or more virtual directories, application pools, or Web service extensions in your installation are
installed on a target system and you selected the FALSE or TRUE options for the
SSIEnableCmdDirective registry value setting, the SSIEnableCmdDirective registry value is
updated on the target system.
Note: If your product is uninstalled from a target system, the SSIEnableCmdDirective registry value is not changed, even
if its value was changed during installation.
Note: A Web site is not created on a target machine unless a virtual directory that is associated with it is installed. That is,
if you create a Web site in the Internet Information Services view but you do not add a virtual directory, the installation
does not create the Web site at run time.
Task To create a Web site and a virtual directory on the target system at run time:
1. In the View List under Server Configuration, click Internet Information Services.
2. Right-click the Web Sites explorer and click Add Web Site. InstallShield adds a new Web site.
3. Select the Web site to configure its settings.
4. Right-click the new Web site and click New Virtual Directory. InstallShield adds a new virtual
directory.
5. Select the virtual directory to configure its settings.
If an end user runs your installation on a target system that already has the Web site that you configured
in the Internet Information Services view, the virtual directories that are tied to that Web site in your
project are installed. However, none of the properties that are set in the Internet Information Services
view for that Web site are applied to the existing Web site on the target system.
Tip: To learn how virtual directories are associated with components and features, see Feature and Component
Associations for IIS Support.
Project: For InstallScript projects, in order to ensure that a parent virtual directory is installed before its child virtual
subdirectory, the component that contains the parent virtual directory must be installed before the component that
contains the child virtual subdirectory.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site that should contain the nested virtual directory.
3. Right-click the new Web site and click New Virtual Directory. InstallShield adds a new virtual
directory.
4. Click the General tab.
5. In the Name setting, indicate the name of the existing directory, as well as the name of the nested
virtual subdirectory that you want to create. Separate both names with a slash.
For example, to create a virtual directory called MySubDirectory under the existing virtual
directory called VirtualDirectory, enter the following:
VirtualDirectory/MySubDirectory
Note: If the parent directory does not already exist on the target system, the target system displays an error when the
end user opens the directory in the IIS Manager.
Task To specify the TCP port and site numbers for a Web site:
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site that you want to configure.
3. Click the Web Site tab.
4. In the TCP Port and Site Number boxes, enter the appropriate numbers.
Run-Time Behavior
At run time, if the Web site does not exist on the target system, the installation creates it according to the
following rules:
Table 16-2: Run-Time Results for Various Sample TCP Port and Site Number Setting Values
0 Any non-zero number Since the TCP Port setting is 0 but the Site Number setting
is not 0, the installation installs the Web site to the first site
number on the system.
For example, if the first site number on the target system
is 1, the installation installs the virtual directory under site
number 1.
80 (a non-zero number) 0 (the default value) Since the Site Number setting is 0 but the TCP Port setting
is not 0, the installation installs the virtual directory to the
Web site that is running on the port that is specified in the
InstallShield project—in this example, port 80.
81 (a non-zero number) 3 (a non-zero number) Since neither setting is 0, the installation installs the virtual
directory under the Web site whose site number matches
the one specified in the InstallShield project—in this
example, site number 3.
Note: A Web site is not created on a target machine unless a virtual directory that is associated with it is installed. That is,
if you create a Web site in the Internet Information Services view but you do not add a virtual directory, the installation
does not create the Web site at run time.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site whose host header name you want to specify.
3. Click the Web Site tab.
4. For the Host Header Name setting, type the host header name that you want to use. For example:
www.mycompany.com
Task To specify a SSL certificate that should be installed for a Web site:
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site whose SSL certificate you want to specify.
3. Click the Directory Security tab.
4. In the SSL Certificate list, select Browse to certificate file. The Open dialog box opens.
5. Select the security certificate file (.cer or .pfx) that you want to be installed, and then click Open.
6. If the certificate requires a password, specify it for the SSL certificate password setting.
InstallShield stores the .cer file in the Binary table. At run time, when the installation installs the Web
site and its virtual directories, it also installs the SSL certificate.
1. Add an IIS Web site to your project if you have not already done so. InstallShield automatically adds
the predefined path [IISROOTFOLDER] to the Files and Folders view.
2. In the View List under Application Data, click Files and Folders.
3. In the Feature list, select the feature with which you want the file associated.
4. In the Destination computer’s folders pane, add the file to the [IISROOTFOLDER] folder, or
a subfolder of the [IISROOTFOLDER] folder.
5. In the View List under Server Configuration, click Internet Information Services.
6. Create a new virtual directory.
7. In the Web Sites explorer, click the virtual directory that you created, and then click the Virtual
Directory tab.
8. Select the A directory located on this computer option.
9. In the Local Path box, enter the same target directory as the one that contains the new file that you
added in the Files and Folders view.
To quickly add the [IISROOTFOLDER] folder to the box without having to manually type the
folder name, select Browse, create, or modify a directory entry and then select that folder.
At installation, files are copied to the target directory folder. In addition, the virtual directory is
configured for that folder on the target system if IIS is present.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, right-click the virtual directory and click Delete.
Project: If you are creating an application pool in an InstallScript project that you want to be associated with a virtual
directory or Web site, you must create the application pool and the virtual directory or Web site within the same
component. This ensures that the application pool is created before the virtual directory or Web site is created. This is a
requirement of IIS 6 and later, and it is not a limitation for Basic MSI or InstallScript MSI projects.
Note: Application pools are available only on machines with IIS 6.0 or later installed.
Task To add a new application pool in the Internet Information Services view:
1. In the View List under Server Configuration, click Internet Information Services.
2. Right-click the Application Pools explorer and click Add Application Pool. InstallShield adds a
new application pool item.
3. Rename the new application pool item, and configure its settings.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Application Pools explorer, right-click the application pool and click Delete.
Note: Web service extensions are available only on machines with IIS 6.0 or later installed.
On systems with IIS 7, Web service extensions require that the IIS Metabase and IIS 6 Configuration Compatibility feature
be installed. For more information, see Version-Specific Information for IIS Support in InstallShield.
1. In the View List under Server Configuration, click Internet Information Services.
2. Right-click the Web Service Extensions explorer and click Add Web Service Extension.
InstallShield adds a new Web service extension.
3. Rename the new Web service extension item, and configure its settings.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Service Extension explorer, right-click the Web service extension and click Delete.
Project: If you are creating an application pool in an InstallScript project that you want to be associated with a virtual
directory or Web site, consider creating the application pool and the virtual directory or Web site within the same
component. This ensures that the application pool is created before the virtual directory or Web site is created, which is a
requirement of IIS 6. This is not required for Basic MSI or InstallScript MSI projects.
Task To associate a virtual directory, application pool, or Web service extension with a different component in your
project:
1. In the View List under Server Configuration, click Internet Information Services.
2. In the explorer, click the virtual directory, application pool, or Web service extension that you want
to associate with a component.
3. Click the General tab (for a virtual directory or an application pool) or the Web Service
Extension tab (for a Web service extension).
4. In the Component setting, enter the name of the existing component that should contain the
selected IIS data. You can click the Browse button to select an existing component or create a new
one for the IIS data.
Tip: If you delete a component in your project, any virtual directories, application pools, and Web service extensions that
are associated with the component are simultaneously removed from your project.
Note: Web service extensions, application pools, and associated properties are available only on machines with IIS 6.0 or
later installed.
On systems with IIS 7, Web service extensions require that the IIS Metabase and IIS 6 Configuration Compatibility feature
be installed. For more information, see Version-Specific Information for IIS Support in InstallShield.
Any Web service extensions and application pools installed in the IIS Management Console that have
identical names as the Web service extensions and application pools in an installation will always be
uninstalled when the features with which they are associated are uninstalled unless their components
are marked as permanent. Even if the Web service extension or application pool was originally created
by something other than the installation, it will be removed from the target system upon uninstallation if
the names (of the Web service extensions and application pools) match those in the installation. One
exception is that the default application pool, named DefaultAppPool, will never be removed by the
uninstallation.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Service Extensions explorer, select the Web service extension.
3. On the Web Service Extension tab, clear the Mark Component as Permanent check box.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Application Pool explorer, select the application pool.
3. Click the General tab.
4. Clear the Mark Component as Permanent check box.
If the Mark Component as Permanent check box is selected, the Web service extension or application
pool is left on the target system after uninstallation.
Tip: Selecting or clearing the Mark Component as Permanent check box on the General tab affects the value of the
Permanent setting (in Basic MSI and InstallScript MSI projects) or the Uninstall setting (in InstallScript projects) for the
component that contains the Web service extension or the application pool. Therefore, if you select the Mark Component
as Permanent check box and the component contains other data, such as files, shortcuts, and registry entries, the IIS
data, as well as the other data in the component, are not uninstalled during uninstallation.
Important: Microsoft does not recommend using the Aspnet_regiis.exe tool on Windows Vista and Windows Server
“Longhorn” systems because it has limited capabilities. As a result, you may need to manually define application mappings
in the Internet Information Services view: on the Home Directory tab for a Web site and on the Virtual Directory tab for a
virtual directory. To learn more, see Defining Application Mappings for a Web Site or Virtual Directory.
ASP.NET 3.0 does not include the Aspnet_regiis.exe tool. Therefore, you cannot set the ASP.NET version to version 3
of ASP.NET.
Task To specify the ASP.NET version for a Web site or virtual directory in your project:
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site or virtual directory whose ASP.NET version you want
to specify. The settings for the Web site or virtual directory are displayed on the right.
3. Click the General tab.
4. In the ASP .NET Version box, enter the complete version number of the .NET Framework that is
required by your application.
For example, to specify version 2 of ASP.NET, type 2.0.50727. To specify version 1.1 of ASP.NET,
type 1.1.4322.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site or virtual directory that you want to configure.
3. Click the Home Directory tab (for a Web site) or the Virtual Directory tab (for a virtual
directory).
4. In the Application settings area, click the Configuration button. The Application Mappings
dialog box opens.
5. Do one of the following:
a. To add a new mapping, click the Add button. The Application Extension Mapping dialog
box opens. For more information, see Application Extension Mapping Dialog Box.
b. To change an existing mapping, select the one that you want to edit, and then click the Edit
button.
c. To delete an existing mapping, select it and then click the Delete button.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site or virtual directory that you want to configure.
3. Click the Home Directory tab (for a Web site) or the Virtual Directory tab (for a virtual
directory).
4. In the Application settings area, click the Configuration button. The Application Mappings
dialog box opens.
5. In the Options area, specify the timeout settings.
If the HRESULT fails, the target machine does not have legacy object support.
Project: The advanced IIS settings apply to IIS 6 and earlier. IIS 7 ignores these settings.
When you select a Web site or a virtual directory in the Web Sites explorer in the Internet Information
Services view, the main tabs that are displayed expose the most common IIS settings. You can use the
Advanced tab to configure other IIS settings that are not exposed on the main tabs.
Task To configure a setting that is not exposed in the Internet Information Services view:
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, select the Web site or virtual directory whose advanced settings you
want to configure.
3. Click the Advanced tab.
4. In the property list, select the property whose value you want to change, and then click the Change
Value button. The Edit ISIISMetaData Value dialog box opens.
5. In the Value box, specify the new value.
If you change the default value for any advanced property, InstallShield adds the property, the value that
you specify, and the additional required information to the ISIIMetaData table.
Tip: For help on specific settings, see “Metabase Property Reference” on the MSDN Web site.
Task To configure custom error messages for a Web site or virtual directory:
1. Create a file that contains your custom error message and add it to your installation.
2. In the View List under Server Configuration, click Internet Information Services.
3. Select the Web site or virtual directory for which you want to customize HTTP error messages. The
settings for the Web site or virtual directory are displayed on the right.
4. Select the Custom Errors tab.
5. Select the HTTP error code that you want to change and click Edit. The Error Mapping Properties
Dialog Box opens.
6. To map the error code to a file:
a. In the Message Type list, select File.
b. In the File box, type the path and file name that points to the custom error message in your
installation, or click the browse button to locate the file.
To map the error code to a URL:
a. In the Message Type list, select URL.
b. In the URL box, type the URL that points to your custom error message.
For Basic MSI and InstallScript MSI projects, you can configure an IIS setting dynamically at run time
through the use of Windows Installer properties. This enables you to let end users specify the name of
the virtual directory, the TCP port, the site number, or other IIS settings for the Web sites, virtual
directories, Web service extensions, and application pools that they are installing on the target machine.
Windows Installer uses MsiFormatRecord to resolve the property at run time. The installation writes
the property and its value to the following registry key so that the value is available during uninstallation
and repair:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\InstallShield
Uninstall Information\{ProductCode}
Therefore, if your Web site is installed to an end user–specified site number, the Web site and its virtual
directories can be successfully uninstalled from that site number.
Tip: If you do not want the IIS data to be stored in the registry, set the IS_IIS_DO_NOT_USE_REG property in your
project.
If you use a property for any of the passwords in the Internet Information Services view, the passwords
are encrypted when they are stored in the registry.
Example
The following procedure demonstrates how to let end users specify during installation the user name
used for anonymous access to the Web site. Note that you can substitute a hard-coded value with a
property for any of the IIS settings in the Internet Information Services view that allow you to enter
characters. The property that you specify in this view must be enclosed within square brackets, and the
property name must be all uppercase; for example, [MYPROPERTY].
Step 6 of the procedure is slightly different, depending on the project type, since Windows Installer
controls the user interface of Basic MSI installations, and the InstallScript engine controls the user
interface of InstallScript MSI installations.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, click the Web site whose user name end users should be able to specify
for anonymous access.
3. Click the Directory Security tab.
4. Select the Enable anonymous access check box.
5. In the User name setting, type the following:
[MYPROPERTY]
6. Use the property in a dialog. This part of the procedure depends on which project type you are using.
MYPROPERTY
Example
The following procedure demonstrates how to let end users specify during installation the user name
used for anonymous access to the Web site. Note that you can substitute a hard-coded value with a text
substitution string variable for any of the IIS settings in the Internet Information Services view that
allow you to enter characters. The string variable that you specify in this view must be enclosed within
angle brackets; for example, <MYPROPERTY>. The string variable that you specify is case-sensitive.
1. In the View List under Server Configuration, click Internet Information Services.
2. In the Web Sites explorer, click the Web site whose user name end users should be able to specify
for anonymous access.
3. Click the Directory Security tab.
4. Select the Enable anonymous access check box.
5. In the User name setting, type the following:
<MYPROPERTY>
Tip: To learn how to add a virtual directory to your project, see Creating a Web Site and Adding a Virtual Directory.
1. In the View List under Application Data, click Files and Folders.
2. Select the folder (target directory) for installing files on the target system. Add your files to this
folder.
3. In the View List under Server Configuration, click Internet Information Services.
4. In the Web Sites explorer, select the virtual directory that is associated with the Web service.
5. In the Local Path box, enter the same target directory as the one that contains the new files that
you added in the Files and Folders view.
At installation, files are copied to the target directory folder. In addition, the virtual directory is
configured for that folder on the target system if IIS is present.
Note: All of the files added to the IISROOTFOLDER directory in the Files and Folders view will be installed to the Web
server’s root directory on the target machine. If IIS is not installed, the files will be copied to the root folder.
IIS_WEBSITE_NAME Property
The IIS_WEBSITE_NAME property is obsolete. If this property exists from earlier project versions,
the upgrader will handle it automatically. The upgrader will create a Web site and set the site number
field to [IIS_WEBSITE_NAME]. For new Web sites, you can use any property or hard-coded number.
IIS_PORT_NUMBER Property
The IIS_PORT_NUMBER property is obsolete. If this property exists from earlier project versions,
the upgrader will handle it automatically. The upgrader will create a Web site and set the port number
field to [IIS_PORT_NUMBER]. When you create new Web sites, you can use any property or hard-
coded number.
InstallShield supports the latest mobile devices, enabling you to add any number of mobile device
installations to a desktop installation.
You can add to your project an installation for Windows Mobile devices such as the Microsoft
Smartphone and handheld PCs.
Note: Microsoft ActiveSync 3.x or later must be installed on the desktop computer in order to provide a desktop-to-device
installation. Active Sync 4.x is required for Windows Mobile 5.x devices.
1. Prepare your application by compiling your code in Microsoft eMbedded Visual Tools 3.0, Microsoft
eMbedded Visual C++ 4, or Microsoft Visual Studio.
2. Create the desktop installation that will be used to install the components of your application to the
end user’s desktop machine. This also sets up your application to be installed on the Windows
Mobile device the next time that it is synched with the desktop computer.
Note: You are not required to add anything to the desktop. You can use the desktop installation solely to deploy the
application to Microsoft ActiveSync.
1. Prepare your application by compiling your code in a development tool that supports Palm OS.
2. Create the desktop installation that includes the Palm OS files that are to be installed on Palm OS
devices.
3. Add a Palm OS installation to your project:
a. Open the Mobile Devices view.
b. Right-click Mobile Device Installations and click New Palm OS. The Palm OS Wizard
opens.
c. Follow the wizard panels to customize the installation.
When you add an installation for a Palm OS device to your project, a corresponding component is
created and added to all of the features that you selected to associate with the Palm OS application.
When you build a release for the installation, InstallShield creates an installation that installs your
application files to the Palm OS device via a storage card, or they can be downloaded directly to the
device over a network or the Internet.
• Basic MSI
• InstallScript MSI
• Web
If you are creating an installation for a Palm OS device, you may want to target a specific user or slot ID,
or you may want an end user to be able to specify a particular user or slot ID. Two properties that are
available to you when you create your installation can help you with these scenarios:
• ISPALMUSER—Use the ISPALMUSER property to specify a single Palm user for your
installation. This property is relevant only if a file has a destination of Handheld. By default, this
property is null.
• ISPALMSLOTID—Use the ISPALMSLOTID property to specify a specific slot ID for your
installation. This property is relevant only if a file has a destination of Storage Card. By default,
this property is null.
InstallShield uses the Palm APIs PltInstallFile and PlmSlotInstallFile for Palm OS installations.
PltInstallFile requires a user name to which to install a file. This API is used if you select Handheld as
the destination of the file. If a value is specified for the ISPALMUSER property, the file installs for the
user specified in ISPALMUSER. If the ISPALMUSER is not set to any value, then the file installs to
all users.
PlmSlotInstallFile requires a slot ID for the installation of a file. This API is used if you select Storage
Card as the destination of the file. If a value is specified for the ISPALMSLOTID property, the file is
installed to the slot ID specified in ISPALMSLOTID. If the ISPALMSLOTID property is not set to
any value, the file installs to the first slot ID that is found.
It is not possible for InstallShield to know the names of users or slot IDs, so you can create the
ISPALMUSER and ISPALMSLOTID properties in the Property Manager view. It is likely that you
may not know the names of users on end users’ machines, so to enable an end user to specify a specific
user or slot ID, you can create a dialog that prompts the end user for the user name or storage card’s slot
ID. The dialog would need to prompt for only user name if the destination of all files was set to
Handheld.
If you create a new dialog, it is recommended that you associate the ISPALMUSER and
ISPALMSLOTID properties with the controls where the end user will enter the data.
Project: If you have .cab files that have already been built for one of the following types of projects, you can add them to
your installation to create a Windows Mobile package:
• Basic MSI
• InstallScript MSI
• Web
If you would like to add more than one .cab file to a single Windows Mobile installation, see Special
Considerations for Adding Multiple .cab Files.
Note: Microsoft ActiveSync 3.x or later must be installed on the desktop computer in order to provide a desktop-to-device
installation. Active Sync 4.x is required for Windows Mobile 5.x devices.
Task To add existing .cab files for a Windows Mobile device to your project:
1. Prepare your .cab files if you have not already done so. The .cab files can be created by using the
Smart Device Setup Wizard, or they can be some other Windows Mobile–compatible .cab files that
you have on your machine.
2. Create the desktop installation that will be used to install the components of your application to the
end user’s desktop machine. This also sets up your application to be installed on the Windows
Mobile device the next time that it is synched with the desktop computer.
Note: You are not required to add anything to the desktop. You can use the desktop installation solely to deploy the
application to Microsoft ActiveSync.
A Windows Mobile installation is a set of .cab files. If your Windows Mobile installation supports more
than one platform-processor combination, the set of .cab files consists of a separate .cab file for each
platform-processor combination. If your installation supports all platform-processor combinations, the
set of .cab files consists of only one .cab file that can be used for any platform-processor combination.
Note: If a Windows Mobile installation consists of multiple .cab files, you should add all of the installation’s .cab files to the
same node of the Mobile Device Installations explorer in the Mobile Devices view. You should not separate the .cab files
into different nodes.
If you want to add to your project multiple .cab files from different Windows Mobile installations (that is, from different sets
of .cab files), you should create a separate node in the Mobile Device Installations explorer for each set of .cab files. You
should not mix .cab files from different installations in the same node.
You can use the CEAPPMGRLOC property to refer the CE AppManager. This property holds the path
of CEAPPMGR.exe.
Task To use CEAPPMGRLOC to obtain the AppManager location on the target desktop machine:
• From a C++ custom action, use the Windows Installer API MsiGetProperty.
The CESERVICEDIR directory variable points to the location where ActiveSync is installed on the target
system.
1. In the Mobile Devices view, click the Windows Mobile installation that you would like to modify.
The Project Settings window for that installation opens.
2. In the Project Settings window, click Desktop Settings. The Desktop Settings panel of the
Windows Mobile Wizard opens.
3. In the Target desktop folder box, select the [CESERVICEDIR] option.
4. Click OK.
You can also create subdirectories under this directory and then deploy files to the subdirectories.
Some legacy mobile device platforms include support for portrait mode but not landscape mode.
Therefore, in some circumstances, the installation for a mobile device displays the following warning:
The program you have installed may not display correctly because it was designed for a previous
version of Windows Mobile software.
Task To prevent this warning from ever displaying, do one of the following:
• On the Device Files panel of the Windows Mobile Wizard, select the Suppress Display
Warning check box. For more information, see Device Files Panel.
• On the Processor/Platform tab of the Device Files dialog box, do not select the Platform/
Processor independent option. Selecting this option triggers the warning on legacy platforms.
For more information, see Processor/Platform Tab.
• On the Processor/Platform tab of the Device Files dialog box, select the Specific platform/
processor option and in the Platforms list, select only the latest platforms. For more information,
see Processor/Platform Tab.
The Windows Mobile Wizard guides you through the process of creating installation packages for
Windows Mobile devices, and the Palm OS Wizard guides you through the process of creating
installation packages for Palm OS devices. If you want to modify an mobile device installation in your
project, you can run through the entire wizard again, making changes as needed. You also have the
option of accessing only a selected panel of the wizard, bypassing the other panels of the wizard. Both
methods begin with the Mobile Devices view.
• Right-click the mobile device installation whose name you would like to modify and click
Rename.
• Select the mobile device installation whose name you would like to modify and press F2.
When you rename an installation for a mobile device in the Mobile Devices view, the component for
that installation is also renamed.
Your mobile device installation is built when you build the desktop installation that your mobile device
installation is part of.
If your project includes a Windows Mobile device installation, the resulting Setup.exe—and other files if
the release was built uncompressed—contains all of the logic required to configure Microsoft ActiveSync
on the desktop machine to install the application and, if necessary, the .NET Compact Framework on the
device.
If your project includes a Palm OS device, the resulting Setup.exe—and other files if the release was built
uncompressed—contains an installation that installs your application files to the Palm OS device via a
storage card, or they can be downloaded directly to the device over a network or the Internet.
InstallShield lets your users rerun your installation to change program features or reinstall or remove
your application. When users select your application in Add or Remove Programs in the Control Panel,
the installation displays dialog boxes that let users do any of the following:
• Install individual features that were not previously installed, and uninstall individual features.
• Reinstall your application with the settings selected during the first installation.
• Uninstall your application.
To modify, repair, or uninstall an application, the operating system must have some indication that the
application is present. To allow this, an installation registers an application with the operating system so
that it can be easily maintained or uninstalled. You enter the necessary information in the General
Information view’s Project Properties View and Add or Remove Programs View.
In all InstallShield installations, maintenance (that is, modification and repair) is handled automatically
by default.
In a Windows Installer–based installation, uninstallation is handled automatically—with the sole
exception of custom actions, which must either undo their own effect during uninstallation or have their
effect undone by another custom action that runs only during uninstallation.
In an InstallScript or InstallScript MSI installation, many script functions’ actions are logged for
automatic uninstallation; your uninstallation script must handle those script function actions that are
not logged.
There are other functions that play important roles in setting up uninstallation functionality. For
example, all keys created using the RegDBCreateKeyEx function are recorded for uninstallation, unless
logging is disabled. Also, if you call the Disable function to disable logging, remember to call Enable to
enable the logging again for subsequent actions that must be recorded for uninstallation.
MaintenanceStart (or DeinstallStart) creates the necessary registry key and its necessary values. To create
additional registry values under this key, call RegDBSetItem, or for custom values use code like the
following:
RegDBSetDefaultRoot( HKEY_USER_SELECTABLE );
RegDBSetKeyValueEx( "Software\\Microsoft\\Windows\\Current Version\\Uninstall\\" +
INSTANCE_GUID, "My Custom Value", nType, szValue, nSize);
Note: Uninstallation is available only if the initial installation calls ComponentTransferData or ComponentMoveData. (In an
event-based script, the ComponentTransferData function is called automatically.) If your installation installs files by some
other means (for example, XCopyFile) and you want to make uninstallation available to your end users, deselect all
components and call ComponentTransferData or ComponentMoveData; while this call is executed, you can call
SdShowMsg to display a message.
Note: If you call DeinstallStart to enable uninstallation, the installation script is not executed during uninstallation. To
execute script code during uninstallation, call MaintenanceStart instead. (In an event-based installation MaintenanceStart is
called in the default OnMoveData event handler code.)
Event-Based Scripts
If your script is event-based, the following event handler functions are called during uninstallation:
OnBegin
OnMaintUIBefore
OnMoving
<component name>_Uninstalling (for each installed component)
<component name>_Uninstalled (for each installed component)
OnMoved
OnMaintUIAfter
OnEnd
The code in these event handler functions (whose default code you can override) is executed during the
uninstallation. For instructions on executing certain event handler code only during uninstallation, or
only during installation, see Executing Script Code Only During Uninstallation or Only During
Installation.
Procedural Scripts
If your script is procedural (that is, uses a program block) and calls MaintenanceStart rather than
DeinstallStart to enable uninstallation, the script is executed during uninstallation. For instructions on
executing certain script code only during uninstallation, or only during installation, see Executing Script
Code Only During Uninstallation or Only During Installation.
To execute code only during a first installation, enclose it in the following if-then statement:
if !MAINTENANCE then
/* this code is executed only during
a first installation */
endif;
If code is not enclosed in either if-then statement, it is executed during uninstallation, maintenance
installations, and first installations—with the following exceptions in event-based scripts:
• The code in the following event handlers is executed only during uninstallation and maintenance
installations:
OnMaintUIBefore
OnMaintUIAfter
• The code in the following event handlers is executed only during the first installation:
OnCCPSearch
OnAppSearch
OnFirstUIBefore
OnFirstUIAfter
Logged Functions
InstallShield records installation events created by the following functions for uninstallation in the
uninstallation log file:
Maintenance/Uninstallation Feature
The maintenance/uninstallation feature installs the files needed for maintenance setups and
uninstallation, including engine files; the files’ target location is specified by the value of the system
variable DISK1TARGET. This feature is automatically placed in your .cab files by the release builder and is
not displayed in the InstallShield interface.
At run time the maintenance/uninstallation feature is automatically selected for all setup types. Calling
FeatureUpdate deselects this feature. The maintenance/uninstallation feature can also be selected or
deselected by calling FeatureSelectItem and passing the system variable DISK1COMPONENT as the function’s
second argument. For example, the following code deselects the feature:
FeatureSelectItem( MEDIA, DISK1COMPONENT, FALSE );
FileKey remove_file
Component_ ProgramFiles
FileName Product.ini
DirProperty INSTALLDIR
InstallMode 2
Note: The RemoveRegistry table—exposed in the Direct Editor—specifies data to be removed only when your product is
installed. For details, see the Windows Installer Help Library.
Once you have configured the features, components, files, shortcuts, registry entries, end-user dialogs,
and other elements of your installation project, you are ready to create and build a release for your
installation. InstallShield lets you create multiple releases for a project and configure each release for a
different media type and according to different sets of requirements. Building releases packages the
content of your installation, creating a disk image that you can copy to your distribution media and
distribute or deploy as needed.
Testing is an essential part of creating a reliable installation. InstallShield enables you to selectively test
run just the end-user interface portion of a release. You can also run your installation by simply clicking
a button in InstallShield; when you run an installation by using this method, your installation executes
exactly as it would on an end user’s machine. All files are transferred, shortcuts and registry entries are
made, and the user interface is displayed.
Before you release your product, you may want to validate your installation project. Validating a
Windows Installer project involves applying a set of internal consistency evaluator (ICE) rules to your
installation project. These ICEs are designed by Microsoft to ensure that your resulting installation
package contains a valid database that performs its actions correctly.
With the debugging tools in InstallShield, you can debug your InstallScript script or Windows Installer
release to identify the sources of problems. When you debug a script, you execute your script, statement
by statement, and trace the flow of control by watching the execution point as it moves through the
script. You can also monitor the value of any variable in your script at any point during script execution.
When you debug a Windows Installer release, InstallShield runs through each action and dialog box
until it reaches your breakpoint, when it halts execution. At this point, you can view and set properties.
Every release that you build is a member of a product configuration. A product configuration provides a
means for grouping together releases that share similar properties, such as the product name, product
code, and package code.
Product configurations also enable you to keep a history of your builds without having to set up a folder
structure outside InstallShield. For example, when your product is in development, you might have
many releases of the same version. You do not necessarily want to overwrite each release every time that
you rebuild the product. With product configurations, you can maintain your previous build history and
incorporate new releases at the same time.
In the past, you may have had to maintain this type of historical record of your builds outside
InstallShield. You had to create a directory structure on a drive, label each folder manually, and then
copy the release into its directory. With product configurations, all of this is done for you in
InstallShield.
Tip: You can also create product configurations through the Release Wizard. You can specify existing product
configurations from the command line (using the -a parameter), but you cannot define the settings of a release through
the command line.
Project: For installation projects: Before building your installation project, ensure that you have completed designing and
setting the properties for every element in your project, including the features, components, files, shortcuts, registry
entries, and end-user interface.
For merge module projects: Before building your package, ensure that you have completed designing and setting the
properties for every element in your merge module, including components, files, shortcuts, and registry entries.
Once you have designed your project in InstallShield, you are ready to create a release that you can
configure and build to distribute to end users. You can create multiple releases for a project and
configure each release for a different media type and according to different sets of requirements.
InstallShield offers several methods for creating and building a release:
• Use the Release Wizard.
• Use the Releases view.
• Build from the command line using ISCmdBld.exe.
• Build a release through the automation interface.
Tip: Make sure that Windows Explorer is not pointing to the Disk1 folder or a subfolder when you build your release. If
Windows Explorer is pointing to the Disk1 folder, the build process fails and generates an error.
Task To launch the Release Wizard and build your installation package, do one of the following:
Creating and Building a Release in Basic MSI, InstallScript MSI, Merge Module,
and Web Projects
You can set the release location either in the Advanced Settings panel of the Release Wizard or in the
Release Location property in the Releases view.
• You can build a release from the command line for a Standalone Build using IsSaBld.exe. To learn
more, see Standalone Command-Line Build.
For the syntax and available command-line parameters for ISCmdBld.exe, see ISCmdBld.exe.
Corresponding
Command-Line
Entry Parameter Description
[Project]
[Release]
[Mode]
Corresponding
Command-Line
Entry Parameter Description
[BuildLocation]
Note: The entries CompileOnly, BuildTablesRefreshFiles, and BuildTablesOnly are mutually exclusive. Only one
can be set to yes. CompileOnly should not be used with Compile Script.
For more information about the .ini file entries, see Building a Release from the Command Line.
To learn about entries that apply only to a Standalone Build, see Standalone Command-Line Build.
Rebuilding Releases
You can rebuild a release at any time using the default entries that you already provided in the properties
in the Releases view or in the Release Wizard. The release that currently has focus is rebuilt.
• In the Releases view, right-click a release name and then click Build.
You can run the Release Wizard again to rebuild a release. Because the wizard stores the release settings
in your InstallShield project file, the wizard displays all of the options that you set when you last built the
release, even if you deleted the release.
To see your new installation package, click Disk Image(s) for the appropriate release in the Releases
view. InstallShield places the built installation package into the following folder if you have not changed
the default release location:
C:\InstallShield 2008 Projects\project name\product configuration\release name\DiskImages\Disk1
Note: Make sure that Windows Explorer is not pointing to the Disk1 folder or a subfolder when you build your release. If it
is pointing to the Disk1 folder, the build process can continue indefinitely. If Windows Explorer is accessing a subfolder,
the build generates an error.
Task To build only your installation’s Windows Installer tables, do one of the following:
• In the Releases view, right-click the release that you would like to build and click Build Tables
Only.
Task To build your Windows Installer tables and refresh the installation’s files, do one of the following:
• In the Releases view, right-click the release that you would like to build and click Build Tables &
Refresh Files.
Task To learn how to resolve a build error or warning that you encounter, do one of the following:
• On the Tasks tab of the Output window, click an error code to launch your Internet browser and
see Knowledge Base articles and HelpNet topics for the selected build error or warning.
• See Build Errors and Warnings, which provides tips on how to resolve build errors and warnings.
Canceling Builds
Standalone Build
InstallShield provides a Standalone Build module that enables you to maintain a clean build system by
using the part of InstallShield that compiles the installations, plus any redistributables that you want to
include. For instructions on installing the Standalone Build and any redistributables on a build machine,
see Installing the Standalone Build to a Build Machine.
The Standalone Build can coexist with other versions of InstallShield, InstallShield DevStudio, or
InstallShield Developer. Standalone Build files from different service packs of InstallShield,
InstallShield DevStudio, or InstallShield Developer can coexist on the same machine (in different
folders).
Note: The Standalone Build is supported by the following platforms: Windows 2000 SP3 or later, Windows XP, or Windows
Server 2003.
Upgrading Projects
The Standalone Build automatically upgrades projects created with InstallShield Developer 7.0 or later.
However, it does not upgrade projects created with InstallShield for Windows Installer.
Edition: The Standalone Build is available to users of InstallShield Premier Edition. In addition, support for multilanguage
installations is available with InstallShield Premier Edition only.
• If you have the InstallShield CD, the file is on the CD and you can find it using the CD Browser.
• If you downloaded InstallShield, the file is available through FLEXnet Connect. For more
information, see Obtaining Updates for InstallShield.
2. Double-click the Setup.exe file.
1. Locate the required redistributables on the machine that has the full version of InstallShield. The file
is typically located in InstallShield Program File Folder\Redist or a subfolder of the Redist folder.
If an InstallShield redistributable is not available on your machine, you must download it first. For
more information, see Redistributable Downloader Wizard.
2. Copy the redistributable from the machine that has InstallShield to the Standalone Build Program
Files Folder on the build machine.
Task To add a redistributable for Basic MSI or InstallScript MSI projects to your build machine:
1. Locate the required redistributables on the machine that has the full version of InstallShield. If an
InstallShield redistributable is not available on your machine, you must download it first. For more
information, see Downloading Redistributables to Your Computer.
• If you built your own merge modules in InstallShield, you would find them in any of the
locations that are listed on the Merge Modules tab of the Options dialog box.
2. Copy the redistributable from the machine that has InstallShield to appropriate location on the
build machine.
• Add merge modules to the following folder:
Standalone Build Program Files Folder\Modules\i386
Task To add to your build machine one of the InstallShield redistributables for InstallScript projects:
1. Download the installation for the redistributable. The installations are available through FLEXnet
Connect. For more information, see Obtaining Updates for InstallShield.
2. Run the redistributable installation on the build machine. When the InstallShield Wizard displays
the Choose Destination Location dialog, browse to the following location:
Standalone Build Program Files Folder\ObjectsPro
If the ObjectsPro folder has not been created yet, you will need to add that folder.
Task To add to your build machine one of your own InstallScript redistributables or a third-party redistributable:
If the ObjectsPro folder has not been created yet, you will need to add that folder.
The Standalone Build contains an enhanced version of the command-line build. For information on how
to build a release from the command line, see Building a Release from the Command Line. The process
is the same, except for the executable file—for the Standalone Build, the executable is IsSaBld.exe.
The Standalone Command-Line Build supports all of the same command-line parameters as
IsCmdBld.exe.To learn about those command-line parameters, see ISCmdBld.exe.
In addition, the Standalone Command-Line Build supports several options that are normally controlled
by the InstallShield interface (in the Options dialog box):
Parameter Description
-g <minimum target MSI Specifies the minimum version of Windows Installer that the
version> installation will accept on the target machine. This parameter is
optional and defaults to the latest version of Windows Installer
supported by the InstallShield interface (for example, the default
is -g 2.0.2600.0).
-j <minimum target Specifies the minimum version of the .NET Framework that the
Microsoft .NET Framework setup will accept on the target machine. This parameter is
version> optional and defaults to the latest version of the .NET Framework
supported by the InstallShield IDE (for example, the default is -j
1.0.3705.2).
-o <merge module search Specifies one or more comma-delimited folders that contain the
path> merge module (.msm) files referenced by your project. The
default is the folder that contains the Standalone Build, which by
default does not contain any merge modules.
-t <Microsoft .NET Specifies the path to the Microsoft .NET Framework. The path is
Framework path> the location of the .NET Framework installed on the machine with
which the installation author is using to build the installation. This
is not the path to DotNetFx.exe redistributables. Specifically,
this is the path to Regasm.exe. Only the path is needed.
The Standalone Build includes a standalone version of the automation interface—the InstallShield
Standalone Automation Interface. This interface is similar to the ISWiAutomation14.dll file installed
with InstallShield. However, the library name is different and the GUIDs are different.
Future service packs of the Standalone Build will have new prog IDs and new GUIDs. You will be able
register multiple versions of the Standalone Build Automation side by side on the same build machine.
Registering SAAuto.dll
The Standalone Automation Interface is contained in the file SAAuto.dll. If you installed InstallShield
Standalone Build.msi, then this file is already self-registered. If you used xcopy to install the Standalone
Build, you need to register this file manually using Regsvr32.exe.
Additional Properties
The SAAuto14.ISWiProject object supports a few more properties than ISWiAutomation14.ISWiProject.
These properties are useful if you use the ISWiRelease.Build method. These properties enable you to
control the build in ways normally controlled by the InstallShield interface (through the Options dialog
box).
Note: Setting one of these properties for one instance of SAAuto14.ISWiProject sets the same property for all other (and
subsequent) instances of SAAuto14.ISWiProject until the .dll file is released.
Overview
MSBuild is an extensible build framework designed to remove the build dependence on Visual Studio.
The .NET Framework functions in a role similar to the InstallShield Standalone Build, providing the
capability to build projects or solutions from the command line or any other host of MSBuild. For more
information on MSBuild, see the MSDN Library.
MSBuild Tasks
The flexibility and extensibility of MSBuild is controlled through atomic groupings of internal build
steps referred to as tasks. One example of a task that ships with MSBuild is Csc, which can compile code
from a Visual C# project. InstallShield installs an MSBuild task called InstallShield, which builds an
InstallShield project, and a targets file that provides default build steps for the project. This customized
task, along with the targets file, enables MSBuild to perform all required actions to build the
InstallShield project as part of a Visual Studio solution.
InstallShield Path String This parameter specifies the path to folder containing the
InstallShield application.
Project String This parameter specifies the location of the project file (.ism).
ProductConfiguration String This parameter specifies the product configuration for the release.
OutDir String This parameter specifies the fully qualified path to the folder where
you want the output folders and files to be placed.
MergeModulePath String[ ] This parameter specifies one or more folders that contain the
merge module files (.msm) referenced by your project. The default
is the folder that contains the Standalone Build, which by default
does not contain any merge modules.
ReleaseFlags String[ ] This parameter enables you to specify any release flags that you
want to include in your release. Separate multiple flags with
commas.
PathVariables ITaskItem[ ] This parameter enables you to override the path variables for the
project. Using this parameter, you can specify the path to the path
variable and also define a value for the name of the path variable
using the PathVariable subelement.
For more information on MSBuild ITaskItem[ ] properties, see the
MSDN Library.
PreprocessorDefines ITaskItem[ ] This parameter enables you to add or override the preprocessor
defines for the project. Using this parameter, you can specify the
definition of the preprocessor define and also define a value for the
name of the preprocessor define using the Token subelement.
For more information on MSBuild ITaskItem[ ] properties, see the
MSDN Library.
OutputGroups ITaskItem[ ] This parameter specifies the project output groups from the Visual
Studio solution. Using this parameter, you can specify the path to
the source location of the project output group and also define
these additional values using these subelements as listed:
• Name—Name of the project
• OutputGroup—Name of the project output group
• TargetPath—Target path of the project output group (different
from its source location)
For more information on MSBuild ITaskItem[ ] properties, see the
MSDN Library.
Build String This parameter specifies what type of build to perform. You can
choose from these types of builds:
• Complete
• Compile
• Tables
• TablesAndFiles
• UpgradeOnly
BuildSetupExe Boolean This parameter specifies whether you want to create a Setup.exe
file along with your installation.
ProductVersion String This parameter specifies the product version. This is especially
helpful if you want to increment the build version (the third field) of
the product version.
For information on valid product version numbers, see Specifying
the Product Version.
RunMsiValidator String This parameter enables you validate the .msi package using a .cub
file.
RunUpgradeValidation Boolean This parameter specifies whether or not to run upgrade validation.
StopOnFirstError Boolean This parameter specifies whether or not to stop the build after an
initial error.
MsiVersion String This parameter specifies the minimum version of Windows Installer
that the installation can accept on the target machine.
DotNetFrameworkVersion String This parameter specifies the minimum version of the .NET
Framework that the installation can accept on the target machine.
Disk1Folder Output String This parameter specifies the location of the output folder.
MSBuild Scripts
MSBuild natively understands one file format: its XML build script, which is used as the project file
format for Visual C# and Visual Basic .NET projects (.csproj and .vbproj). MSBuild also has internal
hooks to handle solution files and the Visual C++ project file format (.sln and .vcproj).
The InstallShield integration with Visual Studio uses an MSBuild-compatible XML format project file
(.isproj), which enables MSBuild to seamlessly build Visual Studio solutions that include InstallShield
projects. To build solutions in a standalone environment, install the InstallShield Standalone Build on
the build machine.
3. Type the command-line statement to build the release build of the Visual Studio integration project.
For example:
MSBuild.exe C:\Folder Containing My Visual Studio Solution\My Solution.sln /
property:Configuration=Release
Note: The single executable file that you create accepts any command-line parameter that Setup.exe accepts.
Task To package a build as a single executable file by using the Release Wizard:
7. Complete the Release Wizard; in the Summary panel, select the Build the Release check box
and then click the Finish button.
Task To package a build as a single executable file by using the properties in the Releases view:
Note that you can specify a non-default icon only when building on a Windows NT, Windows 2000,
or Windows XP machine.
6. If you want the executable file to extract the installation files to the target machine and not run the
installation, enter the following for the Setup Command Line setting:
-extract_all:<path>
Specifying the Required Execution Level for Your Setup Launcher on Windows
Vista Platforms
InstallShield lets you specify the minimum execution level required by your installation’s Setup.exe file
for running the installation (the setup launcher, any setup prerequisites, and the .msi file) on Windows
Vista platforms. You can configure this for each individual release in your project.
For InstallScript and InstallScript MSI projects, and for Basic MSI projects if the Setup Launcher setting
is set to Yes, InstallShield embeds a Windows Vista application manifest in the Setup.exe launcher. This
manifest specifies the selected execution level. Operating systems earlier than Windows Vista ignore the
required execution level.
If the Setup Launcher setting is set to No for a Basic MSI project, InstallShield does not embed the
Windows Vista application manifest in the Setup.exe launcher.
The benefit of elevating the required execution level is that privileges can be elevated only once if
necessary to run Setup.exe, and that these privileges can be carried over to all of the installation’s
prerequisites and the .msi file without requiring multiple prompts for approval. Thus, if two of your
prerequisites require administrative privileges, for example, you can change this setting to
Administrator, and then end users are prompted only once during the installation, before Windows
Installer runs the Setup.exe file. Note, however, that if you elevate the privileges and also launch the
application at the end of the installation, the elevated privileges are carried over to the application. In
most cases, running an application with elevated privileges on Windows Vista platforms is discouraged.
Note that an end user’s installation experience is more secure when installations are run with only the
permissions that they need. Unless an application is designed to be run only by system administrators, it
should be run with the least privilege.
If an installation and its setup prerequisites require elevated privileges, Windows Vista displays a User
Account Control (UAC) prompt for the setup prerequisites, and another one for the .msi file. If this
common scenario applies to your installation, you may want to specify that your installation should
advertise and then run your .msi file to help end users avoid the second UAC prompt. If this scenario
does not apply to you, Macrovision recommends that you avoid advertising the .msi file because it would
not avoid a second UAC prompt.
Tip: The Require Administrative Privileges setting in the Summary Information Stream area of the General Information view
is where you specify whether the .msi file requires administrative privileges. The Behavior tab in the Setup Prerequisite
Editor is where you specify whether a prerequisite requires administrative privileges. For more information about other
InstallShield settings that may affect whether Windows Vista displays UAC prompts, see Minimizing the Number of User
Account Control Prompts During Installation.
Important: The package must support advertisement in order for either of the advertise options to work. Advertisement is
not instantaneous, and it adds extra delays to the installation. In addition, unexpected behavior may occur if the end user
clicks Cancel after advertisement but before the main part of the installation has finished. For example, advertised
shortcuts for your product may appear on the desktop before the main installation begins, and a confused user canceling
the main installation may leave your package advertised but not fully installed. Therefore, in some cases, it may be better
to leave this setting as No to allow the second UAC prompt and avoid product advertisement.
A common goal is for an installation to display only one UAC prompt. The advertise options for the
Advertise If Prerequisites Are Elevated setting facilitate this but do not guarantee it in all situations. For
example, any time that an installation causes a restart, the installation process returns to limited
privileges after the restart. The subsequent privilege elevation may display an additional UAC prompt,
whether the elevation is required for a prerequisite or for the .msi file. When the restart comes between
the last prerequisite and the .msi file, the .msi file is not advertised. Following are some examples of
different outcomes that may occur when you select one of the advertise options for this setting:
• The prerequisites require elevation and install successfully on the target machine. The product is
advertised and installed. The product installation does not display a UAC prompt.
• One of the prerequisites in the installation may require a restart. After the restart for the
prerequisite occurs, either no additional prerequisites are installed or none of the other
prerequisites that are installed require elevation. Since the last prerequisite that is installed in this
scenario is not a simple success of an elevated prerequisite, advertisement of the .msi file does not
occur.
• None of the prerequisites in the installation need to be installed because they are already present on
the target machine; therefore, advertisement of the .msi file does not occur.
• None of the prerequisites in the installation require elevation; therefore, advertisement of the .msi
file does not occur.
• Elevated prerequisites are successfully installed. However, for this situation, the package is a minor
upgrade for a product that is already installed. That is, the product code in the package matches the
product code of the product that is already present on the target machine. Advertisement of the .msi
file does not occur. UAC prompts may or may not be displayed; it depends on whether a suitable
digital certificate is included in the earlier installation and in the patch.
Task To place some or all features’ files uncompressed in the disk image, use the Media Layout panel in the
Release Wizard.
1. Launch the Release Wizard and navigate to the Media Layout panel.
2. Do either of the following:
• To place all features’ files uncompressed in the disk image: Select the CDROM Folder(s)
option. All features’ files are placed in the disk image in the folders specified by the features’
CD-ROM Folder properties. If no folder is specified for a feature, that feature’s files are placed
in the root of the disk image.
• To place some features’ files uncompressed in the disk image:
a. Select the Custom option, and then click Next. The Custom Media Layout panel opens.
b. In the Features in cabinets box, select or clear the check boxes next to the features. If a
feature’s files are stored in cabinet files, clear the check box. If a feature’s files should be
placed in the disk image in the folder specified by the feature’s CD-ROM Folder property,
select the check box. If no folder is specified, that feature’s files are placed in the root of the
disk image.
Tip: If you want most of your features stored in cabinet files, click Clear All and then select the features to be placed
uncompressed in the disk image. Conversely, if you want most of your features placed uncompressed in the disk
image, click Select All and then clear the check boxes for the features to be stored in cabinet files.
Note: Regardless of whether you selected Yes or No for the Compressed setting of a feature’s component, by selecting
the uncompressed (CD-ROM folder) option for the feature, its files will be uncompressed on the distribution media.
Password-Protecting Installations
For added security, you can password-protect your installation package. When you password-protect
your installation, any end user who wants to install your package must enter a case-sensitive password
to open your installation.
You can activate password protection in the Password & Copyright panel of the Release Wizard.
Caution: Do not release the files in the TestTools folder with your product or make them available to your customers.
Doing so would enable end users to continually restart a trial each time that it expires. Note that the TestTools files are
specific to a particular product and license and cannot be used to delete licenses for other products.
For each file being wrapped, the TestTools folder contains the following files:
• SCResetLicense<WrappedBaseFileName>.exe
• IsSvcInstSCResetLicense<WrappedBaseFileName>.dll
For example, if a file called Calc.exe is wrapped, the files in the TestTools folder are
SCResetLicenseCalc.exe and IsSvcInstSCResetLicenseCalc.dll.
You can use the TestTools files to remove the license for your product from a machine, resetting the
trialware state. This enables you to restart the trial for your protected product and retest it. For more
information, see Testing a Trialware Release of Your Product.
Task To prepare a release of your product that does not have the trialware protection:
6. In the Releases explorer, click the release that you want to build.
7. Click the Build tab.
8. For the Disable Trialware Build setting, select Yes.
9. Build the release.
If you have not added a trialware file to your project in the Trialware view, the Disable Trialware Build
property has no effect on the release build.
A setup prerequisite is a base application or component that must be installed on the target machine
before your application can be installed. The Redistributables view is where you add setup prerequisites
to your project.
Task To specify where all of the setup prerequisites should be located for a release, do one of the following:
• In the Releases view, select the release. Then on the Setup.exe tab, for the Setup Prerequisites
Location setting, select the appropriate option.
1. In the Redistributables view, specify the appropriate location for each setup prerequisite. For
more information, see Specifying a Location for a Specific Setup Prerequisite.
2. In the View List under Media, click Releases.
3. Select the release that you want to build.
4. Click the Setup.exe tab.
5. For the Setup Prerequisites Location setting, select Follow Individual Selections.
Tip: As an alternative, you can select the Follow Individual Selections option in the Setup Prerequisite panel of the Release
Wizard.
Note that if a setup prerequisite is added to a project as a dependency of another prerequisite, the
location for the prerequisite dependency follows the location setting of the prerequisite that requires it.
If you build a release that includes setup prerequisites and both of the following are true, one or more
build errors may be generated:
• You specify for the setup prerequisites location that the prerequisites should be extracted from
Setup.exe or copied from the source media (instead of being downloaded from the Web to the end
user’s computer).
• The prerequisite files are not on your computer.
To eliminate the build errors, remove the prerequisite from your project, download the prerequisite
from the Internet to your computer, or change the setup prerequisites location for the release to the
download option; then rebuild the release.
Note: When you are building a release on a Windows 2000 machine, SP4 must be installed in order for you to digitally sign
the application.
The Signing tab is where you specify the digital signature information—including the digital signature
files granted to you by a certification authority—that InstallShield should use to sign your files.
The Signing tab is also where you specify which files in your installation should be digitally signed by
InstallShield at build time. InstallShield enables you to sign any and all of the following files in a release,
depending on what type of project you are using:
• Windows Installer package (.msi file) for Basic MSI, InstallScript MSI, and Web projects
• Merge module package (.msm file) for Merge Module projects
• Setup.exe file for Basic MSI, InstallScript MSI, and Web projects
• Media header file for InstallScript projects
• Package (self-extracting single-executable file) for InstallScript projects
• Any files in your release, including your application files
Windows Logo Guideline: All executable files (including .exe, .dll, .ocx, .sys, .cpl, .drv, and .scr files) in an installation must
be digitally signed for the Certified for Windows Vista program.
To learn more about the various settings on the Signing tab, see Signing Tab.
Certification Authorities
A certification authority is an organization such as VeriSign that issues and manages digital certificates
(also known as digital IDs). The certification authority validates the requester’s identity according to
prescribed criteria and issues a digital certificate. Obtaining a digital certificate requires providing the
certificate authority with specific information about your company and your product.
For a list of certification authorities, see Microsoft Root Certificate Program Members on the MSDN
Web site.
To learn more about Signcode.exe, including its command-line parameters, see the Microsoft Web site.
Tip: Using a .pfx file is often the preferred method for digitally signing files, since it is more likely to work in many different
environments (such as locked build machines). Since the SignTool.exe utility accepts the password as a command-line
parameter, it can be automatically provided even in scenarios where Signcode.exe cannot accept the password.
Therefore, if you specify the digital signature password in InstallShield, you will never see a password prompt if you are
using a .pfx file.
Important: InstallShield does not support using .pfx files to sign media header files (.hdr files), which are used for the
One-Click Install type of installation for InstallScript projects. For this type of installation, consider one of the following
alternatives:
• Use .spc and .pvk files instead of a .pfx file for your digital signature.
• Build a compressed installation, which would enable you to sign with a .pfx file.
To learn more about SignTool.exe, including its command-line parameters, see the Microsoft Web site.
Contact a certification authority for more details about digital certificate files.
Digital Certificates
A digital certificate identifies you, your company, or both to end users and assures them the data they
are about to receive has not been altered during its transfer over the Web. Certification authorities issue
and manage digital certificates.
When end users download your application, a digital certificate is displayed. The digital certificate is a
panel that informs end users when your application was signed and asks if they want to download and
run your application. End users click OK to accept your application package.
Below is an example of a digital certificate. The appearance of digital certificates may vary among
browsers and browser versions.
Task To configure digital signing for your release and its files:
• Certificate URL
• Private file key (PVK)—Note that if you specify a .pfx file, you do not also need to specify a
.pvk file.
• Certificate password
5. Select the appropriate check boxes to indicate which files in your release you want InstallShield to
sign.
If you select the Sign files in package check box, you must configure which files or file patterns
(such as all *.exe files) should be signed. You can also specify which files and file patterns should not
be signed.
Note that the files and file patterns that should not be signed override any files and file patterns that
should be signed. For example, if you specify *.exe in the Include patterns and files box and in
the Exclude patterns and files box, InstallShield does not sign any .exe files.
Tip: For detailed information about any of the settings on the Signing tab, see Signing Tab.
At build time, InstallShield signs the files as specified on the Signing tab. If the release is for an
installation that includes merge modules, note that the files are signed before the merge module is
merged.
Digitally Signing a Release After It Has Been Built From the Command Line
As an alternative to having InstallShield sign your application at build time, you can use the iSign
application (iSign.exe) to digitally sign a release of an InstallScript project from the command line after
you have built the release from the command line.
The iSign application is located in the following directory:
InstallShield Program Files Folder\System
This application uses Microsoft Authenticode technology to create digital signatures for your
installation. In order to use this program, you need a digital ID from VeriSign.
When you use the iSign application, you can specify options that are not available in the release build,
such as the cryptographic service provider.
The iSign syntax is as follows:
iSign [options] Filename
Filename is the fully qualified file name of your built release’s Data1.hdr file.
Following is a list of the options that you can use with iSign. Note that, unlike other command-line
applications, the switch and the argument for the switch should be separated by a space; for example:
iSign.exe -spc "C:\Temp\MyFile.spc" -v "C:\Temp\MyFile.pvk" -p "Test" -cp "Microsoft Base
Cryptographic Provider v1.0"
Option Description
-spc Fully qualified file name of the software publishing credentials (.spc) file.
Option Description
If iSign.exe is unable to determine the file to sign, the .spc file, or the .pvk file from the specified
command line, the application displays the options (help) screen.
Release Flags
Project: Release flags are not available for the following project types:
• InstallScript
• InstallScript Object
When you build your release, you can include and exclude features and setup prerequisites depending
on the type of release. For example, if you are creating a trial version of your product and do not want to
include all the features in the build, you can flag features and then specify those flagged features under
the product configuration or the release.
In this example, the full version comes with the application’s executable file, help files, and an add-on
pack. The trial version does not include the add-on pack, but it does include an upgrade pack. Rather
than having to create two separate installation projects for what is essentially one product, you can flag
those features that are specific to certain versions. For example, the add-on feature is flagged as Full
and the upgrade feature as Trial.
Feature or Setup
Prerequisite Version Release Flag
If you build your release through the Release Wizard, you are given the option of including any flagged
features and flagged setup prerequisites into your release. By default, the release contains all features
and setup prerequisites. If you specify the release flag Full in the Filtering Settings panel of the Release
Wizard, only the feature Add_Ons—along with all features and setup prerequisites without release
flags—is built into your release. The upgrade pack is not included in the installation.
Tip: By default, all features and setup prerequisites are included in a release. When you specify a release flag in either the
Releases view or the Release Wizard, only the unflagged features, the unflagged setup prerequisites, the features that
contain the specified flag, and the setup prerequisites that contain the specified flag are included in your installation.
Features and setup prerequisites that have only a release flag that you did not include in the Releases view or Release
Wizard are not built into your installation.
To demonstrate how product configuration and release flags interact, consider a project with the same
features as the example above:
Feature or Setup
Prerequisite Version Release Flag
The following table explains which features and setup prerequisites are included in your installation
based on the combination of product configuration flags and release flags:
Project: Release flags are not available for the following project types:
• InstallScript
• InstallScript Object
Once you have assigned release flags to your features and setup prerequisites, you can create a release
that includes the ones that are based on those flags. By default, all features and setup prerequisites are
included in a release. Once you specify a flag in either the Releases view or the Release Wizard, only the
unflagged features, the unflagged setup prerequisites, the features that contain the specified flag, and
the setup prerequisites that contain the specified flag are included in your installation. To include only
unflagged features and unflagged setup prerequisites, specify a flag that does not exist. For example, you
might use NoFlags. This way, only unflagged features and unflagged setup prerequisites are built into a
release.
It is possible to include a subfeature but not its parent feature. In such a case, the subfeature is built into
the release as a top-level feature, and its parent is excluded from the release.
You can filter features and setup prerequisites either in the Release Wizard or the Releases view. Each
method is described below.
You may want to release your product with more than one configuration—for example, an evaluation
release and a full release. Within a single project, you can build releases containing different subsets of
the project’s features; with a single installation script using preprocessor directives, you can build
releases with different run-time behaviors.
1. In your script, use preprocessor directives to execute different code for different product
configurations; for example:
#ifdef EVAL_RELEASE
/* Evaluation-specific code */
#elif FULL_RELEASE
/* Full release-specific code */
#endif
2. In the Compiler Preprocessor Defines box (on the General Options panel of the Release
Wizard) or the Compiler Preprocessor Defines setting (on the Build tab in the Releases
view), specify the preprocessor constant that corresponds to the code that you want the release to
execute.
3. Build the release.
11. The end user locates the application executable file on disk and launches the application.
Like any other installation, an Internet installation can use features such as updating, maintenance
mode, multi-instance installation, silent installation—in short, any feature that is available for any
InstallShield installation.
The following InstallScript functions are Internet-enabled:
Table 19-9:
Function Description
CopyFile Copies a file that is specified by a valid URL, or transmits a CGI or ASP request.
SeekBytes Repositions the file pointer within a file that is specified by a valid URL.
Player Object
Before you can use the setup player, you must create an instance of it. For more information, see Using
the Setup Player.
The Player has one method and one property.
• Open (<URL>)—Specifies the location of the data .cab files and returns a reference to an Ether
object. The argument consists of a URL representing the path to a web server, a UNC path, or the
path to the location of the files on your local drive.
Examples
Player.Open("http://www.mydomain.com/myproduct");
Player.Open("file://\\server\myproduct");
Player.Open("file://c:/my installations/myproduct/media/default");
LastError Method
Syntax
var nError = player.LastError;
Example
var ether = Player.Open("http://www.macrovision.com")
Parameters
None.
Return Values
-2147186688 No permissions were granted. Clicking Deny on the Java Security dialog throws this error.
-2147186686 Failed to update or install the Setup Player ActiveX control. Verify your ability to download from
the URL specified in the Codebase attribute of the APPLET tag.
-2147166892 Requested URL not found. Verify that your installation files are available at the URL specified
during the player.Open call.
-2147166895 Unable to access protected resource. This error is returned when attempting to access an
installation that requires authentication and the end user does not enter the correct information.
-2147012889 The server name could not be resolved. Verify that the URL used in your player.Open call.
Misspelling the domain name the URL is a common cause of this error.
Note: For the first six errors listed, the end user can check the Java console for detailed error information.
Open Method
Syntax
var ether = Player.Open("<URL string>")
Example
var ether = Player.Open("http://www.macrovision.com")
Parameters
Parameter Description
Return Values
The Open method returns a reference to an Ether object.
Ether Object
The Ether object supports the following methods:
Method Description
GetLastError Method
After calling the Ether object’s Play method, call the GetLastError method to find out the result of the
installation. GetLastError tells you if an error occurred, if the installation finished successfully, or if the
installation was canceled.
Syntax
ether.GetLastError( );
Example
It is best to poll GetLastError as in the following example:
var intervalID = 0;
function startInstall() {
if (ether)
{
ether.Play();
if (intervalID == 0)
intervalID = window.setInterval("IsSetupFinished()", 3000);
}
}
function IsSetupFinished()
{
var nResult = ether.GetLastError();
if (nResult != 0)
{
if (nResult == SETUP_FINISHED) // setup has completed successfully
/* to do */ ;
if (nResult == SETUP_ERR_CANCELLED) // setup was cancelled
/* to do */ ;
clearInterval(intervalID);
intervalID = 0;
}
}
Parameters
None.
Return Values
A complete list of GetLastError return values is in Disk1\_graphics\Utilities.js under the release’s
Disk Images folder, and is given below.
• SETUP_RUNNING
• SETUP_FINISHED
• SETUP_ERR_GENERAL
• SETUP_ERR_LOADMEDIA
• SETUP_ERR_INSTALLKERNEL
• SETUP_ERR_STARTKERNEL
• SETUP_ERR_OPENCAB
• SETUP_ERR_INSTALLSUPPORT
• SETUP_ERR_SETTEXTSUB
• SETUP_ERR_INITINFO
• SETUP_ERR_GETSETUPDRIVER
• SETUP_ERR_INITPROPERTIES
• SETUP_ERR_RUNINSTALL
• SETUP_ERR_UNINSTALLSUPPORT
• SETUP_ERR_EXTRACTBOOT
• SETUP_ERR_DOWNLOADFILE
• SETUP_ERR_CANCELLED
IsPlaying Method
The IsPlaying method of the Ether object returns a Boolean value indicating whether the installation is
running.
Syntax
var <variable> = ether.IsPlaying();
Example
var bPlaying = ether.IsPlaying();
Parameters
None.
Return Values
Play Method
The Play method of the Ether object starts the installation.
To see an example of the use of this method, build a release using the Create a default Web page option
in the Release Wizard’s Internet Options panel or the Release property grid’s Create Default Web Page
property, then examine the code in the generated Web page (Setup.htm).
Syntax
ether.Play();
Parameters
None.
Return Values
None.
SetProperty Method
The SetProperty method of the Ether object accepts two arguments. The first, a string, represents the
name of the property. The second represents the value to which the property is set, and it may be a
string, number, or Boolean value. The SetProperty method can set a script-defined property or a
predefined installation property as listed in the Parameters section. (Calling SetProperty to set a
property that is neither defined in the installation script nor on the list results in runtime error -5010.)
Syntax
ether.SetProperty("<string value>","<string value>");
Examples
ether.SetProperty("Name","Frank");
ether.SetProperty("Age",23);
Parameters
The following table contains the parameters for the SetProperty method.
Return Values
None.
• Setup.exe
• Data1.hdr
• ISSetup.dll
• _Setup.dll
If any of those files are unsigned or the signature is corrupted, the setup player displays a single prompt
to inform the end user that the signature could not be verified. If all files are properly signed and your
certificate is not yet always trusted, the setup player displays a prompt to ask the end user to authorize it
(similar to the one that is displayed when you run an executable file that you downloaded).
Macrovision signs the Setup.ocx and _Setup.dll files for you. The certificate that is used to sign the
Setup.exe, the Data1.hdr, and ISSetup.dll files must match. This happens automatically if you select the
options for signing the Setup.exe file and the media header.
AskDestPath
To display the equivalent dialog during the installation, call the InstallScript function AskDestPath in
your installation script. To pass a destination path to the installation from the Web page, set a script-
defined property.
CommandLine
Replace a line like the following:
ether.CommandLine = "<string value>";
To offer the equivalent functionality during the installation, call the InstallScript function SdFeatureTree
in your installation script. To pass a feature selection to the installation from the Web page, set a script-
defined property; in addition, in the installation script, use its value to conditionally call
FeatureSelectItem.
Features, GetState
To get a feature’s selection state during the installation, call the InstallScript function
FeatureIsItemSelected in your installation script. A Web page cannot get a feature’s selection state.
FileToOpen
To open a file during the installation, call the InstallScript function LaunchAppAndWait in your
installation script. To pass a file name to the installation from the Web page, set a script-defined
property.
GetDownloadSize, FileLevelCosting
To get the required disk space during the installation, call the InstallScript function FeatureGetTotalCost
in your installation script. (Feature dialogs such as SdFeatureTree display the required disk space.) A
Web page cannot get the required disk space.
Language
Replace a line like the following:
ether.Language = "<language code>";
By default, Internet installations run in legacy mode—that is, with the installation’s user-interface
events generated as appropriate. There are two ways to duplicate the effect of setting
ether.LegacyMode=false; on your Web page:
• Run the installation silently with the following line:
ether.SetProperty("is::CmdLine","-s");
ProductName
A Web page cannot get this information.
GetTargetDir
A Web page cannot get this information.
GetTextSub
A Web page cannot get this information.
IsInstalled
A Web page cannot get this information.
SetSetupType
To specify a setup type during the installation, call the InstallScript function FeatureSetupTypeSet in your
installation script. To display a setup type selection dialog during the installation, call SdSetupType in
your installation script. To pass a setup type to the installation from the Web page, set a script-defined
property.
SetTargetDir
To specify a target directory during the installation, assign a value to the system variable TARGETDIR in
your installation script. To pass the target directory to the installation from the Web page, set a script-
defined property.
SetTextSub
To specify a text substitution during the installation, assign a value to the TextSub object’s Value
property in your installation script. To pass a text substitution to the installation from the Web page, set
a script-defined property.
If ether.IsPlaying() Then
MsgBox "Setup is running."
Else
MsgBox "Setup is not running."
End If
Your One-Click Install installation can be run under the secure hypertext transfer protocol (HTTPS)—
that is, HTTP using the Secure Sockets Layer (SLL). The only modification that your installation
requires in order to run with HTTPS is to change http:// to https:// in URLs that are passed to Internet-
enabled functions.
Task To create a One-Click Install installation for a Basic MSI or InstallScript MSI project:
When you specify a language by using the following method, the One-Click Install installation runs in
this language regardless of the default language specified in InstallShield or the default language of the
target system. If you do not use this method, the One-Click Install installation determines the run-time
language in the same way as any other installation.
The easiest way to do so is to use the InternetErrorDlg API in WinInet.dll and return the value IDRETRY
from OnInternetError. This causes the installation to issue the HTTP request for the file again. If users
enter incorrect information, they will be prompted to enter it again.
Note: FLEXnet Connect works only with version numbers in packed DWORD format.
If any of these version numbers are not in packed DWORD format, you must modify the script code as
discussed in the following sections.
default:
IFX_INSTALLED_VERSION = "0.0.0";
endswitch;
endif;
Note: If you pass a null string ("") as the second argument to UpdateServiceRegisterProduct, only the first two parts of
your packed DWORD format version string—that is, major.minor—are registered as the version with the target machine’s
FLEXnet Connect database. To register the full version string—that is, major.minor.build—pass the system variable
IFX_PRODUCT_VERSION as the second argument to UpdateServiceRegisterProduct.
Setup.ini
If you want to customize Setup.ini further, modify it with a text editor. You can automate this process
by using the Postbuild Options panel of the Release Wizard or the Execute Batch File property in the
Releases view to launch a batch file or executable file that performs the desired modifications. Do not
simply overwrite Setup.ini with a modified copy from a previous media build; doing so could cause your
installation to work improperly.
Setup.ini contains two predefined sections:
• [Startup]
• [Mif]
You can add additional sections to Setup.ini to pass information to your setup script. You can then call
the GetProfString and GetProfInt functions to transfer the information from the Setup.ini file to your
installation.
Here is an example Setup.ini file:
[Startup]
AppName=My Application
CmdLine=/f1Test1.iss
EnableLangDlg=Y
LauncherName=MyInstall.exe
ProductGUID=23EAFFCA-361D-11D3-8B0F-00105A9846E9
SmallProgress=N
SplashTime=5
Skin=Setup.skin
CheckMD5=N
[Mif]
Type=SMS
Filename=Ishield
SerialNo=IS50-32XYZ-12345
Locale=DEU
Note: If you need to access the file later (after Disk1 has been removed), you should copy Setup.ini to the support
folder (SUPPORTDIR) at the beginning of the installation.
AppName
The AppName keyname identifies an application or product name to be displayed at the beginning of the
text string in the startup message dialog box.
Tip: MD5 checking can detect corrupted files, which is useful during Internet installations; not doing MD5 checking can
make file transfer proceed faster.
CmdLine
The installation reads the command-line parameters specified in Setup.ini first, and then appends any
command-line parameters passed to Setup.exe from the command prompt.
For more information about available command-line parameters, see Setup.exe and Update.exe
Command-Line Parameters.
EnableLangDlg
The EnableLangDlg keyname tells the installation whether to display the Language dialog during
installation initialization. The Language dialog lets your end user decide which available language the
installation should run in. You can set this value in the Setup Languages panel of the Release
Wizard or through the Languages Dialog property in the Releases view.
For more information about the Language dialog, see How InstallShield Determines Which Language
the Installation Runs In.
LauncherName
If you rename Setup.exe, the LauncherName keyname specifies the file’s new name. This keyname is
required if another installation will launch this installation using the DoInstall function.
ProductGUID
The ProductGUID keyname specifies the installation’s GUID so that Setup.exe has access to this data
during initialization. The media builder automatically enters the correct value in Setup.ini; do not
change the value.
SmallProgress
The SmallProgress keyname specifies whether the installation initialization dialog is the small box that
was shown by installations created with InstallShield Professional version 6.31 and earlier, or if it is
larger and is consistent with the rest of the end-user dialogs. Set the value to Y to display the small dialog
or N to display the larger dialog. (If the installation displays a security, Save and/or Run Setup, Choose
Setup Language, or Qualifying Product(s) Detected dialog, the installation initialization dialog is larger
and is consistent with the rest of the end-user dialogs, regardless of the value of this key.) You can set
this value in the User Interface panel of the Release Wizard or through the Small initialization dialog
property in the Releases view.
If SmallProgress is set to N, the installation initialization dialog (and the Choose Setup Language dialog,
if any) are not displayed until the startup graphic closes. To specify the length of time for which the
startup graphic displays, set the SplashTime value.
SplashTime
The SplashTime keyname specifies the length of time (in seconds) for which the startup graphic is
displayed.
Skin
The Skin keyname specifies the name of the skin file that the installation uses to display end-user
dialogs. If this keyname is not in Setup.ini, no skin is used. You can specify a skin in the User Interface
panel of the Release Wizard or through the Specify Skin property in the Releases view.
CheckMD5
The CheckMD5 keyname tells the installation whether to compare each file’s MD5 hash value to the
value stored in the installation header file during file extraction. You can set this value with the Verify
MD5 signature check box in the General Options - Advanced dialog box.
• Filename
• SerialNo
• Locale
Type
Set this key to SMS.
Filename
The Filename key is optional. It provides the alternate name for the .mif file to be created. If this key is
not included, the installation tries to use the AppName key under the [Startup] section of Setup.ini as
the .mif file name. If the AppName key is also not present, the installation creates a file with the default
name Status.mif.
The file name should not include an extension, since .mif files must have the .mif extension. The file
name should not include a path—it is placed in the Temp folder by default.
SerialNo
The SerialNo key is also optional. If provided, the information from this key is placed in the Serial
Number section in the .mif file. If this key is not present, the installation instead places quotation marks
("").
Locale
The Locale key tells the installation to place the indicated locale in the .mif file. English (ENU) is the
default; refer to Microsoft documentation for a complete listing of locale strings.
The following is an example of a Setup.ini file for an installation that will automatically create an .mif
file.
[Startup]
AppName=InstallShield
[Mif]
Type=SMS
Filename=IShield
SerialNo=IS50-32XYZ-12345
Locale=DEU
Cloning Releases
InstallShield enables you to clone or copy a release in the Releases view. This allows you to create a
release with all of its properties populated as they were in the cloned release. This way, if you want to
create more than one release with only a few differences between them, you can clone a release and
change only the settings that you need to change.
You can test run an installation to review the end-user dialogs. The test run displays the full user
interface, but it does not copy any files over to the target system or update the registry.
If you test a Try and Die product by running the protected trial version, it will expire at the end of the
trial; you will not be able to test your product further on the same test machine without removing the
license.
1. Copy the files that are added to the TestTools folder at build time to the test machine that contains
the license that you want to delete. For each file being wrapped, the TestTools folder contains the
following files:
• SCResetLicense<WrappedBaseFileName>.exe
• IsSvcInstSCResetLicense<WrappedBaseFileName>.dll
For example, if a file called Calc.exe is wrapped, the files in the TestTools folder are
SCResetLicenseCalc.exe and IsSvcInstSCResetLicenseCalc.dll.
2. On the test machine, run the SCResetLicense<WrappedBaseFileName>.exe file.
The license for your protected product is removed, and the trial state is reset. The next time you restart
your protected product on the same test machine, the trial starts over, enabling you to retest it.
Caution: Do not release the files in the TestTools folder with your product or make them available to your customers. Doing
so would enable end users to continually restart a trial each time that it expires. Note that the TestTools files are specific
to a particular product and license and cannot be used to delete licenses for other products.
Task To run any of your built installation packages, do one of the following:
• On the Build menu, click Run ReleaseName, where ReleaseName is the name of the release that
currently has focus in the Releases view.
InstallShield runs the release that currently has focus in the Releases view.
If you selected the Uninstall before installing check box in the Options dialog box, the previously run
release (if any) is uninstalled before the current release is run. This option is available on the Preferences
tab in the Options dialog box.
You cannot specify any command-line parameters when launching your installation from the
InstallShield interface. You must launch your installation from the command line to pass parameters to
the Windows Installer. For more information, see MsiExec.exe Command-Line Parameters.
If your release settings include Setup.exe, you can run the following command:
Setup.exe /s /v"/qn"
Basic MSI installations do not create or read response files. To set installation properties for a Basic MSI
project, run a command line such as:
msiexec /i Product.msi /qn INSTALLDIR=D:\ProductFolder USERNAME="Valued Customer"
Windows Logo Guideline: To comply with Windows logo requirements, a silent installation must create a response file in
which the default installation options are selected.
You can run your installation with the Setup.exe -r parameter to select installation options and
automatically record the InstallShield Silent response file, or you can create your own. To view a real-
world example of a response file, refer to the Setup.iss file located on InstallShield installation’s Disk1.
For a description of the response file format, see Creating the Response File.
If you need to install an InstallScript MSI installation without using Setup.exe, you can use the MSI
silent mode.
• RECORDMODE—Indicates that the Setup.exe file is automatically generating a silent installation file
(.iss file), which is a record of the installation input, in the Windows folder.
• SILENTMODE—Indicates that the installation is running in silent mode.
Tip: All InstallShield built-in and Sd dialogs automatically handle the values stored in the InstallShield Silent response file
(.iss file). If you are creating custom dialogs, you will need to call SilentReadData to handle the dialog’s return values in
silent mode.
After you have created or modified the installation, the next step in creating a silent installation is to
create the response file.
There are two ways in which you can create an InstallShield Silent response file: you can run the
installation and have InstallShield record and create the response file for you, or you can write the
response file directly.
All InstallShield built-in and Sd dialog functions are designed to write values into the Setup.iss file
when InstallShield runs in record mode (Setup -r). If you are creating custom dialogs, you will need to
call SdMakeName and SilentWriteData to add sections and dialog data to the response file when the
installation runs in record mode. Refer to the Sd dialogs’ source code in the <InstallShield
location>\Include folder for examples of using these functions to write to Setup.iss. Read the following
section for more information about what data to add to Setup.iss when calling SdMakeName and
SilentWriteData.
[InstallShield Silent]
Version=v7.00
File=Response File
The Version=v7.00 line indicates the version of the InstallShield Silent response file, not the version of
InstallShield. Use v7.00 in all response files. Future versions of InstallShield that use later response file
versions will be able to read earlier response file versions, so response file backward compatibility will be
maintained.
The Dlg<#> part consists of the letters Dlg and a sequence number. The first dialog in the installation is
Dlg0. Each dialog after that increments the value of <#> by one.
<DialogIdentifier> is in the form functionname-<#>, where functionname is the name of the function that
created the dialog, and <#> represents the sequential order of that particular dialog in the installation.
For custom dialogs, you can use any unique alphanumeric name for the functionname portion of
<DialogIdentifier>. For example, you could refer to a custom dialog as MyDialog. If the tenth dialog in
the installation were the second occurrence of the custom dialog MyDialog, there would be an entry in
the dialog sequence section such as the following:
Dlg9=<PRODUCT_GUID>-MyDialog-1
The <DialogIdentifier> expression is used to identify the dialog data section for the dialog.
Always end the dialog sequence section with a statement that has the following form:
Count=<number of dialogs>
The statement specifies the exact number of dialogs listed in the dialog sequence section. Count every
entry. Since dialog numbering begins with 0, the value of Count will always be 1 greater than the highest
<#> value for a dialog sequence.
The example below lists two dialogs, the Welcome dialog and the AskOptions dialog. Enter your dialog
sequence list into Setup.iss as shown in the example below.
[{23EAFFCA-361D-11D3-8B0F-00105A9846E9}-DlgOrder]
Dlg0={23EAFFCA-361D-11D3-8B0F-00105A9846E9}-Welcome-0
Dlg1={23EAFFCA-361D-11D3-8B0F-00105A9846E9}-AskOptions-0
Count=2
The corresponding dialog data entry in the Setup.iss file for a silent installation might look like the
following:
[{23EAFFCA-361D-11D3-8B0F-00105A9846E9}-AskDestPath-0]
Result=1
szPath=C:\Program Files\Macrovision\IS2008
In the above example, Result=1 is equivalent to clicking the Next button in the dialog, and
szPath=C:\Program Files\Macrovision\12 is the value returned in the svDir parameter of AskDestPath.
The name of the variable used in the script is meaningless relative to the Setup.iss file. However, in the
Setup.iss dialogdata sections, each built-in and Sd dialog has its own set of keynames that map to its
parameters. The keynames are important and must be exactly as defined for each dialog. Refer to Dialog
Data Keynames List, below.
When you use custom dialogs, you must create a dialog data entry for the Result keyname for each
dialog, plus entries for any other values set or returned by the custom dialogs. Use the Dialog Data
Keynames List, below, as an indicator of how to create keyname=value expressions for your custom
dialogs. Call GetProfString or GetProfInt to read the dialog data information for the custom dialog.
GetProfString and GetProfInt allow you to specify the .iss file, the section, and the keyname, and they
return the value assigned to that keyname.
When you are creating keynames to record subcomponent selections, precede the type, count, and <#>
keyname entries with the name of the component to which the subcomponents belong, thus:
Program Files-typeProgram Files-countProgram Files-0Program Files-1
To create complete value entries, use the equal sign to attach the values to the keynames. (The types of
values assigned to each kind of keyname are described below.) The following example shows complete
value entries for two components, Program Files and Binary Files, and two subcomponents of
Program Files, Executables and Support Elements:
Component-type=string
Component-count=2
Component-0=Program Files
Component-1=Binary Files
Program Files-type=string
Program Files-count=2
Program Files-0=Executables
Program Files-1=Support Elements
The type keyname indicates the data type of the components or subcomponents list. Since InstallShield
dialogs currently use only string lists for components and subcomponents lists, type is always equal to
string, as in Component-type=string. Future versions may use number lists, in which case type could
equal number.
The following example shows how subcomponent list selections are recorded. The example is for an
instance of the SdComponentMult dialog. The example shows that two components—Program Files and
Help Files—were selected. It also shows that four subcomponents were chosen: Main Files, Aux.
Files, Main Help, and Tutorial Files. Main Files and Aux. Files are subcomponents of Program
Files, and Main Help and Tutorial Files subcomponents of Help Files.
[{23EAFFCA-361D-11D3-8B0F-00105A9846E9}-SdComponentMult-0]
Component-type=string
Component-count=2
Component-0=Program Files
Component-1=Help Files
Program Files-type=string
Program Files-count=2
Program Files-0=Main Files
Program Files-1=Aux. Files
Help Files-type=string
Help Files-count=2
Help Files-0=Main Help
Help Files-1=Tutorial Files
Result=1
bvOpt1 = FALSE;
bvOpt2 = TRUE;
else
/* When the silent installation requires rebooting,
if you want to reboot immediately call
the System function as follows: */
System (SYS_BOOTMACHINE);
endif;
endif;
[Application]
Name=InstallShield
Version=10.50.000
Company=Macrovision Corporation
[{77AB941D-5876-11D4-A4A2-006067620F66}-DlgOrder]
Dlg0={77AB941D-5876-11D4-A4A2-006067620F66}-SdBitmap-0
Count=8
Dlg1={77AB941D-5876-11D4-A4A2-006067620F66}-Welcome-0
Dlg2={77AB941D-5876-11D4-A4A2-006067620F66}-SdRegisterUser-0
Dlg3={77AB941D-5876-11D4-A4A2-006067620F66}-AskDestPath-0
Dlg4={77AB941D-5876-11D4-A4A2-006067620F66}-SetupType-0
Dlg5={77AB941D-5876-11D4-A4A2-006067620F66}-SelectFolder-0
Dlg6={77AB941D-5876-11D4-A4A2-006067620F66}-SdStartCopy-0
Dlg7={77AB941D-5876-11D4-A4A2-006067620F66}-SdFinish-0
[{77AB941D-5876-11D4-A4A2-006067620F66}-SdBitmap-0]
Result=1
[{77AB941D-5876-11D4-A4A2-006067620F66}-Welcome-0]
Result=1
[{77AB941D-5876-11D4-A4A2-006067620F66}-SdRegisterUser-0]
szName=John Doe
szCompany=Macrovision Corporation
Result=1
[{77AB941D-5876-11D4-A4A2-006067620F66}-AskDestPath-0]
szPath=C:\Program Files\Product Name Version
Result=1
[{77AB941D-5876-11D4-A4A2-006067620F66}-SetupType-0]
Result=301
szDir=C:\Program Files\Product Name Version
[{77AB941D-5876-11D4-A4A2-006067620F66}-SelectFolder-0]
szResultFolder=Product Name Version
Result=1
[{77AB941D-5876-11D4-A4A2-006067620F66}-SdStartCopy-0]
Result=1
[{77AB941D-5876-11D4-A4A2-006067620F66}-SdFinish-0]
Result=1
bOpt1=1
bOpt2=0
The Setup.log file contains three sections. The first section, [InstallShield Silent], identifies the version
of InstallShield Silent used in the silent installation. It also identifies the file as a log file.
The second section, [Application], identifies the installed application’s name and version, and the
company name.
The third section, [ResponseResult], contains the result code indicating whether the silent installation
succeeded. An integer value is assigned to the ResultCode keyname in the [ResponseResult] section.
InstallShield places one of the following return values in the ResultCode key:
0 Success.
-1 General error.
-2 Invalid mode.
[ResponseResult]
ResultCode=0
You need to override the OnMsiSilentInstall event if you want to support the MSI silent installation
mode. This allows you to perform tasks that are normally performed in the OnFirstUIBefore,
OnFirstUIAfter, and feature event handlers.
Again, OnMsiSilentInstall will be called on MSI silent installation and on activation of an advertised
shortcut. It will not be called on Install-On-Demand, auto-repair, and uninstall mode.
To detect whether an MSI silent mode installation (including /q, advertise, auto-repair, uninstall, or
install-on-demand) is running from InstallShield script, check the Windows Installer property
ISSETUP_UISEQUENCE_PROCESSED using the MsiGetProperty Windows Installer API function.
If this property is not set, then it is a silent install. (It indicates that the InstallUISequence is not
executed.)
Validating Projects
Validating a project involves applying a set of internal consistency evaluator (ICE) rules to your
installation or merge module package. The ICEs are designed to ensure that the package contains a valid
database that performs its actions correctly. If a package fails one or more ICEs, InstallShield reports the
specific ICE rules that were violated and offers additional information to help you troubleshoot the
problem.
Microsoft created many of the ICEs that are available in InstallShield; Macrovision created the custom
InstallShield ICEs (ISICEs) that are available for the Certified for Windows Vista Validation Suite. The
ISICEs ensure that your installation is validated against best practices for Windows-based installations.
Windows Logo Guideline: Validating your project may help you identify whether your installation meets installation
requirements for Microsoft’s Certified for Windows Vista program. Therefore, if you are interested in being able to use the
Certified for Windows Vista logo, it is recommended that you use the Certified for Windows Vista Validation Suite to
validate your installation package. If you create a merge module in InstallShield, you can use the Certified for Windows
Vista Merge Module Validation Suite to validate your merge module.
To learn more about the Certified for Windows Vista program, visit http://www.InnovateOnWindowsVista.com.
Project: The InstallShield Premier Edition includes a set of validators called the InstallShield Best Practice Suite. The
InstallShield Best Practice (ISBP) validators in this suite alert you if your installation violates best-practice guidelines.
InstallShield also provides an engine for upgrade and patching validation. You can access this through
the Upgrade Validation Wizard.
Project: The only way to validate a package for an MSI Database project or an MSM Database project is to perform
validation on demand.
Note: If you want to see validation warnings that apply to your installation or merge module, you must perform validation
on demand; this type of validation message is not available if you perform validation at build time. InstallShield reports the
other types of validation messages—errors and failures—during both validation methods. To learn more about the
different types of validation messages, see Viewing Validation Results.
1. On the Tools menu, click Options. The Options dialog box opens.
2. Click the Validation tab.
3. Select the check boxes for the types of validation that you would like InstallShield to perform at
build time. If you prefer to validate on demand, and not at build time, clear the check boxes.
4. If you select the Perform validation using check box or the Perform Merge Module
validation using check box, select the type of validation that should be performed.
Note: If you want to see validation warnings that apply to your installation or merge module, you must perform validation
on demand; this type of validation message is not available if you perform validation at build time. InstallShield reports the
other types of validation messages—errors and failures—during both validation methods.
Task To specify which ICEs, ISBPs, ISICEs that should be run during validation:
1. On the Tools menu, click Options. The Options dialog box opens.
2. Click the Validation tab.
3. Click Customize. The Customize Validation Settings dialog box opens.
4. In the Select CUB file to customize list, click the suite that you want to customize.
5. In the list of ICEs, select the check box for each of the validators that should be used to evaluate the
installation package or merge module. Clear the check box for each of the validators that should not
be used for the validation.
To configure multiple consecutive validators, select the first file, press and hold SHIFT, and select
the last file. Then either select or clear the check box of one of the selected validators.
6. Click OK.
If you customize the list of ICEs, ISICEs, and ISBPs for a validation suite, anytime that validation is
performed—whether it occurs at build time or on demand—only the selected ICEs, ISICEs, or ISBPs are
used.
Validation Messages
Validation messages are broken down into three categories:
• Errors—Describe problems with your database, such as having duplicate component GUIDs.
• Failures—Occur when your database has severe enough problems that the validation tool might not
be able to run.
If the scan results for your project include validation messages, the messages and associated codes are
also listed on the Tasks tab of the Output window.
Note: If you want to see validation warnings that apply to your installation or merge module, you must perform validation
on demand; this type of validation message is not available if you perform validation at build time. InstallShield reports the
other types of validation messages—errors and failures—during both validation methods. To learn more about these two
validation methods, see Validating an Installation Package or Merge Module.
Tip: You can click a validation code on the Tasks tab of the Output window to see the corresponding Knowledge Base
article or HelpNet topic.
In addition, you can click a validation message on the Tasks tab to jump to the area of the Direct Editor that corresponds
to the validation message. This functionality is available for ICEs, ISICEs, and ISBPs.
ICEs
The validation tool checks your project for compliance with each of the internal consistency evaluators,
or ICEs. These ICEs are those used by Msival2.exe (part of the Microsoft Windows Installer Platform
SDK) to validate installation and merge module packages for Windows logo compliance.
If your installation project or merge module project fails one or more of these ICEs, InstallShield reports
the specific ICE rules that were violated and offers additional information to help you troubleshoot the
problem.
To learn about specific ICEs, see ICE Reference in the Windows Installer Help Library.
ISICEs
A number of InstallShield ICEs (ISICEs) were added to the Certified for Windows Vista Validation Suite
to check your project for compliance with installation requirements of the Certified for Windows Vista
program.
The following table lists the ISICEs that are available in InstallShield.
ISICE Description
ISICE01 Validates that the application is installed to ProgramFiles or the user’s AppData folder by default.
ISICE02 Validates that all executable files included with the installation are digitally signed.
ISICE03 Validates that there are no nested-installation custom actions (type 7, 23, and 39).
ISICE04 Validates that there are no custom columns added to standard .msi tables.
ISICE05 Validates that there are no properties or custom tables that begin with MSI (case-insensitive).
ISICE06 Validates that the installation does not include any files protected by Windows Resource Protection.
ISICE07 Validates that MSI components are authored for proper installation and uninstallation.
ISICE08 Validates that deferred custom actions do not have the impersonate bit set.
ISICE10 Validates that each custom action has a path specified for the Help File Path setting in the Custom
Actions view.
ISICE11 Validates that .exe files have embedded manifests with required information.
ISICE13 Validates that no .hlp files or WinHelp run-time files are included in the installation. This ICE is now
ISBP17.
ISICE Description
ISICE14 Validates that no obsolete APIs are imported. This ICE is now ISBP18.
ISICE15 Validates that no deprecated APIs are imported. This ICE is now ISBP19.
ISICE16 Validates that no 16-bit components are distributed in an installation that targets 64-bit systems.
ISICE19 Validates properties related to upgrades, that the Upgrade table is present, and that the installation
prevents downgrades.
Tip: In some cases, the following validation error message may be displayed for an ISICE:
File [1] in Component [2] could not be found. All tests against this file's contents may be
invalid.
This error occurs if the specified file is missing, and the associated ISICE could not be verified for the file. For example, if
an executable file is missing, ISICE11 cannot verify whether the file has an embedded manifest.
If the aforementioned validation error message is displayed, resolve the missing file issue, and then rerun validation for
your project.
ISICE01
Message (Error)
The application should be installed to either ProgramFiles or AppData folder by default. The
current default location is [1].
Description
Users should be able to install products where they need them, and they should have a consistent
experience with where files are stored by default.
ISICE01 verifies that the default destination location for your product is the Program Files folder or the
Application Data folder. If a different location is used, this error message is displayed during validation.
Corrective Action
Change the default location. For more information, see Setting the Default Product Destination Folder
(INSTALLDIR).
ISICE02
Message (Error)
File [1] in Component [2] is not digitally signed. All [3] files distributed to Windows(R) Vista
are required to be signed.
[1] is the name of an executable file, [2] is the name of the component that contains that file, and [3] is
the type of file that must be signed.
Description
ISICE02 verifies that all executable files in your installation have been digitally signed. This includes
files with the following extensions: exe, dll, ocx, sys, cpl, drv, and scr. If an executable file in your
installation has not been digitally signed, this error message is displayed during validation.
Corrective Action
Ensure that all executable files in your installation have been digitally signed. For more information, see
Digital Signing and Security.
ISICE03
Message (Error)
Nested custom action [1] of type [2] is not allowed.
[1] is the name of a custom action in your project, and [2] is the Windows Installer type number of
custom action.
Description
ISICE04 verifies that your installation does not include any nested-installation custom actions. Nested
installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft
Corporation recommends that you avoid using nested installations and nested-installation custom
actions to install products that are intended to be released to the public. To learn more, see Concurrent
Installations on the MSDN Web site.
Corrective Action
To resolve this error, remove the nested-installation custom action from your project. The MSI Type
Number value in the Custom Actions and Sequences view (in Basic MSI, InstallScript MSI, MSI
Database, Transform, and Web projects) or the Custom Actions view (in Merge Module and MSM
Database projects) for nested-installation custom actions is 7, 23, or 39.
As an alternative to using a nested installation, you may want to create a create a setup prerequisite, and
then add that setup prerequisite to your installation project. For more information, see Defining Setup
Prerequisites.
ISICE04
Message (Error)
The standard MSI table [1] does not match the MSI schema defined in schema.msi.
Description
ISICE04 verifies that your installation does not add custom table columns to standard tables. Adding
columns to standard tables is reserved for future versions of Windows Installer.
Corrective Action
To resolve this error, remove any custom table columns that were added to the table that is mentioned in
the error message. You can do this by exporting the table from the Direct Editor, editing the table in a
text editor, and importing the revised table.
ISICE05
Messages
Message 1 (Error)
MSI property [1] begins with reserved characters. MSI property names cannot start with "MSI"
(case-insensitive).
Message 2 (Error)
Table [1] begins with reserved characters. Custom table names cannot start with "MSI" (case-
insensitive).
Description
ISICE05 verifies that your installation does not include any custom properties or custom tables whose
names begin with MSI in any combination of uppercase and lowercase letters. The MSI prefix is
reserved for future use in new standard properties and tables.
Corrective Action
To resolve the property-related error, use the Property Manager to rename the custom property that is
mentioned in the error message.
To resolve the table-related error, use the Direct Editor to export the table, use a text editor to edit the
table name in the exported .idt file, and use the Direct Editor to import the newly renamed table into the
Direct Editor. Then delete the original custom table.
ISICE06
Message 1 (Error)
File [1] in Component [2] is a Windows Protected File. Protected files may not be distributed to
Windows(R) Vista.
[1] is the name of a file in your project, and [2] is the name of the component that contains that file.
Message 2 (Warning)
File [1] in Component [2] has the same file name as a Windows Protected File, but appears to be
distributed to a different path.
[1] is the name of a file in your project, and [2] is the name of the component that contains that file.
Description
ISICE06 verifies that your installation does not install files that are protected by Windows Resource
Protection (WRP). WRP is designed to ensure that protected system resources are updated on Windows
Vista machines only through Microsoft-approved installation or update mechanisms.
If your installation installs a file that has the same name as a Windows Protected File, but the file is not
installed to the same location as the Windows Protected File, warning message 2 is displayed.
Corrective Action
To resolve the validation error, remove the file that is mentioned in the error message from your project.
If you encounter the validation warning, determine if the file that is mentioned in the message is a
protected file:
• If the file is not a protected file but it has the same name as a protected file, you can ignore this
warning.
• If the file is a protected file, remove it from your project to resolve this warning.
If your product requires newer versions of system components, the components must be updated on
target machines by using a Microsoft service pack or a Microsoft-approved installation package that
contains the system component. System components should not be repackaged.
ISICE07
Messages
Message 1 (Error)
Component.ComponentId for Component [1] is null. All components must have a valid ComponentId
for proper installation and uninstallation. If this is left null, justification must be
documented.
[1] is the name of a component in your project that does not have a GUID specified in the Component
Code setting in the Components view.
Message 2 (Error)
Component [1] contains COM data, but it has more than 1 file. Each COM component should contain
only 1 COM file.
[1] is the name of a component in your project that contains more than one COM server.
Message 3 (Error)
Component [1] has more than one file as the target of a Desktop or Start Menu shortcut.
[1] is the name of a component in your project that has more than one file specified as the target of a
shortcut.
Message 4 (Error)
Component [1] is associated with multiple features and is referenced in the following tables:
[2]. These references require the component to be associated with exactly 1 feature.
[1] is the name of a component in your project that is associated with more than one feature and that has
references in any of the following tables: Class, Extension, MsiAssembly, PublishComponent,
TypeLib. [2] is a comma-delimited list of tables that contain references to the component.
Description
ISICE07 verifies that the components in your installation adhere to component rules, which help to
ensure that the installation or uninstallation of one product does not harm any other product on a target
system. These rules also help to ensure that Windows Installer correctly removes all resources that are
connected with a product that is being uninstalled.
Corrective Action
To resolve error 1, open the Components view, select the component that is mentioned in the error
message, and click the Component Code setting. In the help pane that is displayed in the lower-right
pane, click Generate GUID. If you have a valid reason for leaving the Component Code setting blank, you
can document it in the application that you submit for the Certified for Windows Vista program.
To resolve error 2, move any COM servers to separate components so that each COM server is the key
path of its component.
To resolve error 3, use the Shortcuts view to delete all but one of the shortcuts that are associated with
the component mentioned in the error message.
To resolve error 4, use the Setup Design view or the Features view to remove the component from all but
one feature.
ISICE08
Message (Error)
Custom Action [1] uses impersonation. Impersonation should not be used when running setups on
Windows Vista.
Description
ISICE08 verifies that your installation does not contain any custom actions that use impersonation. If
you select one of the Terminal Server Aware options for the type of in-script execution setting (in the
Custom Actions and Sequences view, in the Custom Actions view, or on the Respond Options panel of
the Custom Action Wizard), the custom action impersonates the end user during per-machine
installations on terminal server machines.
Corrective Action
To resolve this validation error, open the Custom Actions and Sequences view (or the Custom Actions
view) and click the custom action that is mentioned in the error message. Change the value of the In-
Script Execution setting to one of the options that does not include Terminal Server Aware.
ISICE09
Message (Error)
An MsiPatchCertificate table entry is required for User Account Control (UAC) patching.
Description
ISICE09 verifies that your installation includes an MsiPatchCertificate table entry. In a base
installation, this table provides the signer certificate that will be used to verify the digital signature of
subsequent patches when they are applied by a non-administrator or an administrator who is not using
elevated privileges.
Corrective Action
To resolve this validation error, add the MsiPatchCertificate table to your project. To learn how, see
Preparing Installations for Non-Administrator Patches.
ISICE10
Message (Error)
Custom action [1] of type [2] is not documented in table [3].
[1] is the name of a custom action in your project, and [2] is its Windows Installer type number. [3] is the
name of the table that is missing an entry for the custom action that is listed.
Description
The intended behavior of each custom action must be documented for the Certified for Windows Vista
program. This is especially helpful if system administrators deploy your product to enterprise
environments; they sometimes need to know what the custom actions do.
ISICE10 verifies that each custom action in your installation is documented by validating that each entry
in the CustomAction table has a corresponding ISCustomActionReference table entry.
Corrective Action
To resolve this validation error, open the Custom Actions and Sequences view (or the Custom Actions
view), select the custom action that is mentioned in the error message, and use the Help File Path setting
to specify a path to the document that describes the behavior of the custom action. When you specify a
value in the Help File Path setting, InstallShield adds a row for that custom action in the
ISCustomActionReference table if one has not already been created.
In addition, configure the product configuration for the release so that InstallShield streams the
contents of each of the custom action help files into the .msi file at build time. For more information, see
the description of the Include Custom Action Help setting for a product configuration in the Releases
view.
Note that if the custom action is a merge module that is consumed in your installation project, specify
the path in the Custom Actions view of the merge module project and then rebuild the merge module.
ISICE11
Messages
Message 1 (Error)
Exe [1] in component [2] lacks a manifest.
[1] is the name of an executable file in your project that does not have a manifest, and [2] is the name of
the component that contains the executable file.
Message 2 (Error)
Exe [1] in component [2] lacks a requiredExecutionLevel level setting in its manifest.
[1] is the name of an executable file in your project that has a manifest that was possibly created for
Windows XP but that was not updated for Windows Vista. The manifest does not define the execution
level for the executable file. [2] is the name of the component that contains the executable file.
Message 3 (Error)
Exe [1] in component [2] lacks a requiredExecutionLevel uiAccess setting in its manifest.
[1] is the name of an executable file in your project that has a manifest that was possibly created for
Windows XP but that was not updated for Windows Vista. The manifest does not define the UI
accessibility value for the executable file. [2] is the name of the component that contains the executable
file.
Message 4 (Warning)
Exe [1] in component [2] is marked to require elevated privileges (highestAvailable) which
requires a waiver from Microsoft.
[1] is the name of an executable file in your project that has a manifest that specifies that elevated
privileges are required, and [2] is the name of the component that contains the executable file.
Message 5 (Warning)
Exe [1] in component [2] is marked to require elevated privileges (requireAdministrator) which
requires a waiver from Microsoft.
[1] is the name of an executable file in your project that has a manifest that specifies that elevated
privileges are required, and [2] is the name of the component that contains the executable file.
Message 6 (Warning)
Exe [1] in component [2] is marked to require uiAccess which requires a waiver from Microsoft.
[1] is the name of an executable file in your project that has a manifest that specifies that the executable
file is allowed to bypass UI protection levels in order to use higher privileges to pass information to other
windows on the desktop; that is, the value of uiAccess is set to true. [2] is the name of the component
that contains the executable file.
Description
ISICE11 verifies that every .exe file in your installation has an embedded manifest that defines its
execution level. The execution level is defined in the manifest as follows:
<requestedExecutionLevel
level="asInvoker"
uiAccess="false"/>
Other valid values for the level attribute are highestAvailable and requireAdministrator. Note that if you
set the level value to highestAvailable or requireAdministrator, you must apply for a waiver from
Microsoft to obtain Windows logo certification.
The uiAccess attribute indicates whether the executable file is allowed to bypass UI protection levels in
order to use higher privileges for passing information to other windows on the desktop, such as on-
screen keyboards. This attribute should be set to true only for UI accessibility applications. Note that if
you set the UI accessibility value to true, you must apply for a waiver from Microsoft to obtain Windows
logo certification.
Corrective Action
To resolve the validation errors (messages 1 through 3), replace the executable file in your installation
with one that has an embedded manifest whose level and uiAccess values are set appropriately.
The validation warnings (messages 4 through 6) are displayed to inform you that if you want to have
your product qualify for the Certified for Windows Vista program but you keep the
requestedExecutionLevel element as it is currently defined in the executable file’s manifest, you may
need to obtain a waiver from Microsoft.
ISICE12
Message (Error)
Registry key [1] in Component [2] is a protected registry key. Protected registry keys may not
be modified on Windows(R) Vista.
[1] is a registry key that only the Trusted Installer group can modify on Windows Vista systems, and [2]
is the name of the component that contains that registry key.
Description
ISICE12 verifies that the installation does not attempt to modify registry keys that are protected by
Windows Resource Protection (WRP) on Windows Vista systems. Registry keys that can be modified by
only the Trusted Installer group are protected by WRP.
Corrective Action
To resolve this validation error, use the Registry view to remove the protected registry key from your
project, or move it to a part of the registry that is not protected by WRP.
ISICE16
Message (Error)
File [1] in Component [2] is a 16-bit file. Installations that target 64-bit systems may not
include 16-bit files.
[1] is the name of a 16-bit file in your project, and [2] is the name of the component that contains the file.
Description
If your installation targets 64-bit platforms, ISICE16 verifies that it does not contain any 16-bit files,
since 64-bit platforms do not support 16-bit files.
Corrective Action
To resolve this validation error, replace the 16-bit file with a 64-bit or 32-bit file.
ISICE17
Messages
Message 1 (Error)
Sequence [1] includes the [2] action. Use of the [2] action requires a waiver from Microsoft.
[2] is the name of an action in your project, and [1] is the name of the sequence that contains that action.
Message 2 (Error)
Control [1] on Dialog [2] runs the [3] action. Use of the [3] action requires a waiver from
Microsoft.
[3] is the name of an action in your project. [2] is the name of the control that includes an event that
launches that action. [2] is the name of the dialog that has the control.
Description
ISICE17 verifies that the installation does not use an action to force a reboot. Currently, the only action
that is validated is ForceReboot.
Corrective Action
The errors are displayed to inform you that if you want to have your product qualify for the Certified for
Windows Vista program but you keep the specified action in your installation, you may need to obtain a
waiver from Microsoft.
To resolve these validation errors, remove the action from sequence or dialog that is mentioned in the
message.
Ensure that your project includes the MsiRMFilesInUse dialog to minimize system reboots, and that
your application has been properly instrumented to use the Restart Manager API. For more information,
see Minimizing Reboots on Windows Vista Systems.
ISICE18
Messages
Message 1 (Error)
Dialog [1] is not present in the Dialog table.
Message 2 (Error)
The Title of Dialog [1] does not include '[2]' or '[ProductName]'.
[1] is the name of a dialog in your project, and [2] is the value of the [ProductName] variable.
Description
ISICE18 verifies that the installation includes the MsiRMFilesInUse dialog, and that the dialog’s title bar
contains the name of the product.
Corrective Action
To resolve error 1, ensure that the MsiRMFilesInUse dialog is in your project. All Basic MSI projects
include this dialog by default. For more information about this dialog, see Minimizing Reboots on
Windows Vista Systems.
To add the dialog back to a Basic MSI project, you can open another Basic MSI project that contains this
dialog, or create a new Basic MSI project. Then export the dialog to the project that needs it. For more
information, see Exporting Dialogs to Other Projects.
To resolve error 2, add the product name or the [ProductName] property to the Caption property for the
MsiRMFilesInUse dialog.
ISICE19
Messages
Message 1 (Error)
The table [1] is not present in the installation package.
Message 2 (Error)
UpgradeCode [1] does not detect and prevent downgrades with a properly scheduled Type 19 Custom
Action; the package must prevent downgrades.
Message 3 (Error)
The property [1] is not listed in SecureCustomProperties; this can prevent it from being used
correctly for downgrade prevention.
Message 4 (Error)
The property [1] must be a valid GUID; '[2]' is not a valid GUID.
[1] is the name of a property whose value should be a valid GUID. [2] is the invalid value that is currently
used for that property.
Message 5 (Error)
Column [1] of table Upgrade must hold a valid GUID; '[2]' is not a valid GUID.
[1] is the name of a column in the Upgrade table, and [2] is the value of an entry in the specified
column.
Message 6 (Error)
The property [1] must hold a valid numeric version in the format Major.Minor.Build; '[2]' is not
a version in this format.
[1] is the name of a property whose value should be a version number in the Major.Minor.Build format.
[2] is the invalid value that is currently used for that property.
Message 7 (Error)
Column [1] of table Upgrade must hold a valid numeric version in the format Major.Minor.Build;
'[2]' is not a version in this format.
[1] is the name of a column in the Upgrade table, and [2] is the value of an entry in the specified
column.
Message 8 (Error)
The property [1] must not be null or empty.
Message 9 (Error)
Column [1] of table Upgrade must not be null or empty.
Message 10 (Error)
The property [1] must be provided; '[2]' is the default value.
[1] is the name of a property in your project that has not been customized. [2] is the default value that
InstallShield uses for that property.
Message 11 (Error)
The property [1] must hold a valid numeric LANGID; '[2]' is not a numeric LANGID.
[1] is the name of a property whose value should be a valid language identifier. [2] is the invalid value
that is currently used for that property.
Description
ISICE19 validates properties related to upgrades and that the Upgrade table is present. ISICE19 also
ensures that the installation prevents an earlier package from installing over a new package.
Corrective Action
To resolve errors 1 and 2, ensure that the Upgrades view contains a major upgrade item, that the major
upgrade item is properly configured to prevent the current version of your product from being installed
over a future version, and that your project includes a properly configured and scheduled type 19 custom
action. For detailed instructions, see Preventing the Current Installation from Overwriting a Future
Major Version of the Same Product. For more information, see Preventing an Old Package from
Installing Over a Newer Version in the Windows Installer Help Library.
To resolve error 3, add the specified property to the value of the SecureCustomProperties property.
You can use the Property Manager view to set a value for a property. To add multiple values, separate
each with a semicolon. For more information, see SecureCustomProperties Property in the Windows
Installer Help Library.
To resolve errors 4 and 5, replace the existing value with a valid GUID. To change the value, open the
General Information view and click Product Properties. Then click the property that is listed in the error
message. Type a valid GUID. Note that if you want to use a new, unique GUID, you can click the
Generate GUID button in the help pane that is displayed in the lower-right area of InstallShield. For
more information, see GUIDs.
To resolve errors 6 and 7, replace the specified value with a valid version number; you can click the error
message in the Output window to move to the location in the Direct Editor that has the invalid value.
The version number must contain only numbers, and it must be in the format aaa.bbb.ccccc, where
aaa represents the major version number, bbb represents the minor version number, and ccccc
represents the build number. The maximum value for the aaa and bbb portions is 255. The maximum
value for ccccc is 65,535. For more information, see Specifying the Product Version.
To resolve error 8, enter a value for the specified property. You can use the Property Manager view to set
a value for a property.
To resolve error 9, enter a value for the specified column. You can use the Direct Editor view to set the
value; you can click the error message in the Output window to move to the location in the Direct Editor
that needs to be revised. To learn more about any of the Windows Installer tables, see Database Tables in
the Windows Installer Help Library.
To resolve error 10, replace the default value of the specified property with the appropriate value. You
can use the Property Manager view to change the value.
To resolve error 11, replace the existing value of the specified property with a valid language identifier.
ISICE20
Messages
Message 1 (Error)
Row [1] of Table [2]: installing, modifying, or deleting a registry key in root [3] requires
elevated privileges, but this package does not request elevated privileges.
[1] is the name of the row that contains information about a registry change in your project. [2] is the
name of the table that contains that registry-related data. [3] is the predefined root key for the registry
data, as listed in the Root column for the specified row.
Message 2 (Error)
Row [1] of Table [2]: installing, modifying, or deleting a file in directory [3] requires
elevated privileges, but this package does not request elevated privileges.
[1] is the name of a row that contains information about a directory that end users cannot access without
elevated privileges. [2] is the name of the table that contains that directory data. [3] is the name of the
directory.
Message 3 (Error)
Environment variable [1] is a system environment variable, but this package does not request
elevated privileges.
[1] is the name of a system environment variable that is included in your project.
Description
If the Require Administrative Privileges setting in the General Information view is set to No for your
project, ISICE20 verifies that your installation does not attempt to perform tasks that require
administrative privileges, such as writing to system registry or folder locations.
Corrective Action
To resolve ISICE20 errors, do one of the following:
• Select Yes for the Require Administrative Privileges setting in the General Information view. For
more information, see Entering Summary Information Stream Data.
• Change your project so that it does not install, modify, or delete data in system locations. For
example, if your project adds a registry key to HKEY_LOCAL_MACHINE, use the Registry view to
move that registry key to HKEY_CURRENT_USER. If your project adds or modifies a system
environment variable, use the Environment Variables view to change the Type setting of that
environment variable from System to User.
Edition: The InstallShield Best Practice Suite is available in the Premier edition of InstallShield.
InstallShield includes a set of validators called the InstallShield Best Practice Suite. The InstallShield
Best Practice (ISBP) validators in this suite alert you if your installation violates best-practice guidelines.
The following table lists the ISBPs that are available in InstallShield.
ISBP03 Basic MSI, MSI Verifies that no ComboBox is shorter than 50 units.
Database
ISBP04 Basic MSI, MSI Verifies that properties used on dialogs are secure or restricted public
Database properties.
ISBP06 Basic MSI, Verifies that InstallUISequence custom actions are also sequenced in the
InstallScript MSI, MSI InstallExecuteSequence.
Database
ISBP07 Basic MSI, Verifies that all features have associated components and all components are
InstallScript MSI, MSI associated with features.
Database
ISBP08 Basic MSI, Verifies that ARPINSTALLLOCATION is set after CostFinalize in the
InstallScript MSI, MSI InstallExecuteSequence.
Database
ISBP09 Basic MSI, Verifies that LIMITUI is not set without ARPNOMODIFY.
InstallScript MSI, MSI
Database
ISBP10 Basic MSI, Verifies that AppSearch properties are secure or restricted public properties.
InstallScript MSI, MSI
Database
ISBP11 Basic MSI, Verifies that no precompiled .NET assemblies are being distributed.
InstallScript MSI, MSI
Database
ISBP13 Basic MSI, MSI Verifies that properties set by dialog controls and used in the installation have
Database a default value.
ISBP14 Basic MSI, Verifies that each file has the correct version information or an MsiFileHash
InstallScript MSI, MSI entry.
Database
ISBP15 Basic MSI, MSI Verifies that no RadioButtonGroup has Text defined.
Database
ISBP16 Basic MSI, Verifies that each component with a 64-bit destination is marked as a 64-bit
InstallScript MSI, MSI component.
Database
ISBP17 Basic MSI, Validates that no .hlp files or WinHelp run-time files are included in the
InstallScript MSI, MSI installation.
Database
ISBP01
Message (Error)
Feature ALL conflicts with the installation meta-feature ALL.
Description
ISBP01 verifies that your installation does not have a feature called ALL in uppercase, lowercase, or
mixed case letters. In the context of features, Windows Installer reserves the word ALL for use as a valid
value for feature-state properties such as ADVERTISE, REINSTALL, and ADDLOCAL, which can
contain the names of specific features, as well as the word ALL to indicate all features. Therefore, none
of the individual features in a project should be called ALL.
Corrective Action
To resolve this error, change the name of the feature to something other than ALL. For more
information, see Creating Features.
You can also resolve this error by clicking the ISBP01 error message in the Output window. InstallShield
displays the Feature table in Direct Editor view, and highlights the row that contains the feature named
ALL. To rename the feature, select the current name and then type a new one.
ISBP02
• Basic MSI
• InstallScript MSI
• MSI Database
Message (Error)
Directory DATABASE conflicts with Windows Installer's undocumented directory DATABASE.
Description
ISBP02 verifies that your installation does not have a directory called DATABASE in uppercase,
lowercase, or mixed case letters. Windows Installer reserves this directory name.
Corrective Action
To resolve this error, click the ISBP02 error message in the Output window. InstallShield displays the
Directory table in Direct Editor view, and highlights the row that contains the directory named
DATABASE. To rename the directory, select the current name and then type a new one.
ISBP03
Message (Warning)
ComboBox [1] on Dialog [2] has a height less than 50. This results in a ComboBox too short to
view multiple items at once.
[1] is the name of a combo box control, and [2] is the name of the dialog that has that control.
Description
If a combo box control has a height of less than 50 installer units, end users may be able to see only one
item in the box at a time. To improve the usability, consider changing the height to 50 or higher.
Corrective Action
To resolve this warning, click the ISBP03 warning message in the Output window. InstallShield displays
the Control table in Direct Editor view, and highlights the row that contains the combo box control.
Then change the value in the Height column for that control to 50 or higher.
ISBP04
• MSI Database
Messages
Message 1 (Warning)
Dialog [1] Control [2] uses private property [3]. Its value will be unavailable to the execute
sequence.
[1] is the name of a dialog in your project, [2] is the name of a control on that dialog, and [3] is the name
of a private property that is being set or used by the control.
Message 2 (Warning)
Dialog [1] Control [2] uses insecure custom property [3]. Its value may be unavailable to the
execute sequence.
[1] is the name of a dialog in your project, [2] is the name of a control on that dialog, and [3] is the name
of a property that is used by that control.
Description
You cannot set a private property in the user interface sequence of the installation and then pass the
value of that private property to the execute sequence. Therefore, ISBP04 verifies that your installation
does not have any dialog controls that use private properties. If a dialog control does use a private
property, warning 1 occurs to alert you that you may need to take steps to allow a property’s value to be
passed to the execute sequence.
In addition, if you set a public property in the user interface sequence of an installation that requests
elevated privileges for the execute sequence, and you want to pass the property’s value to the execute
sequence, the property must be listed as a value for the SecureCustomProperties property, or it
must be a restricted public property. Therefore, ISBP04 also verifies that if your installation has dialog
controls that use custom public properties, the custom public properties are listed as values for the
SecureCustomProperties property. If the custom public properties are not listed in the
SecureCustomProperties property, warning 2 occurs to alert you that you may need to take steps to
allow a property’s value to be passed to the execute sequence.
Corrective Action
If you do not need to use the property in the execute sequence, you can disregard the warning message.
However, if you do need to use the property in this sequence, you need to resolve the warning.
If you need to resolve warning 1, change the private property to a public property. To do so, find the
dialog control in the Dialogs view; for the Property property of that control, use all uppercase letters,
since public properties must be in all uppercase. Also update all other instances of that property name in
your project so that it matches.
If you need to resolve warning 2, open the Property Manager view. For the Value column of the
SecureCustomProperties property, add the name of the property that is mentioned in the warning
message. If this property contains more than one property, separate each one with a semicolon (;).
ISBP05
• Basic MSI
• MSI Database
Message (Warning)
Dialog [1] Control [2] has a NULL condition. To ensure the control event always runs, use a
condition of 1.
[1] is the name of a dialog in your project, and [2] is the name of a control on that dialog.
Description
ISBP05 verifies that each event’s condition for each dialog control is not null. This helps to ensure that
Windows Installer triggers the control’s events under the proper circumstances.
Corrective Action
If Windows Installer should trigger the event that has a null condition only if no other event for that
control is triggered, you can disregard the warning message.
If you do need to resolve this warning, locate the dialog in the Dialogs view. Click the Behavior item
under the dialog. In the list of controls, click the one that is mentioned in the warning message. Ensure
that in the lower-right pane, the Events tab is displayed. Then, in the grid in the upper-right pane, enter
a condition for the event. To ensure that Windows Installer triggers the event, enter 1 as the condition.
ISBP06
Message (Warning)
Custom Action [1] is scheduled in the InstallUISequence but not the InstallExecuteSequence. It
will not run during a silent or reduced UI installation.
Description
Actions that are scheduled for the Execute sequence during the Installation sequence do not run during
silent, basic UI, or reduced UI installations.
Corrective Action
If Windows Installer should launch the custom action during silent, basic UI, and reduced UI
installations, consider scheduling the custom action for the installation execute sequence—in addition to
or instead of the installation UI sequence.
To reschedule the action, open the Custom Actions and Sequences view, and find the action mentioned
in the warning message. Then drag it from the Installation sequence’s User Interface sequence to the
Installation sequence’s Execute sequence.
To schedule the action in both sequences, copy the action in the Installation sequence’s User Interface
sequence to the Installation sequence’s Execute sequence. You can do this in the Custom Actions and
Sequences view by pressing and holding CTRL while dragging the action from the former sequence to
the latter sequence.
If Windows Installer should not launch the custom action during silent, basic UI, and reduced UI
installations, you can ignore this warning.
ISBP07
Messages
Message 1 (Warning)
Feature [1] has no components.
Message 2 (Warning)
Component [1] is not associated with any features.
Description
ISBP07 verifies that every component in your project belongs to at least one feature. If you do not
associate a component with at least one feature, Windows Installer cannot install the component.
ISBP07 also verifies that every feature in your project contains at least one component. Components
contain the installation elements, such as files, shortcuts, and registry entries; if a feature does not
contain a component, it does not contain anything to install.
Corrective Action
To resolve either of these warnings, use the Setup Design view to associate components with features. To
learn more, see Associating Existing Components with Features.
ISBP08
• Basic MSI
• InstallScript MSI
• MSI Database
Message (Warning)
There does not appear to be a Type 51 action setting ARPINSTALLLOCATION after CostFinalize in
the InstallExecuteSequence.
Description
The ARPINSTALLLOCATION property specifies the fully qualified path to the primary destination
folder of a product. Windows Installer writes this value to the Uninstall registry key.
The ARPINSTALLLOCATION property is typically set by a set-a-property type of custom action (type
51).
The SetARPINSTALLLOCATION custom action is a built-in InstallShield custom action that is added
automatically to Basic MSI and InstallScript MSI projects. If you delete this custom action from your
project, you may encounter the ISBP08 warning.
Corrective Action
To resolve this warning, add to your project a custom action with the following settings:
• Property Name: ARPINSTALLATIONLOCATION
ISBP09
Message (Error)
The property LIMITUI has been set, but ARPNOMODIFY has not. This can lead to undesirable
behavior with Add or Remove Programs.
Description
If you set the LIMITUI property in an installation, you should also set the ARPNOMODIFY property.
The LIMITUI property sets the user interface level to basic. An installation run with a basic UI typically
displays only progress messages to end users. It does not allow end users to select features or provide
other feedback.
The ARPNOMODIFY property prevents end users from modifying the product through Add or
Remove Programs.
Corrective Action
To resolve this error, add the ARPNOMODIFY property to your project through the Property Manager
view, and set its value to 1. For more information, see Creating or Changing Properties.
ISBP10
Message (Warning)
AppSearch [1] uses insecure custom property [2]. Its value may be unavailable to the execute
sequence.
[1] is the name of a system search in your project, and [2] is the name of a property that is used by that
system search.
Description
If you set a public property in the user interface sequence of an installation that requests elevated
privileges for the execute sequence, and you want to pass the property’s value to the execute sequence,
the property must be listed as values for the SecureCustomProperties property, or it must be a
restricted public property. Therefore, ISBP10 verifies that if the AppSearch table in your project contains
custom public properties, the custom public properties are listed as values for the
SecureCustomProperties property. If the custom public properties are not listed in the
SecureCustomProperties property, the warning occurs to alert you that you may need to take steps
to allow a property’s value to be passed to the execute sequence.
Corrective Action
If you do not need to use the property in the execute sequence, you can disregard the warning message.
However, if you do need to use the property in this sequence, you need to resolve the warning.
To resolve this warning, open the Property Manager view. For the Value column of the
SecureCustomProperties property, add the name of the property that is mentioned in the warning
message. If this property contains more than one property, separate each one with a semicolon (;).
ISBP11
Message (Warning)
File [1] appears to be a precompiled native image of a .NET assembly. This may decrease the
efficiency compared to precompiling on the target machine.
Description
ISBP11 verifies that your project does not include a precompiled native image of a .NET assembly.
Corrective Action
To resolve this warning, replace the native image file mentioned in the message with the appropriate
.NET assembly file.
If you want the assembly to be compiled to machine code during the installation, select Yes for the .NET
Precompile Assembly setting of the file’s component.
Precompilation, or just-in-time compilation, takes into account the fact that some code might never be
called during execution. It converts the assembly as it is needed during execution and stores the
resulting native code so it is accessible for subsequent calls. Precompiling on the target machine allows
the process to take advantage of the exact architecture of the machine on which it will be running.
ISBP12
Messages
Message 1 (Error)
Custom Action '[1]' appears to invoke self-registration via RegSvr32. Best practices encourage
authoring COM and Registry table data into the installer package.
[1] is the name of a custom action in your project that may be registering a file through RegSvr32.exe at
installation time.
Message 2 (Error)
File '[1]' is self-registered. Best practices encourage authoring COM and Registry table data
into the installer package.
Description
Although InstallShield lets you designate that a COM server is self-registering, the preferred method of
registering a COM server is to extract the COM information from the file at build time or design time;
with this method, InstallShield writes the COM class information to the Class, ProgID, and Registry
tables of the .msi database. Self-registration has several limitations; for details, see Self-Registering
COM Servers.
Corrective Action
To resolve error 1, remove the custom action that is referenced in the error message, and configure COM
extraction for the file as appropriate.
To resolve error 2, configure COM extraction for the file as appropriate.
To learn more, see Extracting COM Information from a COM Server.
ISBP13
Message (Error)
Property '[1]' has no default, is set by a dialog control, and is used in table [2]. This may
not be populated in a silent or reduced UI installation.
[1] is the name of a property in your project, and [2] is the name of the table that uses that property.
Description
In most cases, each property in the Property table should have a default value. The default value is used
if end users run the installation in silent, reduced UI, or basic UI mode.
Corrective Action
If you do not need to add a default value for the property, you can disregard the error message.
To resolve this error, open the Property Manager view. Enter a value in the Value column for the
property that is specified in the error message.
ISBP14
Messages
Message 1 (Error)
File '[1]' has neither a file version nor an MsiFileHash record. This may require the source
package when installing a patch.
Message 2 (Error)
File '[1]' is recorded as version '[2]' but is actually version '[3]'. This may require the
source package when installing a patch.
[1] is the name of file in your project. [2] is the version number that is configured for the file, but [3] is
the actual version number.
Description
ISBP14 verifies that each file in the project has the correct version information or an MsiFileHash entry.
Using the correct version information in versioned files and MsiFileHash entries for unversioned files
helps Windows Installer to detect and eliminate unnecessary file copying. It also helps ensure that the
source package is not required to apply a patch to an earlier version of a product.
Corrective Action
To resolve error 1, consider adding the file version number to the file. If the file is an unversioned file,
configure the file so that a file hash is used.
InstallShield enables you to override a file’s version information. Error 2 may occur if the file’s
properties were overridden. To resolve this error, consider removing the version override.
To configure the settings for a file, open the Files and Folders view. In the Destination computer’s
files pane, locate the file, right-click it, and click Properties. The Properties dialog box opens, enabling
you to configure version information and specifying whether file hashing should be used.
ISBP15
Message (Error)
Control [2] on the Dialog [1] is a borderless RadioButtonGroup with overlapping controls and
data in the Text column. This may cause repaint issues on some systems.
Description
ISBP15 verifies that if you have a borderless radio button group control on a dialog and one or more
other controls overlap the radio button group, the radio button group does not have anything specified
for its Text attribute. If it does, it may cause repaint issues for some versions of Windows Installer.
Corrective Action
To resolve this error, click the ISBP15 error message in the Output window. InstallShield displays the
Control table in Direct Editor view, and highlights the row that contains the radio button control that is
mentioned in the error message. Delete the string in the Text column for that radio button control.
As an alternative, you can change the radio button group control so that it uses a border. To do this, open
the Dialogs view and find the dialog mentioned in the error message. Click the radio button control, and
change its Has Border property to True.
ISBP16
Message (Error)
Component [1] installed to 64-bit location [2] is not marked with the 64-bit component
attribute. This may allow files to be installed to an incorrect location.
[1] is the name of a component, and [2] is the destination folder for the component’s files.
Description
If a component is not configured to be 64 bit, Windows Installer may not install the component’s files to
the appropriate 64-bit location.
Corrective Action
To specify that a component is 64 bit, select Yes for the component’s 64-Bit Component setting.
For more information about the 64-Bit Component setting, as well as additional component settings, see
Component Properties.
ISBP17
Messages
Message 1 (Error)
File [1] in Component [2] is a WinHelp file and may not be distributed to Windows(R) Vista.
[1] is the name of an .hlp file in your project, and [2] is the name of the component that contains the .hlp
file.
Message 2 (Error)
File [1] in Component [2] is a WinHelp run-time file and may not be distributed to Windows(R)
Vista.
[1] is the name of a Windows Help application file in your project, and [2] is the name of the component
that contains that file.
Description
ISBP17 verifies that .hlp files are not included in your project because Windows Vista does not support
this type of file.
In addition, ISBP17 verifies that WinHlp32.exe and WinHelp.exe are not included in the project because
these applications should not be redistributed.
Corrective Action
To resolve this validation error, remove the help file from your project. Consider converting your help
system to a different file format such as .chm, .htm, or .xml. Note that you would need to change your
calls from the WinHelp API to the new help system.
ISBP18
Message (Error)
File [1] in Component [2] imports obsolete API [3].
[1] is the name of a file in your project, and [2] is the name of the component that contains the file. [3] is
the name of the obsolete API that the file uses.
Description
ISBP18 verifies that none of the .dll or .exe files in your project use obsolete kernel APIs.
Corrective Action
To resolve this validation error, replace the file with an updated version that does not use the obsolete
API. Note that to create the updated version, you may need to rewrite and rebuild the .exe or .dll file. If
the .exe or .dll file is from a third-party vendor, contact the vendor to request an updated version.
ISBP19
Message (Error)
File [1] in Component [2] imports deprecated API [3].
[1] is the name of a file in your project, and [2] is the name of the component that contains the file. [3] is
the name of the deprecated API that the file uses.
Description
ISBP19 verifies that none of the .dll or .exe files in your project use deprecated kernel APIs.
Corrective Action
To resolve this validation error, replace the file with an updated version that does not use the deprecated
API. Note that to create the updated version, you may need to rewrite and rebuild the .exe or .dll file. If
the .exe or .dll file is from a third-party vendor, contact the vendor to request an updated version.
Note: Do not confuse the MSI Debugger with the InstallScript Debugger, since they have completely separate purposes.
You cannot debug an installation package with the InstallScript Debugger, and you cannot debug an InstallScript custom
action with the MSI Debugger.
• On the Build menu, point to MSI Debugger and click Start MSI Debugging.
• On the Build menu, point to MSI Debugger and click Step Over.
• Press F5.
• Press F11.
The debugger runs the installation, returns focus to itself, and stops the execution of the installation
when it reaches the breakpoint. Back in the debugger, you can do any of the following:
• View and set Windows Installer properties.
• On the Build menu, point to MSI Debugger and click Toggle Breakpoint.
• Press F9.
You can set the breakpoint before you start debugging or while a debugging session is open.
When the debugger reaches the breakpoint, you can view and set properties or continue debugging.
Tip: Notice that the debugger lists the condition, if any, after each action. Set breakpoints carefully on conditional actions,
because if the condition does not evaluate to true, the action is not executed and the debugger will not step in at that
point.
Removing Breakpoints
Task To clear all breakpoints set in the debugger, do one of the following:
Task To step into the current action in the MSI Debugger, do any of the following:
• On the Build menu, point to MSI Debugger and click Step Into.
• Press F11.
A dialog box opens and asks if you want to launch your registered debugger. Select Yes to launch the
deubugger. Select No to step over to the next custom action.
Note: Because InstallShield does not provide the source code for the entry point, you will see some machine code once
the registered debugger is launched. You need to click the Step Into button twice to see your code.
Task To step over the current action or dialog and continue the execution in the MSI Debugger, do any of the
following:
• On the Build menu, point to MSI Debugger and click Step Over.
• Press F10.
Once the debugger reaches a breakpoint on a standard or custom action, it halts the execution of the
installation and receives focus. You can then watch and set installer properties.
To continue stepping through each successive action, keep pressing F10. You may need to click Next on
each dialog in the Setup wizard to progress through the sequence. To view the return value of an action,
place the cursor over the action after it has executed. The return value is displayed as a tooltip. If the
action executed successfully, the tool tip reads ERROR_SUCCESS.
Although setting a breakpoint on an action causes the debugger to break at each subsequent action,
setting a breakpoint on a dialog takes you just to that dialog and then the debugger does not step in again
until the next breakpoint.
• On the Build menu, point to MSI Debugger and click Stop MSI Debugging.
• Press SHIFT+F5.
If the debugger is stopped at a break point on a dialog when you try to end the debugging session,
InstallShield displays a message box with this message: “Please close all the dialogs to stop the
debugging session.” To close any open dialogs, first press F11 to step over the current breakpoint. Then,
close any open dialogs.
Canceling out of the installation also stops the debugger.
If your installation requires more than one floppy disk, CD, DVD, or custom-sized media disk, you need
to span it across multiple disks.
Limitations
Due to limitations of the Windows Installer service, you cannot run multi-disk installations on a non-
removable drive. For example, if your installation spans two CDs, you need to physically burn the CDs in
order to test your installation. If you try to run it from a fixed drive, the installation will fail.
• The second file that must be included on disk one is the .msi file that you are building. The total
combined size of the .msi file, Setup.exe, and the Windows Installer installation files exceeds the
maximum capacity of a standard 1.4 MB floppy disk. You have two options if you plan to distribute
your setup on floppy disks:
• You can distribute your installation without Setup.exe. This option is not available if you are
creating an InstallScript MSI project. In addition, this option is not viable if you are targeting
any platform other than Windows 2000 or later.
• The second and most feasible option is to use a distribution medium other than floppy disks.
• Any transforms included in your installation must reside on the first disk. For example, if you create an
installation with multiple run-time languages, an .mst file is created for each of those languages.
This file is applied to the installation database, and it provides the language selected in the Language
Selection dialog.
• Redistributables (including merge modules) included in your installation must be stored on the first disk.
Redistributables are streamed into the installation database while the script is built. This process
cannot be completed if the redistributables are located on another disk.
Disk Prompts
Disk prompts are displayed to end users when they need to place another disk in the drive to continue
with the installation. Although a standard disk prompt is provided, you can provide a prompt that is
specific to your product.
The string that is displayed actually comes from a number of sources throughout your project, as
described below:
1. The complete prompt originates in the Error table (exposed in the Direct Editor) as error 1302.
2. This value in turn comes from the string table, and the default value for English reads “Please insert
the disk: [2].”
3. Windows Installer resolves [2] with the value of the property DiskPrompt, which is set to [1] in
the Property Manager.
4. Finally, Windows Installer evaluates [1] to the string you enter into the Disk Prompt field.
In most cases, you will want to enter the same name as the disk volume. For example, assuming the
defaults are unchanged, a Disk Prompt entry of Disk8 would cause the user to be prompted with “Please
enter the disk: Disk8.”
You can use a question mark where the disk number will be displayed. This question mark automatically
evaluates to the correct disk number. If you want to prompt your users with, “Please insert the disk:
DISK4,” you would enter DISK? for the fourth disk’s name. You need to specify the disk prompt for each
disk in your installation.
Volume Labels
The volume label is the name of the disk on which your installation resides. When the installation calls
for a new disk, the Windows Installer engine verifies that the volume label of the disk matches the
volume label that is stored in the installation database. If the labels do not match, the service assumes
that the wrong disk has been inserted in the drive. You can change the volume label when you customize
your disk spanning options. The default volume label is DISK1, DISK2, DISK3, and so on. When you
build your installation, you will see these directories created in your output location. The disks on which
you put your setup need to have the volume labels set to the same names as given by the wizard.
Caution: You cannot change a volume label after the installation has been built. If you do not specify the correct volume
label, the Windows Installer service will not recognize the disk and the installation will fail.
You can use a question mark to define the number of the disk. For example, if you want to set the volume
label for your disks to InstallShield Disk 1, InstallShield Disk 2, and so on, you would rename
every disk so that they read InstallShield Disk ?. At build time, this question mark evaluates to the disk
number.
Additional Information
If you add features to your installation after you have defined how you want your installation to span
across multiple disks, those features are automatically added to the last disk of your installation. You can
add new disks to your installation at any time by using the Release Wizard.
Distributing Installations
Once you have created your installation, you may need to distribute it to a specified location. This
location can be a network drive, a floppy disk, a different location on a local drive, or an FTP site. When
you distribute your installation, the disk image created when you built your installation is copied to the
location that you specify.
Note: If your installation consists of only one disk, the contents of the Disk1 folder are copied to the release location, but
not the folder itself. If your installation spans across multiple disks, the folders and their contents are copied to the release
location.
Project: For InstallScript and InstallScript Object projects, InstallShield automatically copies the release to the location
that you specify on the Postbuild tab every time that you build the release.
For any of the following project types, InstallShield copies all of the relevant files for your release to the specified location
whenever you right-click the release in the Releases view and then click Distribute:
• Basic MSI
• InstallScript MSI
• Merge Module
• Web
If you specify a folder and an FTP site on the Postbuild tab, InstallShield copies the files to only the FTP location.
If you want the build engine to copy your release to the specified location after every build in a Basic
MSI, InstallScript MSI, Merge Module, or Web project, select Yes for the Distribute after build
setting.
Compressed Size
Although many people now connect to the Internet through high-speed cable modems or DSL lines,
others still use lower-speed modems. Package size is very important to people with slower connections
due to the increased amount of online time required to download an application.
Self-Extracting
Many file compression utilities require a special client-side application to decompress the application
files. This need for another utility complicates the download and installation process for end users. To
simplify the installation process, the compression utility that you use should be self-extracting so that no
other application is required.
Digitally Signed
To make your customers feel more secure about downloading and installing your software, you can
digitally sign your application package. The digital signature identifies you or your company to end users
and assures them that the application code has not been altered or tampered with since publication. To
learn how to digitally sign your application, see Digital Signing and Security.
To learn more about digital signatures, visit www.verisign.com.
Easy to Use
Perhaps the most important aspect of packaging your installation for Internet distribution is making it
easy to use. Your end users may not want to specify a location where the installation files should be
saved and then search their computer to locate those files. Instead, the installation should be seamlessly
integrated into the compression package, requiring only one step to begin the installation.
Challenge Explanation
Disk Space Although Microsoft ships Windows 2000 and later with the Windows Installer
service, all other operating systems to date do not ship with this service.
Therefore, the Windows Installer service must be installed before your
installation can run. Unfortunately, there are two versions of this installation—
one for Windows NT 4.0 and one for Windows 9x. Each of these installations
requires more than 1.4 MB of disk space. Because of these file size
requirements, it is difficult to distribute your installation program on a floppy
disk if you need to distribute the Windows Installer service installations as well.
Disk Spanning The .msi file created by InstallShield that interacts with the Windows Installer
service cannot be spanned across multiple disks and it must reside on the first
disk of your installation. Therefore, if you want to include all of your files in one
compressed .msi file, it might not fit on one floppy disk. However, if your files
can remain uncompressed, they can be included on successive disks of the
installation.
Note: If you build a multiple-disk installation, you need to set the volume label on the second and subsequent disks.
• data<2, 3, 4, …>.cab
• data1.cab
• data1.hdr
• ISSetup.dll
• layout.bin
• setup.exe
• setup.ini
• setup.inx
Option Files
• setup.isn—Skin File
Offering prospective customers a free trial version of your product can be a highly effective sales tool,
but it carries the risk that some will abuse the privilege and continue to use the product without paying
for it. InstallShield enables you to create a protected trialware version of your product without requiring
you to modify the source code.
With the Trialware view, you can configure trialware settings for one or more of your product’s
executable files to protect your product from piracy. Using InstallShield to protect your product lets you:
• Invest minimal time and expense to turn your product into trialware.
• Set firm expiration dates using sophisticated, flexible technology that blocks unauthorized
extensions of trials.
• Specify hyperlinks that should be displayed in the trialware run-time dialogs, which are launched
whenever end users launch a protected application. The hyperlinks direct users to Web pages that
inform them, for example, how to purchase your product.
• Ensure that paid-for copies of your product automatically revert to trial mode when they are shared
with other end users.
Types of Trialware
InstallShield offers different types of trialware to help you control unauthorized use of your product:
• Try and Buy/Product Activation
• Try and Die (available with the Premier edition of InstallShield only)
• Unprotected (that is, the product’s installation is built without applying trialware protection)
• A customer buys your product but does not need to evaluate it. Distributing a Try and Buy/Product
Activation version of your product to paying customers lets you control unauthorized use of your
product.
Note: Try and Die functionality is available with the Premier edition of InstallShield only.
Unprotected Product
You can configure the trialware settings in your installation project and then later easily build a release
of your product that does not have the trialware protection. You can use this non-trialware release if you
want to test the installation of your product but you do not want to test the trialware run time. For more
information, see Excluding Trialware Protection from a Release.
Unprotected Product
If an application is not protected with the trialware functionality available in InstallShield, the end user
launches the main application file when starting the product. This main application may call
subordinate applications and use data contained in data files.
The structure of a typical unprotected application is illustrated in the following diagram:
The addition of the Try and Die shell to the main application file does not change the file’s version
number or the file’s last-modified date. However, it does increase the size of that file.
Figure 20-3: Product protected with a Try and Buy/Product activation shell
Trialware Technology
With the Trialware view, you can configure a license for trialware. InstallShield uses the license to wrap
a trialware shell around your product’s executable file (.exe, .dll, .ocx, or .scr file). The file can be
unwrapped and used only according to the license settings that you configure, such as the trial limit (a
specified number of days or a specified number of uses).
The trialware technology available in InstallShield should not be confused with freeware or shareware.
Often freeware and shareware have limited functionality. For example, end users sometimes cannot
print anything from shareware or freeware, or a watermark might be added to every page. Such
limitations are established to encourage prospective customers to purchase a fully functional version of
a product; however, building such limitations into your product can be costly and waste valuable
development time.
With trialware, the only limitation is the time limit or the limited number of uses. You enable a
prospective customer to use the latest version of your product—with all of its features fully available—on
a trial basis. No dongle is used to limit or lock software access. After a predetermined trial limit has been
reached, the trialware expires.
Licenses
Trialware technology actually involves two types of licenses: a license that wraps the protected
executable file and a license that identifies a protected trialware product on the end user’s machine. Both
types of license are associated with each other by a license number, and the term license is used to refer
to both types of licenses.
When you create trialware with InstallShield, you acquire a unique license for your product. The license
is downloaded from the license server to your machine, and it is stored in your InstallShield project file.
InstallShield uses the license to wrap a trialware shell around your product’s application file. The
application file can be unwrapped and used only according to the license settings that you configure.
When an end user runs your trialware for the first time on their machine, the trialware stores a license in
both a license file and an anchor. Both must be present on a system to allow licensing to work. The
anchor is stored in an operating system–specific location to hinder end users from trying to reset the
license state by simply deleting the license file. This approach allows license data to remain safe even if
the trialware product or the operating system requires reinstallation.
If an end user reformats a hard drive that has trialware, it will not affect license data stored on that
machine. However, repartitioning the hard drive will. End users can use ghosting utilities to back up a
disk or partition to an image and restore the trialware later.
• License number
• Request code
• Transaction ID
The request code is created using the following information:
• License serial number, which identifies the license for the trialware on the end user’s machine
• 64-bit machine serial number, which is used to identify the end user’s machine
• 32-bit machine disk identifier, which is generated from information about the Windows boot disk
returned by the disk controller
• Date that the license request is made, as displayed by the machine’s system clock
• Obfuscate the function call to make it difficult for unscrupulous users to create their own versions of
the unwrapped .dll file in an attempt to work around the trialware protection and use your
application without having to activate it.
With this workaround, when an end user tries to launch the executable file, the executable file calls the
protected .dll file, which triggers the trialware technology.
Customer Support
Customer support employees primarily use the InstallShield Activation Service Publisher Web Site to
assist end users with the offline activation of your products. They will also use this Web site to perform
the following activities:
• Manage serial numbers to protect against the misuse of your products.
• Add to your licenses the serial numbers that end users will use to activate your product.
• Limit the number of times each serial number may be activated, thereby allowing your customers to
install your product on multiple machines, while also preventing abuse of the license.
• Prevent any additional activations if abuse is suspected.
• Monitor and record the number of times that end users attempt to activate additional copies of your
product. This indicates the need for additional licenses and can guide direct sales.
Product Managers
Product managers use this Web site to run reports on the state of the product’s business. They also use
this Web site to perform the following activities:
• Run reports on the number of activations during a trial period.
Note: End users cannot activate a Try and Buy/Product Activation version of your product unless you purchase the
InstallShield Activation Service.
Online Activation
The online activation process starts when the end user chooses to activate the product and then enters a
serial number in the trialware run-time dialog. From there, the rest of the activation process is
automatic. No manual intervention is required by you or the end user.
The following procedure outlines the steps that occur during an online activation.
1. The end user launches the trialware. Before the trialware application starts, the trialware run-time
dialogs are displayed.
2. The end user enters the serial number in the run-time dialog.
3. The trialware sends an activation transaction to the activation server via the Internet.
4. A response code is sent to the trialware shell on the end user’s machine.
The trialware shell uses the response code to activate the product. The entire process typically takes only
seconds to complete. The amount of data being transmitted is very small, so high-speed connections are
not required.
Offline Activation
If the online activation process does not work (for example, if the end user does not have an Internet
connection), the end user can choose to activate offline (if you allowed it when you configured the
trialware settings for the product). Offline activation requires manual intervention by both the end user
and by one of your customer support employees; therefore, offline activation is more costly for you to
support than online activation.
The following procedure outlines the steps that occur for an offline activation.
1. The end user launches the trialware. Before the trialware application starts, the trialware run-time
dialogs are displayed.
2. The end user enters the serial number in the run-time dialog.
3. The trialware attempts to perform the online activation, but it fails because, for example, the end
user’s machine does not have an Internet connection. The trialware run-time dialog displays several
options: Activate by Internet (to enable the end user to retry the activation by Internet),
Activate by Email, or Activate by Phone.
4. If the end user selects email or phone and then clicks Next, the next trialware run-time dialog
contains contact information, as well as the serial number and the request code. They use the
contact information to provide you with the serial number and the request code.
5. Your customer support employee logs on to the InstallShield Activation Service Publisher Web Site
and enters the serial number and request code that the end user provided. The Web site provides a
response code, and your customer support employee gives that response code (via email or phone—
whichever method the end user selected) to the end user.
6. The end user enters the response code in the trialware run-time dialog.
The trialware shell uses the response code to activate the product.
Note that the entry of the response code can either be done immediately or at a later time. Minutes, days,
or even months later, the product will still be waiting for the same response code. The product will be
instantly activated once the end user enters the response code.
Caution: The request codes and response codes that are used with phone activations are shorter than the ones that are
used with offline email activations; the shorter length of the codes makes it possible to read the codes over the phone.
However, short codes are not as secure as the longer codes used with email activations. Therefore, Macrovision
recommends that you carefully consider the security risks associated with offline phone activation before offering it as an
offline activation method. Use of this option is at your own risk, and Macrovision accepts no responsibility if your company
experiences security issues.
3. Rename the item if necessary. The name is for internal use only and is not displayed to end users.
4. On the General tab, select the application file (.exe, .dll, .ocx, or .scr) in your project that you want
to protect.
Once you have added the file in the Trialware view, you need to select the appropriate type of trialware
and acquire a license.
Note: InstallShield displays a warning icon ( ) for the item that you added to the Trialware Files explorer. In order to
protect a file, you must specify the corresponding .exe, .dll, .ocx, or .scr file; the type of trialware; and the license. Once
you have specified these settings, InstallShield changes the warning icon to a protected trialware icon ( ).
Edition: The Try and Die type of trialware is available in the Premier edition of InstallShield.
Acquiring a License
A license identifies a protected trial product. Macrovision recommends that you acquire a unique license
for each version of your product. Otherwise, the following results could occur:
• For Try and Buy/Product Activation trialware—If end users activated version 1.0 of your product
and you use the same license to wrap version 2.0, end users would be able to download version 2.0
and it would be activated. This may be acceptable, but you may prefer that they purchase version
2.0.
• For Try and Die trialware—If end users try version 1.0 of your Try and Die product, the trial expires
when the predetermined trial limit has been reached. Thus, the same end users would not be able to
also try version 2.0 if you use the same license to wrap version 2.0.
Under certain conditions, you may want to use the same license for multiple versions of a Try and Buy/
Product Activation product. For example, if all of the following are true, you could use the same license:
• You are preparing an upgrade for the earlier version of your product that was wrapped with the Try
and Buy/Product Activation type of trialware.
• End users who have activated the earlier version should not need to re-activate when they apply the
upgrade and then run the upgraded product.
• You are not charging existing end users for the upgrade; you are making it available to all end users
who paid for the earlier version.
the end user clicks the Cancel button on one of the trialware run-time dialogs and does not start
using the product.
• If you set the trial limit to a specific number of uses, the countdown for the number of trial uses
starts with the first time that the end user launches your product. If an end user clicks the Cancel
button on one of the trialware run-time dialogs and does not start using the product, the number of
uses does not change.
Note that for per-user installations of trialware, the trialware usage count is per machine—not per
user on the same machine.
In addition to specifying the trial limit, you can specify whether end users are allowed to extend the trial
limit. If you allow trial extensions, you must specify the number of days or the number of uses that the
trial can be extended. You also must specify the extension serial number that all end users should use to
extend the trial.
If you want to prevent end users from evaluating or activating your trialware after a specific date, you
can specify the expiration date. To learn more, see Expiration Dates for Trialware.
Trial Limit and Extension Example for Try and Buy/Product Activation
To illustrate how the trial limit and a trial extension affect the Try and Buy/Product Activation type of
trialware, consider the following properties and the corresponding values that are specified on the
Advanced tab of the Trialware view:
• Type of Trial Limit = Uses
Table 20-1: Trial Limit and Extension Example for Try and Buy/Product Activation
1 through 20 For the first 20 times that the end user launches the product, a trialware
run-time dialog is displayed before the product starts, informing the end
user how many more times the y can use the product without activating
it. If the Product Purchase URL property contains a URL, the run-time
dialog displays a hyperlink that the end user can click to visit a Web
page for information on purchasing the product.
If the end user chooses to evaluate the product without activating it, the
end user can click Finish. Then the trialware run-time dialog closes and
the product starts.
Table 20-1: Trial Limit and Extension Example for Try and Buy/Product Activation (cont.)
21 When the end user launches the product for the twenty-first time, a
trialware run-time dialog is displayed before the product starts,
informing the end user that the trial has expired and they must activate it
to continue using it.
If the end user clicks Cancel, the trialware run-time dialog closes and the
product cannot be started. The end user can launch the product again,
which again displays this same run-time dialog.
If the end user clicks Next, the trialware run-time dialog prompts the end
user for a serial number that will activate the product.
• If the end user enters the correct extension serial number, the trial
is extended, and the end user can continue using the product 10
more times. When the end user clicks Next, the trialware run-time
dialog closes and the product starts.
• If the end user does not enter the correct extension serial number
(as specified in the Extension Serial Number property in the
Trialware view), the trialware run-time dialog does not permit the
end user to start the product. The end user can try to re-enter the
extension serial number.
• If the end user enters a serial number that was added to the license
through the InstallShield Activation Service Publisher Web Site, the
end user can activate the product. The trialware run-time dialog
closes and the product starts. The trialware run-time dialogs are no
longer displayed.
22 through 30 When the end user launches the product for the twenty-second through
thirtieth times, a trialware run-time dialog is displayed before the product
starts. The dialog informs the end user how many more times the end
user can use the product without activating it.
If the end user chooses to evaluate the product without activating it, the
end user can click Finish. Then the trialware run-time dialog closes and
the product starts.
31 When the end user launches the product for the thirty-first time, a
trialware run-time dialog is displayed before the product starts. The
dialog informs the end user that the trial has expired and the product
must be activated if they want to continue using it. If the Product
Purchase URL property contains a URL, the run-time dialog displays a
hyperlink that the end user can click to visit a Web page for information
on purchasing the product.
Note: If the end user activates the product, the trialware run-time dialogs are never displayed again. For details about the
end-user experience with activation, see Overview of the Activation Process.
Table 20-2: Trial Limit and Extension Example for Try and Die
Date Description
January 1 An end user launches the trialware for the first time on this day.
Therefore, the trial period begins on this day, regardless of what day the
trialware was actually installed on the target machine.
January 1 through Whenever the end user launches the product, a trialware run-time dialog
January 20 is displayed before the product starts, informing the end user how many
days remain in the trial period. For example, on January 18, there are 3
days left in the trial period. If the Product Purchase URL property
contains a URL, the run-time dialog displays a hyperlink that the end user
can click to visit a Web page for information on purchasing the product.
When the end user clicks Next, the trialware run-time dialog closes and
the product starts.
Table 20-2: Trial Limit and Extension Example for Try and Die (cont.)
Date Description
January 21 through If the end user launches the product during this period, the trialware run-
January 30 time dialog is displayed to inform the end user that the trial period has
expired. If the Product Purchase URL property contains a URL, the run-
time dialog displays a hyperlink that the end user can click to visit a Web
page for information on purchasing the product.
If the end user clicks the icon in the upper-left corner of the dialog and
then clicks Sales Support, the run-time dialog prompts the end user for
the extension serial number:
• If the end user enters the correct extension serial number, the trial
period is extended through January 30 (even if the end user waits
until January 30 to extend the trial). When the end user clicks Next,
the trialware run-time dialog closes and the product starts.
• If the end user does not enter the correct extension serial number,
the trialware run-time dialog does not permit the end user to start
the product. The end user can try to re-enter the extension serial
number.
Note that the countdown for the number of days in the trial extension
period starts the day after the initial trial period ends. This occurs even if
the end user does not immediately extend the trial, but instead waits
several days after the trial period is over to extend it.
January 31 or If the end user tries to use the product, the product cannot be started. A
anytime afterward trialware run-time dialog is displayed to inform the end user that the trial
period has ended. If the Product Purchase URL property contains a URL,
the run-time dialog displays a hyperlink that the end user can click to
visit a Web page for information on purchasing the product.
Note that the end user can no longer extend the trial.
Table 20-3: The Effect of an Expiration Date on Trialware with the Days Type of Trial Limit
Scenario Result
The end user starts and The expiration date does not affect the trialware.
finishes the trial period and
the trial extension period
before the expiration date.
The end user starts the trial When the number of days remaining is displayed in the trialware
period before the expiration run-time dialogs, it will take into account the expiration date.
date; however, the trial
For example, if the trial limit is set to 30 days, but the end user
period is set to end after the
first launches the trialware 10 days before the expiration date,
expiration date.
the trialware run-time dialog states that 10 days remain in the
trial.
Note that even if trial extensions are allowed, the end user will
not be able to extend the trial because it would occur after the
expiration date.
The end user tries to start The end user cannot run the trialware. The trialware run-time
the trial period after the dialog states that the trial period has ended.
expiration date.
If the type of trialware is Try and Buy/Product Activation and the
end user tries to activate the product, the following run-time
error is displayed:
The end user starts and The expiration date does not affect the initial trial period.
finishes the trial period
If the end user tries to extend the trial period after the expiration
before the expiration date.
date, the end user will not be able to do so. The trialware run-
Next, the end user tries to
time dialog will state that the trial period has ended.
extend the trial.
If the end user extends the trial period before the expiration date,
the end user can continue evaluating the product, as long as the
end user is extending the trial before the trial extension period is
over. (Note that the countdown for the number of days in the trial
extension period starts the day after the initial trial period ends.
This occurs even if the end user does not immediately extend
the trial, but instead waits several days after the trial period is
over to extend it.)
When the system calculates the number of days remaining in the
trial period, it takes into account the expiration date. If the trial
extension is scheduled to end after the expiration date, the
number of days remaining is decreased accordingly.
Table 20-4: The Effect of an Expiration Date on Trialware with the Uses Type of Trial Limit
Scenario Result
Before the expiration date, The expiration date does not affect the trialware.
the end user launches the
trialware the maximum
number of times that are
allowed for the initial trial
limit and the trial extension.
The end user starts using The end user can continue using the trialware until either of the
the product before the following occurs:
expiration date; however,
• The end user launches the trialware the maximum number
the end user does not
of times that are allowed.
(before the expiration date)
launch the trialware the • The current date is the expiration date (or after the
maximum number of times expiration date).
that are allowed. As soon as either of those conditions becomes true, end user
cannot run the trialware. The trialware run-time dialog states that
the trial period has ended.
If the type of trialware is Try and Buy/Product Activation and the
end user tries to activate the product after the expiration date,
the following run-time error is displayed:
Before the expiration date, The expiration date does not affect the number of initial trial uses
the end user launches the in this scenario.
trialware the maximum
If the end user tries to extend the trial after the expiration date,
number of times that are
the end user will not be able to do so. The trialware run-time
allowed. Next, the end user
dialog will state that the trial period has ended.
tries to extend the trial.
If the end user extends the trial before the expiration date, the
end user can continue evaluating the product until they no longer
have any remaining uses or until the expiration date is reached—
whichever occurs first.
• Allow Trial Extension—If you set this property to Yes, also set the values of the Extension
Limit Quantity and Extension Serial Number properties.
For details about setting the trial limits and allowing a trial extension, see Trial Limits and Extensions.
Note: The expiration date does not affect how long the Try and Buy/Product Activation type of trialware can remain
activated. Activating this type of trialware before the expiration date will make it permanently activated, unless end users
deactivate the product by uninstalling it. If they deactivate the product after the expiration date, they will not be able to
reactivate it.
Tip: If you want to end the life of a product that you distributed as the Try and Buy/Product Activation type of trialware, you
can do so at any time by disabling the product’s license. When you disable a license, you are preventing end users from
using any of its associated serial numbers to successfully activate the product. To disable a license, you need to use the
InstallShield Activation Service Publisher Web Site. For more information, see the InstallShield Activation Service Help
Library.
To access the InstallShield Activation Service Help Library, log on to the InstallShield Activation Service Publisher Web Site,
and then click the Help link in the upper-right corner of any page.
If you want end users to be able to activate your product by telephone, you can specify a phone number
that end users should call to request an offline activation. The phone number that you specify should be
your own organization’s phone number—typically, the phone number for your customer support staff.
Caution: The request codes and response codes that are used with phone activations are shorter than the ones that are
used with offline email activations; the shorter length of the codes makes it possible to read the codes over the phone.
However, short codes are not as secure as the longer codes used with email activations. Therefore, Macrovision
recommends that you carefully consider the security risks associated with offline phone activation before offering it as an
offline activation method. Use of this option is at your own risk, and Macrovision accepts no responsibility if your company
experiences security issues.
Note that offline phone activation requires manual intervention by both the end user and by one of your
customer support employees; therefore, phone activation is more costly for you to support than online
activation. For more information about offline activations, see Overview of the Activation Process.
• One or more locations. For example, if you have offices in North America and Europe, you might
want to provide one phone number for customers calling from North America and a different phone
number for customers calling from Europe.
• Other text strings, such as hours of operation.
The format for this property is:
Location1;Phone1|Location2;Phone2
Location1, Phone1, Location2, and Phone2 each represent a different text string. You can add as many
locations and phone numbers as necessary. Use a pipe (|) to separate each set of locations and phone
numbers.
For example, you can set this property to the following value:
North America (English);1-800-555-1234 (Mon. 12 a.m. - Sat. 12 a.m. US Central)|Europe
(English);+44 (0) 555 555 5678 (Mon. 6 a.m. - Sat. 6 p.m. GMT)
• Phone2 = +44 (0) 555 555 5678 (Mon. 6 a.m. - Sat. 6 p.m. GMT)
If the end user chooses to use activate by phone, the trialware run-time dialog will have a drop-down list
with the following options:
• North America (English)
• Europe (English)
If the end user selects the North America option, the following text is displayed in the trialware run-time
dialog:
North America (English): 1-800-555-1234 (Mon. 12 a.m. - Sat. 12 a.m. US Central)
If the end user selects the Europe option, the following text is displayed in the trialware run-time dialog:
Europe (English): +44 (0) 555 555 5678 (Mon. 6 a.m. - Sat. 6 p.m. GMT)
• Try and Buy/Product Activation Message Box (Sample Error for Internet Activation)
You can also specify the text for the Subject line with the following code, using %20 in place of spaces:
mailto:feedback@mycompany.com?Subject=My%20Subject
Figure 20-4: Sample Try and Die dialog (Trial has not expired.)
Figure 20-5: Sample Try and Die dialog (Trial has expired.)
Figure 20-6: Sample Try and Die dialog (Trial extension is allowed.)
Figure 20-7: Sample Try and Die dialog (Serial number required to extend trial.)
Figure 20-9: Sample Try and Buy/Product Activation dialog (Choose to activate or evaluate.)
Figure 20-10: Sample Try and Buy/Product Activation dialog (Enter serial number to activate.)
Figure 20-11: Try and Buy/Product Activation dialog (Activating via Internet)
Figure 20-13: Try and Buy/Product Activation dialog (Trial has expired.)
Figure 20-15: Try and Buy/Product Activation message box (Sample error for Internet activation.)
• Activate by Email—If you allow email activation, the end user can choose to activate offline by
email. If the end user selects this option, the next dialog includes a hyperlink for the email address
that you specified.
• Activate by Phone—If you allow phone activation, the end user can choose to activate offline by
phone. If the end user selects this option and you had specified more than one phone number, the
Location drop-down list is displayed and enabled, allowing the end user to select the appropriate
location. The next dialog provides the corresponding phone number.
where activate@mycompany.com is the email address that was configured for your trialware. The end user
needs to send that message to your organization, and then your customer support staff needs to reply
with a valid response code. (For more information about email activation, see Allowing Offline Email
Activations.) Then one of the following occurs:
• If the end user enters the response code correctly in the Activation Response Code box and then
clicks Next, the product is activated and the next trialware run-time dialog opens.
• If the end user enters the response code incorrectly and then clicks Next, an error message box
opens. When the end user clicks OK, the message box closes. The same run-time dialog shown below
remains open, enabling the end user to re-enter the response code.
• If the end user enters the response code incorrectly and then clicks Next, an error message box
opens. When the end user clicks OK, the message box closes. The same run-time dialog shown below
remains open, enabling the end user to re-enter the response code.
• If the end user clicks No, the trial ends, and the trialware cannot be started.
This is done to prevent end users from trying to gain more time for their trial by setting their computer’s
date back to an earlier date.
Caution: Do not release the files in the TestTools folder with your product or make them available to your customers. Doing
so would enable end users to continually restart a trial each time that it expires. Note that the TestTools files are specific
to a particular product and license and cannot be used to delete licenses for other products.
For each file being wrapped, the TestTools folder contains the following files:
• SCResetLicense<WrappedBaseFileName>.exe
• IsSvcInstSCResetLicense<WrappedBaseFileName>.dll
For example, if a file called Calc.exe is wrapped, the files in the TestTools folder are
SCResetLicenseCalc.exe and IsSvcInstSCResetLicenseCalc.dll.
You can use the TestTools files to remove the license for your product from a machine, resetting the
trialware state. This enables you to restart the trial for your protected product and retest it. For more
information, see Testing a Trialware Release of Your Product.
For the Try and Buy/Product Activation type of trialware, end users can simply enter the extension serial
number when the trialware run-time dialogs prompt them for a serial number to activate the product.
The extension serial number does not actually activate the product; it allows them to continue evaluating
the product for an additional number of days or an additional number of uses.
The instructions below explain how end users would extend a Try and Die trial if it has expired.
Task If end users want to extend a Try and Die trial, they need to:
1. Start the trialware product. The trialware run-time dialog displays a message that states that the
trial has ended.
2. Click the icon in the upper-left corner of the dialog, and then click Sales Support.
Figure 20-20: Sample Try and Die dialog (Trial extension is allowed.)
3. Enter the extension serial number that you have provided to them, and then click Next.
A transform (.mst file) is a simplified Windows Installer database that contains the differences between
two .msi databases. Transforms enable an administrator to apply modified settings to a database when
deploying an installation package.
Customizing Installations
For example, a user may need to customize an installation in different ways for different departments in
their company. The traditional office suite comes with a spreadsheet program, a word processor, and a
presentation tool. The accounting department may need only the spreadsheet and the presentation
programs, while the writing department may need the word processor and the spreadsheet. A third
department may need the entire suite of applications.
Rather than manually setting up every person in the company, a user can take the original installation of
the entire suite, customize it to the needs of each department, and then create a transform between the
two packages. A transform needs to be created for each separate product configuration.
Creating Transforms
InstallShield makes the task of creating multiple configurations of your product as easy as stepping
through a wizard. You can create a transform by using either of the two methods described below.
This method of creating a transform enables you to specify additional transforms that should be
incorporated into your transform project. It also lets you specify default user-interface responses for end
users.
Applying Transforms
Once a transform has been created, it can be applied at run time, depending on whose machine the
application is being installed. For example, you can check if the target machine is in the accounting
department. If it is, the accounting transform is applied to the original installation, and only the
spreadsheet and presentation programs are installed.
Note: If a transform project includes new files (files not found in the original .msi file), these files will not be found when
running the installation. To avoid this issue, you can either put the transform project in the same location as the base .msi
package, or manually copy the source files to the location of the base .msi package.
Note: If a transform project includes new files (files not found in the original .msi file), these files will not be found when
running the installation. To avoid this issue, you can either put the transform project in the same location as the base .msi
package, or manually copy the source files to the location of the base .msi package.
1. On the File menu, click New. The New Project dialog box opens.
2. On the Windows Installer tab, click Transform.
3. In the Project Name box, type a name for your transform project.
4. In the Location box, type the path where your transform project should be stored or click Browse
to find the location.
5. Click OK. The Open Transform Wizard opens.
6. Complete the panels in the Open Transform Wizard to create the transform.
Applying Transforms
When you apply a transform, you are modifying a base .msi package to incorporate changes that you
included in the transform (an .mst file).
The two methods of applying a transform are described below.
Caution: Do not use semicolons in the name of your transform because the Windows Installer service interprets
semicolons as file name separators.
When you specify more than one transform at the command line, the transforms are applied in the order
specified. For example, you could have a base package that has only one feature, and one transform that
adds a second feature, and another transform that changes the second feature in some way. The
transform that adds the feature must be specified before the transform that changes the second feature;
otherwise, the change will not be made properly.
Editing Transforms
InstallShield enables you to edit .msi packages without having to convert them to an InstallShield (.ism)
project. You can save the changes made as a transform (.mst) file.
1. On the File menu, click Save As. The Save As dialog box opens.
2. In the Save as type box, select Windows Installer Transforms (*.mst).
All the changes made since the last save are saved to the .mst file specified.
1. Open the transform project in InstallShield if you have not already done so.
2. On the File menu, click Save As. The Save As dialog box opens.
3. In the Save as type box, select Windows Installer Packages (*.msi).
An .msi file is created. It contains all of the data from the base .msi file, the .mst file that you were
editing, and any additional .mst files applied. The project is treated as a Direct Mode MSI project. For
more information, see Editing MSI/MSM Databases in Direct Edit Mode.
Response Transforms
A response transform is a type of transform that enables administrators to set up default values for an
installation by simply running the user interface sequence and entering the desired values. For example,
you might want to create a response transform that contains default values for which features are
installed, for the installation location of the application, and for the company name. The default values
that you specify are used as a starting point for your transform.
To create a response transform, use the Open Transform Wizard.
The simulated installation exits, and InstallShield saves all of the changes that you made during the
simulated installation as values in the Property table of your transform project. These values are used as
default values in the your installation.
1. On the File menu, click Open. The Open dialog box opens.
2. Select the transform project (.mst file) whose responses you would like to modify.
3. Click Open. InstallShield opens your transform project in Direct MST mode.
4. In the Direct Editor, click the Property table.
5. Modify the values of any response properties as needed. Examples of properties that you may want
to modify include COMPANYNAME and USERNAME.
As an alternative, you can also follow the same steps described for Creating Transforms; these steps
enable you to launch the user interface of the installation and select the appropriate responses.
• Press CTRL+T.
Tip: Server paths can contain variables delimited with a percent sign (%). For example, the following path uses the Home
environment variable:
\\Server1\%Home%\Office
Tip: Server paths can contain variables delimited with a percent sign (%). For example, the following path uses the Home
environment variable:
\\Server1\%Home%\Office
InstallShield enables you to create your own merge modules that can be used in any of your installation
projects or distributed for use by other installation developers.
The most important step in creating your merge module lies in its design. To have a well-designed merge
module, you need to break up your files into components, which constitute the developer’s perspective
of the project. Unlike creating a complete installation with features, components, and files, a merge
module contains only components, which, in turn, contain files.
The major aspects involved in creating a merge module are listed below.
Components Enable you to group your application data together. They constitute the developer’s
view of a project—containing data such as files, registry entries, and shortcuts. The
Components view is where you design the components for your merge module.
Files, registry data, and Elements that are added to a component to complete the hierarchy, as described
shortcuts above.
Advanced settings Enable you to publish your component, register COM servers, file extension servers,
and MIME types. You can also use the component’s advanced settings to create an
application paths entry in the registry.
Merge Modules
A merge module (or .msm file) contains all of the logic and files needed to install distinct pieces of
functionality. For example, many applications require Visual Basic run-time DLLs. Instead of having to
include the file in a component and figure out its installation requirements, you can simply attach the
Visual Basic Virtual Machine merge module to one of your project’s features.
Merge module properties include the following:
• Product Name
• Product Version
• Application Type
• Language
• INSTALLDIR
You can specify any merge module dependencies and exclusions in the Module Dependencies and
Module Exclusions subviews.
Task To configure the settings for publishing a merge module to a repository from within the merge module
project:
5. For the Display Name property, specify a name for the merge module that you are publishing to
the repository. This name is displayed for the merge module in the Redistributables (Objects) View.
6. For the Publisher property, type your name.
7. For the Description property, type a description of the merge module.
Whenever you build the selected release, InstallShield publishes the merge module to the specified
repository.
Merge modules are built into an installation at build time. If you make a change to a repository merge
module and then republish it to the repository, any project that has the old version of the repository
merge module will be updated the next time that a release of the project’s installation is rebuilt.
Note: Objects that you create can be used only with InstallShield X or later, InstallShield DevStudio, or InstallShield
Professional 6.1 or later.
Creating an object is little different from creating a standard installation project. One difference is the
importance of scope. When you create an object, you need to ensure that the object’s scope is optimal for
its intended use. The scope of an object affects its usability. If the scope is too narrow, the object may be
insufficient for your needs. If the scope is too large, the object may to be too cumbersome to be practical.
The following sections describe the steps in the object creation process.
Creating an Object
Currently, there are two ways to create an object. You can create a new InstallScript Object project from
the New Project dialog box or convert an existing InstallScript project into an InstallScript object.
1. On the File menu, click Save Project As. A Save As dialog box opens.
2. Select a folder in which to create a copy of the project. Note that you cannot save the new object
project in the same folder as the original project.
3. In the File name box, type a name for the new project.
4. In the Save as type list, select InstallScript Object Project (*.ism).
5. Click Save.
An object project file (.ism file) with the name that you specified, and all project subfolders, are created
in the location that you specified. That project opens in InstallShield.
Object Design
The purpose of an object is to install a discrete piece of functionality. For example, you may need to
install the latest version of DirectX in order for your application to run. Rather than including all the
necessary files separately in your installation project, you can include the DirectX object that comes with
InstallShield. Imagine if this same object contained, for example, Visual Basic run-time .dll files and
MDAC support. The object would be too large for your needs. It would install files that are not needed
and would increase the time required for the installation process. Therefore, it is a good idea to
streamline your object as much as possible. Do not try to include four different technologies in one
object. Instead, create four separate objects.
Objects follow the same structure as traditional installations, with one major difference—objects do not
support setup types. The highest level of organization in an object is the feature. Under features fall
components. Additionally, objects do not support shell objects. If you would like to create shell objects
from an object, you will need to do so via script.
For more information, see Designing Objects.
Building an Object
Building an object is very similar to building an installation project. The easiest way to complete this
task is to use the Release Wizard. The main difference between building an object and building an
installation project is the fact that you do not need to specify a media type for an object. The wizard
enables you to create media in the CD-ROM format only.
For more information, see Building an Object from the User Interface.
Testing Objects
As with any other software endeavor, it is a good idea to test before you release to the public. Testing an
object is easy—just create a standard installation project, add your object to it, build it, and run it. If it
works as planned, you are ready to include your object in projects. If not, you will need to debug. See
Testing and Debugging an Object. (Note that if you have the object project and its associated installation
project open in separate instances of InstallShield and you modify and rebuild your object, you must
close and reopen the associated installation project to incorporate those modifications.)
Distributing Objects
As used here, distributing an object does not mean including that object in an installation and installing
the files from that object on a target machine. Instead, distributing an object refers to creating an
installation that will make that object available on other users’ machines for use in their installation
projects. Because you do not want to install the logic contained within an object, you cannot just add it to
a component as you normally would. To help you register your objects, you can use the InstallShield
Object Installer object. When you associate this object with a feature, you will be prompted to select the
object from your local gallery that you would like to distribute.
For more information, see Distributing an Object.
Designing Objects
The design of your object—how components and file groups are arranged—accompanied by the actual
content of the object, is the single biggest hurdle you need to clear in order to have a stable, usable
object.
Several key areas are involved in designing an object. Each is described below.
Managing Components
It is important that you take the time to properly divide your project into features. When designing your
features, you need to plan for scenarios such as localization and conditional selection of features. For
more information, see Designing Features for Objects.
Custom Wizards
If you need to provide a more professional look to your wizard, greater functionality, or customized
display, you should create your own wizard using Visual C++ or Visual Basic. If you had these
applications installed before you ran the InstallShield installation, the functionality to create an
InstallShield object wizard will have been added. If you installed either of these programs after you
installed InstallShield, you will need to run the InstallShield installation in maintenance mode in order
to add the wizard functionality to your Visual Studio application. To create an InstallShield object wizard
in Visual C++, click New on the File menu. Then, select InstallShield Object Wizard from the list of
project types. In Visual Basic, select InstallShield Object Wizard from the New Project dialog box.
When you create an InstallShield Object Wizard project in Visual C++, a new ATL-MFC based VC wizard
framework project will be displayed. In Visual Basic, a template project will be created. Commented
code within the each project type shows how to retrieve and save the object properties. For more
information, see Custom Object Wizards.
When finished creating your wizard, you will need to compile it. That compiled file can then be linked to
from the Language-Independent Object Properties tab of the Project Settings dialog box. When you
compile and build your object, the wizard will be included.
Note: When you are distributing an object that has a custom wizard, make sure to include any dependencies for the
wizard .dll file in the distribution installation project. Include the required files in a feature that you place above the
InstallShield Object Installer feature in the Setup Design or Features view. You can avoid having dependencies by creating
a static wizard .dll file.
• A Boolean return value that indicates whether changes should be made to an existing object’s
properties or, if there is no existing object, whether a new object should be created.
In C++, this interface is defined as follows:
interface IDevWizard : IDispatch
{
HRESULT Display([in] IDispatch *pObject,
[out, retval] VARIANT_BOOL* Confirmed);
};
The server can also implement an ISetupDesignObjectBuild interface. The InstallShield release builder
calls this interface to determine which of the object’s features should be excluded from the build of a
project containing the object. (If this interface is not implemented, all of the object’s features are
included in the build.)
This interface is useful for excluding from the built project those object features that will never be
installed because of selections that the installation author made in the object’s wizard. For example, if
your object offers optional support for various drivers, and the project author chooses not to include
some of those drivers, the features containing those drivers can be excluded from the built project.
This interface, if implemented, must offer an IsIncluded method with three arguments:
• An IDispatch pointer that provides access to the object’s properties.
• A string value specifying the feature, for example, Feature 1\Subfeature 1A.
• A Boolean return value that indicates whether the component should be included in the build.
Note: When you are distributing an object that has a custom wizard, make sure to include any dependencies for the
wizard .dll file in the distribution installation project. Include the required files in a feature that you place above the
InstallShield Object Installer feature in the Setup Design or Features view. You can avoid having dependencies by creating
a static wizard .dll file.
Note: If you create your own wizard, you will need to provide run-time strings in the wizard’s executable file for each
language that you are supporting.
view and set the Project Properties sheet’s Platforms property. To add language support to your
object project, see Preparing an Object for Internationalization.
• Include, with the object, documentation that informs installation authors which operating systems
and languages are supported. To do this, create an .htm file that contains the necessary information,
then on the Project menu, click Settings. Click the Language-Specific Object Properties tab, and
specify the .htm file in the HTML Help field.
Creating a Property
Properties can be useful in object scripts. In an object script, properties enable your object’s users to
change certain settings of your object during either design time through the use of an InstallShield
Object Wizard or during run time by passing parameters through script. Common properties include
passing error messages from the object to the installation, getting the user name, or any information
that your object needs during either run time or design time. For examples of how properties are used,
see the inline help for any of the InstallShield objects included in your Objects view.
Note the following details about properties:
• If a Boolean property’s value is set to TRUE, either by the object script or the script of the
installation that includes the object, subsequent checks of the property’s value will show the value to
be –1 rather than 1.
• You cannot pass a LIST variable between an object and an installation script; you can, however, pass
a string array.
Creating a Property
The Add New Property dialog box adds the following to your script:
• A property declaration with the following syntax:
property(<procedures>) <property data type> <property name> ( );
<procedures> is get for a read-only property, put for a write-only property, and get,put for a read/
write property. For example:
property(get,put) STRING MyProperty ( );
You can specify arguments for your property by adding the arguments’ data types inside the
parentheses after the property name. For example:
property(get,put) STRING MyProperty ( NUMBER );
If you add argument data types to the property declaration, you must add corresponding argument
variables to the definitions of the property’s procedure functions.
• A declaration of a variable to store the property’s value within the script. For example:
STRING m_strMyProperty;
If you specify an array property in the Add New Property dialog box (by selecting the Array check
box), two variables are declared: a variable of type VARIANT that stores the property’s value and an
unsized array variable that is used in the InitProperties function block to initialize the property’s
value. For example:
STRING arrayMyArrayProperty();
VARIANT m_arrayMyArrayProperty;
• A statement, in the InitProperties function block, that initializes the variable that stores the property’s
value. For example:
m_strMyProperty = "My Default Value";
If you specify an array property in the Add New Property dialog box (by selecting the Array check
box), the variable that stores the property’s value is assigned the value of an array variable. For
example:
m_arrayMyArrayProperty = arrayMyArrayProperty;
To initialize elements of the array property to non-null or nonzero values, add assignment
statements for the array variable’s elements before the statement above. For example:
/* Resize the array variable, which is declared with no size. */
Resize ( arrayMyArrayProperty , 3 );
m_arrayMyArrayProperty = arrayMyArrayProperty;
• A function call, in the ReadProperties function block, to retrieve the property values stored in the
property bag object. This call has the following syntax:
<ReadxxxxProperty> ( PropertyBag, "<property name>", <property value variable> );
<ReadxxxxProperty> is the ReadxxxxProperty function that is appropriate to the data type of the
property’s value. For example:
ReadStringProperty( PropertyBag, "MyProperty", m_strMyProperty );
• A function call, in the WriteProperties function block, to save the property values to the property bag
object. This call has the following syntax:
<WritexxxxProperty> ( PropertyBag, "<property name>", <property value variable> );
<WritexxxxProperty> is the WritexxxxProperty function that is appropriate to the data type of the
property’s value. For example:
WriteStringProperty( PropertyBag, "MyProperty", m_strMyProperty );
• A function block or blocks defining the property’s procedures—that is, defining the actions that are
executed when the property’s value is read or written to by a project containing the object or the
object’s design-time wizard (if any)
A get_<property name> function is defined for a read-only or read/write property; a
put_<property name> function is defined for a write-only or read/write property. For example:
function STRING get_MyProperty()
begin
return m_strMyProperty;
end;
If you specify arguments for your property (by adding the arguments’ data types to the property
declaration, inside the parentheses after the property name), you must add corresponding argument
variables to the definitions of the property’s procedure functions. For example:
function STRING get_MyProperty( szAddedArgument )
function void put_MyProperty( szAddedArgument, newVal )
When you are adding arguments to the put_ function, place them before the newVal argument. The
newVal argument takes the value that is written to the property by an assignment statement in the
calling project or by the object’s design-time wizard (if any).
Note: The get_ and put_ functions must not be renamed; if they are renamed, your script will not function properly.
• A declaration of a read-only property whose data type is OBJECT. (To write values to the property,
you will define a method.) For example:
property(get) OBJECT StructProp();
Place this declaration in the Properties Section block of the object script.
• A declaration of a variable to store the property’s value within the object script. For example:
STRUCT m_structStructProp;
Place this declaration in the Local Variables Section block of the object script.
• A declaration of a method with an argument of the appropriate data type corresponding to each
member of the data structure. For the STRUCT structure defined above, the following is an example
of an appropriate method declaration:
method NUMBER SetStructProp(NUMBER, NUMBER);
Place this declaration in the Methods Section block of the object script.
• Statements, in the InitProperties function block, that initialize the members of the variable that stores
the property’s value. For example:
m_structStructProp.Mem1 = 3;
m_structStructProp.Mem2 = 5;
• Function calls and statements, in the ReadProperties function block, to retrieve the property member
values stored in the property bag object. The function calls have the following syntax:
<ReadxxxxProperty> ( PropertyBag, "<storage name for member value>",
<member value variable> );
<ReadxxxxProperty> is the ReadxxxxProperty function that is appropriate to the data type of the
property member’s value. For example:
ReadNumberProperty(PropertyBag, "StructProp_Mem1", nStructPropMem1);
For each such function call, add below it a statement that sets a member of the property variable
equal to the value that the function retrieved. For example:
m_structStructProp.Mem1 = nStructPropMem1;
• Function calls, in the WriteProperties function block, to save the property member values to the
property bag object. The function calls have the following syntax:
<WritexxxxProperty> ( PropertyBag, "<storage name for member value>",
<property variable member> );
<WritexxxxProperty> is the WritexxxxProperty function that is appropriate to the data type of the
property member’s value. For example:
WriteNumberProperty(PropertyBag, "StructProp_Mem1", m_structStructProp.Mem1);
• A get_<property name> function block defining the property’s get procedure—that is, defining the
actions that are executed when the property’s value is read by a project containing the object or by
the object’s design-time wizard (if any). For example:
function OBJECT get_StructProp()
begin
return m_structStructProp;
end;
• A function block defining the method that you declared; this method sets the members of the
property variable equal to the arguments passed to the method. For example:
function NUMBER SetStructProp( nMem1, nMem2 )
begin
m_structStructProp.Mem1 = nMem1;
m_structStructProp.Mem2 = nMem2;
end;
Place this declaration in the Properties Section block of the object script.
• Declarations of the necessary variables, including a variable to store the property’s value within
the object script:
STRING arrayTest();
variant m_arrayTest;
Place these declarations in the Local Variables Section block of the object script.
• Statements, in the InitProperties function block, that initialize the members of the variable that
stores the property’s value. For example:
m_arrayTest = arrayTest;
• A function call, in the ReadProperties function block, to retrieve the value stored in the property
bag object. For example:
ReadArrayProperty(PropertyBag, "Test", m_arrayTest);
• A function call, in the WriteProperties function block, to save the value to the property bag
object. For example:
WriteArrayProperty(PropertyBag, "Test", m_arrayTest);
• A function block defining the property’s get procedure—that is, defining the actions that are
executed when the property’s value is read by a project containing the object or by the object’s
design-time wizard (if any). For example:
function variant get_Test()
begin
return m_arrayTest;
end;
• A function block defining the property’s put procedure—that is, defining the actions that are
executed when the property’s value is written to by a project containing the object or by the
object’s design-time wizard (if any). For example:
function void put_Test(newVal)
begin
m_arrayTest = newVal;
end;
• In each function block in which you will read a string array from or write it to the object,
declarations of an object variable and a string array. For example:
OBJECT oObject;
string szTest(3);
• To set the value of the object’s string array property, use code like the following:
oObject.Test = szTest;
To retrieve the value of the object’s string array property, use code like the following:
szTest = oObject.Test;
When you change a property at run time, that information is not stored for future uses of the
installation. For example, if the installation is later run in maintenance mode, that property will not
retain the value it was given during the initial installation.
If a Boolean property’s value is set to TRUE, either by the object script or the script of the installation
that includes the object, subsequent checks of the property’s value will show the value to be –1 rather
than 1.
Tip: If you simply want to retrieve the current status of an object (that is, the current value of Status.Number) in the
InstallScript Object, you can use the GetStatus function. For more information, see GetStatus.
Creating a Method
Methods, like properties, allow your object to interact with the installation containing it. Methods, for all
practical purposes, are functions. As a matter of fact, the only difference between a method and a
function is the fact that a method is declared with the method keyword. Methods allow you to expose
your object’s functions to other objects and setups.
Creating a Method
For example:
method STRING MyMethod( NUMBER, BOOL );
Using Methods
An object’s methods can be accessed only at run time. You can call an object’s methods from within your
installation project or from another object. To gain access to an object’s methods, you first need to get a
reference to that object. The following code snippet taken from the BDE 5.0 object demonstrates how to
access an object from within your installation script.
IsBDERunning - This method returns TRUE if the BDE is running on the target system and FALSE if
not. Here is a brief example of this method:
function OnBegin()
/* Declare an object variable to hold a reference to the object.*/
OBJECT oObj;
STRING szDir;
begin
/* Get a reference to an BDE 5.0 object named "New BDE 5.11 1". */
set oObj = GetObject("New BDE 5.11 1");
while (oObj.IsBDERunning() )
szMsg = "Borland Database Engine is running, please shut down BDE.";
nvResult = SprintfBox( MB_RETRYCANCEL, "BDE in use", szMsg );
if ( nvResult = 2 ) then
abort;
endif;
endwhile;
end;
• StatusBase
• StatusStruct
StatusBase and StatusStruct are intended only for advanced users. See the following sections for
information on these properties.
Status
The Status property is a structure with the following properties as members:
Property Description
Property Description
Status.szSource For an error, the source of the error; typically the name of
the object as read from the object’s string table.
Status.szScriptFile For an error, the name of the script file that was executing
when the error occurred.
Status.nScriptLine For an error, the line of script that was executing when the
error occurred.
In an object script, you can set these values by calling SetStatusEx. When you query the status of an
object, by default it first queries the status of its subobjects (if any); if one or more of an object’s
subobjects report an error (that is, have a Status.Number property that is less than
OBJ_STATUS_SUCCESS), the value of the first failing object’s status property is returned as the value
of the parent object’s status. A user-defined object’s script can override this default behavior by explicitly
defining a get_Status function (with no arguments).
You can check the value of an object’s Status.Number property to determine whether the object can be
successfully installed—and, if not, what the cause is—and display the value of Status.Description to
your end user. You can perform this check at any point in a setup; it is recommended that you at least
check for success or failure in the OnBegin event handler, as in the following example:
function OnBegin()
/* Declare an object variable to hold a reference to the object. */
OBJECT oObject;
begin
/* Get a reference to an Access 97 Object named "New Access 97 1". */
set oObject = GetObject("New Access 97 1");
The following table lists those possible values of Status.Number and Status.Description that are
common to all objects. Some objects also have possible values of these properties that are unique to that
object. For lists of those possible values, see the individual object’s help page (by selecting the object in
the Objects view, or in the Setup Design or Features view under its associated feature).
Table 23-3: Possible Values of Status.Number and Status.Description that Are Common to All Objects
oObject.Status.Number oObject.Status.Description
Table 23-3: Possible Values of Status.Number and Status.Description that Are Common to All Objects (cont.)
oObject.Status.Number oObject.Status.Description
StatusBase
The StatusBase property is a structure with the same members as the Status property. This property
is typically used only by objects that have a customized get_Status method; except for special cases a
setup should not query this property directly, as it could bypass any custom status handling that the
object provides.
The StatusBase property enables you to use an object’s default status handling, including checking the
statuses of the object’s subobjects. If you have created a custom get_Status function for your object, you
can use the StatusBase property within the get_Status function to use the default object status
handling, as in the following example:
function object get_Status()
object oThis;
begin
// Do some custom handling here.
return NULL;
endif;
StatusStruct
The StatusStruct property is a structure with the same members as the Status property. This property
is typically used only by objects that have a customized get_Status method; except for special cases, an
installation should not query this property directly because it could bypass any custom status handling
that the object provides.
The StatusStruct property allows you to bypass the default object status handling. You can use this
property if you want your object to ignore subobject status values, as in the following example:
function object get_Status()
object oThis;
begin
// Get a reference to this object.
set oThis = GetObject( "" );
code. For example, calling ShowObjWizardPages in a project’s OnFirstUIBefore event handler displays
each included object’s OnFirstUIBefore code. The included objects’ UI event handlers are executed in
the order in which the objects appear in the project’s Components view.
The end user should be able to advance through the installation’s entire dialog sequence by using the
Next and Back buttons. To allow this, do what is done in the default UI event handler code: assign each
dialog function’s return value (NEXT or BACK) to the variable nResult, and call ShowObjWizardPages as
follows:
nResult = ShowObjWizardPages(nResult);
As with the ShowObjWizardPages function, enable end-user navigation by assigning each dialog
function’s return value to nResult, and calling ShowxxxxxUIyyyyy methods as in the preceding example.
Unsupported
Feature Description
Setup Types Setup types are not supported in objects. If you are creating an object out of an
existing installation project, your setup types will be disregarded.
Media Types When creating an object, you do not have any choices as to the type of media
that you would like to build. All objects will be built uncompressed with the CD-
ROM option.
Shortcuts and The Shortcuts view is not supported in objects. In order to create a shortcut or
Folders folder within an object, you need to do so from the script with the
AddFolderIcon, CreateProgramFolder, or CreateDir function.
Support Files Where standard installations allow you to specify splash screens; billboards;
and language-dependent, language-independent, and advanced files in the
Support Files view, objects allow only language-dependent and language-
independent files.
Product
Registry Keys
Windows Logo Guideline: When any installation created with InstallShield is
run, product registry keys are automatically created on the target machine. The
product registry keys, which are created at HKLM\SOFTWARE\<Company
name>\<Product name>\<Version> are required for Microsoft Logo
compliance. Therefore, if you would like to have these registry keys created,
you need to add them yourself.
Building an Object
Building an object is essentially the same as building a standard installation. To build your object from
the InstallShield user interface, you will need to use the Release Wizard, which prompts you for all the
information necessary to build your object.
You can also compile and build an object from the command line. Building and compiling an object from
the command line is handled in an identical fashion to building and compiling an installation from the
command line. To compile your object from the command line, you will need to use Compile.exe, which
is located in the InstallShield folder’s Program subfolder.
Note: An object must be compiled using the library files Ifxobject.obl and Isrt.obl. These files are automatically
referenced by your object project if you created your project by using the New Project dialog box’s InstallScript Object
project type or the Save As command on the FIle menu. If you created your object project in some other way, click
Settings on the Build menu and check the Compile/Link tab’s Libraries field to make sure that Ifxobject.obl and
Isrt.obl are listed there.
Building an object is essentially the same as building a standard installation. To build your object, you
will need to use the Release Wizard, which prompts you for all the information needed to build your
object. The Release Wizard displays the following panels for object projects:
Release Wizard
Panel Description
Specify a Release Enables you to create a new release or select an existing release.
Panel
General Options Lets you specify preprocessor variable definitions and advanced release
Panel properties.
Modify Property Lets you select the operating systems that your object supports.
Dialog Box/
Release Wizard—
Platforms Panel
Setup Languages Displayed if more than one language is selected in the Project Settings
Panel property sheet’s Language page. Lets you select the languages that your
object will support, a default object language, and whether to let end users
select the language in which the object runs.
Features Panel Lets you specify which features are included in the built release.
Digital Signature Lets you digitally sign your object. Digitally signing your object assures end
Panel users that the code within your object has not been modified or corrupted
since publication.
Postbuild Options Lets you copy disk image folders to a folder or FTP site, or execute a batch
Panel file, after the next time you build the release.
Note: When you build an object, that object is automatically added to the
Objects view and can be used in any installation that you create from that
point on. If a previous version of that object already exists in the gallery, it will
be overwritten with the newly built object. If you build more than one media,
the latest media will be copied to your Objects view.
Note: If you have the object project and its associated installation project open in separate instances of InstallShield and
you modify and rebuild your object, you must close and reopen the associated installation project to incorporate those
modifications.
Script Debugger
The Script Debugger enables you to step through the code of your installation as it runs. To debug an
object with the Script Debugger, you must include that object in a standard installation project, compile,
and debug. Alternatively, you could design your object as a standard installation, test and debug it, and
then convert it to an object through the following procedure.
1. On the File menu, click Save As. The Save As dialog box opens.
2. Select a folder in which to create a copy of the project. Note that you cannot save the new object
project in the same folder as the original project.
3. In the File name box, type a name for the new project.
4. In the Save as type list, select InstallScript Object Project (*.ism).
5. Click Save.
An object project file (.ism file) with the name that you specified, and all project subfolders, are created
in the location that you specified. That project opens in InstallShield.
For additional information, see InstallScript Debugger.
Note: When you are designing your object as a standard installation with the intent to later convert it to an object, be
aware of the following restrictions:
• An object cannot contain setup types; any setup types that you define or setup type functions that you call in the
project are ignored when it is converted to an object project.
• There are a number of functions and events that are not supported in objects.
• All information on built media will be lost when the project is converted; you will need to rebuild the project.
Macrovision recommends, for two reasons, that you clear the Generate inline debugging
information option before compiling the Setup.inx file that you ship with your final product. First, the
debugging information increases the size of Setup.inx and may cause the installation to run more slowly.
Second, inline debugging information will make it easier for others to reverse engineer your code.
On the Tools menu, point to InstallScript and click Cabinet File Viewer.
On the Tools menu, point to InstallScript and click Log File Viewer.
1. From within your development environment, launch a debug version of the wizard, setting
breakpoints as desired.
2. In the InstallShield interface, insert the object in a feature of another project to launch the object’s
wizard.
3. If your development environment is Microsoft Visual Basic, you must also do the following:
a. Minimize the interface. A Server Busy message box opens. (You may need to click the title
bar’s minimize button a few times before the message box opens.)
b. In the Server Busy message box, click the Switch To button or press ENTER.
Distributing an Object
The major advantage of objects is the fact that anyone creating an InstallShield installation can include
your object in their installation with a minimal amount of work, as long as your object is installed and
registered on their machine. The easiest way to register an object is to use the InstallShield Object
Installer. This object enables you to package the object that you would like to distribute, and it will
register that object on the target machine, if InstallShield X or later, InstallShield DevStudio, or
InstallShield Professional 6.1 or later is present.
1. Open the Objects view. The InstallShield Objects/Merge Modules pane lists all of the
available objects.
2. In the Features pane, select the feature to which you want to add the InstallShield Object Installer.
3. Right-click InstallShield Object Installer and click Add to selected feature.
An associated wizard appears to guide you through the customization process.
Note: The object that you would like to distribute must be present in your InstallShield Object Gallery. If it is not present,
you need to register that object by right-clicking an object and clicking Register new object.
Object Scripts
InstallShield enables you to extend object support by defining additional functions and constants that
are not supported in object projects by adding scripts in the InstallScript view. Essentially, you can write
scripts that enhance the functionality supported by the InstallShield interface.
• OnRemovingSharedFile
• OnFileLocked
• OnNextDisk
• OnMD5Error
• OnFileError
• OnComponentError
• SdSetupType
• SdSetupTypeEx
• SetupType
• ComponentSetupTypeSet
• ComponentSetupTypeEnum
• ComponentSetupTypeGetData
• IFX_ONNEXTDISK_MSG
• IFX_MAINTUI_MSG
• IFX_ONMAINTUI_CAPTION
• IFX_SDFINISH_MSG1
• IFX_SDFINISH_MAINT_MSG1
• IFX_SDFINISH_MAINT_TITLE
• WizardDirection
d. In the Data Type list, select String (since you will be writing string data to the property).
e. In the Access Method list, select Read/Write. (You can select Write Only instead if you are
certain users of the object will never want to check the current value of the property from their
main script.)
4. Click OK to close the dialog box and automatically add all the necessary code to your object script.
5. Make the following changes to the property script code that was automatically added:
a. Open the InstallScript view.
b. In the InstallScript explorer, under Properties, double-click ScriptDefinedVar to move
the script editor pane’s insertion point to the ScriptDefinedVar declaration. Add a string
parameter to the declaration—that is, change the declaration from this:
property(get,put) STRING ScriptDefinedVar();
to this:
property(get,put) STRING ScriptDefinedVar( STRING );
Change it to this:
function STRING get_ScriptDefinedVar( szScriptVar ) /* Add string argument. */
begin
return TextSub.Value( szScriptVar ); /* Get value associated with szScriptVar. */
end;
Change it to this:
function void put_ScriptDefinedVar( szScriptVar, newVal ) /* Add string argument. */
begin
TextSub.Value( szScriptVar ) = newVal; /* Associate newVal with szScriptVar. */
end;
• A write-only or read/write object property whose put_ function calls ComponentSetTarget, for
example:
function VOID put_SetTargetDest ( szScriptVar , szValue )
begin
ComponentSetTarget ( MEDIA , szScriptVar , szValue );
end;
Installing upgrades for applications is a much more common operation than installing the original
release of an application. This makes creating effective, reliable upgrades a very important task.
“Updating Applications” provides solid background information on the different types of upgrades and
also clears up common misconceptions about patching. It helps you determine the best upgrade solution
for your product and guides you through the steps of creating upgrades, patches, QuickPatch projects,
differential releases, and full releases. In addition, this section explains how you can use FLEXnet
Connect to notify end users that a new version of your product is ready for release.
Upgrades Overview
The cost of maintaining software applications is often more expensive than the cost of original
development. This makes creating effective, reliable upgrades an important task. Being able to distribute
robust upgrades for an application depends on how the original installation package was structured and
distributed. This help topic will provide a basic foundation for creating robust upgrade packages.
Note: If you used a version of InstallShield Professional earlier than 6.0 to create media for an InstallScript project, the
media cannot be updated.
Major Upgrades
In a major upgrade, the product changes are large enough to merit changes to both the product version
number and the product code, as well as the package code. An example is updating version 1.2 of a
product to 2.0. A major upgrade acts like a first-time installation if an earlier version is not present. If an
earlier version is present, a major upgrade typically uninstalls the earlier version and then installs the
new version. It is also possible to have a major upgrade first install over the earlier version and then
remove any unused files. This method is more efficient, but strict component-authoring rules must be
followed.
Note: You can set the product code for your installation in the Product Properties grid of the General Information view. It
does not matter what the new product code is, as long as it is unique.
By virtue of having a unique product code, your latest installation will have its own independent
registration with the Windows Installer service on end users’ machines. This means that unless some
other step is taken, the Windows Installer installs the latest version of your product independently of
any of the previous versions. This may be okay if the two versions of your product can coexist on the
same machine, but then that would not be an upgrade. Therefore, for the sake of this discussion, it is
assumed that two versions should not coexist on the same machine.
Once you update the product code for your latest installation, you need to use the Upgrades view to
specify information for any previous version or versions that you want to upgrade.
For more information about what is involved in creating a major upgrade, see Creating Major Upgrades.
Minor Upgrades
A minor upgrade is a change to the product database and files large enough to merit a change to the
ProductVersion property but not to the ProductCode property. In other words, both the package
code and the product version number are different than those in the earlier installation package, but the
product code of the minor upgrade does not change. An example is updating version 1.1 of a product to
version 1.2. Minor upgrades usually do not have significant changes to the installation organization
between versions. A minor upgrade packaged as a full installation acts like a first-time installation if an
earlier version is not present, or it installs over an existing installation of a product. Essentially for an
upgrade of an existing installation, a minor upgrade installs the differences between your version 1.2 and
1.1 application.
Tip: You can modify the product version for your upgrade in the Product Properties grid of the General Information view.
Small Updates
In essence, a small update is a type of upgrade used to modify a few files for an installed application; it
typically delivers small bug fixes. A small update consists of product changes (such as hotfixes) so small
that no change to the product version is necessary or desired. A package code change is required for a
small update.
A drawback to small updates installed with versions of Windows Installer earlier than 3.0 is that
external programs, including installers for later versions of your product, cannot distinguish between
the original version and the updated version. In addition, Windows Installer versions earlier than 3.0
cannot enforce the correct order in which small updates should be applied.
Patching
Patching is a streamlined mechanism for updating earlier versions of a Windows Installer installation
package, thereby updating the application. With a patch, you deliver to your customers only the bits
required to change an installed file into a new file. One benefit of a patch is that the size of the upgrade
package can be significantly smaller than the full-installation package required to deliver the same
upgrade. Keeping an upgrade package as small as possible allows you to more easily deliver your
upgrades over the Internet.
However, you should note that a patch may not always present the best solution. For example, if you
want to change your installation from compressed to uncompressed, or vice versa, you should package
your upgrade as a full installation, but not as a patch. To learn more about determining the best
packaging option for your upgrade, see Packaging Options for Upgrades.
A patch is delivered in the form of a patch package (.msp) file, which your end user can apply to an
installed product. A patch package is capable of updating as many earlier versions of an installation
package as required. A patch package contains separate transforms and instructions for updating each
previous version that you specify.
An important aspect of patch creation is generating a patch creation properties (.pcp) file, which defines
the parameters on which the patch package is to be created. The .pcp file is a database that has a specific
schema, but you can open it and edit it directly with InstallShield or Orca.
The Patch Design view provides an easy-to-use interface to simplify the patch creation process. This
view groups together all the logical considerations you will need to make in patch creation.
QuickPatch Projects
A QuickPatch project is a specific type of project recommended for installation authors who want to ship
small, single updates to their users. Changes that are more extensive such as adding custom actions and
changing .ini data typically require a standard patch.
QuickPatch authoring provides a simple alternative to creating a patch configuration in the Patch Design
view, even though it provides less customization. Fundamentally, both patch creation methods produce
the same deliverable types: .msp and .exe files.
With a QuickPatch, you can do any of the following:
• Add new files to the original installation or an earlier QuickPatch.
• Remove custom actions that were included with the original installation but that do not apply to the
current QuickPatch project.
The creation of a QuickPatch project always begins with the Create New QuickPatch Wizard. Completing
the wizard ensures that all basic requirements for the QuickPatch project are met. Then you can
configure project settings once the QuickPatch project opens in InstallShield.
Differential Releases
In an InstallScript project, you can define and build a differential release—that is, a release that contains
the files that are absent from—and/or have a different date, time, size, or attribute than the version in—
one or more of a specified set of existing releases. A differential release is used to update the versions of
your product that were installed by those existing releases. This type of upgrade also includes all of the
maintenance/uninstallation feature’s files. The new versions of Data1.hdr, Data1.cab, and Layout.bin do
not overwrite the existing versions but are placed in a new folder.
Note: Since a differential release consists of only the changed files between the specified existing media and the new
media, installing a differential release on a system that does not have a specified earlier version of the product would most
likely not produce a valid application. To update a system that does not have an earlier version of the product, create a full
release.
• The file is absent from—or has a different date, time, size, or attribute than the copy in—at least one
of the specified comparison releases.
• The file is in a component whose Difference property is set to Include Always.
• The file is in a component that is absent from at least one of the specified comparison releases.
• The file is in a component whose name is different in at least one of the specified comparison
releases.
• The file is in a component whose Destination, Languages, or Operating Systems properties are
different in at least one of the specified comparison releases.
• The file is in a component that is associated with a feature whose name or path within the feature
hierarchy is different in at least one of the specified comparison releases.
• The product version of the differential release is newer than the product version of the installation.
Full Releases
With an InstallScript project, you can define and build a full release for an upgrade. A full release
includes all of the files linked into the installation project. By default, this type of release behaves as a
first-time installation if an earlier version of the product is not already present on the target system. It
also is capable of installing over an earlier version and replacing that version completely.
When you create a full release to update one or more earlier versions of a product, you must specify
whether the release is version specific or non-version specific:
• Non-version specific—This is the default option. A non-version-specific full release can be installed
on a system that does not have an earlier version of the product. It can also update any earlier
version of the product.
• Version specific—A version-specific full release updates only the versions that you specify should be
updated. If you set your full release to be version specific but you do not also specify version
numbers, the update can be applied to any earlier version of your product.
Status of the
Target Systems Type of Installation Needed Technique for Packaging the Update
Some of the target If file size is not an issue, you can Create a major or minor upgrade and package it as a full
systems have an create one installation that does installation.
earlier version of both of the following:
the product, and
• Behaves as a first-time
some do not have
installation if an earlier
any version of the
version of the product is not
product.
already present on the target
system
• Updates an existing product if
it is already installed on the
target system
Some of the target If you want a small installation for For the first-time installation, create a major or minor
systems have an end users who need to update an upgrade and package it as a full installation. For end users
earlier version of earlier version of the product, you who have an earlier version of your product, create a major
the product, and can create two separate or minor upgrade and package it as a patch.
some do not have installations:
any version of the
• A full installation that behaves
product.
as a first-time installation.
Tip: In some cases, a patch is not appropriate. For more
• A smaller installation that guidelines on determining whether a patch is appropriate
updates one or more earlier for your upgrade, see Packaging Options for Upgrades.
versions of an already
installed product. Since this
installation consists of only
the changed data between Note: A patch package is not a type of upgrade; it is simply
the versions to be updated, it a mechanism for distributing an upgrade with a small
usually enables you to deploy footprint.
your upgrade using much
less bandwidth than that
required to deploy a full-
installation package.
Table 24-1: Possible Upgrade Solutions for Windows Installer–Based Projects (cont.)
Status of the
Target Systems Type of Installation Needed Technique for Packaging the Update
All of the target You can create a small installation Do either of the following:
systems have an that updates one or more earlier
earlier version of versions of an already installed
• Create a major or minor upgrade and package it as a
the product. product. Since this installation standard patch.
consists of only the changed data • Create a QuickPatch project.
between the versions to be
The QuickPatch technology in InstallShield enables you to
updated, it usually enables you to
create simple patches for previously installed products.
deploy your upgrade using much
Although customization is somewhat limited when you
less bandwidth than that required
create a patch by using a QuickPatch project, the creation
to deploy a full-installation
of a QuickPatch project is a simpler alternative to creating a
package.
standard patch. For more details, see Patch vs. QuickPatch
Project.
InstallScript-Based Projects
If the original installation was created with an InstallScript-based project, you can create one of two
types of update releases:
• Differential release—This type of release contains the files that are absent from—and/or have a
different date, time, size, or attribute than the version in—one or more of a specified set of existing
releases. A differential release is used to update the versions of your product that were installed by
those existing releases.
• Full (non-differential) release—This type of release behaves as a first-time installation if an earlier
version of the product is not already present on the target system. It also is capable of installing over
an earlier version and replacing that version completely.
Since a differential release consists of only the changed files between the versions to be updated, it
usually enables you to deploy your update using much less bandwidth than that required to deploy the
full release. However, only a full release can be installed on a system on which no version of your product
is currently installed. For more details, see Differential Releases and Full Releases.
or a small update, you should create a major upgrade. If you are not sure which type of upgrade you
should use for your Windows Installer–based project or if you do not have a preference, you can create
an automatic upgrade.
Table 24-2: Major Upgrade vs. Minor Upgrade vs. Small Update
Use a
Requirement for Use a Major Use a Minor Small
the Upgrade Upgrade? Upgrade? Update? Note
Add a new Yes Yes, if the Yes, if the Windows Installer 1.x
component to an version of version of requires new components in
existing feature Windows Windows an upgrade package to be
Installer is Installer is placed in new features for
2.0 or later 2.0 or later minor upgrades and small
updates; it also requires
special command-line
handling.
Table 24-2: Major Upgrade vs. Minor Upgrade vs. Small Update (cont.)
Use a
Requirement for Use a Major Use a Minor Small
the Upgrade Upgrade? Upgrade? Update? Note
Table 24-3: Codes that Need to Be Changed for the Different Types of Upgrades
Small Update X
Table 24-3: Codes that Need to Be Changed for the Different Types of Upgrades (cont.)
Minor Upgrade X X
Major Upgrade X X X
Automatic Upgrades
To simplify the upgrade creation process, InstallShield offers you the ability to create automatic
upgrades. An automatic upgrade is a special type of upgrade that you can create if you do not know
which type of upgrade you should use or if you do not have a preference. With automatic upgrades,
InstallShield determines which type of upgrade—major upgrade or minor upgrade—would be optimal
based on comparisons between the earlier and later packages that you specify.
Note: Major upgrades are typically not packaged as patches. Therefore, the table below assumes that the patch created
through the Patch Design view is for a minor upgrade or a small update. QuickPatch projects produce QuickPatch
packages that serve as minor upgrades.
Full-Installation Packages
Both a minor upgrade and a small update act like first-time installations if an earlier version is not
present, or they install over an existing installation of a product. A major upgrade also acts like a first-
time installation if an earlier version is not present; however, a major upgrade typically uninstalls any
earlier version and then installs the new version.
Patch Packages
Patches enable you to distribute just the bits and portions of the database necessary to update your
application’s files to a specific version, possibly resulting in a much smaller package than an upgrade
packaged as a full installation. This enables you to deploy your upgrades using much less bandwidth
than that required to deploy a full-installation package.
Note: A patch is not a type of upgrade. Patching is simply a mechanism for distributing a major upgrade, a minor
upgrade, or a small update with a small footprint. In fact, creating a patch involves first designing the upgrade and then
packaging it as a patch. Before you create a patch, it is recommended that you test the upgrade as a full-installation
package.
• Patches cannot be created for major upgrades of InstallScript MSI projects. Therefore, if you need to
distribute a major upgrade for an InstallScript MSI project, you should package it as a full
installation.
If all of the target systems have an earlier version of the product, you can package your upgrade as a
differential release. This type of release contains the files that are absent from—and/or have a different
date, time, size, or attribute than the version in—one or more of a specified set of existing releases. A
differential release is used to update the versions of your product that were installed by those existing
releases.
Note: If you used a version of InstallShield Professional earlier than 6.0 to create media for an InstallScript project, the
media cannot be updated.
Upgrade Considerations
Following are some guidelines for creating upgrades.
Updating the Package Code, the Product Version, and the Product Code
For any type of upgrade, you must change various combinations of the package code, product version,
and product code to identify the product being installed. For more information, see Major Upgrade vs.
Minor Upgrade vs. Small Update.
• Advanced tab
Note: When you change the product code, Windows Installer treats your latest and previous product versions as
unrelated, even though the ProductName values are likely the same. If you want both versions of your product to be
installable on the same system, you can simply change the product code and the main installation directory (often
INSTALLDIR).
Essentially, a major upgrade is two operations rolled into one installation package. The major upgrade
either installs the new version of the product and then silently uninstalls the older version or silently
uninstalls the older version and then installs the newer version. The sequence of these two separate
operations depends on how you configure the installation package of the newer version of the product.
For more information on creating a major upgrade using InstallShield, refer to this section of the
InstallShield Help Library.
Tip: In the Upgrades view, you can disable the initial upgrade prompt when you click Upgrade Windows Installer Setup in
the explorer and configure the Common tab properties for small updates and minor upgrades.
Note: This update process follows all file overwrite rules. Therefore, only files with newer versions will be updated. The
upgrade also follows componentization rules. Therefore, a file will be updated only if the key file of the component
containing that file is also updated.
A minor upgrade installs its new resources over the application that currently exists on the target
machine. If you want to completely uninstall and then reinstall your application, you should consider a
major upgrade.
The Installer properties REINSTALL and REINSTALLMODE must be set from the command line to
start an installation in upgrade mode. In all but the most advanced scenarios, the property
REINSTALLMODE should be set to vomus and the property REINSTALL should be set to ALL. A
typical command line can look like the following:
msiexec.exe /i \product.msi REINSTALLMODE=voums REINSTALL=ALL
If the update contains features that you do not want to update, you should set REINSTALL to a
comma-separated list of the features that you want to update, as in the following command:
msiexec /i \product.msi REINSTALLMODE=voums REINSTALL=F1,F3,F5
The feature names you use in the REINSTALL property are case-sensitive.
A critical point to note is that you do not want to set these properties on the command line unless a
previous version of your installation already exists on the target machine. If you do, the installation will
appear to run in minor upgrade mode, and your application files may not be installed. Be sure that your
end users will be able to discern when command line should and should not be used.
Note: The REINSTALLMODE attribute v is very important if you are performing a minor upgrade. This parameter tells the
installer to refresh its internal setup cache for your product with the new installation package. Without this parameter, your
installation will have no knowledge of any of the changes that you have made to the latest installation package.
Tip: If you are creating an upgrade that can update more than one previous version, you can add additional minor upgrade
items.
Method 1
To configure a minor upgrade to remove data that was installed during an earlier release, open your
original installation in InstallShield, and in the Files and Folders view, delete the file. Then you can
create a record in the corresponding Remove tables within the Direct Editor. The Remove tables in the
Direct Editor include the RemoveFile, RemoveIniFile, and RemoveRegistry tables.
To remove registry data from a component in a minor upgrade, you should create a record in the
RemoveRegistry table. Records in the RemoveRegistry table describe the registry key and value to
remove when the associated component is installed. Unlike the RemoveFile table, the
RemoveRegistry table does not accept an option to remove the specified registry data when the
associated component is uninstalled. Instead, you can author a registry value with the Uninstall entire
key flag. If your component contains a registry value with a hyphen in the Name field and an empty
Value field, the specified registry key and all its contents will be removed when the component is
removed.
For other types of data, there is usually either an uninstallation flag available in the Windows Installer
table or a corresponding uninstallation table. To remove .ini data, for example, there is a
RemoveIniFile table. For environment variable data, there is a corresponding uninstallation flag.
Note: If a component is shared with other products, you should change the component code when removing resources.
Furthermore, changing an existing component’s component code requires a major upgrade. For major upgrades, you do
not need to populate the Remove tables since a major upgrade requires a complete uninstallation.
Method 2
Mark a component as transitive, and set a condition on the component that will evaluate to false when a
minor upgrade is applied.
If you need to create your upgrades so that they can be applied to your product using versions of
Windows Installer earlier than 3.0, it is recommended that you avoid creating small updates. Since small
updates do not change the product version, external programs—including installers for later versions of
your product—cannot distinguish a product with the small update applied from one without the small
update. Windows Installer 3.0 and later requires Windows 2000 Service Pack 3, or later.
Small updates are typically packaged as a patch, not as a full installation. If you are sure that the
upgrades that you create will be applied to your product with version 3.0 or later of Windows Installer,
you can take advantage of patch sequencing support and use small-update patches to update earlier
versions of your product.
Patching Considerations
Following are some guidelines for creating patches and QuickPatch projects.
• Patch Uninstallation
• Non-Administrator Patches
Note that Windows Installer 3.0 and later supports major-upgrade patches that do not have any
sequencing data. However, the installer does not support major-upgrade patches that have sequencing
data, which would be stored in the MsiPatchSequence table.
Patch Sequencing
InstallShield enables you to specify the order that Windows Installer version 3.0 or later should apply
small-update patches to an installed product, regardless of the order in which they are provided to the
target machine. With patch sequencing data, you can ensure that Windows Installer knows the intended
relationships among the upgrades packaged within a family of patches. Consequently, applying patch 1
of a product after patch 2 has already been applied will register patch 1 without overwriting patch 2 files.
For versions of Windows Installer earlier than version 3.0, the patch sequence is ignored, and any small-
update patches are applied to the product in the order that they are provided to the target machine.
The patch sequencing functionality available with Windows Installer 3.0 and later simplifies the patch
creation process. The following sections show how.
Creating Patches to Be Applied with Versions of Windows Installer Earlier than 3.0
If you need to create your patches so that they can be applied to your product via versions of Windows
Installer earlier than 3.0, it is recommended that you avoid creating small updates. Small updates do not
change the product version; therefore, external programs, including installers for later versions of your
product, cannot distinguish a product with the small update applied from one without the small update.
For scenarios limited to versions of Windows Installer earlier than 3.0, you need to plan around such
limitations of the installer, thus targeting an increasing number of possible earlier product states. The
sample application lifecycle presented in the following table illustrates the resulting complexity.
Table 24-5: Sample Application Lifecycle for Patches Applied with Versions of Windows Installer Earlier than 3.0
Table 24-6: Sample Application Lifecycle for Patches Applied with Windows Installer 3.0
All of the small updates in the table above belong to the same patch family. Windows Installer 3.0 and
later uses the patch family to compare a small-update patch with all of the other patches within the same
family and determine the order in which each of the patches should be applied to the target machine.
Patch sequences are added to the MsiPatchSequence table of the patch package database. This table
defines the relationships between patches that target the same family of patches.
• If you do not want your minor-upgrade patch to remove all of those earlier patches, select No. If you
select this option, it may be necessary for your patch to contain the information needed to target
each of the earlier minor upgrades that were created after the RTM (or the most recent major
upgrade of the product, if one was created).
For example, if you are creating a minor-upgrade patch for service pack 2 and you select No for this
property, your patch needs to target the minor-upgrade patch for service pack 1. You could also
optionally target other baselines (such as RTM); doing so would increase the patch payload. Note
that if you do not target the RTM version, any end user who has the RTM version but not the service
pack 1 minor-upgrade patch would need to install service pack 1 before service pack 2.
Patch Uninstallation
Windows Installer 3.0 or later supports the uninstallation of patches for small updates and minor
upgrades; the patches to be uninstalled must have been installed with Windows Installer 3.0 or later.
When a patch is uninstalled, the product is returned to the state it was in before the patch was
uninstalled. With earlier versions of Windows Installer, an end user who wants to remove a patch needs
to uninstall the patched product and then reinstall the product without applying the patch. In this case,
any patches that should not be removed must be reapplied.
End users can uninstall patches through Add or Remove Programs on systems running Windows XP
SP2 and later. For systems running Windows Installer 3.0 or later with earlier versions of Windows,
patches must be uninstalled from the command line. For more information, see Uninstalling Patches in
the Windows Installer Help Library.
The uninstallation of patches is not enabled by default because not all patches can be uninstalled. For
example, a major upgrade packaged as a patch cannot be uninstalled. It is recommended that you
thoroughly test the uninstallation of your patch before deploying it to your end users. To learn more
about patches that are not uninstallable, see Uninstallable Patches in the Windows Installer Help
Library.
Non-Administrator Patches
Windows Installer 3.0 and later enables you to create patches that can be installed by non-
administrators. Non-administrator patches can be used if all of the following criteria are met:
• The target machine must be running Windows Installer 3.0 or later on the Microsoft Windows XP or
later client platform. Server platforms are not supported.
• The application was installed from a removable media such as a CD-ROM or DVD.
Note: If the ALLUSERS property is overwritten at the command line, non-administrator patches will fail.
• The base installation must include the certificate that will be used to sign all subsequent patches.
• The base installation must include the MsiPatchCertificate table. This table provides the signer
certificate that will be used to verify the digital signature of subsequent patches when they are
applied by a non-administrator. If necessary, this table can contain multiple certificates, and
subsequent patches would need to be able to verify at least one of the certificates. For more
information, see Preparing Installations for Non-Administrator Patches.
• The non-administrator patch must contain the MsiDigitalCertificate table. This table contains
the signing certificates for the signed patches. For more information, see Signing a Patch Package or
Signing a QuickPatch Package.
If any of the above criteria are not met, end users cannot install the digitally signed patch in a locked-
down environment.
A typical scenario in which non-administrator patches are used is the computer game industry. Some
computer game users are children who might not have access to areas of the system other than folders in
their own user profile and registry keys under HKEY_CURRENT_USER. Their parents would have
administrative access to the machines so that they can control what is installed and what their children
can access. Parents would install any and all applications. If patches are available for the installed
software, children would be able to download and install non-administrator patches without help from
their parents, as long as all of the above criteria have been met.
• Identification
• Digital Signature
• Sequence
• Advanced
After you have set the patch configuration properties, drill down the hierarchy in the explorer, and
configure the latest and previous setup items.
Tip: Every time that you change the latest setup for a patch configuration in the Patch Design view, InstallShield uses the
Add or Remove Programs information from the latest setup as the values for the Identification tab settings. You can
override the values on the Identification tab as needed.
1. In the Patch Design view, create a patch configuration if you have not already done so.
2. In the Patch Design explorer, click the patch configuration.
3. Click the Identification tab.
4. Configure each of the settings.
1. In the Patch Design view, create a patch configuration if you have not already done so.
2. In the Patch Design explorer, click the patch configuration.
3. Click the Common tab.
4. Select the Allow Patch to be Uninstalled (Requires Windows Installer 3.0) check box.
Sequencing Patches
Before you define a sequence for patches, you should create the necessary upgrade items in the
Upgrades view. Then you should add a patch configuration item in the Patch Design view. Once you have
completed those tasks, you can specify the sequence for the patches.
• To use default patch sequencing that InstallShield generates, select the Use Default Patch
Sequencing check box.
• To use no patch sequencing, clear the Use Default Patch Sequencing check box.
Note: If you want to digitally sign the files—such as your application’s executable fils—in your patch, you can specify
which files should be signed through the Signing tab in the Releases view.
1. In the Patch Design view, create a patch configuration if you have not already done so.
2. In the Patch Design explorer, click the patch configuration.
3. Click the Digital Signature tab.
4. Select the Sign the patch package check box.
5. Configure the digital signature settings.
Task To copy a latest setup item from one patch configuration to another:
Building a Patch
Once you have configured the settings for a patch configuration in the Patch Design view and created a
new release for the patch in the Releases view, you are ready to build a patch for your upgrade.
By default, InstallShield also performs upgrade and patch validation every time that you build a patch.
For more information, see Validating Upgrades and Patches.
The build will return an error and exit if your latest setup version was built compressed.
Applying Patches
A patch package (.msp) file contains the transforms and instructions necessary for upgrading one or
more installed versions of a product.
Before you can apply a patch package, Windows Installer version 1.1 or later must be present on the
system. In addition, the package that you want to update must be installed locally or as an
administrative image. A further requirement is that the existing installation package be installed with
the same privileges and for the same users as the patch package. For example, if the product was
installed for all users, the update should be installed for all users, as well.
The easiest way to apply a patch is to double-click the .msp file in Windows Explorer or right-click the
file and then click Open. When you apply a patch for a minor upgrade, a PatchWelcome dialog is the first
dialog that opens. When you apply a patch for a major upgrade, the full dialog sequence appears, as
when you run an installation standalone.
From the command line, you can apply a patch with the MsiExec.exe /p option. Type the following
statement to apply a patch package located at X:\Product Updates\Build 36\PatchForV1.msp:
msiexec /p "X:\Product Updates\Build 36\PatchForV1.msp"Update.exe
If you selected the Create Update.exe check box for your patch configuration in the Patch Design view,
InstallShield wraps your .msp file in an executable file. Update.exe launches your patch package with the
following command-line expression:
msiexec /p <path to .msp file> REINSTALL=ALL REINSTALLMODE=omus
When a patch package is applied with a full user interface, one of your installation’s default dialogs,
PatchWelcome, is displayed. It includes control events to set REINSTALL and REINSTALLMODE
with the correct options. However, since this dialog is not displayed when the end-user interface is
suppressed, you must set the properties at the command line, as demonstrated below:
msiexec /p <path to .msp file> /qn REINSTALL=ALL REINSTALLMODE=omus
Because a patch does not modify the existing cached .msi database, including the v setting for
REINSTALLMODE is unnecessary.
Note: You can perform upgrading and patching validation on uncompressed releases only.
The validation engine for upgrading and patching currently consists of different validators that are
designed to test for a specific condition and report failure as necessary. Upgrading and patching
validation was designed to facilitate the detection of upgrade scenario issues and is distinct from
Windows Installer validation, which is better suited for validating first-time installation issues.
Validators
The following table contains a list of validators for upgrading and patching validation.
Val0001 This validator ensures when the upgrade is applied, the files that have been removed from
the latest version of the installation will be uninstalled from the target machine.
Val0002 This validator detects cases where RemoveFile table entries are scheduled to run during
installation only.
Val0003 This validator ensures that the proper settings exist so that an upgrade can start
successfully.
Val0004 This validator ensures that when the upgrade is applied, all files that have changed in the
latest installation will be installed properly.
Val0005 This validator ensures that feature InstallLevel values are configured so that no feature will
be ignored in an upgrade.
Val0006 This validator detects when a minor upgrade is being attempted, even though a major
upgrade should be performed.
Val0007 This validator ensures that the name of the .msi package has not changed.
Val0008 This validator ensures the integrity of the ActionProperty and Version elements of all
records in the Upgrade table.
Val0009 This validator ensures that when the installation is run as an upgrade, registry entries that
have been deleted from an installation will be removed.
Val0010 This validator ensures that changes made to any data in a component will be applied to
the target machine when the installation is run as an upgrade.
Val0011 This validator detects when schema incompatibility exists. Schema incompatibility will
prevent the creation of a patch.
Val0012 This validator ensures that new features are properly added to the latest installation so
that they will be installed when the upgrade is run.
Val0013 This validator ensures that the user is informed of the intended functionality for the
Remove attribute for a major upgrade item.
Val0014 This validator warns you that because of a specific entry in the Upgrade table, part of the
existing product will be left on the target machine when the major upgrade is applied.
Val0015 This validator warns you that if you want to package your upgrade as a patch, end users
will not be able to uninstall your patch. This validator applies to small updates and minor
upgrades.
Val0001
Message (Error)
The file [1] with a target of [2] appears to have been removed from the setup, but does not
appear in the RemoveFile table. This file will not be removed from the target machine when
an upgrade is run unless the RemoveFile table has been authored.
[1] is the name of the file that has been removed, while [2] is the target path of this file.
Description
When a small update or minor upgrade is applied, any file or files that have been removed from the
latest setup will not automatically be uninstalled from the target machine because a minor upgrade will
recache the local .msi database. This recached copy no longer contains any reference to the file, since it
has been removed from the setup.
To remove this file when the upgrade is run, you must add entries to the RemoveFile table. When the
upgrade is run, these RemoveFile table entries will be executed, and the file will be deleted.
Note: This validator does not apply to major upgrades because the uninstall-and-then-reinstall nature of major upgrades
does not lend itself to this type of consideration.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
Using the file name and file destination from the previous version setup package, create an entry in the
RemoveFile table using the Direct Editor. The file name can contain wildcard characters.
Note: When authoring the RemoveFile table, you must specify a component. This component’s install state is used to
determine if a file matching the RemoveFile signature should be removed or not. Be sure to specify a component that you
are certain will reinstall when the upgrade is applied.
Val0002
Message (Note)
The RemoveFile table entry [1] has an InstallMode of 1. In an upgrade scenario, if the component
[2] does not have to reinstall, the files attributed to this table entry will not be
removed. You can change the InstallMode value to 3 so that the files will at least get
removed on uninstall, or make sure that this RemoveFile table entry is associated with a
component that will get reinstalled.
[1] is the name of the entry in the first column of the RemoveFile table that is causing this message. [2]
is the name of the component with which this RemoveFile table entry is associated.
Description
When you author an entry in the RemoveFile table, you must specify a value in the InstallMode
column. If this value is set to 1, this tells the installer that the specified file should only be removed upon
installation of the associated component. In an upgrade scenario, if the associated component does not
need to be reinstalled, then the RemoveFile table entry will not be executed, and the file will not be
removed from the target machine.
In a subsequent uninstallation, you will need to manually remove this file and the directory that contains
it since the file still exists on the target machine.
Note: This validator does not apply to major upgrades because the uninstall-and-then-reinstall nature of major upgrades
does not lend itself to this type of consideration.
To perform this validation test, the validation engine will need to compare the latest setup to a previous
version of that setup.
Corrective Action
This validator is only a note. It is designed to make you aware of a potential issue with your setup when
you are creating an upgrade. If you do not intend on performing an upgrade or you are certain that the
component associated with this RemoveFile entry will be reinstalled in an upgrade, you can choose to
disregard this note.
You can also choose to change the InstallMode value to 3. In this case, a file will not be removed during
installation, but it will always be removed during an uninstallation.
Val0003
Message 1(Note)
This setup will perform a SMALL upgrade of the referenced previous setup.
Message 2(Note)
This setup will perform a MINIOR upgrade of the referenced previous setup.
Message 3(Note)
This setup will perform a MAJOR upgrade of the referenced previous setup.
Message 4(Error)
The package code for the latest setup does not differ from that of the previous version. In
order to perform an upgrade, the package code MUST change.
Message 5(Note)
The product version [1] differs from the product version [2] but only past the third element.
The Windows Installer does not detect version differences past the third version element.
[1] is the version number of the previous installation. [2] is the version number of the latest installation.
Message 6(Error)
The setup needs to perform a Major Upgrade of the previous setup specified. However, the Upgrade
Code for the previous setup [1] is not in the upgrade table. An upgrade will not occur.
Message 7(Error)
The setup needs to perform a Major Upgrade of the previous setup specified. While upgrade table
entries exist for the Upgrade Code, there is no upgrade table entry that matches the Product
Version [1] or Product Language [2].
[1] is the version number, and [2] is the language ID of the installation.
Description
This validator determines the type of upgrade that is necessary to update an earlier installation. For
example, if you are creating a minor upgrade but this validator states that your installation is configured
to perform a major upgrade, consider changing your minor upgrade to a major upgrade.
This validator also checks if the package code has changed. This check is performed for all upgrade
types. Changing the package code is a requirement any time that you decide to release an installation,
whether or not you intend to upgrade it. If the package code has not changed, you will see the error
described in message 4.
If the product version has changed but only past the third version item, the validator displays the note
described in message 5. This note is designed to alert you that changes to the fourth item in a version
resource will not appear as unique versions to the installer at run time.
Additionally, if a major upgrade is required, this validator will check if the appropriate entries exist in
the latest installation to remove the previous installation from the target machine. If these entries do not
exist, you will see message 6 or 7. Message 6 is displayed when there are no settings related to the earlier
product. Message 7 is displayed when there is a setting related to the earlier product, but the signature of
that setting does not patch the signature of the previous setup.
Corrective Action
If you receive message 4, you must generate a new package code for the latest version of your
installation. A good option is to set the Generate Package Code property for the product configuration to
Yes.
If you receive message 5, you can choose to disregard it since it is for informational purposes. However,
note that having indistinguishable versions can create difficulties if you attempt to apply a major
upgrade at a later date.
If you receive message 6, you need to add a major upgrade item.
There are several possible reasons why you might receive message 7. The first possibility is that the
product version does not fall within the range of versions specified as potential target installations. If the
version of the previous installation is either the upper bound or the lower bound of the acceptable range
of product versions to upgrade, you may want to check the minimum and maximum inclusive settings
for your major upgrade item. Additionally, the product language may not be listed in the list of
supported languages for upgrading. You will also get error message 7 if you have defined a major
upgrade item for the previous setup but have marked that item to Detect Only.
Val0004
Message (Error)
The file [1] in component [2] is different from the file in the previous package, but the key
file for this component did not change. As a result, the changed file will not be installed
in an upgrade scenario. Place this file in its own new component.
[1] is the name of the component that contains the new or changed file, while [2] is the name of the file
name that is new or has been changed.
Description
In most cases, when the installer runs an upgrade, files are installed based on the component’s
InstallState. The InstallState is determined by the component’s key file. If the component’s key file
has not been upgraded, it is assumed that the component does not need to be reinstalled. Therefore, if a
file that is not the key file has changed, and the key file has not changed, it is likely that your upgraded
file will not be installed in an upgrade scenario.
The exception is when the user sets the REINSTALLMODE property to a, which forces the installation
of all files, regardless of version.
Note: This validator does not apply to major upgrades because the uninstall-and-then-reinstall nature of major upgrades
does not lend itself to this type of consideration.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
Delete the file that has changed from the existing component, and add it to its own new component. In
this component, mark the file as the key file.
Val0005
Message 1(Warning)
The default InstallLevel for feature [1] is zero. If this feature gets enabled on install, you
must author similar logic to ensure that it is also enabled in maintenance mode, otherwise
in an upgrade the feature will be ignored.
[1] is the name of the feature whose InstallLevel is the cause of concern.
Message 2(Warning)
A condition for feature [1] may possibly set the InstallLevel for this feature to zero at
runtime. If this feature gets enabled on install, you must author similar logic to ensure
that it is also enabled in maintenance mode, otherwise in an upgrade the feature will be
ignored.
[1] is the name of the feature whose InstallLevel is the cause of concern.
Description
The significance of setting a feature InstallLevel to zero is that it will cause the feature to appear as
disabled at run time, and the user will not be able to enable it. It is tempting to set this feature to zero by
default and then enable it as needed through a feature condition.
In an upgrade, if this feature condition does not get evaluated so that it can set the install level to a value
other than zero, the InstallLevel for the feature will remain at zero. Therefore, no changes made to the
components in that feature will be installed.
Another variation of this issue is that the feature InstallLevel defaults to something other than zero,
but there exists a feature condition that sets this feature InstallLevel to zero at run time. This issue
raises problems for major upgrades, since the previous installation is already in the field.
Val0005 applies to all upgrade types: major, minor, and small.
To perform this validation test, the validation engine will need to examine only the latest version of your
setup.
Corrective Action
Ensure that any processing that can effect the evaluation of these feature conditions is also performed
when an upgrade is run. Remember that in an upgrade, the user interface being displayed to the end
user may be different from the user interface displayed the first time the installation is run.
Making sure that your feature InstallLevel values do not default to zero is important so that a major
upgrade will be able to safely install and uninstall files.
Val0006
Message 1(Error)
The Component [1] identified by ComponentID [2] is missing from the newest version of your
setup. You cannot delete components and still do a minor/small upgrade. You must perform a
major upgrade.
[1] is the name of the component that has been removed. [2] is the ComponentID associated with the
component that was deleted.
Message 2(Error)
The Feature [1] is missing from the newest version of your setup. You cannot delete features and
still do a minor/small upgrade. You must perform a major upgrade.
Description
If any components or features have been deleted from the latest version of the installation, you must
perform a major upgrade to avoid potential problems associated with leaving resources and
registrations on a machine.
Note: If you move a feature or component to another location in the installation, you have effectively deleted it from its
original location.
This validator does not apply to major upgrades. It identifies when a minor upgrade or small update
should be a major upgrade.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
If you need to make major architecture changes to your installation, you should apply a major upgrade.
You can also use the RemoveFile, RemoveRegistry, and RemoveIniFile tables to clean up some resources
that may be orphaned. However, this will not clean up the Windows Installer registration information
for those components and features. Leaving that registration information behind can cause
unpredictable results in a future upgrade installation or uninstallation of your product.
Val0007
Message 1(Error)
The MSI package name for the most recent setup [1] differs from the MSI package name of the
previous setup [2]. Small/Minor upgrades require that the package name remain the same.
[1] is the name of the new .msi package that has changed. [2] is the name of the original .msi package.
Description
When you perform a minor upgrade or a small update, the previous and latest versions of your
installation must have the same .msi package name. Renaming the .msi package will result in the
inability to find the source media when the files are transferred.
This validator does not apply to major upgrades.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
This is a limitation of the Windows Installer service. The only recourse here is to give your .msi packages
the same name.
Val0008
Message 1(Warning)
In the Upgrade table, the Action Property [1] is not listed as a member of
SecureCustomProperties. The defined upgrade may not function properly.
[1] is the name of one of the action properties specified in the Upgrade table.
Message 2(Error)
In the Upgrade table, the Action Property [1] is not public. The defined upgrade will not
function properly.
[1] is the name of one of the action properties specified in the Upgrade table.
Message 3(Error)
In the Upgrade table, the Action Property [1] is already defined in the property table. The
defined upgrade will not function properly.
[1] is the name of one of the action properties specified in the Upgrade table.
Message 4(Error)
In the Upgrade table, the Action Property [1] is used more than once. This may cause undesirable
results at runtime.
[1] is the name of one of the action properties specified in the Upgrade table.
Message 5(Error)
In the Upgrade table, there exists a record where the MaxVersion [1] is less than the MinVersion
[2]. This will cause unpredictable results a runtime.
[1] and [2] are version numbers specified in the Upgrade table.
Description
For all records in the Upgrade table:
• Ensure that the ActionProperty is public.
Corrective Action
To find where the value of the Action property is entered, open the Upgrades view. Select the major
upgrade item, and then click the Advanced tab. The Detect Property value is used for the Action
property.
Val0009
Message 1(Warning)
A registry entry has been removed from the component [1]. There exists a corresponding entry in
the RemoveRegistry table, however, that entry is not associated with this component. This
may result in the registry entry not being removed when an upgrade is run.
[1] is the name of the component from which a registry entry has been removed in the latest version of
the setup.
Message 2(Error)
A registry entry has been removed from the component [1]. This key must be added to the
RemoveRegistry table, otherwise it will be orphaned by an upgrade. [2].
[1] is the name of the component from which a registry entry has been removed in the latest version of
the setup. [2] is the missing registry entry in the form <Root>|<Key>|<Value>.
Description
When a small update or minor upgrade is performed, any registry entries that have been removed from
the latest installation will not automatically be uninstalled from the target machine. The reason is that a
minor upgrade will recache the local .msi database. This recached copy no longer contains any reference
to these registry entries, since it has been removed from the installation.
To remove this registry entry, add entries to the RemoveRegsitry table so that it will be removed when
the upgrade is applied. When the upgrade is run, these RemoveRegistry table entries will be executed,
and the registry entry will be deleted.
Note: This validator does not apply to major upgrades because the uninstall-and-then-reinstall nature of major upgrades
does not lend itself to this type of consideration.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
Using the root, key, and value of a registry entry from the previous version of the installation package,
create an entry in the RemoveRegistry table through the Direct Editor. The Value field can be
authored with the minus character (–). This will result in the removal of the entire registry key with all of
its values and subkeys.
Note: When you add an entry to the RemoveRegistry table, you are required to specify a component. This component’s
install state is used to determine if a registry entry matching this RemoveRegistry signature should be removed. Ensure
that you specify a component that you know will be reinstalled when the upgrade is applied.
Val0010
Message 1(Warning)
The data in component [1] differs from the previous setup. However, this component will not
reinstall in an upgrade scenario. Therefore, the changes will not be applied to the target
system during the upgrade. Table: [2] Record: [3]
[1] is the name of the component whose information has changed since the previous version, and [2] is
the name of the specific table that has changed. [3] is the specific table record that has changed; this is a
formatted string that contains all of the fields for the offending record, separated by the pipe (|)
character.
Description
When a small update or minor upgrade is performed, a specific component will be reinstalled only if the
component key file has changed. Therefore, if some component data has changed, and the key file for the
component has not been updated, the new data will not be reapplied in an upgrade.
This validator does not apply to the Shortcut or Registry tables. The REINSTALLMODE property
takes parameters that will force shortcuts and registry entries to always be reapplied in an upgrade.
This validator checks the component key file to see if it is newer than the key file in the previous
installation. If it is not, this validator checks all component-related tables for any changes that have been
made. If it detects any, it will display an error.
The following tables are checked by this validator:
• IniFile
• Class
• Complus
• CreateFolder
• Environment
• DuplicateFile
• Extension
• FeatureComponents
• IniFile
• MoveFile
• MsiAssembly
• MsiAssemblyName
• ODBCDataSource
• ODBCDriver
• ODBCTranslator
• PublishComponent
• RemoveFile
• RemoveIniFile
• RemoveRegistry
• ServiceControl
• ServiceInstall
• TypeLib
Note: This validator does not apply to major upgrades because the uninstall-and-then-reinstall nature of major upgrades
does not lend itself to this type of consideration.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
You have the following three options:
• Update the key file for the component so that the component will reinstall in an upgrade scenario.
• Add the altered data to another new component instead of the existing component.
Val0011
Message 1(Error)
The data types for the Version column of the TypeLib table differs from that of the Upgraded
image. This will cause a failure to create the patch package.
Message 2(Warning)
The target image was created with Windows Installer 1.2 or previous, and the Upgraded Image was
created with Windows Installer 2.0 or later. Although validation did not detect any data
type conflicts, creating patches for packages that span this schema inflection point can be
problematic.
Description
With the release of Windows Installer 2.0, the schema of the .msi installation package changed. The data
type of the Version column in the TypeLib table changed from I2 to I4. It is not possible to patch .msi
installations using the old schema with .msi packages using the new schema.
Note: This validator does not apply to major upgrades because the uninstall-and-then-reinstall nature of major upgrades
does not lend itself to this type of consideration.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
You can still distribute your upgrade as a minor upgrade, however, you will not be able to distribute your
upgrade as a patch.
Val0012
Message 1(Error)
The new feature [1] is defined as a root level feature. New features MUST be defined as sub-
features of features that already exist in the original setup.
Message 2(Error)
The validation engine has detected the new feature [1]. This feature must have the 'FavorParent'
and 'Required' attributes set to Yes in order to install in an upgrade scenario.
Description
If you intend to distribute the latest version of your installation as a small update or a minor upgrade,
you must follow certain rules if you decide to add features to the installation. The first rule is that the
feature must be added as a child to an existing feature. The second rule is that the feature must have its
Remote Installation property set to FavorParent and its Required property set to Yes.
If these two rules are not followed, the contents of the new feature will not be installed when the upgrade
is applied. Instead, the end user will need to run the installation in maintenance mode and manually
select the feature to be installed locally.
This validator does not apply to major upgrades.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
Add the new feature as a child of an existing feature, and set its Remote Installation property set to
FavorParent and its Required property set to Yes.
Val0013
Message 1(Warning)
Validation has detected that you are using the Remove column in the Upgrade table for the entry
[1]. Doing this will result in the incomplete uninstallation of the referenced setup. For
the most common upgrade scenarios, you should not author the Remove column of the upgrade
table.
Description
When the remove attribute of a major upgrade item is left empty, it will remove all of the features from
the target product, effectively uninstalling the entire product.
If you place one feature name in the remove attribute of a major upgrade item, only that feature will be
removed, and all of the other features of the existing product will be left on the target machine along
with the target product itself. This means that you will be left with two products on the target machine
with two entries in Add or Remove Programs.
This feature is intended for users who want to leave the target product on end users’ machine while
removing only some of its features.
This validator applies only to major upgrades.
To perform this validation test, the validation engine needs to examine the latest installation only.
Corrective Action
This is a warning. If the behavior described above is what you desire, you can disregard this warning.
Otherwise, do not use the Remove attribute of a major upgrade item.
Val0014
Message 1(Error)
The component identified by ID [1] has been removed from the latest version of the setup. On a
Major Upgrade the resources contained within these components will get uninstalled, possibly
deleting resources necessary for your application to run.
[1] is the component code that identifies a component in the earlier installation.
Description
This validator performs this check only if the major upgrade is configured to install new files, then
remove unneeded files. The issue this validator is designed to protect you against does not exist if the
major upgrade is configured to uninstall the product first, then reinstall it.
When the target upgrade mode is selected, the installer achieves this functionality by relying on
reference count components on the target machine. The reference count for a required component is
incremented when the latest application is installed, and it is decremented when the earlier application
is removed. However, since the reference count never reaches zero, the persistent components remain
on the target machine.
The problem exists when you delete a component from the installation, and then add the resources from
that component to a different component. Instead, you should perform the following:
1. Install a new component with new resources.
2. Uninstall the old component with old resources.
When the old component is uninstalled in step 2, it may remove registry entries, .ini file changes,
environment variables, and so on if they were added by the new component in step 1.
Since components are referenced by a GUID, and a new component GUID is generated every time you
add a new component to your installation project, even a simple deletion or addition of a component
that already exists can cause this behavior.
This validator applies only to major upgrades.
To perform this validation test, the validation engine compares the latest installation to an earlier
version of that installation.
Corrective Action
To correct this problem, you can either configure your upgrade to uninstall the application first and then
reinstall it, or you can add a component with a GUID equal to the one specified in this error message.
Even though the component is empty, its existence ensures that accurate reference counts are kept, and
nothing is prematurely uninstalled.
Val0015
Message 1(Warning)
The [1] table contains new content. Therefore, if you are packaging this upgrade as a patch, you
will not be able to make it an uninstallable patch.
Description
When an end user uninstalls a patch, the product is returned to the state it was in before the patch was
uninstalled. If a patch is not uninstallable, an end user who wants to remove the patch needs to uninstall
the patched product and then reinstall the product without applying the patch.
Note: If a target machine does not meet certain requirements (for example, it must have Windows Installer 3.0 or later),
the patch will not be uninstallable, even if this validator warning is resolved. For more information about the requirements
for uninstallable patches, see Patch Uninstallation.
If a patch adds a row to any of the following specific tables, the patch cannot be uninstalled, even if the
Allow this patch to be uninstalled check box is selected for the patch.
• BindImage
• Class
• Complus
• CreateFolder
• DuplicateFile
• Environment
• Extension
• Font
• IniFile
• IsolatedComponent
• LockPermissions
• MIME
• MoveFile
• ODBCAttribute
• ODBCDataSource
• ODBCDriver
• ODBCSourceAttribute
• ODBCTranslator
• ProgId
• PublishComponent
• RemoveIniFile
• SelfReg
• ServiceControl
• ServiceInstall
• TypeLib
• Verb
Note that under certain conditions, it is possible that an end user may not be able to remove a patch that
adds content to the RemoveFile or RemoveRegistry tables. If the patch is designed to remove a file or
registry entry that was not included in the original installation package, then uninstalling the patch will
not restore that file or registry entry.
This validator applies to small updates and minor upgrades only.
To perform this validation test, the validation engine compares the latest installation to an earlier
version if the Allow this patch to be uninstalled check box is selected for the patch.
Corrective Action
This validator is designed to warn you that if you are creating a patch—or you later decide to package
your upgrade as a patch—your end users will not be able to uninstall the patch unless you take corrective
action to resolve it. To resolve this warning, do one of the following:
• Clear the Allow this patch to be uninstalled check box for the patch. If you do this, end users will not
be able to uninstall the patch.
• Remove the new data from the table mentioned in the warning message. Note, however, that
depending on your patch requirements, removing new table data may mean that your patch will not
fix the issue in your application that led you to create the patch in the first place.
Note: You can create a QuickPatch to update an earlier version of your product only if the earlier version was installed
using Windows Installer.
A QuickPatch project is recommended for installation authors who want to ship small, single upgrades
to their users. QuickPatch authoring provides a simple alternative to creating a patch in the Patch
Design view, even though it provides less customization. Fundamentally, both patch creation methods
produce the same deliverable types: .msp and .exe files.
To create a QuickPatch project for an existing .msi file or an already existing QuickPatch, use the Create
New QuickPatch Wizard. Completing the wizard ensures that all basic requirements for the QuickPatch
project are met.
Caution: If you open and modify any of the releases listed in the History of the General Information view, your latest project
will not work, since intermediate data shared across the releases in the History may have been lost or altered. Therefore,
whenever you create a QuickPatch project for an existing QuickPatch project, InstallShield changes the existing
QuickPatch project (.ism file) to read-only mode.
1. In InstallShield, open the QuickPatch project (.ism file) that you would like to patch.
2. Open the General Information view.
3. In the General Information explorer, click History.
4. Click Create Next Version.
Your new QuickPatch project opens in InstallShield.
You can also use the Create New QuickPatch Wizard to create a QuickPatch for an existing QuickPatch.
Note: You cannot clear the check box for the Base QuickPatch Image or the current project. If you clear the check box of
an intermediate QuickPatch project, your current QuickPatch project cannot be used to upgrade a machine that has that
intermediate image as the latest image of your application.
For example, suppose you distributed version 1.0 as an installation and later released a patch that upgrades the original
installation to version 1.1. If you create a version 1.2 QuickPatch and the check box for the 1.1 QuickPatch is not selected
in the History, your 1.2 QuickPatch can be used to upgrade the 1.0 release but not the 1.1 release.
Task To specify which custom actions should be run when your QuickPatch is applied:
1. In the General Information view, click Build Settings, and then click the Identification tab.
2. Configure each of the settings.
1. In the General Information view, click Build Settings, and then click the Common tab.
2. Select the Allow Patch to be Uninstalled (Requires Windows Installer 3.0) check box.
1. In the General Information view, click Build Settings, and then click the Advanced tab.
2. Do one of the following:
• To use default patch sequencing that InstallShield generates, set the Create patch
sequencing entry property to Yes.
• To use no patch sequencing, set this property to No.
Note: With QuickPatch projects, you can digitally sign the patch package and the Update.exe file. If you want to digitally
sign individual files—such as your application’s executable files—in your QuickPatch package, you must manually sign
them and then add them to your project. You can use Signcode.exe or SignTool.exe to manually sign your files. For
more information, see Digital Signing and Security.
1. In the General Information view, click Build Settings, and then click the Digital Signature
tab.
2. Select the Sign the patch package check box.
3. Configure the digital signature settings.
Tip: As an alternative to steps 3 and 4 above, you can drag and drop files or folders from the Original Setup Files
explorer to the Files To Patch explorer.
Tip: To change any registry settings that you modified for the QuickPatch project, you can right-click the item and then
click Revert.
Using COM Extraction to Register .dll and .ocx Files with a QuickPatch
Task To use COM extraction (as opposed to self-registration) for a .dll or .ocx file in your QuickPatch:
1. Add the .dll or .ocx file to your QuickPatch project if you have not already done so.
2. Open the Files view.
3. In the Files To Patch explorer, click the file for which you want to use COM extraction. The file’s
settings are displayed in the right pane.
4. In the right pane, clear the Self-Registering check box.
5. Open the Direct Editor.
6. In the Tables explorer, click ISQuickPatchFile.
7. Find the row associated with the .dll or .ocx file.
8. In the Attributes field, add a value of 8 to the existing value. For example, if 2 is in this field, replace
it with 10.
Note: To automatically generate entries for the MsiPatchOldAssemblyFile and MsiPatchOldAssemblyName tables,
InstallShield must have write access to the latest version of the .msi package to which the patch applies. InstallShield
modifies this package before creating the patch. InstallShield automatically attempts to make this package writable; if it
cannot, a build warning is generated, and the table entries are not created.
These table entries are applied only if the target system is running Windows Installer 3.0 or later. The patch runs if the
system is running Windows Installer 2.0; however, these tables are ignored, and if the patch needs to update a file in the
GAC, it makes a request for the original source package. InstallShield generates these table entries even if you include
only the Windows Installer 2.0 engine in Update.exe, since a target system with Windows Installer 3.0 or later already
installed can use them.
Note: If the product that you want to update was not installed by an installation created with InstallShield X or later,
InstallShield DevStudio, or InstallShield Professional 6.0 or later, you must create a new project. You may also want to
consider creating a new project if you plan to include extensive changes in this update.
Note: If you are creating a new project and you want to update features that were installed by the original installation,
ensure that each feature’s GUID matches the GUID with which the previous version of that feature was installed. To
check a feature’s GUID, select it in the Features or Setup Design view and inspect the value of its GUID property.
Note: For information about product version numbers in InstallScript projects, see Product Version Numbers. If you
are creating an update for a product that was installed by an installation created with InstallShield Professional 6.x,
see the Version Number of the Already Installed Product section in Product Version Numbers. For guidelines on
assigning a version number when using FLEXnet Connect, see How FLEXnet Connect Identifies Products.
Note: If you are using the Release Wizard, the Update panel is where you select the release format (Full or
Differential).
6. If you are building a full release, specify the versions of your product to which the update should be
applied. In the Supported Versions property, type the applicable version numbers using a
semicolon to separate the different versions (for example, 1.2.3;1.2.4). If you leave the Supported
Versions property blank or select the Non-version specific, the update is applied to all earlier
versions of your product. Continue with step 8.
Note: These version numbers can also be specified in the Release Wizard by selecting version numbers from the box
on the Update panel. Do not specify version numbers that correspond to releases that were created by versions of
InstallShield Professional earlier than 6.0 because those releases cannot be updated.
See Product Version Numbers for more information on product version numbers in InstallScript
projects.
7. If you are building a differential release, you must use the Release Wizard to specify one or more
existing releases to which the current project is compared when creating the new differential release.
Note: Do not specify existing releases that were created by versions of InstallShield Professional earlier than 6.0
because those releases cannot be updated. Only the specified existing releases can be updated by the resulting
differential release. To review the criteria that determine whether a file in the current project is included in a differential
release, see Differential vs. Full Releases.
• Confirm the specified release’s version information is displayed in the Differential Media box
of the Update panel. If no version information is displayed, do the following:
a. Select the release in the list box and click Modify. The Media File Properties dialog box
opens.
b. Select the Specify the version information below option and type or select a version
number in the list.
c. Click OK.
See Product Version Numbers for more information on product version numbers in
InstallScript projects.
8. Build the release.
See Migrating from InstallShield Professional 6.x for more information on using a version 6.x-created
script with an update-enabled installation.
Update Deployment
1. Use InstallShield to create an update for your application.
2. Register your new product version and product code with the FLEXnet Connect Publisher site, a
Web-based management portal.
3. Publish your update to the FLEXnet Connect Publisher site, and set the Message Status to Test.
4. Test your update.
5. Publish your update to the FLEXnet Connect Publisher site, and set the Message Status to Active.
FLEXnet Connect includes a variety of options that can be purchased together for a complete solution,
or separately for a customized solution. To learn more, visit the Macrovision Web site. To access the
FLEXnet Connect documentation, see the FLEXnet Connect Help Library.
In addition to helping you create an installation package that installs products, InstallShield provides
other installation options to help you enhance your final installation package. Some of these options
include enabling multilingual installations, building conditional statements, and defining installation
prerequisites.
Read more about additional installation options in the following sections.
InstallShield supports many powerful features that allow you to easily customize your installation for
global distribution. Using these features, you can create a single installation project that displays end
user text in multiple languages and can handle conditional installation of language-specific files.
Language Support
In order to display end user text in a particular language, you must purchase support for that language
from Macrovision Corporation. To see which languages are supported in your edition of InstallShield,
navigate to the General Information view and look at the project properties. Under the Setup Languages
property, click Show only available languages. Support for 33 languages is included in the Premier
edition of InstallShield.
If you have purchased the English release of the InstallShield Professional edition, you can create only
an English installation. If you also include installation resources or language-specific files for a second
or third language, InstallShield creates only an English installation and does not include the non-
English files.
Task InstallShield enables creating multilingual installations by dividing installation authoring into the following
distinct tasks:
Caution: It is strongly recommended that you develop multilingual installation projects on Windows NT 4 or Windows 2000
(or later). Operating system limitations on Windows 95, Windows 98, and Windows Me prevent creation of an installation
that uses multiple extended character sets or code pages.
Globalization Tips
Consider these points when designing your installation project for a global audience:
• The goal of global distribution is a localized product that is international in scope and readily
adaptable to specific areas of the world.
• The key to globalization is resource and code separation, plus country and language independence.
• Creating a worldwide specification package means incorporating global requirements into the
installation specifications from the beginning. InstallShield’s globalization features make it an ever-
present and seamless venture.
• Make bitmaps and icons culturally sensitive. What may be acceptable in one country could be
misleading or offensive in another.
• English strings are usually shorter than equivalent text strings in other languages. Translated strings
grow an average of 30 to 40 percent. This implies that both static and temporary storage areas will
increase in size.
• When designing prompts, use only one-half of the available space to allow for expansion.
• Avoid hard-coding element positioning and size on the screen, because these items can change when
the element is translated.
• The default language is the language that the setup runs in if you do not let the end user select a
language in the Language dialog. If you do display the Language dialog by selecting the Language
dialog option in the Release Wizard, the Language dialog is displayed in the default language.
Tip: You may have components specific to several languages depending on your selections in the Release Filtering panel.
To install them only on machines with a specific locale, set the components’ Condition property to check for the value of
SystemLanguageID.
You can add languages to your installation project in the project’s Setup Languages property. One of
these supported languages must serve as the project’s default language, which initially is English.
You can build an installation for distribution in as many languages as you have support for, but
InstallShield runs an installation in only one language. For more information, see How InstallShield
Determines Which Language the Installation Runs In.
1. Select the component in the Setup Design view or Components view to open its property sheet.
2. Click on the Languages property to see the help and list of languages below the property sheet.
3. Select as many languages from the list as this component’s data apply to. Click on a selected
language to clear the selection.
SystemLanguageID = 1036
Other properties that can be used to determine language characteristics at run time are
UserLanguageID, which contains the numeric identifier of the user’s default language, and
ProductLanguage, which contains the identifier of the language the setup program is running in.
Note: When you edit resources in the InstallShield Dialog Editor, you must use string IDs for labels and other localizable
strings. You can also use string IDs in your InstallScript custom actions instead of hard-coding string literals.
String IDs are defined in the string tables found in the General Information view. You can associate a
string value and a comment with each string ID. You can have unique string values in each string table
for the same string identifier. When you include a language in your setup project, InstallShield creates a
string table for that language and includes in it all existing string IDs. Then, it is your responsibility to
translate the strings into the target language.
While you can translate the strings directly in the String Table editor, an easier way to translate the
values is to export the table to a text file, translate the strings, and then merge the translated file back
into the string table in your project. You can export all or part of the string table.
When you build your setup with the Release Wizard, InstallShield includes the string tables for the
target languages you select in the Setup Languages panel.
The string table that is used during the setup depends upon which language the setup is running in. For
more information, see How InstallShield Determines Which Language the Installation Runs In.
3. Browse to the location where you want to save the text file, and enter a file name. InstallShield
exports the strings into a tab-delimited text file (.txt).
4. Click Save.
InstallShield exports the entire string table to a tab-delimited text file. You can give this text file to your
translator.
Task To import the tab-delimited text file that has been translated:
1. Click the Dialogs shortcut on the View List, and expand the All Dialogs item.
2. Double-click on the name of a dialog to see an item for each supported language.
Resizing Elements
The exceptions to the above rule are the Height and Width properties of a control. These properties are
specific to each language’s version. Because string lengths can vary widely from one language to another,
when you resize a control, you are not affecting the control’s size for any other language.
For example, you may need to enlarge a push button to accommodate a longer string after it is translated
into German. The push button remains the same size for every version of the dialog since it was created.
When you resize the control in the German layout, it is resized only for that language.
Modifying Strings
The strings in each dialog come from that language’s string table. When you select a string for a control
that accepts localizable text, although the string ID is the same for each language-specific version, the
string value that is displayed comes from the current language’s string table. If you edit the value in the
control’s property sheet, you are actually editing that string ID’s value in the string table.
• When Setup.exe initializes, it determines the target system’s language. If you selected more than one
language in the Setup Languages panel of the Release Wizard, and one of those languages matches
the target system’s language, then InstallShield launches the installation in the target system’s
language. To learn how to require an exact language match, see Requiring an Exact Match for a
Language.
• If the target system’s language is not present in your setup, InstallShield launches the installation in
the default language .
Note: The first time the end user selects a language in the Language dialog, the installation runs in the selected language.
However, if the end user then selects a different language from the Language dialog and runs the installation a second
time, it runs in the language that was selected the first time. After an installation has been run in a particular language, it
cannot be run in any other language on the same machine due to caching performed by the Windows Installer service.
This Setup.ini is copied during the build and used in your setup project’s release.
2. Modify the RequireExactLangMatch entry to include the language for which you want to require an
exact match. You can add to the default entry, modify the entry, or specify ALL for all languages.
Entry Description
Entry Description
1. In the General Information view, open up the String Tables item to view the string tables for
all of your project’s languages.
2. Right-click on the language that you want to serve as the default, and select Make default in the
resulting context menu.
You can also set the default language by clicking Make Default in the Release Wizard’s Setup Language
panel.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The Source Location property names a subfolder where this component’s files will be stored in the
source disk images, if the component’s files are not compressed. The component’s files will be copied to
this subfolder in your release image.
This property does not require a value, and in most cases, can be left blank. If you enter a value, it must
be a valid Windows folder name.
One instance where the Source Location property could be used is when you are creating a setup
containing more than one language. In this scenario, you can have multiple files with the same name.
You can create a component for each language and set the Source Location property for each one. With
the Source Location property set, any file with the same name can be copied onto the disk in two
different locations, without the risk of being overwritten.
For example, create two components called German and English. For the first component, set the
Source Location property to GermanVersion. For the second, set the Source Location property to
EnglishVersion. Create two files called Test.txt, giving them slightly different contents.Assign each file to
a component.
When you build your setup with uncompressed files, two separate folders on the disk images will be
created, one called GermanVersion and one called EnglishVersion. Separate versions of Test.txt will be
copied to each of these folders, but neither copy will be overwritten.
Note: The Source Location property is not the same as the destination location. While it is conceivable that you might
want to copy both versions of the file to the user’s machine, it is more likely that you would want to filter the files by
language.
Note: The New Language Wizard is available in the Premier edition of InstallShield. For more information, visit the
Macrovision Web site.
On the Tools menu, click Add New Language. You must first close any open project, or the menu
item is grayed out.
Language Identifiers
Throughout the InstallShield interface, you must refer to specific languages by their language identifiers,
or LCIDs. The identifier is an integer value that identifies a specific language. The language ID is more
commonly given as a hexadecimal value, but you must specify the decimal version for Windows
Installer.
Project: Note that Basic MSI and InstallScript MSI installations use different IDs than InstallScript installations.
Identifier (Windows
Language Name Identifier (InstallScript) Installer Based)
Identifier (Windows
Language Name Identifier (InstallScript) Installer Based)
Windows NT 4.0
Windows 2000
Windows XP
1. Select the Date, Time, Language, and Regional Options category from the Control Panel.
2. Click Add other languages.
3. Click Details.
4. Click Add.
5. Select the language for which you want to add a code page.
6. Click OK.
Caution: It is strongly recommended you develop multi-language installation projects on Windows NT 4 or Windows 2000
(or later). Operating system limitations on Windows 9x prevent creation of an installation program that uses multiple
extended character sets or code pages.
Caution: This capability requires sophisticated authoring and serious commitment on the part of the installation developer.
It is recommended only for advanced installation developers.
Note: Multiple-instance support works only with version 2.0.2600.1106 of Windows Installer and later, and with Microsoft
Windows XP SP1 and Microsoft Windows Server 2003 family and later. It is available only with Basic MSI projects.
Windows Installer allows only one instance of a product code to be installed in the same context (same
machine and user context). With the release of Windows XP SP1 and Windows Server 2003 family,
Windows Installer began including support for a product code–changing transform. This type of
transform—called an instance transform—enables the same .msi package to be installed multiple times
in the same context because it changes the product code, product name, and package code. You can
change these properties by adding them to the ISProductConfigurationInstance Table (in the Direct
Editor).
Build Support
Validation
If the build recognizes that the ISProductConfigurationInstance Table contains one or more records, the
build validates the following:
• InstanceId is defined in the Property table and is set to a value that is not duplicated in the
ISInstance table. If not, a warning is displayed.
• InstanceId appears in the component condition for each component with attribute
msidbComponentAttributesRegistryKeyPath or msidbComponentAttributesODBCDataSource. If
not, a warning is displayed.
• This is not an InstallScript MSI package. If the package is InstallScript MSI, an error is triggered.
Instance Packages
The build generates .msi files for each instance. These can be used to create patches. These are stored in
a folder called Instances under the release location.
Instance Transforms
The build generates instance transforms for each instance. The instance transforms are streamed into
the .msi file that is created in the Disk1 folder.
• <release folder>\instances\instance2.msi
• <release folder>\instances\instance3.msi
• and so on...
7. In the Tables explorer, click ISUpgradedImage. There should be one record per instance. The
Family column will have values such as Family1, Family2, Family3. All of the fields in the Family
column should be set to the same value. If you have three instances, all three should be set to
Family1.
8. Build the patch. This creates a single .msp file that is capable of patching all instances of your
application.
For information on the command line to use to apply the patch to a selected instance, see the following
Windows Installer topics:
• Installing Multiple Instances with Instance Transforms
• Command-Line Options
Project: Setup prerequisites can be included in Windows Installer and ClickOnce projects.
Use the Setup Prerequisite Editor in InstallShield to modify the settings for any of the prerequisites that
are included with InstallShield. You can also create custom prerequisites using this tool and then add
them to your projects.
Specifying your own setup prerequisites and modifying existing ones enables you to set options such as
the following:
• The URL from where the prerequisite files should be downloaded to the target machine
• Conditions under which the prerequisite should be installed
• Whether the installation should display a message box that enables end users to choose whether to
install the prerequisite
1. On the Tools menu, click Prerequisite Editor. The Setup Prerequisite Editor opens.
2. Configure the settings on each of the tabs as needed.
3. On the File menu, click Save.
1. On the Tools menu, click Prerequisite Editor. The Setup Prerequisite Editor opens.
2. On the File menu, click Open. The Open dialog box opens.
3. Select the prerequisite file by browsing and click Open.
4. Make changes as needed.
5. On the File menu, click Save.
Note: Every time you open the Setup Prerequisite Editor to create a new prerequisite, a new GUID is generated and
listed in the Unique identifier for setup prerequisite box.
3. In the Description box, type an overview of the setup prerequisite. This description is displayed
under the Overview heading when you select a prerequisite in the Redistributables view.
Tip: If the setup prerequisite should be installed on some—but not all—operating systems, you can create multiple
operating system conditions for the prerequisite. If a target machine meets any one individual operating system condition,
it meets the operating system requirements for that prerequisite.
3. Select the appropriate option for the type of condition and then set the properties for the condition
as needed.
The Setup Prerequisite Editor adds the condition to the Conditions tab.
The prerequisite is installed on the target machine if the target machine meets any of the operating
system conditions and all of the other conditions that are listed on the Conditions tab.
• In the Select the operating system on which to run the setup requirement box, select
the operating system that is required on the target system for the prerequisite.
• In the Select the operating system on which to run the setup requirement box, select
Custom. Then configure the operating system settings as appropriate.
Tip: You can also use the values from an existing predefined operating system condition as the basis for a new
custom condition. To do so: In the Select the operating system on which to run the setup requirement box,
select the appropriate predefined operating system, and then change the setting to Custom. Then you can further
configure the operating system condition by specifying additional values in the Custom area.
5. To specify the minimum service pack of the selected operating system, type the service pack in the
Minimum Service Pack box.
6. Click OK.
The Setup Prerequisite Editor adds the operating system condition to the Conditions tab.
Note: Instead of storing in the .prq file the value that you selected in the Select the operating system on which to run
the setup requirement box, the Setup Prerequisite Editor stores the underlying operating system settings that are
associated with the value that you selected. Therefore, if you select the Custom option but do not change or configure any
settings in the Custom area, the Setup Prerequisite Editor does not set the value of this box to Custom the next time that
you reopen the Prerequisite Condition dialog box for the selected condition. Instead, it sets the value of the box to the
predefined operating system option.
For example, if the URL for the file is http://www.mywebsite.com/Folder1/Notepad.exe, enter the
following in this box:
http://www.mywebsite.com/Folder1
Note: Adding files by using this method does not also set the URL where those files can be downloaded. To set the URL
for multiple files, see Specifying URLs for Downloading Prerequisites.
5. Click OK.
Tip: As an alternative to the above steps, you can also specify the URL for an individual file when you add it to the list of
prerequisite files on the Files to Include tab. See Specifying Files for a Prerequisite for more information.
Note: Selecting this check box does not add the Windows Installer engine and/or the .NET Framework to your
installation. It only specifies that if they are included in the installation, they should be installed before this setup
prerequisite is installed. To include the Windows Installer engine and/or the .NET Framework with your installation, you
must add them to your project.
4. If applicable, in the Specify the command line for the application box, type the command line
for the file selected in the Specify the application you wish to launch list. Do not include the
file name of the .exe in this box.
5. If applicable, in the Specify the command line for the application when the setup is
running in silent mode box, type the appropriate command line. Do not include the file name of
the .exe in this box.
6. If the selected prerequisite application requires that the target machine be restarted after the
application is installed, type the return code in the Specify the return code (in decimal) the
application returns if a reboot is required box.
• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnceEx
• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Session Manager\FileRenameOperations
The registry keys are counted before and after the .exe or .msi is run. If these numbers are not the same,
it is assumed that the file is trying to restart the system and exit the installation.
On Windows 9x platforms, InstallShield also checks the Wininit.ini file and looks at the [rename]
section.
• ERROR_SUCCESS_REBOOT_REQUIRED (3010)
Note: This setting applies to installations that are run on Windows Vista systems. Earlier versions of Windows ignore this
setting.
• The conditions that were specified for the prerequisite were not accurate.
For example, a condition may indicate that the prerequisite needs to be installed if a particular file does
not exist on the target machine. If the file is still missing even after the prerequisite is installed, it is
possible that the condition should not have been created. The Behavior tab of the Setup Prerequisite
Editor lets you indicate how the installation should proceed under these types of circumstances.
Task To specify the behavior for a setup prerequisite that requires the target machine to be restarted:
4. Click OK.
Saving a Prerequisite
Once you have created a new setup prerequisite or modified an existing one using the Setup Prerequisite
Editor in InstallShield, you must save the setup prerequisite (.prq) file.
1. In the Setup prerequisite file box, specify the full path, including the file name and .prq
extension, for the prerequisite file. Setup prerequisite files are stored in the following location:
InstallShield Program Files Folder\SetupPrerequisites
2. Click Save.
Setup prerequisites that are stored in the SetupPrerequisites directory are listed in the Redistributables
view.
Tip: If a new setup prerequisite that you just saved in the Setup Prerequisite Editor is not listed in the Redistributables
view, you may need to refresh the view. To do so, reselect an option in the Object types to display list at the top of the
Redistributables view.
A conditional statement is an expression that the Windows Installer can evaluate as True or False.
Typically, conditional statements are used to perform some action or enable a component’s installation
based on the value or existence of a property.
You can use operators similar to those in Visual Basic for comparative and logical operations. For more
information, see Conditional Statement Syntax.
Note: In the Components, Dialogs, Custom Actions and Sequences, and Custom Actions views of InstallShield, you can
access the Condition Builder dialog box when you click the ellipsis button in the condition property to help you build
conditional statements.
Caution: No validation is made during design time. Use valid syntax and double-check to ensure that your statement
evaluates to the expected outcome.
Examples
The following table provides examples of some conditional statements and explanations of how they can
be used. Consult the Windows Installer Help Library for more information on Windows Installer
properties and conditional expression operators.
Purpose Description
Purpose Description
Functionality
A conditional statement performs some action in an installation—such as launching a custom action or
installing a component—based on whether the expression evaluates to True, which has the numeric
value of 1. False returns have the numeric value of 0. The simplest of expressions, specifying a property
name, is True if the property is defined. For example, the simple conditional statement Version9X
evaluates to True when the installation is running under Windows 95 or Windows 98.
You can build more complex conditional statements using the operators and values described in the
tables below.
Values
The following table describes how to use values in your conditional statements. All values except for
environment variables are case sensitive.
Value Description
"InstallShield"
%TEMP
Operators
The tables below list all of the conditional statement operators by type. Note the following:
• The operators follow the same precedence as those in Visual Basic.
• Use parentheses to override precedence.
• Operators are not case sensitive.
• Unlike in Visual Basic, there are no arithmetic operators.
• Precede the operator with a tilde (~) if you do not want the comparison to be case sensitive.
• The result is always False when you compare a string with an integer, unless you use the <>
operator.
Not Performs logical negation. The result is True if the value is False, and
vice versa.
Eqv The result is True if both values are True or both values are False.
Imp Performs a logical implication. The result is True if the first term is False
or the second is True.
<> The result is True if the first value is not equal to the second.
> The result is True if the first value is greater than the second.
>= The result is True if the first value is greater than or equal to the
second.
< The result is True if the first value is less than the second.
<= The result is True if the first value is less than or equal to the second.
>< The result is True if the first string contains the second.
<< The result is True if the first string starts with the second.
>> The result is True if the first string ends with the second.
>< The result is True if both integers have any bits in common.
<< The result is True if the high 16 bits of the first integer are equal to the
second integer.
>> The result is True if the low 16 bits of the first integer are equal to the
second integer.
InstallScript Projects
In an InstallScript project, you can use the MAINTENANCE system variable to determine whether the
installation is running in maintenance mode or if it is a first-time installation.
Using the MAINTENANCE system variable applies for both InstallScript and InstallScript MSI projects.
The following code sample shows how to use it in your script:
if (!MAINTENANCE) then
// it is a first-time install
endif;
if (MAINTENANCE) then
// ...not first-time
endif;
Note: Property names are case sensitive, so Version9X and Version9x are considered different properties.
InstallShield provides support for the Windows Installer capability of searching for installed data on a
target system at run time. Depending on the results of the search, the installation can store a value in a
property and even use the property in an installation condition. Examples of system searches that your
installation can perform include:
• Search for a file or folder on the target system at run time and store the full path to the file or folder,
if found, in a property. This includes support for XML files.
• Read data from the registry or from an .ini file located in the target system’s WindowsFolder
directory and store the data in a property. Then use the property in an installation condition.
InstallShield includes several predefined system searches that you can add to your project. In addition,
system searches that have been defined in one project and published to a repository can be reused in
other projects. Use the System Search view to add a predefined system search—whether it is a search
that is included with InstallShield or one that is stored in a repository—to your project. You can also use
the System Search view to customize any predefined searches or define your own system searches for
your installation.
4. Select the value for the system search that you would like to add.
5. Click OK.
InstallShield adds the search to the grid in the System Search view. If you need to make changes to the
predefined search after you have added it to your project, see Modifying a System Search to learn how.
Example
This section presents an example that shows how to search for XML data on target systems at run time.
For this example, the product called MyProduct has an executable file called MyProduct.exe. The
path for this .exe file is written to a file called Configuration.xml at run time.
Tip: For information on how to use properties to change XML files at run time, see Using Windows Installer Properties to
Dynamically Modify XML Files.
The value of the path attribute in the above XML code depends on where end users install MyProduct.
The main objective of this example is to find the value of the path attribute and store that value in a
property.
1. In the View List under Behavior and Logic, click System Search.
2. Right-click the grid and then click Add. The System Search Wizard opens.
3. Complete each of the wizard panels as follows:
a. On the What do you want to find? panel: In the list, select XML file value.
b. On the Specify the file details panel:
• In the Look In area, select A full path, and type the following path:
[ProgramFilesFolder]MyCompany\MyProduct
• In the XPath to XML Element box, type the following XPath expression:
/configuration/appSettings/add[@value='MyProduct']
• In the Look For area, select Value of Attribute in this Element, and type the following
in the Attribute Name box:
path
• In the Store the value in this property box, type the following:
PATH_IN_XML_FILE
• In the Additional Options area, select Just store the value in the property.
You can use the value of the search property in another area of your project. For example, to display the
value of the property in a dialog in your installation, add a text control to the dialog, and set the Text
value of the control to something like this:
PATH_IN_XML_FILE = [PATH_IN_XML_FILE]
ISComCatalogAttribute This table contains information about COM+ catalog attributes. Each
entry has a foreign key to a ISComCatalogObject table entry to which
the attribute belongs.
ISComCatalogCollectionObject This table contains information about COM+ catalog collections where
COM+ catalog objects belong.
ISComCatalogObject This table contains information about COM+ catalog objects. A COM+
catalog object is an item that is contained within a COM+ catalog
collection. Each entry has the display name.
ISCustomActionReference This table contains information about the behavior of each of the
custom actions that are included in the installation.
ISDRMFile This table contains information about the file being wrapped for trialware
protection.
ISProductConfigurationInstance This table provides Windows Installer support for installing multiple
instances of products.
ISSelfReg If you have selected ISSelfReg as the self-registration method for COM
servers, and if your project contains any files (or dynamic links) marked
as self-registered, InstallShield adds information about those files to the
ISSelfReg table of your .msi database.
ISAlias Table
If you migrate a project created with InstallShield Professional to InstallShield, InstallShield might add
data to the ISAlias table.
In Windows Installer, identifiers cannot contain spaces and must contain only specified characters.
Because of this, some of your component names, feature names, or script-defined folder names that you
used in InstallShield Professional might not be valid in a project that you upgraded to a Windows
Installer–based project. To address this issue, InstallShield uses aliasing to match the old name with a
new identifier. (InstallShield does not perform a lexicon change for these names because they might be
used as strings within your script.)
Note: If you upgrade to an InstallScript project, the only invalid characters in feature names or script-defined folder names
are the following:
\/:*?"<>|
In component names, the preceding characters and the single quotation mark (') are invalid.
Table Name of the table that uses the alias (for example, Feature). This table
is available in the Direct Editor.
ISCOMCatalogAttribute Table
The ISCOMCatalogAttribute table contains the information about COM+ catalog attributes. Each
entry has a foreign key to a ISComCatalogObject table entry to which the attribute belongs.
Columns
ISCatalogObject_(primary key)
A foreign key into the ISCatalogObject table
ItemValue
A value associated with the attribute defined in ItemName
ISCOMCatalogCollection Table
The ISCOMCatalogCollection table contains information about COM+ catalog collections. A COM+
catalog collection is a folder of a same type of COM+ catalog objects. For example, COM+ application,
Component and Legacy Component nodes in the Component Services view are the COM+ catalog
collections. Each entry has a foreign key to a ISComCatalogObject table entry to which the collection
belongs.
Columns
ISCatalogCollection (primary key)
A unique key for the ISCatalogCollection table.
ISCatalogObject_
A foreign key into the ISCatalogObject table. This is the catalog object that a catalog collection belongs
to.
Name
A catalog collection name.
ISCOMCatalogCollectionObject Table
The ISCOMCatalogCollectionObject table contains information about COM+ catalog collections
where COM+ catalog objects belong.
Columns
ISCatalogCollection_(primary key)
A unique key for the ISCatalogCollection table
ISCatalogObject_(primary key)
A foreign key into the ISCatalogObject table; This is the catalog object that a catalog collection
contains.
ISCOMCatalogObject Table
The ISCOMCatalogObject table contains information about COM+ catalog objects. A COM+ catalog
object is an item that is contained within a COM+ catalog collection. Each entry has the display name.
Columns
ISCatalogObject (primary key)
A unique key for the ISCatalogObject table
DisplayName
The display name of a catalog object
ISCOMPlusApplication Table
The ISCOMPlusApplication table contains information about a COM+ application. A COM+
application is a COM+ catalog object with extra information. This table has application specific
information and a foreign key to an ISComCatalogObject table entry that has the basic information.
Columns
ISCatalogObject_(primary key)
A foreign key into the ISComCatalogObject table. This is the root level application object. All other
data associated with this application can be derived through the ISComCatalogObject table.
ComputerName
If the ComponentService object was loaded from a remote machine, store the computer name here. This
can be NULL for the local computer.
Component_
A foreign key to the component table.
ISCustomActionReference Table
The ISCustomActionReference table contains information about the intended behavior of each
custom action that is included in the project.
Description Text No No Text that describes the behavior of the custom action.
When InstallShield builds a release of a Basic MSI,
InstallScript MSI, or merge module project, it
populates this column with the text in the file that is
referenced in the ISCAReferenceFilePath column.
If you are working on a project in Direct Edit mode,
InstallShield streams the contents of the file into this
column as soon as you select the help file in the
Custom Actions and Sequences view (or the Custom
Actions view).
ISCAReference Text No No The full path, including the file name, for the file that
FilePath describes the behavior of the custom action.
This column is included in the InstallShield project file
(.ism), but not in the .msi file.
ISDRMFile Table
The ISDRMFile table contains information about the file being wrapped for trialware protection. For
more information, seeTrialware Technology.
ISDRMFileAttribute Table
The ISDRMFileAttribute table contains information about a trialware license.
ISDRMLicense Table
The ISDRMLicense table contains information about a trialware license.
ISDRMLicense Identifier Yes No Primary table key that identifies the internal
name of the trialware license.
ISIISMetaData Table
The ISIISMetaData table provides support for the METADATA_RECORD structure, which contains
information about a metabase entry. The METADATA_RECORD structure is used as an input
parameter by the SetData method and as an input/output parameter by methods that retrieve data from
the metabase, such as GetData, EnumData, or GetAllData.
When you configure advanced settings for a Web site or a virtual directory in the Internet Information
Services view, InstallShield configures the ISIISMetaData table automatically. To learn more, see
Configuring Advanced IIS Settings.
ISIISCommon_ Foreign key into the ISIISCommon table, denoting the Web site or
virtual root that this property is for.
Order The order that you would like the properties to be applied to the meta
data.
ISProductConfigurationInstance Table
The ISProductConfigurationInstance table provides support for Windows Installer multiple
instance support. The main properties to add to the ISProductConfigurationInstance table are:
• ProductCode
• ProductName
• PackageCode
• UpgradeCode (optional)
Value Text Yes No Specifies the value for this property for
this instance.
ISSelfReg Table
If you have selected ISSelfReg as the self-registration method for COM servers, and if your project
contains any files (or dynamic links) marked as self-registered, InstallShield adds information about
those files to the ISSelfReg table of your .msi database.
FileKey Foreign key into the File table, identifying the file (.dll, .ocx, .exe, .tlb,
.olb) to be self-registered.
Feature ISReleaseFlags Release Flags that specify whether this feature will
be built in a particular release.
In the Direct Editor, you can undo or accept the difference. Icons in the first column of the Direct Editor
tables indicate whether the row is a deletion, an addition, or if the row contains a change. The
comparison file also displays added or removed columns in a table.
Icon Description
To see the specific change that has been made, move your mouse over a column and a tooltip appears.
On the Tools menu, point to Difference, and then click Compare to File. This command is available
only when a project is open in InstallShield.
4. Enter a new value or modify the existing one in the resulting dialog. The data type required can be
determined from the column heading. For example, S255 indicates a string value with a maximum
length of 255 characters. If the field takes a foreign key into another table, the Direct Editor
provides a list of existing fields from that table.
Note: The Direct Editor performs field-level validation to ensure the proper data type.
To ensure referential integrity when editing tables in the Direct Editor, select the Maintain referential integrity option on
the Preferences tab in the Options dialog.
• Press Ctrl+F.
4. Specify the data you want to find, and the appropriate settings. To search among different tables, the
Search in current table only option must be deselected.
5. Click Find Next or press F3.
Note: To cancel the Find operation, click Cancel in the Find dialog or press the ESC key.
• Press Ctrl+H.
4. Specify the data you want to find and replace, and any appropriate settings.
5. Click Find Next or press F3 to locate the data, and click Replace to replace it. You can replace all
occurrences by clicking Replace All.
Note: You can remove (drop) only user-defined tables. Standard tables cannot be removed.
Windows Installer properties allow you to set project-wide values for use in your project. To add a
property or change an existing one, use Property Manager. All of the built-in installer properties are
outlined in the Windows Installer Property Reference.
Property Types
There are four general types of Windows Installer properties:
• Public
• Private
• Restricted public
• Required
Note: Some of these categories overlap. For example, the ProductCode property is a required private property.
Public Properties
Public properties have names that contain only uppercase letters. For example, INSTALLDIR is a
public property. Public properties can be specified at the command line used to launch the installation
or chosen by using an authored user interface. If you are creating your own properties, use all uppercase
letters if you want end users to have access to these properties.
In order to allow the end user or administrator to change the destination via the user interface or from
the command line, the Directory Identifier for the component’s destination must be a public property.
Note: Only public properties have their values preserved from an installation’s user interface to the point where the
installation is changing the target system. If you set the value of a property in a dialog box displayed to the end user, use
a public property (for example, MY_PUBLIC_PROPERTY) if you want its value written to a file or to the registry.
Private Properties
Private properties have at least one lowercase letter in their name and cannot be changed from the user
interface. For example, ProgramFilesFolder is a private property. End users have no control over the
values of private properties, as they cannot be set from the command line.
Required Properties
The Windows Installer service relies on five properties that are required in every Windows Installer
setup. By default, these properties are included in every installation you create using InstallShield. If you
delete any of the following properties from your project, you need to reinsert them for your installation
to function correctly.
• ProductCode
• ProductLanguage
• Manufacturer
• ProductVersion
• ProductName
Conditions
Many properties are not set until the installation is launched. These properties are populated with
information from the target system. For example, the Version9X property is not set until the setup is
launched. This property is set to the version of Windows that the target machine is running, if the
operating system is Windows 95, Windows 98, or Windows Millennium Edition.
Properties set at run time can be used to create conditional installations. If you want your product to be
installed only on Windows 98, you can use conditional logic to check the end user’s system, and install
the product if all conditions are met.
Note: By default, Windows Installer writes the final value of every Windows Installer property contained in your project to a
log file generated by launching MsiExec with the /L argument. Starting with Windows Installer version 2.0, you can prevent
certain properties (such as those containing passwords) from being written to the log file by creating a property called
MsiHiddenProperties in the Property Manager and setting its value to a semicolon-delimited list of property names. For
more information about this property, see MsiHiddenProperties in the Windows Installer Help Library.
Any of the properties that are with all-uppercase names can be set at the command line. Properties with
all-uppercase names are called public properties. The following lists are organized according to the
functions of the properties. Each table has a brief description of the kinds of properties it contains.
The following categories of Windows Installer properties are described in this topic. Click on a link to go
directly to a category.
• Special Folder Properties
• User-Supplied Information
• Product-Specific Properties
• MDAC Properties
Note: Do not confuse installer properties with path variables, which are surrounded by angle brackets (<>). While they
both represent directories, you can use Windows Installer properties at run time, but path variables are used to point to
source files only during setup design and at build time.
INSTALLDIR This property contains the default destination folder for the files in your
features and components. See Setting the Default Product Destination
Folder (INSTALLDIR) for more information.
INSTALLDIR is available directly as a variable in your InstallScript code.
SETUPEXEDIR This property stores the path to Setup.exe. For example, if the path to
Setup.exe is C:\MySetups\MyApp\Setup.exe, the value of
SETUPEXEDIR is C:\MySetups\MyApp.
SOURCEDIR This property stores the folder where the running .msi file is located.
TARGETDIR The TARGETDIR property is the location where the Windows Installer
package is copied (and its data files uncompressed) during an
Administrative installation.
In an InstallScript MSI project, this value is represented by the
InstallScript MSI_TARGETDIR variable.
ADDLOCAL This property stores a list of features, separated by commas, that are
to be installed locally. Each feature has a Remote Installation property
that determines whether features selected for installation are to be
installed locally or run from the source medium.
ADDSOURCE This property stores a list of features, separated by commas, that are
to be run from the source medium. If this property is set to ALL, all the
features will run from the source medium.
ADVERTISE This property stores a list of features, separated by commas, that are
to be advertised.
REINSTALL This property stores a list of features, separated by commas, that are
to be reinstalled. If REINSTALL is set to ALL, all of the features that are
already installed on the user’s system will be reinstalled.
REINSTALLMODE This property contains a string of letters that specify the reinstall type.
These options correspond to the values available for the Msiexec.exe /
f command-line parameter. For more information on this property, see
REINSTALLMODE Property in the Windows Installer Help Library.
REINSTALLMODE is always set in conjunction with REINSTALL.
ReinstallModeText This property contains the reinstallation options that will be set when the
user selects Repair in the MaintenanceType dialog. The value of
ReinstallModeText is passed as an argument to the control event
ReinstallMode, which accepts the same options that are available for the
REINSTALLMODE property.
ReinstallModeText is not a predefined Windows Installer property.
Nonetheless, it is provided in the Property Manager for every new
project, with a default value of omus, for use in the control event
described above.
REMOVE This property stores a list of features, separated by commas, that will
be removed. If REMOVE is set to ALL, all features will be removed.
PATCH When installing a patch, this property contains the full path to the patch
package.
ARPAUTHORIZEDCDFPREFIX This property stores the URL for the update channel of the application.
ARPCOMMENTS This property contains the comments about this product that are
displayed in the Add/Remove Programs applet of the Control Panel.
This value is set in the Add/Remove Programs Comments property. You
should provide a string table entry to facilitate globalizing your setup.
ARPINSTALLLOCATION This property stores the fully qualified path to the application’s primary
folder. You can set ARPINSTALLLOCATION to the value of
INSTALLDIR with a custom action of type “Set a property”.
ARPREADME Holds the fully qualified path or the URL for the product’s Readme file.
This value is set in the Add/Remove Programs Read Me property. You
should provide a string table entry to facilitate globalizing your setup.
ARPSIZE This property stores the estimated size, in kilobytes, of the application.
ARPSYSTEMCOMPONENT Set this property to 1 to keep your program from appearing in the user’s
Add/Remove Programs panel.
ARPURLINFOABOUT This property stores the URL for the application’s home page or the
publisher’s home page.
This value is set in the Add/Remove Programs Publisher/Product URL
property. You should provide a string table entry to facilitate globalizing
your setup.
ARPURLUPDATEINFO This property stores the URL for update information on your application.
This value is set in the Add/Remove Programs Read Me property. You
should provide a string table entry to facilitate globalizing your setup.
ARPNOREMOVE Setting this property disables the Add/Remove Programs and Programs
Wizard functionality that allows the product to be removed.
AVAILABLEFREEREG This property allows you to set the amount of additional free registry
space, in kilobytes, required by your application.
CCP_DRIVE This property holds the root path on the installation disk for any of the
qualifying products for a competitive upgrade.
DISABLEMEDIA This setting prevents the installer from adding media information to the
source list.
DISABLEROLLBACK Set this property to 1 to stop the installer from creating a rollback script
that will save copies of changed or deleted files during the installation
process.
EXECUTEACTION This property sets the top-level action initiated by the ExecuteAction
action.
EXECUTEMODE This property sets the mode of execution performed by the installer.
The value None means that no changes are made to the system. The
default value, Script, means that all changes made to the system are
run through a script execution.
INSTALLLEVEL This property holds a value that corresponds to the values of the
features. If the level of features to be installed is less than or equal to
the INSTALLLEVEL property, then a feature is installed. This is primarily
used for different setup types, such as Typical or Custom.
Privileged This property will run an installation with elevated privileges if the user is
an administrator or if the application is an administrator-assigned
application.
PROMPTROLLBACKCOST This property specifies what will happen if there is insufficient disk
space to continue the installation. Depending on the user interface level,
the rollback could happen automatically, without any input from the user,
or it could ask the user to continue with rollback disabled.
PRIMARYFOLDER The folder that you specify with this property will be the “primary” folder
for the installation. The path to this folder will be used to determine the
values for the PrimaryVolumePath property, the
PrimaryVolumeSpaceAvailable property, the
PrimaryVolumeSpaceRequired property, and the
PrimaryVolumeSpaceRemaining property.
REBOOT This property allows you to force or suppress a reboot after the
installation completes. Possible values are:
• F—To force a reboot when your installation is complete.
• S—To suppress any reboot except one caused by the ForceReboot
action.
• R—To suppress any reboot caused by Windows Installer actions.
ROOTDRIVE In Administration mode this property sets the default drive to the first
writable network drive found. In all other modes, this property sets the
default drive to the writable local drive with the most disk space
available.
SCRIPTFILE This property defines the location of the script file that contains all
operations executed during the installation.
SEQUENCE This property specifies an .msi database table that lists the order in
which the actions in the table will run.
SHORTFILENAMES In Administration mode, this property may be set to ensure that only
short file names are used.
TRANSFORMSATSOURCE By setting this property to 1, you are specifying the installer to look for
the transforms at the installation source.
LIMITUI Setting this property limits the user interface level at basic. This is
useful if you do not create a custom user interface to interact with the
installer’s built-in UI.
DefaultUIFont This property should be set to one of the predefined styles found in the
TextStyle table in order to specify your default font. If this property is not
set, the installer will use the system font, which may disrupt your
formatting.
User-Supplied Information
The following section contains information about input taken from the end user. Such input can include
the end user’s name, company, or language.
COMPANYNAME This property stores the organization name for the end user performing
the installation. This information is taken from the Customer
Information dialog box (for Basic MSI projects), or from the
SdCustomerInformation or SdCustomerInformationEx dialogs (for
InstallScript MSI projects).
UserLanguageID This property retains the default language identifier for the end user.
USERNAME This property stores the name of the end user performing the
installation, which is taken from the Customer Information dialog (for
Basic MSI projects), or from the SdCustomerInformation or
SdCustomerInformationEx dialogs (for InstallScript MSI projects).
ProductLanguage This property stores the numeric language ID for the product.
Product-Specific Properties
Information on product-specific properties that can be set in the Property table is listed below.
Examples of these types of properties include technical support numbers, product name, and serial
number.
ARPHELPLINK This property retains the Internet address for technical support.
This value is set in the Add/Remove Programs Support URL property.
You should provide a string table entry to facilitate globalizing your
setup.
ProductCode The ProductCode is the GUID for this particular version of the product.
This ID must be different for different language versions and different
release versions. This property is set in the General Information view
under Product Properties.
ProductState The installer sets this property to the installed state of the product. This
property can hold one of four numeric values:
-1—The product has not been installed or advertised.
1—The product has been advertised, but not installed.
2—The product has been installed for another user.
5—The product has been installed and is available to the current user.
ProductVersion The ProductVersion property stores the major, minor, and build
version numbers in the format AA.BB.CCCC. This property is set in the
General Information view under Product Properties.
DiskSerial The DiskSerial property should be set to the internal serial number for
this release.
ComponentDownload This property retains the URL for downloading a product by its string
identifier (GUID).
LeftUnit This property places units to the left of the number. This is necessary
for languages that require this structure.
UpgradeCode This is a GUID used to search for a related set of products that are
already installed.
IsAdminPackage This property is set to 1 if the current installation package was created
through an administrative installation. You can use this property to
detect post-administrative installations.
AppDataFolder This property holds the full path to the current user’s Application Data
folder.
CommonAppDataFolder This property holds the full path to the All Users Application Data folder.
CommonFilesFolder The value of this property is the full path to the 32-bit Common Files
folder.
CommonFiles64Folder The value of this property is the full path to the 64-bit Common Files
folder. This property requires Windows Installer version 2.0.
DesktopFolder This property is used to hold the full path to the Desktop folder for the
current user. If the setup is being run under Windows NT or Windows
2000 or later for All Users, and the ALLUSERS property is set, then the
DesktopFolder property should hold the full path to the All Users
desktop folder.
FavoritesFolder The FavoritesFolder property retains the full path to the Favorites
folder for the current user.
FontsFolder This property holds the full path to the Fonts folder.
PersonalFolder This property holds the full path to the current user’s Personal folder.
ProgramFilesFolder This property holds the full path to the current user’s Program Files
folder.
ProgramFiles64Folder This property holds the full path to the current user’s 64-bit Program
Files folder. This property requires Windows Installer version 2.0.
ProgramMenuFolder This property is used to hold the full path to the Program menu for the
current user. If the setup is being run under Windows NT or Windows
2000 or later for All Users, and the ALLUSERS property is set, then the
ProgramMenuFolder property should hold the full path to the All Users
Programs menu.
SendToFolder This property holds the full path to the current user’s SendTo folder.
StartMenuFolder This property is used to hold the full path to the Start menu folder for
the current user. If the setup is being run under Windows NT or Windows
2000 or later for All Users, and the ALLUSERS property is set, then the
StartMenuFolder property should hold the full path to the All Users
Start Menu folder.
StartupFolder This property is used to hold the full path to the Startup folder for the
current user. If the setup is being run under Windows NT or Windows
2000 or later for All Users, and the ALLUSERS property is set, then the
StartupFolder property should hold the full path to the All Users
Startup menu.
SystemFolder This property holds the full path to the 32-bit System folder.
System64Folder This property holds the full path to the 64-bit System folder. This
property requires Windows Installer version 2.0.
TempFolder This property holds the full path to the Temp folder.
TemplateFolder This property holds the full path to the current user’s Template folder.
WindowsFolder This property holds the full path to the user’s Windows folder.
AdminUser This property is set by the installer at installation and is only set on
Windows NT or Windows 2000 or later if the user has administrative
privileges. AdminUser is always set on Windows 9x.
ComputerName This property stores the name of the computer that the installation is
running on. It is set by a call to the Windows API GetComputerName at
the initialization of the installer.
LogonUser This property stores the name of the user performing the installation. It
is set by a call to the Windows API GetUserName.
OLEAdvtSupport This property is set by the installer during initialization if the target
system supports install-on-demand through COM (supported by
Windows 2000 and later).
ServicePackLevel If an operating system service pack is installed, this property stores the
numeric value for that update.
SharedWindows This property is set when Shared Windows is being used on the target
system.
ShellAdvtSupport This property is set by the installer during initialization if the target
system supports feature advertisement. This property is automatically
set on Windows 98 or later, or on earlier systems if Internet Explorer
4.01 is installed.
SystemLanguageID This property stores the default language identifier for the target
system. The value is defined by the installer by calling
GetSystemDefaultLangID at initialization.
TerminalServer This property is set by the installer at initialization if the target system is
a server with Windows Terminal Server.
TTCSupport This property is set by the installer at initialization if the target system
supports true type font collections (TTC). The following systems support
TTC: Windows 2000 or later, JPN - 932, Taiwan - 950, China - 936,
Korea - 949, Hong Kong - 950.
VersionDatabase This property stores a version number of the database used during the
installation.
WindowsBuild This property stores the build number for the operating system being
run.
MsiNTProductType This property stores the type of NT operating system being run on the
target machine. This property requires Windows Installer version 2.0.
MsiNTSuiteDataCenter On Windows 2000 and later, this property is set to 1 if Windows 2000
Datacenter Server is installed. In all other cases this property is not set.
This property requires Windows Installer version 2.0.
MsiNTSuiteEnterprise On Windows 2000 and later, this property is set to 1 if Windows 2000
Advanced Server is installed. In all other cases this property is not set.
This property requires Windows Installer version 2.0.
MsiNTSuiteEnterprise On Windows 2000 and later, this property is set to 1 if Windows 2000
Advanced Server is installed. In all other cases this property is not set.
This property requires Windows Installer version 2.0.
MsiNTSuiteSmallBusiness On Windows 2000 and later, this property is set to 1 if Microsoft Small
Business Server is installed. In all other cases this property is not set.
This property requires Windows Installer version 2.0.
MsiNTSuiteSmallBusinessRestricted On Windows 2000 and later, this property is set to 1 if Microsoft Small
Business Server is installed with the restrictive client license. In all other
cases this property is not set. This property requires Windows Installer
version 2.0.
MsiNTSuitePersonal On Windows 2000 and later, this property is set to 1 if the operating
system is Workstation Personal. In all other cases this property is not
set. This property requires Windows Installer version 2.0.
MsiNetAssemblySupport This property is set if the operating system supports .NET Framework
assemblies. In all other cases this property is not set. This property
requires Windows Installer version 2.0.
MsiWin32AssemblySupport This property is set if the operating system supports Win32 assemblies.
In all other cases this property is not set. This property requires
Windows Installer version 2.0.
Alpha This property stores the numeric value of the processor level, and it is
only defined if the setup is running on an Alpha processor. (This property
is supported only with Windows Installer version 1.0.)
BorderSide This property sets the pixel width of the side window borders.
BorderTop This property sets the pixel width of the top window border.
CaptionHeight This property sets the pixel height of the caption area.
ColorBits This property stores the number of adjacent color bits for each pixel
(that is, the color depth of the user’s monitor). For example, if the user’s
monitor is using 256 colors, ColorBits is set to 8.
Intel This property stores the numeric value of the processor level, and it is
defined only if the setup is running on an Intel 32-bit processor.
Intel64 This property stores the numeric value of the processor level, and it is
defined only if the setup is running on an Intel 64-bit processor. This
property requires Windows Installer version 2.0.
VirtualMemory The amount of available page file space, in megabytes, is stored in this
property.
AFTERREBOOT This property is set to 1 by the installer after a reboot triggered by the
ForceReboot action.
CostingComplete This property is set to 1 as soon as costing has begun and is set to 0
when costing is complete.
OutOfDiskSpace This property is set to True if any of the drives that are targets for the
install do not have enough disk space. Otherwise, it is set to False.
OutOfNoRbDiskSpace This property is set to True if any disk targeted during an installation
does not have enough free disk space and if rollback capability is turned
off. It is set to False if all of the target disks have sufficient space.
Preselected This property determines if features have been preselected, and if so,
does not display the selection dialog.
PrimaryVolumePath The installer sets this property to the path specified in the
PRIMARYFOLDER property.
PrimaryVolumeSpaceAvailable This installer sets this property to a string representing the total number
of bytes, in units of 512, available on the volume specified by the
PRIMARYFOLDER property.
PrimaryVolumeSpaceRequired This property stores a string representing the total amount of disk
space required, in bytes (expressed in units of 512 bytes), by the
currently selected features.
PrimaryVolumeSpaceRemaining The installer sets this property to a string representing the number of
remaining bytes available on the system, in units of 512, if all selected
features were to be installed.
Resume This property stores the text string displayed to the user when an
installation is resumed from a suspended setup.
UpdateStarted This property is set once changes to the system have taken place as a
result of the installation process.
ReplacedInUseFiles This property is set if a file that is currently in use is overwritten. Custom
actions that check to see if a reboot is required will use this property.
NOUSERNAME Setting this property to 1 stops the installer from setting the
USERNAME property. By default, this property is not set and the
USERNAME property is set from the registry.
NOCOMPANYNAME Setting this property to 1 stops the installer from setting the
COMPANYNAME property. By default, this property is not set and the
COMPANYNAME property is set from the registry.
STANDARD_USE_SETUPEXE
MDAC Properties
These properties apply to version checking for MDAC.
ISINSTALL_MDAC_BYVERSION Create and set this property to Yes if you want InstallShield to perform
default version checking.
ISINSTALL_MDAC_SKIP Create and set this property in the Project Manager if you are
performing your own version checking and do not want InstallShield to
install MDAC.
SETUPEXEDIR
SETUPEXEDIR is a property that contains the path to Setup.exe. For example, if the path to Setup.exe
is C:\MySetups\MyApp\Setup.exe, the value of SETUPEXEDIR is C:\MySetups\MyApp.
Using SETUPEXEDIR
SETUPEXEDIR is an alternative to the directory identifier SourceDir. A potential problem with using
SourceDir is that it points to the location of the running MSI package. In the case of a compressed setup,
the MSI package is streamed to a temporary location and run from there. Because of this, SourceDir’s
value will be some temporary location on the end user’s machine, which might not be the value you
want.
Limitations of SETUPEXEDIR
There are two limitations to using SETUPEXEDIR:
• SETUPEXEDIR is set by Setup.exe. If the end user runs the MSI package directly,
SETUPEXEDIR is not set. To account for this, you could have a dual implementation in your
setup—one that uses SETUPEXEDIR and one that uses SourceDir. You could test for the existence
of SETUPEXEDIR and, if it does not exist, you could conditionally use your SourceDir
implementation.
• SETUPEXEDIR might not be set on uninstall. If the end user triggers the uninstallation by
running Setup.exe, SETUPEXEDIR is set. If they run the uninstallation from the Add/Remove
Programs applet, SETUPEXEDIR is not set.
Note: In an uncompressed setup, SourceDir and SETUPEXEDIR have the same value.
Creating Properties
You can create your own project-wide properties through the Property Manager. These properties allow
you to set a value in one place and use it throughout your setup project.
Note: If you want to create a property that can be changed at the command line, use all capital letters in the property’s
name. For example, INSTALLDIR is a property that can be set or changed from the command line.
Windows Logo Guideline: The Property Manager does not provide any validation on the information that you enter into
these fields. For example, if you change the value of the ARPHELPLINK property to MyCompany instead of http://
www.mycompany.com, the link fails when a user clicks on it. No error message is displayed at build time. To ensure that
you have the correct information and syntax for that information, see the Windows Installer Property Reference.
Clearing Properties
You can clear a property’s value without deleting the property from the Property Manager. This
functionality works for localizable and non-localizable properties. For example, you might want to clear
a string-table enabled property like ARPCOMMENTS.
Note: Clearing a property makes the property non-localizable because it does not have a string ID.
Restricted public properties allow network administrators to define public properties that can be
changed only by a system administrator or by someone who has elevated privileges. This way, the
administrator can change settings quickly without having to worry that unauthorized users on the
network may tamper with the installation.
Windows Installer considers a number of public properties to be restricted public properties. For the full
list of restricted public properties, see Restricted Public Properties in the Windows Installer Help
Library.
To include additional public properties, add them to the SecureCustomProperties property.
If you perform tasks such as the following ones through InstallShield user interface, InstallShield
automatically adds the applicable property to the SecureCustomProperties property:
• When you use a public property in a system search, InstallShield adds the public property to the
SecureCustomProperties property.
• When you add or import a dialog to a Basic MSI or Merge Module project, and the dialog contains a
control that is set through a property, InstallShield adds that property to the
SecureCustomProperties property.
• When you add a major upgrade item to your project, InstallShield adds the value of the Detect
Property setting on the Advanced tab for that upgrade item to the SecureCustomProperties
property.
This enables the custom public properties to be set in the user interface sequence and then passed to the
execute sequence.
Task To manually specify that a custom public property should be a restricted property:
1. In the View List under Behavior and Logic, click Property Manager.
2. In the Name column, find the SecureCustomProperties property.
If this property is not listed, double-click the last row to create this property, and in the Name
column, enter SecureCustomProperties.
3. In the Value column, enter the public properties that you would like to restrict. Separate multiple
entries with a semicolon (;).
The MsiGetProperty and MsiSetProperty functions get and set Windows Installer properties. For an
example, see Getting and Setting Properties.
You must include the statement #include "iswi.h" or #include "ifx.h" in order for the Windows
Installer APIs to be available to your script.
The MSI Database and MSM Database project types allow you to edit Windows Installer installation
databases and merge module databases directly, rather than working through an intermediate project
format (.ism file). These project types extend the Direct Editor functionality to include different views
that are supported in standard installation projects. The views that are supported in these project types
are intended to function as they do for an .ism project.
Project: There is no string table or path variable support in an MSI Database or MSM Database project.
You can directly edit an existing .msi file or .msm file, or directly create a new database by opening a new
MSI Database or MSM Database project. The data in this file should match what you would get if you
created a blank MSI project and built a database from that project.
Note: Some functionality may be limited when editing an MSI package in Direct Edit Mode.
1. Click the Open Project button on the toolbar. A browse dialog opens.
2. Select Windows Installer Packages (*.msi) from the Files of Type list.
3. Select the MSI package that you want to open.
4. Ensure that the Open as field is set to Auto, and click Open.
The Open MSI/MSM Wizard can convert an existing Windows installer (.msi) package to an
InstallShield project (.ism) file, and open the new project to modify in InstallShield.
Note: You can also open Patch Creation Project files (.pcp files) in InstallShield and edit them in the Direct Editor.
Note: In Direct Edit Mode, file and media tables are updated during the save process.
When a file is added, a record is created with a default sequence value. No Media table entry is made at
this time. When the media or project is saved, the sequence for the newly added files is updated to
correctly reflect the media, and media entries are created in the Media table.
Once you add, configure, and merge the merge modules, any files included in the merged modules will
be copied to the source media upon saving your project.
An important aspect of InstallShield is how it coexists and integrates with other software development
tools such as Visual Studio as well as source code control software that complies with the Microsoft
Source Control Interface.
Consult the help topics in this section for specific details on the extent of external application support in
InstallShield.
Note: When a project file format is converted to either XML or binary format, the project file extension remains .ism.
Note: The .isv file format has been deprecated to version 2.x of InstallShield for Windows Installer and versions of
InstallShield Developer prior to 8.x.
Task A typical scenario for using InstallShield’s source code control integration is outlined below:
Tip: You can streamline this process by having InstallShield automatically add new projects to source control or check out
edited projects. For more information, see the Source Control tab of the Tools | Options dialog.
When you add a file to source control, most programs make the local copy read only. If this is the case
with your source control program, you need to check out the project file before making any changes.
Note: The project is not automatically checked in to source control when you close the project in the IDE. Check your
project in (from the IDE) before closing it.
Task Follow the steps below to check a project into your source control program through the InstallShield IDE:
Note: The project is not automatically checked into source control when you close the project in the IDE. Check your
project in (from the IDE) before closing it.
Task To break the link between the project on your local machine and the one in your source control application:
On the Project menu, select Source Control, and point to Unlink from Source Control.
Integration Features
InstallShield is fully integrated within the Visual Studio shell. Some of the unique features of the
integration include:
• All InstallShield navigation is presented within the Solution Explorer.
• Each InstallShield view is presented in a separate window so no scrolling is necessary and side-by-
side viewing options are available.
• You can run InstallShield external to Visual Studio.
• InstallShield dynamically links your installation project to other Visual Studio project outputs,
automatically updating your installation with your latest source files every time your product is
built.
• Items identified by the InstallShield debugger can be moved directly into the Visual Studio task list.
Integration Benefits
Some additional benefits of using InstallShield’s integrated installation authoring solution are:
• You can create and customize your installation without leaving the Visual Studio user interface,
enabling use of familiar navigation and layout options.
• Your installation is automatically updated with your latest source files every time your solution is
built, always staying current.
• The installation reflects the Build Configuration for the solution, e.g., Debug, Release, automatically
included source files from the proper build directory.
• .NET properties and dependencies can be scanned and included in an installation automatically.
1. On the File menu, point to New, and click Project. The New Project dialog box opens.
2. In the project types list, select InstallShield 2008 Projects.
3. Select a template.
4. Enter a name and location for the new project.
5. Click OK when you are finished.
Basic MSI A Basic MSI project uses Windows Installer to provide the
user interface for the installation. When you choose this
project type, you need to create features and components,
and specify all application files and other distributable
data.
Merge Module Select this option to create your own merge modules. You
Project need to create any components and file associations.
Smart Device Setup The Smart Device Setup Wizard guides you through the
Project process of creating installations for smart devices.
InstallScript Object Using the InstallScript Object project, you can create an
Project InstallShield merge module that uses InstallScript. This
type of merge module, however, can be consumed only by
InstallShield.
Web Project The Web project type is essentially the same as the Basic
MSI project type, with the addition of IISROOTFOLDER
support. The IISROOTFOLDER directory variable is used
to find the root directory of the Web server on a target
system.
MSM Database Select MSM Database to edit your merge module in Direct
Edit mode. This means that you can directly edit the
Windows Installer tables within InstallShield to configure
your merge module.
1. On the File menu, point to Open, and choose Project to display the Open Project dialog.
2. Browse to the InstallShield file you want to open, and select it.
3. Click Open.
Note: From within Microsoft Visual Studio, you can open only .ism files created with InstallShield X or later, InstallShield
DevStudio, InstallShield Developer, InstallShield—Windows Installer Edition, or InstallShield Express, version 3.x or later.
Files created in InstallShield Professional or pre-3.x versions of InstallShield Express cannot be opened.
1. The Visual Studio Solution node in the Source computer’s folders pane contains sub-nodes
for all projects contained in the current solution. Click a project to display the output groups for the
project. The output groups are displayed in the Source computer’s files pane.
2. To add a reference to an output to your installation project, drag and drop the output to the target
folder in the Destination computer’s folders pane.
Note: To view a reference for a project, right-click the project and select Resolve Project Output. The Outputs dialog is
displayed to show what files the output group resolves to.
• Press CTRL+ALT+X.
2. Click the InstallShield Dialogs tab, if it is not already expanded.
Adding Controls
Note: InstallShield Layout and MSI Debugger toolbar commands are not available as individual toolbar buttons.
Building a Release
Option Description
Build Setup Name Build only the setup project, according to the
release specified in the Project Configuration
column of the Configuration Manager.
1. Select Configuration Manager from the Build menu or select Configuration Manager from
the Solution Configurations drop-down menu in the toolbar.
2. Select a configuration from the Active Solution Configuration menu and then select the
appropriate project configurations to map to the selected solution configuration.
Note: If the Build check box is deselected and you build the solution, the deselected project configuration is not built.
Right-click the tree node for your InstallShield project in the Solution Explorer and select Uninstall.
Task The recommended way to add a .NET assembly to your installation project is as follows:
1. In the Setup Design view, create a component to hold the .NET assembly.
2. (Windows Installer based projects only) Make the file the key file of a component by right-clicking
on the file and selecting Set Key File from the context menu.
3. Set the project to scan for dependencies by doing one of the following:
• Set the .NET Scan at Build component property to Dependencies and Properties. In this
case, the .NET assembly’s Manifest, Application, and related entries are not populated in your
project file. Instead, they are added to the .msi file at build time.
• Run the Static Scanning Wizard. In this case, the .NET assembly’s values are added during the
scan. You can edit these values in the Assembly node under the component’s Advanced
Settings.
InstallShield enables you to automate build processes through the automation interface without having
to directly open the InstallShield interface and making changes in different views. Using the automation
interface is an alternative to that.
By calling methods, setting properties, accessing collections, and so on, through the automation
interface, you can open a project and modify its features and component data in many of the same ways
that you would in the InstallShield interface. In addition, you can build a release using the Build method
of the InstallShield automation interface.
Read more about the automation interface as well as other aspects of automating build processes in this
section of the help library.
LinkToFeature.vbs
The script in the LinkToFeature.vbs file is designed to read the associated Links.ini file and add the files
from the specified folders and subfolders to the specified features. It organizes them into components
based on the model you construct in Template.ini. To start the script, pass it the path to your setup
project and the path to Links.ini, respectively, at the command line:
LinkToFeature.vbs "C:\MySetups\Malaprop.ism" "C:\Automation Interface\Links.ini"
You can examine some of the relevant sections of LinkToFeature.vbs to see exactly how it works. After
opening the .ism file specified at the command line, the script creates a collection of every feature in the
project starting at line 53. This collection is later used to make sure that the features listed in Links.ini
are present in the project.
' The scripting dictionary is defined in Scrrun.dll
Dim pFeatCol
Set pFeatCol = CreateObject("Scripting.Dictionary")
Next, LinkToFeature.vbs opens Links.ini using the InstallShield IniReader. As the comment on line 70
explains, you can use this utility if it serves your needs or otherwise substitute your own. Once Links.ini
is open, the rest of the script is controlled by the For loop beginning at line 80 and ending at line 202:
For Each pLinksSection In LinksIniFile.Sections
The purpose of this loop is to read each section in Links.ini. Each section contains the name of a feature
that you want to add the new components to and the folder where the files and subfolders can be found.
After getting each key’s value, there is a nested For loop, stretching from line 102 to 201, which loops
through every feature in the collection pFeatCol and compares it to the name of the feature in Links.ini:
For Each ISWIFeature In pFeatCol
' See if the feature in Links.ini matches one in the setup project.
If (ISWIFeature.Name = linksFeature) Then
Since this loop is used for almost the remainder of the script, you can assume that everything that is
done acts on the current feature. Next, it checks if the Action key in this Links.ini section is set to Delete
and deletes all of the feature’s components if so:
If (linksAction = "Delete") Then
For Each ISWIComponent In ISWIFeature.ISWiComponents
ISWIProject.DeleteComponent ISWIComponent
Next
End If
At line 27, the script creates a collection of the specified folder and each subfolder:
Set pFolders = CreateObject("Scripting.Dictionary")
pFolders.Add folder, folder.Path
GetSubFolders pFolders, folder
From line 136 to 163, the script opens the Template.ini file that contains the template for all of the
components that will be added to the current feature:
LinkToFeature.vbs does its real work in the For loop that begins on line 169 and ends on 199:
' Create a component for the root folder and all of its subfolders.
For Each folder In pFolders
Based on the description in Template.ini, it forms the component’s name, adds it to the project,
associates it with the current feature, sets the component’s properties, and then adds the files in the
current folder to the component.
Finally, the .vbs file saves and closes the setup project.
Links.ini
Each section of this .ini file contains the following keys, which LinkToFeature.vbs reads to determine
which folders and subfolders to add to each feature in your project:
Key Description
Template.ini
Each section in Template.ini contains information for creating all of the components that will be
associated with a feature. Each section in Links.ini must point to a specific component template file and
section. The template file and sections are described below:
Section Description
Section Description
if(Wscript.Arguments(3)="E")then
StringsExport ISWIProject,Wscript.Arguments(1),Wscript.Arguments(2)
elseif(Wscript.Arguments(3)="I")then
StringsImport ISWIProject,Wscript.Arguments(1),Wscript.Arguments(2)
end if
'/////////////////////////////////////////////////////////////////////////////
' Export the string table
Sub StringsExport(byref p,byval path, byval language)
p.ExportStrings path, Date , language
Wscript.Echo "Exported String table for language " & language & " to " & path
End Sub
'/////////////////////////////////////////////////////////////////////////////
' Import the string table
Sub StringsImport(byref p,byval path, byval language)
p.ImportStrings path, language
Wscript.Echo "Imported String table for language " & language & " from " & path
End Sub
'/////////////////////////////////////////////////////////////////////////////
Sub CheckError()
Dim message, errRec
If Err = 0 Then Exit Sub
message = Err.Source & " " & Hex(Err) & ": " & Err.Description
Wscript.Echo message
Wscript.Quit 2
End Sub
'END ImportExportStrings.vbs
Requirements
The following requirements should be met:
• You must have Windows Scripting Host to run a .vbs file. (It would be very simple to modify this
script to run in a Visual Basic program.)
• InstallShield must be installed on the system before you can use the automation interface.
• Before running the script, assign the fully qualified path of an existing setup project (.ism file) to the
string variable sProj.
Example Script
Option Explicit
' Open a setup project--make sure it is not already open in the IDE
Dim sProj
sProj = "C:\MySetups\TestProject.ism"
pProj.OpenProject sProj
' Start building string that lists features, components, and files
Dim sItems
sItems = "Project Report" & vbNewLine
sItems = sItems & "For project: " & sProj & vbNewLine
sItems = sItems & "Number of features: " & pProj.ISWiFeatures.Count & vbNewLine
sItems = sItems & "Number of components: " & pProj.ISWiComponents.Count & vbNewLine
' Declare and initialize counters for files and file types
Dim i, nEXE, nDLL, nOCX
i = 0
nEXE = 0: nDLL = 0: nOCX = 0
' Loop through components to get the number of files and individual file names
Dim sFileName
Dim pComp, pFile
For Each pComp In pProj.ISWiComponents
For Each pFile In pComp.ISWiFiles
i = i + 1
sFileName = pFile.DisplayName
If Instr (1, sFileName, ".exe", vbTextCompare) > 0 Then
nEXE = nEXE + 1
ElseIf Instr (1, sFileName, ".dll", vbTextCompare) > 0 Then
nDLL = nDLL + 1
ElseIf Instr (1, sFileName, ".ocx", vbTextCompare) > 0 Then
nOCX = nOCX + 1
End If
Next
Next
Note: With earlier versions of InstallShield products, you were required to convert the source control (.isv) files to
InstallShield project (.ism) files, and then back to .isv files. However, with the latest versions of InstallShield products, this
is no longer necessary because you can save .ism files as text files for your source control application.
Section Description
Menu, Toolbar, and Window Describes the various components of the InstallShield user
Reference interface, including menus, toolbars, and windows.
Dialog Box Reference Contains reference information on each of the dialog boxes that
are displayed in InstallShield.
Wizard Reference Provides details about each of the wizards that are available in
InstallShield.
View Reference Describes each of the views that are displayed in InstallShield.
Setup Prerequisite Editor Introduces you to the Setup Prerequisite Editor, which is
Reference available with InstallShield. Use this tool to create custom setup
prerequisites that you can include in your projects.
Errors and Warnings Provides information about error codes and warnings that might
occur when you create, compile, build, or run your installation.
This section also includes reference information about errors
and warnings that may occur when you migrate a project from
an earlier version of an InstallShield product to the latest
version.
InstallShield Custom Action Explains each of the custom actions that are available in
Reference InstallShield.
Section Description
Command-Line Tools Introduces tools that you can use from the command line to
perform tasks such as building a release and running an
installation.
InstallScript Language Provides in-depth information about functions, data types, event
Reference handlers, operators, and other aspects of InstallScript, a simple
but powerful programming language that you can use to design
your installations. This section also contains sample code that
you can use in your script file.
This section describes the various components of the InstallShield user interface, including menus,
toolbars, and windows.
Menus
The menus in InstallShield are located on the menu bar, which is at the top of the InstallShield user
interface. Each menu contains a list of commands. Some of these commands have icons next to them so
that you can quickly associate the command with the icon.
Each of the menus in InstallShield is described in this section:
• File
• Edit
• View
• Go
• Project
• Build
• Tools
• Window
• Help
File Menu
The following table lists the File menu commands, as well as associated keyboard shortcuts and icons.
Edit Menu
The following table lists the Edit menu commands, as well as associated keyboard shortcuts and icons.
Redo Ctrl+Y Reverses the last action that was performed with
the Undo command.
View Menu
The following table lists the View menu commands, as well as associated keyboard shortcuts and icons.
Go Menu
The following table lists the Go menu commands, as well as associated keyboard shortcuts and icons.
Some of the view-related commands are not available from the Go menu, depending on which project
type you have open in InstallShield.
Previous View ALT+UP ARROW Takes you to the view directly above the
current view as shown in the View List.
Next View ALT+DOWN ARROW Takes you to the view directly below the
current view as shown in the View List.
Back ALT+LEFT ARROW Takes you to the view that you last visited in
the history of your view selections. You can
use this multiple times, as long as there are
multiple entries in your view history.
Forward ALT+RIGHT ARROW Takes you to the next view in the history of
your view selections. You can continue until
you reach the view you were at when you
first clicked Back.
Project Menu
The following table lists the Project menu commands, as well as associated icons.
Visual Basic 6.0 Wizard Opens the Visual Basic 6.0 Wizard.
Export Components Opens the Export Components Wizard, which simplifies the
Wizard process of exporting a component from a file to a new or
existing project.
Device Driver Wizard Opens the Device Driver Wizard, which guides you through
the process of adding a device driver to your installation.
Reg-Free COM Wizard Opens the Reg-Free COM Wizard, which guides you through
the process of adding a COM manifest file to your project or
configuring an existing manifest file.
Perform Static Scan Opens the Static Scanning Wizard, which scans the files
already added to your project for any dependencies that they
require.
Perform Dynamic Scan Opens the Dynamic Scanning Wizard, which monitors a
running executable for all .dll and .ocx dependencies files
and automatically adds them to your project.
Convert Source Paths Opens the Convert Source Paths Wizard, which lets you
convert existing hard-coded paths with path variables,
thereby enhancing the portability of your installation project.
Build Menu
The following table lists the Build menu commands, as well as associated keyboard shortcuts and icons.
Release Opens the Release Wizard, which lets you specify the
Wizard settings for a release and build it.
Build F7 Builds your release with default settings, or—if you have
already built your release—rebuilds your release with
your most recently saved settings.
Build Tables SHIFT+F7 Rebuilds only the .msi file tables of your installation to
Only enable you to see your changes take effect more quickly
than with a complete rebuild.
Build Tables ALT+F7 Rebuilds only the .msi file tables and updates only the
& Refresh modified files of your installation. This type of build works
Files only when the media is an uncompressed network image.
This command is available for Windows Installer–based
projects only.
Refresh Build ALT+F7 Rebuilds the active media. This command regenerates
only those items that you changed since the media was
last built. This command is available for InstallScript
projects only.
Test Ctrl+T Enables you to run through the user interface portion of
your installation without making any changes to your
system. All custom actions are executed.
Run from Displays the One-Click Install Web page, which lets you
Web run your completed installation without leaving
InstallShield.
Settings ALT+F6 Opens the Settings dialog box, which enables you to set
preferences for how InstallShield builds your installation.
Tools Menu
The following table lists the Tools menu commands, as well as associated icons.
Open Release Folder Launches Windows Explorer, open in the DISK1 folder of the
current release. If there is no release or if a release has not
been built, Windows Explorer opens to your default project
location.
Add New Language Opens the New Language Wizard, which enables you to add
support for almost any language to one or more projects.
Create/Apply Opens the Transform Wizard, which walks you through the
Transform steps of creating and applying transforms for your installation
projects.
MSI Log Analyzer Launches the InstallShield MSI Log Analyzer, which enables
you to generate easy-to-use reports based on Windows
Installer log files.
Check for Updates Checks for service packs and other updates to InstallShield.
If updates are available, you can select which ones you would
like to download and install.
Prerequisite Editor Opens the Setup Prerequisite Editor, which enables you to
create or modify prerequisites that you can include in your
installation project.
Convert ClickOnce to Opens the Convert ClickOnce to DIM Wizard, which enables
DIM you to convert Microsoft’s ClickOnce manifest file to the
Developer Installation Manifest (.dim) format and a Basic MSI
project.
Options Displays the Options dialog box, which enables you to specify
preferences for creating projects and working in InstallShield.
Window Menu
The following table lists the Window menu commands, as well as associated keyboard shortcuts and
icons.
Next Ctrl+Tab Opens the InstallScript view and displays the next
script file in your project as shown at the bottom of the
Window menu.
Previous Ctrl+Shift+Tab Opens the InstallScript view and displays the next
script file in your project as shown at the bottom of the
Window menu.
Help Menu
The following table lists the Help menu commands, as well as associated icons.
About InstallShield Displays the About InstallShield dialog box, where you can
find version information and register InstallShield.
Toolbars
The InstallShield user interface offers several toolbars that give you quick access to frequently used
menu items and provide graphical tools for use in the Dialog Editor.
Built-in Toolbars
The following toolbars are available in the InstallShield interface. When you open InstallShield, only the
Standard toolbar is displayed near the top of the user interface. The Control and Dialog Layout toolbars
open when you work in the Dialogs view and disappear when you leave that view.
All toolbars can be resized and repositioned, and docked and undocked.
• Standard Toolbar
• Control Toolbar
Standard Toolbar
Below is a description of all the buttons in the Standard toolbar.
New Project Launches the New Project dialog box, which enables you to select
a project type and begin a new project.
Undo Click the Undo button in the Dialog Editor or the Script Editor to
reverse the last change you made.
Redo Click the Redo button in the Dialog Editor or the Script Editor to
restore the last action you reversed by clicking the Undo button.
Viewbar Hides or shows the viewbar, which appears on the left side of the
interface.
View List Hides or shows the View List, which shows all the views available
in the InstallShield interface.
Note: You can also press F4 to hide or show the View List.
Previous View Displays the view directly above the current view, as shown in the
View List.
Next View Displays the view directly below the current view, as shown in the
View List.
Back Displays the view that you last visited in the history of your view
selections. You can click this button multiple times, if there are
multiple entries in your view history.
Forward Displays the next view in the history of your view selections. You
can continue clicking this button until you reach the view in which
you first clicked the Back button.
Insert InstallScript Launches the Function Wizard, which eases the process of writing
Function built-in InstallScript functions.
Release Wizard Launches the Release Wizard, which turns a project into either a
shippable Windows Installer setup package or completed merge
module. The options you select in the wizard determine the layout
and contents of your release.
Compile Compiles the InstallScript files in your project without building the
entire setup.
Build Builds your release with default settings, or—if you have already
built your release—rebuilds your release with your most recently
saved settings.
Test User Runs through the user interface portion of your installation project
Interface without making any changes to your system. All custom actions
are executed.
Open Release Launches Windows Explorer, open in the DISK1 folder of the
Folder current release. If there is no release or if a release has not been
built, Windows Explorer opens to your default project location.
Help View Displays the IDE Help view where you can find answers to many of
your questions regarding InstallShield.
Control Toolbar
The Control toolbar provides every standard control available in a Windows Installer dialog. This
toolbar is displayed when you edit a dialog’s layout in the Dialog Editor.
Click the control’s button, click anywhere on the face of the dialog, drag the mouse pointer while
continuing to press the mouse button, and then release the button when you have reached the intended
dimensions of the control.
Select Tool Allows you to give focus to a control on a dialog. You can then
move, resize, delete, or align the control.
Check Box Allows you to draw a Check Box control on the dialog.
Push Button Allows you to draw a Push Button control on the dialog.
Edit Field Allows you to draw an Edit Field control on the dialog.
Combo Box Allows you to draw a Combo Box control on the dialog.
Text Area Allows you to draw a Text Area control on the dialog.
List Box Allows you to draw a List Box control on the dialog.
Radio Button Allows you to draw a Radio Button control on the dialog. A radio
button must be added to a radio button group, below.
Group Box Allows you to draw a Group Box control on the dialog.
Radio Button Allows you to draw a Radio Button Group control on the dialog.
Group
Selection Tree Allows you to draw a Selection Tree control on the dialog.
Progress Bar Allows you to draw a Progress Bar control on the dialog.
List View Allows you to draw a List View control on the dialog.
Scrollable Text Allows you to draw a Scrollable Text control on the dialog.
Directory List Allows you to draw a Directory List control on the dialog.
Directory Combo Allows you to draw a Directory Combo control on the dialog.
Volume Cost List Allows you to draw a Volume Cost List control on the dialog.
Volume Select Allows you to draw a Volume Select Combo control on the dialog.
Combo
Masked Edit Allows you to draw a Masked Edit control on the dialog.
Path Edit Allows you to draw a Path Edit control on the dialog.
Align Left Select two or more controls and click the Align Left button to align
all of the selected controls with the left edge of the leftmost control.
Align Right Select two or more controls and click the Align Right button to align
all of the selected controls with the right edge of the rightmost
control.
Align Top Select two or more controls and click the Align Top button to align
all of the selected controls with the top edge of the uppermost
control.
Align Bottom Select two or more controls and click the Align Bottom button to
align all of the selected controls with the bottom edge of the
lowermost control.
Center Vertical Select a control and click the Center Vertical button to reposition the
element in the vertical (x-axis) center of the dialog.
Center Select a control and click the Center Horizontal button to reposition
Horizontal the element in the horizontal (y-axis) center of the dialog.
Space Across Select three or more controls on the dialog and click the Space
Across button to have them evenly distributed horizontally across
the dialog.
Space Down Select three or more controls on the dialog and click the Space
Down button to have them evenly distributed vertically along the
dialog.
Make Same Select two or more controls and click the Make Same Width button
Width to resize the width of the smaller controls to the width of the largest
control.
Make Same Select two or more controls and click the Make Same Height button
Height to resize the height of the smaller controls to the height of the
largest control.
Make Same Size Select two or more controls and click the Make Same Size button to
make the smaller controls the exact size of the largest control.
Bring to Front Select a control and click the Bring to Front button to place it on top
of any overlapping controls. See note below.
Send to Back Select a control and click the Send to Back button to place it behind
any overlapping controls. See note below.
Show Grid Click the Show Grid button to place design-time grid lines on the
dialog, or to remove the grid if it is present.
Note: The Bring to Front and Send to Back actions are not saved when you close and reopen your project. These actions
are for use during design only. For example, you might have a dialog that displays different controls based on a condition.
You can use the Bring to Front and Send to Back actions to work on these different controls while you are designing your
dialog.
MSI Debugging Click this button to start debugging or, while debugging, to
continue stepping through the setup.
Step Over Click this button to step over the current action or dialog.
Step Into Click this button to step into the current action and launch
your registered debugger.
Remove All Breakpoints Click this button to clear all breakpoints you have set in the
MSI Debugger.
Output Window
The Output window opens across the bottom of the InstallShield user interface when you build your
project. It also provides information about your project during validation and project conversion. The
following tabs appear in the Output window:
Tab Description
Build Stores distribution output information and displays build output; a link to the
output file saved as a text file is included.
Compile Displays InstallScript information when you click Compile on the Build
menu.
Tasks Provides descriptions of error and warning codes when you build, compile,
or validate your project; each error or warning code is a link to a
Knowledge Base article.
Tip: You can right-click a code for an error or warning and select Direct
Editor. The affected area associated with the error or warning will be
highlighted in the Direct Editor.
Each of the dialog boxes available in the user interface of InstallShield is described in this section:
• .NET Installer Class Arguments Dialog Box
Note: Install custom actions are run when the component containing the Installer class custom action is installed. Uninstall
custom actions are run when the component containing the Installer class custom action is uninstalled. These two types
are run in the Execute sequence, right after StartServices and before RegisterUser.
Using Arguments
For all methods, /LogFile= is the default argument. This results in no log being generated when these
methods are run. You can complete this argument by using Windows Installer properties in [brackets].
To add arguments, type in the appropriate edit field or use the Add Argument button.
Syntax Rules
When you click OK, InstallShield validates what is in the edit fields and displays a warning if the syntax
is incorrect. The syntax rules include the following:
• All quotes must be matched.
• Escape characters are valid. If you use \" in your argument, it is not counted it when checking the
quote matching.
• Every space-separated argument token must consist of a name preceded by a slash and followed by
an equal sign (=). A value to the right of the equal sign is optional.
• Spaces inside quotes do not count when determining what is and is not part of an argument token.
For example, in the argument /arg=“hi there”, “hi there” is all part of the argument token beginning
with /arg. In the argument /arg=hi there, there is its own argument token and an invalid one.
Dialog Options
Argument Name
Provide a name for the argument in the edit field.
Argument Value
Select one of the values from the option button list to create an argument. To create a custom argument,
select the Custom option.
Property
Select a property from the menu to reference a property that exists in your installation project.
Directory
Use the drop-down menu to add a reference to a directory that exists in your installation project.
Custom
Properties
Property Description
This dialog box lets you specify the name and attributes of a new property and automatically paste
corresponding code into your script. This dialog box opens when you right-click the InstallScript view’s
Properties folder and select Add New Property.
Property Name
This is the global name of this property. Therefore, when trying to read from or write to this property
from script, you will need to use this name. The name you enter in this field will be appended to the local
variable name property.
Data Type
Select String, Data, or Boolean, depending on the type of data your property requires. The local variable
name will change depending on the selection you make here.
Access Method
Select whether you would like this property to be read-only, write-only, or read/write.
Array
Select this check box if your property is an array.
Note: If you plan on using the InstallShield stock wizard for your object’s design-time interface, you cannot use array
properties. You can create a custom wizard that will accept array properties or you can redesign the property without
using an array.
Default Value
Enter the starting value for your property. Be sure to match the value to the data type you chose. When
specifying a string value, type it exactly as you would in the script; enclose the string value in quotation
marks and use the appropriate escape sequences for special characters (for example, enter a backslash
as \\). Do not enter a string table identifier or a system variable in an object project; the initialization of
the property’s value is performed when the object is added to a project, at which time string table
identifiers and system variables are not yet initialized.
Dialog Options
Comments
Enter the comments describing the file. These comments are stored in your source control program.
Convert to XML
This option causes the .ism file to use the XML representation, which is better suited for source control.
If you add a project in Binary format to source control, this option is available and is selected by default.
It is recommended that you leave this option selected.
Note: When a project file format is converted to either XML or binary format, the project file extension remains *.ism.
Setting Description
Executable Type the path, or click Browse to launch the Select Executable
dialog box. This enables you to specify the executable in your
project to which you want to map. Type the name of the executable
file (.exe or .dll) or use the Browse button to search for the file. The
executable file must be located on your Web server’s local hard
drive.
Extension Type the file name extension associated with your application (for
example, .abc) or an asterisk (*).
Verbs The Verbs section enables you to specify which HTTP verbs should
be passed to the application.
• All verbs—Select this option to include all verbs. This option
passes all requests to an application.
• Limit to—Select this option to specify the HTTP verbs that
should be passed to an application. Separate verbs with a
comma.
Setting Description
Script Engine (IIS 6 and If you want the application to run in a directory without Execute
earlier only) permissions, select this check box. This setting is intended
primarily for script-based applications, such as ASP and IDC, that
are mapped to an interpreter.
For a script-mapped application to run, either the Scripts Only or
Scripts and Executables option must be selected for the Execute
Permissions property. To allow only script-mapped applications to
run, select the Scripts Only option. To allow both script-mapped
applications and executable files (.exe and .dll) to run, select
Scripts and Executables.
This setting applies to IIS 6 and earlier. IIS 7 ignores this setting.
Check that file exists (IIS To instruct the Web server to verify the existence of the requested
6 and earlier only) script file and to ensure that the requesting user has access
permission for that script file, select this check box.
If the script does not exist or the end user does not have
permission, the appropriate warning message is returned to the
browser and the script engine is not invoked. This option can be
useful for scripts mapped to non-CGI executable files like the Perl
interpreter that do not send a CGI response if the script is not
accessible.
Note: If an asterisk (*) appears in the Verbs column, all verbs will be used for the specified extension.
Setting Description
Add To add an entry for mapping a file name extension and the program
or interpreter that processes those files, click this button. This
opens the Application Extension Mapping dialog box.
Session timeout (minutes) Specify the number of minutes that a session can remain idle
before the server terminates it automatically. If the end user does
not refresh or request a page within the timeout period, the session
ends. The default value is 20 minutes.
ASP Script timeout Specify the length of time in seconds that .asp pages will allow a
(seconds) script to run before terminating and writing an event to the Windows
Event Log. The minimum value for this property is 1 second and the
default value is 90 seconds.
Dialog Options
Tree Control
Select the releases that you would like to build by checking the appropriate boxes. Selecting a product
configuration icon selects all the releases associated with that product configuration.
Select All
Click this button to select all the releases in the tree.
Unselect All
Click this button to deselect all the releases in the tree.
Build
Click this button to build all the selected releases.
Dialog Options
Destination Directories
This field lists all of the currently available destination directories. You can select, create, rename, or
delete directories in this field.
Selecting a Directory
1. Select a directory or the Destination Computer and press the Insert key, or right-click and select
New from the context menu. This creates a directory beneath the selected folder or beneath the
Destination Computer.
2. Type the directory name.
3. Provide a directory identifier, if necessary.
Renaming a Directory
1. Select a directory or the Destination Computer and press F2, or right-click and select Rename from
the context menu.
2. Type the new directory name. Note that you cannot rename predefined directories.
3. Rename the directory identifier, if necessary, to be consistent with the directory’s new name.
Deleting a Directory
Select a directory and press the Delete key, or right-click and select Delete from the context menu.
Note: When you delete a directory, any subdirectories beneath the selected directory are also deleted.
Directory Identifier
You can use the Directory Identifier field to provide a user-friendly name for a directory. For
example, if you have a directory—ProgramFilesFolder\MyProgram\Graphics\Jpg—you can use just JPG to
identify the directory path. The Component Destination field in the IDE displays the path as {JPG}
[ProgramFilesFolder]MyProgram\Graphics\Jpg.
Note: The directory identifier must be a valid Windows Installer identifier. For features, the directory identifier must contain
all capital letters.
Panel Options
Destination Directories
This field lists all of the currently available destination directories. You can select, create, rename, or
delete directories in this field.
Selecting a Directory
1. Select a directory or the Destination Computer and press the Insert key, or right-click and select
New from the context menu. This creates a directory beneath the selected folder or beneath the
Destination Computer.
2. Type the directory name.
3. Provide a directory identifier, if necessary.
Renaming a Directory
1. Select a directory or the Destination Computer and press F2, or right-click and select Rename from
the context menu.
2. Type the new directory name. Note that you cannot rename predefined directories.
3. Rename the directory identifier, if necessary, to be consistent with the directory’s new name.
Deleting a Directory
Select a directory and press the Delete key, or right-click and select Delete from the context menu.
Note that you cannot delete predefined directories.
Note: When you delete a directory, any subdirectories beneath the selected directory are also deleted.
First create two folders — "C:" and "Winnt." Then enter "Notepad.exe" in the filename field of the
Browse for Directory dialog or select the root node, and enter "C:\Winnt\Notepad.exe" in the
filename field.
Directory Identifier
You can use the Directory Identifier field to provide a user-friendly name for a directory. For
example, if you have a directory—ProgramFilesFolder\MyProgram\Graphics\Jpg—you can use just JPG to
identify the directory path. The Component Destination field in the InstallShield interface displays
the path as {JPG} [ProgramFilesFolder]MyProgram\Graphics\Jpg.
Note: The directory identifier must be a valid MSI identifier. For features, the directory identifier must contain all capital
letters.
You can enter the file name in the File name edit box, which means that you are entering the selected
directory\filename as the target of the shortcut.
Setting Description
Select files to sign This box is displayed if you click the Files button next to the Include
patterns and files box on the Signing tab.
This box lists all of the statically included files in your project that
match the file types that are selected in the Show files of type list. It
also lists some default file patterns, such as *.dll.
Select the check boxes for the files and file patterns that correspond
with the types of files in your project that you want InstallShield to sign
at build time.
Select files to skip This box is displayed if you click the Files button next to the Exclude
signing patterns and files box on the Signing tab.
This box lists all of the statically included files in your project that
match the file types that are selected in the Show files of type list. It
also lists some default file patterns, such as *.dll.
If you want to prevent certain files or file patterns from being signed by
InstallShield at build time, select the check boxes for the appropriate
files and file patterns.
Show files of type Use this list to filter the types of files that are displayed in the Select
files to sign box or the Select files to skip signing box.
Windows Logo Guideline: All executable files (including .exe, .dll, .ocx, .sys, .cpl, .drv, and .scr files) in an installation must
be digitally signed for the Certified for Windows Vista program.
When you click OK on this dialog box, InstallShield adds the appropriate files and file patterns to the
Include patterns and files box or the Exclude patterns and files box on the Signing tab.
Note that the files and file patterns that should not be signed override any files and file patterns that
should be signed. For example, if you specify *.exe in the Include patterns and files box and in the
Exclude patterns and files box, InstallShield does not sign any .exe files.
Dialog Options
Comments
Enter comments describing the changes you have made to the file. These comments are stored in your
source control program.
Differences
Click the Differences button to view a line-by-line comparison between the .ism file (in text format)
being checked in and the previous version.
Option Description
• General Tab
• Features Tab
General Tab
The General tab on the Component Properties dialog box is where you set the properties for the selected
component.
Shared
Select this check box if the files contained within this component are shared files.
Never Overwrite
Select this check box if you do not want to replace an existing version of the same file that is already
present on the target machine.
Permanent
Select this check box if the files in this component should not be removed from the system during
uninstallation. For example, validation rule ICE09 requires any component with a destination of
[SystemFolder] to be marked as Permanent.
64-Bit
Select this check box if the files in this component are 64-bit files.
Select this check box to instruct the build process to extract the COM information each time you build a
release. If your COM interfaces are subject to change, this option is preferable to maintaining statically
acquired or provided data in the COM Registration advanced setting.
If you have marked the component’s COM server file as Self-Registering, you should not select this
option.
Modify
Click this button to change the settings of the currently selected dynamic link. You can access the
dynamic link’s settings through the Dynamic File Link Settings dialog box.
Delete
Click this button to remove the currently selected dynamic link.
Features Tab
The Features tab on the Component Properties dialog box is where you specify the features with which
the component is associated. Select the check box next to the feature or features with which you want the
component to be associated.
Dialog Options
Condition(s)
A component, dialog, or custom action can have only one condition. The Condition(s) window allows
you to type the condition you would like to use. In addition, this window displays the conditional logic
selected from the Properties and Operators lists.
Caution: No validation is made during design time. Use valid syntax and double-check to ensure that your statement
evaluates to the expected outcome. For more information, see Conditional Statement Syntax.
Properties
This control lists all of the properties stored in the Property Manager. Select the property you want to
evaluate and click Add to have it appear in the Condition(s) window.
Operators
This control lists all the valid operators recognized by the Windows Installer service. Select an operator
and click Add to append the operator to your conditional statement in the Condition(s) window.
This dialog box is displayed when you select the Project menu’s Convert to InstallScript Project
command.
If you click Yes, most project elements are converted, many with no change. The following changes take
place (the conversion process issues many messages to let you know what is happening):
• INSTALLDIR is changed to TARGETDIR in the following IDE elements:
• Component destinations
• Path specifications in the Files and Folders view
• Target specifications in the Shortcuts view
Note that the value of TARGETDIR must be set in your script, as it is in the following default
code in the OnFirstUIBefore event handler function:
if ( ALLUSERS ) then
TARGETDIR = PROGRAMFILES ^ IFX_COMPANY_NAME ^ IFX_PRODUCT_NAME;
else
TARGETDIR = FOLDER_APPDATA ^ IFX_COMPANY_NAME ^ IFX_PRODUCT_NAME;
endif;
• A registry set is created for each component that had registry data associated with it.
• Each component with multiple dynamic file links is split into multiple components with one
dynamic file link in each.
• The script file Setup.rul is renamed OldSetup.rul and is displayed in the InstallScript view. Note that
no changes are made to this script file.
• Warnings are issued for the following unsupported items:
• Unsupported folder specifiers in path specifications in the Files and Folders view, or
destinations or target specifications in the Shortcuts view
• Win32 assemblies that are associated with components
• Global assembly caches that are associated with components
• Registry value names that contain a hyphen (-) or asterisk (*)
• Advertised shortcuts
• Folders under the Support Files view’s Disk1 folder
• Merge modules (you can re-include these in the converted project from the Objects view)
• Unsupported MSI tables that contain data
Releases and your scripts are not converted. At a minimum, you need to modify your scripts to set
TARGETDIR, as mentioned above, change all INSTALLDIR references to TARGETDIR, and remove
calls to Windows Installer API functions (whose names begin with Msi). Furthermore, the obsolete
string entry PRODUCT_NAME is not converted; IFX_PRODUCT_NAME can be used instead.
Note that setting SHELL_OBJECT_FOLDER in OnFirstUIBefore is not necessary and the default script
line SHELL_OBJECT_FOLDER = @PRODUCT_NAME; should be deleted.
The following Windows Installer folder specifiers are not supported in InstallScript projects:
• ALLUSERSPROFILE
• AdminToolsFolder
• AppDataFolder
• CommonAppDataFolder
• CommonFiles64Folder
• FavoritesFolder
• FontsFolder
• GlobalAssemblyCache
• LocalAppDataFolder
• MyPicturesFolder
• PersonalFolder
• PrimaryVolumePath
• ProgramFiles64Folder
• SendToFolder
• System16Folder
• System64Folder
• TempFolder
• TemplateFolder
• USERPROFILE
• WindowsVolume
In addition, the following folder specifiers are not supported for shortcut destinations:
• ProgramFilesFolder
• CommonFilesFolder
• WindowsFolder
• SystemFolder
Dialog Options
New component name
InstallShield provides a default name for the component. Type a meaningful name into this field. The
name you provide is for your reference only and is never displayed to end users.
Select from the list the feature or features with which you want to associate the new component. If no
features appear in this field, you can add one by clicking New Feature. You are not required to associate
your new component with a feature; however, if you do not, this component will not be installed.
New Feature
Click New Feature to add a feature to your setup project. When you have created a feature, you can
associate your new component with it by clicking the box next to the feature name.
Dialog Options
New feature name
InstallShield creates a default feature name for you. Provide a meaningful name for the feature. The
name you enter here is for your reference only and is never displayed to end users.
Error Number
Enter the SQL error number for which you want to customize error handling.
Behavior
Override the default behavior by choosing one of the following options:
• On Error, Abort Installation
Project Wide
To apply the customized error handling to all scripts in your project, select Yes. To apply it to only this
script, select No.
Note: Deleting the property may affect other areas of your setup.
Select Yes if you are certain that your project will not be affected in the absence of that property. Select
No if you are uncertain whether it will affect your installation.
Note: This is enabled only for key files and when the .NET Scan at Build property is set to Dependencies and Properties.
If the dependency or one of its dependencies cannot be located, a red icon is displayed.
Note: Any new dependencies detected at build time—for files added after closing the Dependencies dialog box—are
added to the build.
Adding Folders
1. Click the folder under which you want to add a new folder.
2. Click New Folder. A new folder is created directly beneath the existing folder.
3. Type a name for the new folder.
You can also add a new folder by right-clicking an existing folder and selecting New Folder.
Renaming Folders
Removing Folders
Select the folder and click Delete. As an alternative, you can right-click the folder and select Delete.
Note: Some folders are predefined by the Windows Mobile operating system and cannot be renamed or removed. Only
user-defined folders can be renamed or removed.
General Tab
The General tab on the Device Files dialog box is where you specify general settings for the mobile device
file.
Setting Description
File The full path and file name of the original file on the desktop
computer that is to be built into the installation package.
Destination folder The path to the folder on the Windows Mobile device or smart device
into which the file should be installed. When you first add a file to your
project, the destination path that is used as the default is the one
selected on the Destination Folder panel of the Windows Mobile
Wizard or the Smart Device Setup Wizard.
To change the destination, click the Browse button next to the
Destination folder box. The Destination Folder dialog box opens.
Shared file Select this check box if the file is a shared .dll file or system file. If
you select this check box, a reference count is maintained on the file
so that it is removed only when all applications that depend on it have
been uninstalled.
Self-register Select this check box if the file is a self-registering .dll file or ActiveX
control that exports the DllRegisterServer and DllUnregisterServer
Component Object Model (COM) functions.
Setting Description
Copy options These options regulate the terms under which the files are installed
onto the Windows Mobile device or smart device. Select one of the
following options:
• Always copy file to target—The source file is always copied
onto the device. If a file by the same name already exists, it is
overwritten. This is the default behavior.
• Always update older file on target—If a file by the same
name already exists on the device, it is overwritten only if the
source file has a more recent date. If no file by the same name
already exists, the source file always is installed.
• Copy only if file exists on target—The source file is installed
only if a file by the same name already exists on the device. The
original file is overwritten. No date check is performed.
• Copy only if file does not exist on target—The source file is
copied onto the device only if there is not already a file by the
same name on the device.
Warn user if file is not This check box is used in combination with the Allow user to skip file
copied on error check box. If you select both of these check boxes and an
error occurs during installation, the end user can skip the file and
continue after a warning message is displayed. If you clear this check
box, no warning message is displayed.
Allow user to skip file on If you select this check box and an error occurs while the file is being
error installed to the Windows Mobile device or smart device, the end user
is asked if they want to skip the file and proceed with the installation.
If you clear this check box, the user is not allowed to skip the file, and
installation aborts.
Processor/Platform Tab
The Processor/Platform tab on the Device Files dialog box enables you to specify platform and processor
options for the included file.
Note: Smart devices do not support the .NET Compact Framework. Therefore, the Processor/Platform tab is available for
Windows Mobile device files. It is not available for smart device files.
Table 38-7: Platform and Processor Settings for the Included File
Setting Description
Banner Image
Browse to a graphic file that will run across the top of interior dialogs. Interior dialogs, which appear
between the first and last installation dialogs, include the LicenseAgreement and CustomSetup dialogs.
The banner .bmp graphic should be 499 by 58 pixels.
Note: If you are building a release on a Windows 2000 machine, SP4 must be installed in order for you to digitally sign the
application.
Setting Description
Digitally sign setup Select this check box to digitally sign your installation.
The other settings on this dialog box are enabled when you select
this check box.
Digital certificate file Specify the location of your digital certificate file (.spc or .pfx)
(SPC or PFX) provided by a certification authority. You can type the path to the file
or use the Browse button to navigate to the file location.
If you specify an .spc file, you must also specify a .pvk file.
Private key file (PVK) If you are using an .spc file, you must also specify the location of
your private key file (.pvk) provided by a certification authority. You
can type the path to the file or use the Browse button to navigate to
the file location.
Setting Description
Certificate password If you would like to pass the password for the .pvk file or the .pfx file
to ISCmdBld.exe to digitally sign your application while building the
release from the command line, type the password in this box.
InstallShield encrypts this password and stores it in your project
(.ism) file.
If you do not specify a password in this box but you are digitally
signing the release while building it from the command line, you will
need to manually enter the password when you are prompted each
time that you build the release from the command line.
Tip: The Signing tab in the Installation Designer lets you specify which portions of your installation should be digitally
signed at build time. InstallShield enables you to sign any and all of the following files in a release, depending on what type
of project you are using:
• Windows Installer package (.msi file) for Basic MSI, InstallScript MSI, Merge Module and Web projects
• Setup.exe file for Basic MSI, InstallScript MSI, and Web projects
• Media header file for InstallScript projects
• Package (self-extracting single-executable file) for InstallScript projects
• Any files in your release, including your application files
To learn more, see Digitally Signing a Release and Its Files at Build Time.
Windows Logo Guideline: All executable files (including .exe, .dll, .ocx, .sys, .cpl, .drv, and .scr files) in an installation must
be digitally signed for the Certified for Windows Vista program.
Source Folder
Enter the full path to the folder that you want to have dynamically linked, or click the Browse button to
navigate to it. You can identify the source folder with any of these methods:
• Enter an absolute path to the folder, such as C:\Build\MySourceFolder\Bitmaps.
• Enter a path variable. Follow the path variable with a backslash to specify a subfolder—for example,
<CommonFilesFolder>\InstallShield\IScript.
Include subfolders
Select this check box to dynamically link the files in each subfolder to a new component. For a full
description of the behavior of this option, see Dynamically Linking to Subfolders.
Option Description
Value name Specifies the name of the value being modified. This is a read-
only property. To rename the value, use the Registry Information
panel.
Value data The binary data that should be stored in the registry value.
Overwrite existing value If a registry value by the same name already exists on the
device, it is overwritten only if this check box is selected. If this
check box is cleared, the existing value is not changed.
Platform A list of platform types (Palm-size PC, Handheld PC, Pocket PC,
Smartphone, etc.) on which the registry value can be created.
Dialog Options
Value name
The name of the registry value as it appears in the Destination computer’s registry data pane. To change
the value name, right-click on the value and select Rename.
Value data
Contains the information that should be stored in the registry value. To change or edit the data, type in
the edit field.
Option Description
Value name Specifies the name of the value being modified. This is a read-only
property. To rename the value, use the Registry Information panel.
Value data The DWORD data that should be stored in the registry value.
Overwrite existing value If a registry value by the same name already exists on the device, it
is overwritten only if this check box is selected. If this check box is
cleared, the existing value is not changed.
Platform A list of platform types (Palm-size PC, Handheld PC, Pocket PC,
Smartphone, etc.) on which the registry value can be created.
Processor The type of processor on which the registry value can be created.
If you change the default value for any advanced property, InstallShield adds the property, the value that
you specify, and the additional required information to the ISIISMetaData table.
Setting Description
Property Name This read-only setting shows the property that you selected to configure on the
Advanced tab.
Value Specify the value that you want to use for the selected IIS property.
Dialog Options
Value Name
The value name is read-only in this dialog box.
Value Data
Enter the data for this registry value as you would like it to appear on the target machine.
Tip: To write the value of a Windows Installer property called PropertyName to the registry, use the expression
“[PropertyName]” in the value data.
Option Description
Value name Specifies the name of the value being modified. This is a read-only
property. If you want to rename the value, you can do so from the Registry
Information panel.
Value data The text that should be stored in the registry value.
Note: When you are working with string registry values, note the following:
• To use a percent sign in an entry, type two percent signs (%%)—for
example, SomeApp.exe %%1 instead of SomeApp.exe %1.
• To use a comma (,) in an entry, enclose the entry within quotation
marks ("")—for example, "1,2,3" instead of 1,2,3.
• To use quotation marks in an entry, enclose the entry within quotation
marks—for example, ""This is quoted."" instead of "This is quoted."
• To create an entry that specifies where the application was installed on
the Windows Mobile device, include %InstallDir%. To create an entry
that specifies a file in the installation directory, include %InstallDir%
with the file name—for example, type %InstallDir%\File.exe. The default
installation directory is specified on the Destination Folder panel.
Overwrite existing If a registry value by the same name already exists on the device, it is
value overwritten only if this option is selected. If this check box is cleared, the
existing value is not changed.
Platform A list of the platform types (Palm-size PC, Handheld PC, Pocket PC,
Smartphone, etc.) on which the registry value can be created.
Processor The type of processor on which the registry value can be created.
Dialog Options
Option Description
Output Directory Specify the directory where the tables are to be exported. You
can also click Browse to navigate to the directory.
Dialog Options
Condition(s)
A feature can have as many conditions as required. The Condition(s) window allows you to type in a
condition. In addition, this window displays the conditional logic selected from the Properties and
Operators drop-down lists.
To learn how to add a new condition, see Conditionally Installing Features.
Caution: No validation is made during design time. Use valid syntax and double-check to ensure that your statement
evaluates to the expected outcome. For more information, see Conditional Statement Syntax.
Properties
This control lists all the properties stored in the Property Manager. Select the property you would like to
evaluate and click Add to have it appear in the Condition(s) window.
Operators
This control lists all the valid operators recognized by the Windows Installer service. Select an operator
and click Add to append it to your conditional statement in the Condition(s) window.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The Lock Permissions table is used to secure individual portions of an application in a locked down
environment. It can be used with the installation of files, registry keys, and created folders.
Access the Lock Permissions table by clicking the Permissions button in a particular folder’s or file’s
Properties dialog. You can also access the Permissions option via the context menu of any registry key or
by clicking the browse button in the Destination Permissions field from a Component’s grid.
Note: Because permissions require NTFS partition, they work only on Windows NT, 2000, or XP systems.
Names
From the Names grid, you can enter any combination of Domain and User names.
Note: To add an entry, right-click on the grid and select New. You can modify or delete entries using the same context
menu.
You can enter [%USERDOMAIN] in the Domain field to represent the current user’s domain, and
[LogonUser] (or any other property name in square brackets) in the User field to represent the user
running the installation.
Permissions
In this section, select the permissions that you want to set for the file or folder. These permissions are
the same ones that appear in the Windows OS when setting permissions. Once you make a selection, you
can click Advanced to specify other permissions associated with the high level one that you initially
select.
For more information about lock permissions, see LockPermissions Table in the Windows Installer Help
Library.
Option Description
Extension The file name extension used by the document type. When the
user opens a file with this extension, the application associated
with it is automatically launched to view it. The extension is not
case-sensitive, and it does not need to begin with a leading period
(.).
Icon index This property specifies the zero-based index of an icon within the
executable. The icon is displayed when the user views a
document file in Windows Explorer. By default, this property is set
to zero (0) to display the first icon within the executable file.
Setting Description
Minimum Version The search is successful if the file exists on the target system
and the version is equal to or higher than the version entered.
Maximum Version The search is successful if the file exists on the target system
and the version is equal to or lower than what is entered.
Minimum Date Select the check box to search by a minimum date. The search is
successful if the file exists on the target system and the date is
equal to or later than the date entered.
Maximum Date Select the check box to search by a maximum date. The search
is successful if the file exists on the target system and the date is
earlier or equal to the date entered.
Minimum Size The search is successful if the file exists on the target system
and is equal to or larger than the size indicated (in bytes).
Maximum Size The search is successful if the file exists on the target system
and is smaller than or equal to the size indicated (in bytes).
Languages Click the Browse (...) button to display the Languages dialog. You
can select multiple languages as a condition of your search. The
search is successful if at least one of the languages listed is a
match.
Note: The information you provide in the edit fields is optional. You can leave any field blank.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The File Properties dialog box lets you specify the properties for a file when it is installed onto the target
system.
1. In the View List under Application Data, click Files and Folders.
2. Right-click a file and click Properties.
Caution: Because the individual files might not be present at build time, most file properties cannot be set for dynamically
linked files.
Font title
If you are installing a font, you can specify the font title in this box in the format FontTitle (FontType)—
for example, Roman (All res). InstallShield provides the name of the font if it is registered on your
system.
You should not specify a font title for .ttf or .ttc fonts, because Windows Installer reads the embedded
font name and registers it for you. Thus, for .ttf or .ttc files, InstallShield marks this field [Title read from
file]. InstallShield provides the name of the font for you if it is registered on your system. For more
information, see ICE07.
Self Register
Select this check box if you want to self-register the file during installation. The Self Register setting is
valid for .dll, .ocx, .exe, .tlb, and .olb files.
If the file is part of a 64-bit component, the installation performs 64-bit self-registration on the target
system. For more information, see Targeting 64-Bit Operating Systems.
Note: It is recommended that you extract COM information from your self-registering files, instead of using self-
registration. For more information, see Registering COM Servers.
Read-only
Select this check box if you want the file to be read-only when installed.
Hidden
Select this check box if you want the file to be hidden when installed.
This option is available only for unversioned files. Windows Installer can use file hashing to detect and
eliminate unnecessary file copying. A file hash stored in the MsiFileHash table can be compared to a
hash of an existing file on the user’s computer obtained by calling MsiGetFileHash. Select this option if
you want to populate the MsiFileHash table for every unversioned file in your build.
Note: If the Releases view counterpart to this option is already set, then no file hash entries are created for any files.
System
Select this check box if you want the file installed as a system file.
Vital
Select this check box to indicate that this file is vital to the operation of its component. A vital file’s
component is not installed if the file cannot be installed for any reason. If a vital file cannot be installed,
the end user sees an error message with Retry and Cancel buttons, instead of the usual Abort, Retry, and
Ignore buttons.
Always Overwrite
This property enables you to specify that if the file already exists on the target system, the installer
should overwrite it, regardless of the file version.
If you select this check box, the file’s version is set to 65535.0.0.0. The maximum version number for a
file is 65535.65535.65535.65535.
Permissions
Click Permissions to launch the File and Directory Lock Permissions dialog box, where you can set
permissions for the file.
This dialog box displays the properties that are set for a file when it is installed on the target system.
Right-click a file and click Properties. This option is disabled for files in components whose Link Type
property is set to Dynamic.
In InstallScript projects, the File Properties dialog box displays information about the selected file. The
information in the dialog box is taken directly from the file system and the dialog box is read only except
for the following controls:
Font title
For an .fon file, this text specifies the font title that the installation registers for the font. By default, the
InstallShield user interface reads the font title from the registry of the source system and enters that font
title in this edit box. For a TrueType file (.ttf or .ttc file), by default no text is displayed in this edit box
and the installation reads the font title from the file at run time. For all three types of files, if you enter
non-default text in this edit box, the installation registers that text as the font title.
Caution: You should only replace text that is unique and will not cause script syntax errors.
Dialog Options
Directory Identifier
This field contains the current directory identifier for the selected folder.
Source Location
The source location determines where files will be copied to the disk image folders when you build an
uncompressed release.
Target
The target specifies the location to which the folder will be installed on the end user’s system.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. In the Custom Actions explorer, select the custom action whose parameters you would like to
specify.
3. In the Function Signature property, click the ellipsis button (...).
Arguments
Build the list of arguments—in order—that you want to pass to the function.
First, click the last row of the Arguments list to add a new argument. Next, complete the Type, Source,
and Value columns for each argument.
Type
In this list, select the data type of the parameter. Note that there are two special cases for argument
types, and these cases are identified below.
Task To set a handle to the .msi database or the Windows Installer window:
Source
Indicate how you want to pass the data to the function. The following options are available in this list.
Option Description
Option Description
When you select a property for the argument’s source, you must specify the name of the property in the
Value column.
Value
The value can be one of two types:
• A number or string literal that you enter when the argument’s source is a constant
Note: When you set the Type list to HANDLE and the Source list to Constant, the Value column contains two options:
MsiHandle and MsiWindowHandle. These constants can be used to get a handle to either the .msi database or the
Windows Installer window.
When the source is a property, the Value list provides the name of every property in the Property
Manager. You can select an existing property or enter a new name, in which case the new property is
added to the Property Manager.
Remember that a property is merely a container for a value. If your parameter stores its value in an in
property or inout property, ensure that you specify a value for the property in the Property Manager.
(Context Menu)
The context menu provides you with options for working with your arguments. To access the context
menu, right-click an argument in the Arguments grid. The context menu options are described below.
Option Description
Move Up The arguments must be in the precise order in which the function
expects to receive them. Click Move Up to place the argument higher
in the list.
Move Down Click Move Down to place the argument lower in the list.
Return Type
Select the data type of the function’s return value. If you do not need to check the return value, you can
accept void.
Return Property
Select the name of a property whose value will be set to the function’s return value. If you are going to
check the return value elsewhere in your installation, you may want to initialize the return property’s
value.
Silent mode
Select this check box if you do not want InstallShield to display a warning message if the custom action
fails to load the .dll file and call the function.
Panel Options
Build the media to the custom folder location
If unchecked, the release’s Disk Images, Log Files, and Report Files folders are created in the default
location:
<project folder>\Media\<release name>
Check this box to specify another location by typing in the combo box, selecting and completing one of
the list items, which are defined relative to path variables, or clicking the browse button and selecting a
folder.
Reserved Space
Project: This option is available in installation projects. If you are building an object project, this setting is not displayed.
Disabled if the current release’s media type produces a single disk image—which is true for Network
Image. Lets you reserve (leave empty) specified amounts of space in particular disk image folders. Select
a disk image folder number in the Disk list box (for example, a value of 1 specifies disk image folder
Disk1) and enter the space (in kilobytes) to be reserved in that folder in the Reserved Space edit box.
Project: This option is available in installation projects. If you are building an object project, this setting is not displayed.
If this check box is checked, the setup compares each installed file’s MD5 hash value to the value stored
in the .cab file. This setting is stored in the CheckMD5 key of the [Startup] section in the Setup.ini file.
Tip: MD5 checking can detect corrupted files, which is useful during Internet setups; not doing MD5 checking can make
file transfer proceed faster.
Panel Options
File name
Select the file for which you want to specify a disk image folder number.
Disk
Select the desired disk image folder for the selected file (for example, selecting 3 places the selected file
in disk image folder Disk3).
Task To display view the table’s history in your source control program:
Project: The Insert Action dialog box is available in the following project types:
• Basic MSI
• InstallScript MSI
• MSI Database
• Transform
• Web
The Insert Action dialog box enables you to insert a standard action, custom action, or dialog into one of
your project’s sequences.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. Right-click a sequence, dialog, custom action, or standard action, and then click Insert.
Dialog Options
Option Description
Note: When you delete a merge module from your project that
contains custom actions or dialogs inserted within one of your
sequences, those actions and dialogs will automatically be
removed from the sequence.
Select an Action After you have selected the action type, you need to select the
specific action. To do this, highlight the action you want to insert.
Condition You can set a condition upon this action. If the condition does not
evaluate to true, the action does not execute. For more information
on conditions, see Conditional Statement Syntax.
Comments Enter comments in this field. These comments are for internal use
only and are not displayed to the end user.
OK.
Note: Components that are not associated with a feature are displayed with the orphaned component icon.
For more information on component-feature relationships, see Associating New Components with
Features.
Dialog Option
Local Gallery
All the modules in your Local Gallery are displayed in this dialog. Click on a module to view its
description. When you are ready to continue, select the module that you want to include or exclude from
your project and click OK.
Dialog Options
Static Links
The component contains file links to files specified by explicit fully qualified filenames.
Dynamic Links
The component contains file links to files whose names can be specified by wild cards (for example, *.*
or *.exe) and whose folder can be specified by an explicit path or by a build variable.
Note: The following controls are enabled only if the Dynamic option button is selected.
Caution: Entering a relative path (for example, .\MyFolder) will give unpredictable results.
Browse
Opens the Browse for Folder dialog box, in which you can specify an explicit path.
Include subfolders
If checked, the component contains file links to files in subfolders of the specified folder.
Wildcard(s)
The file list is constructed by first including all files that match the specification you enter in the
Inclusion combo box, and then excluding from those files all the ones that match the specification you
enter in the Exclusion combo box.
Inclusion
Specify the names of the files to which the component contains file links. By typing an entry or selecting
a path variable, you can enter the name of a single file or use wild cards in this filename specification, for
example *.* or *.exe. To specify multiple wild cards, separate them with semicolons and no spaces, for
example,
*.txt;*.doc
Exclusion
Specify the names of the files to which the component does not contain file links. By typing an entry or
selecting a path variable, you can enter the name of a single file or use wild cards in this filename
specification, for example *.* or *.exe. To specify multiple wild cards, separate them with semicolons
and no spaces, for example,
*.exe;*.dll
In the above example, no .exe or DLL files are included in the component.
Note: To suppress this warning, select the Do not show this dialog again option.
Dialog Options
The dialog contains a grid in which you can modify the configurable values. The left column contains the
name of the configurable value. The right column contains the value options. You can select a new value
from the drop-down menu. Refer to the redistributable vendor’s documentation for information about
the values.
After you specify the values that you want, click OK to save the new values. When you build your project,
these values are used to build the .msi package.
Restore Defaults
Click this button to restore the redistributable’s default settings. All of the configurable values in the
redistributable are returned to their defaults.
Dialog Options
Matches
Select this option to exclude merge modules that match the language you select in the Language field.
• Destination Tab
• Configurable Values
Media Tab
File Location
In this dialog, you can determine the destination and format of your output.
Stream the new .CAB file into the Windows Installer Package
Choose this option to stream the .cab into the .msi package.
Note: For transform (*.mst) project types, the option to stream the .cab into the .msi package is disabled because the
transform project cannot store the .cab fie internally. It can only add uncompressed files or files stored in an external cab.
Destination Tab
The Merge Module Properties dialog is displayed when you right-click a selected merge module or object
in the Redistributables view.
Dialog Options
GUID
Displays the merge module’s unique GUID.
Author
Displays the merge module’s author.
Version
Displays the merge module version.
Destination
Specifies the destination of the merge module’s files. It is recommended you use the default setting
“(Use merge module’s default destination)”.
Modify
Click this button to change the settings of the currently selected dynamic link. You can access the
dynamic link’s settings through the Dynamic File Link Settings dialog box.
Delete
Click this button to remove the currently selected dynamic link.
Table 38-19: Settings on the Modify Property Dialog Box and the Platforms Panel in the Release Wizard
Setting Description
Use platforms specified by the If the selected release supports all of the platforms that are specified for the
Platforms project property Platforms setting at the project level, select this option. If you select this
option, none of the components are excluded from the release at build time.
Table 38-19: Settings on the Modify Property Dialog Box and the Platforms Panel in the Release Wizard (cont.)
Setting Description
Specify the platforms to support If the selected release is specific to one or more operating systems, select this
below option and then select the appropriate operating systems.
If the platform specified for a component does not match one of the platforms
that is selected for this setting, InstallShield does not include the component in
the release.
Tip: To select multiple consecutive operating systems, select the first file,
press and hold SHIFT, and select the last operating systems. To select multiple
non-consecutive operating systems, select the first operating systems, press
and hold CTRL, and select each additional operating systems.
Project: For InstallScript projects, the list of operating systems that are
displayed in this dialog box excludes any of the operating systems whose
check box is cleared at the project level.
Always show legacy platforms (if This check box determines whether the legacy operating systems are
supported by the project) displayed in all of the operating system lists throughout InstallShield. If you
select this check box, you can see whether the legacy operating systems are
selected, and you can remove any references to the no-longer-supported
platforms.
Note that a legacy platform is displayed for the selected release only if it is
selected at the project level.
This check box is an InstallShield interface–wide setting. If you select this
check box from anywhere within any InstallShield project, InstallShield shows
the legacy operating system check boxes throughout InstallShield for all
projects that you open on your computer. Similarly, if you clear this check box,
InstallShield hides the legacy operating system check boxes throughout
InstallShield for all projects.
For more information, see Upgrading Projects from InstallShield 12 or Earlier.
Dialog Options
Suppress Errors Options
Select the check boxes next to the error conditions that you want to suppress.
Condition Description
Modify missing row Updates or modifies a row that does not exist.
Change codepage The transform and .msi code pages do not match and neither
code page is neutral.
Validation Options
In this section, you can indicate the information that you want the transform package to validate on the
base MSI package before the transform is applied.
Match languages Validates the languages in both the base MSI and the
transform. The transform is not applied if the languages do
not match.
Match Upgrade Code Validates the Upgrade Codes in both the base MSI and the
transform. The transform is not applied if the Upgrade
Codes do not match.
Match Product Code Validates the Product Codes in both the base MSI and the
transform. The transform is not applied if the Product
Codes do not match.
Version comparison
Select the type of comparison you want to make.
Version level
Select whether you want only the major versions compared or both the major and minor versions.
For Windows Installer-based projects, you can choose from the following options to indicate where you
want to add the value.
Option Description
Rename String F2
Move Up UP ARROW
Click OK when you are finished entering a line for each null-delimited string. The strings are
automatically concatenated.
Note: Strings that contain only spaces are allowed, but strings cannot be empty or “[~]”, which is the separator for the
strings as they are stored in the project and displayed in the Destination computer’s registry data pane. This separator is
not included when the registry value is created on the target system.
File Type the path and name of the .prq file that is required for the
current prerequisite. To find the .prq file by browsing, click the
ellipsis (...) button. Setup prerequisite files are stored in the
following location:
Option Description
File Type the path and name of the file. To find the file by browsing,
click the ellipsis (...) button.
URL to file If end users should be able to download the file from the Web,
specify the uniform resource locator (URL) in this box. This URL is
the same one that InstallShield uses when installation authors use
the Redistributables view to download a setup prerequisite from
the Internet to their local machines.
For example, if the URL for the file is http://www.mywebsite.com/
Folder1/Notepad.exe, enter the following in this box: http://
www.mywebsite.com/Folder1
Project: If you select an installation project such as InstallScript, Basic MSI, InstallScript MSI, or Compact, the Project
Assistant launches to help you create your project.
Tab Description
InstallScript This tab displays all of the project types that use the
InstallShield installation engine, including the InstallScript
installation project. If you previously used InstallShield
Professional, you will be familiar with these project types.
Windows Installer This tab includes projects that use the Microsoft Windows
Installer engine, including the Basic MSI installation project.
All Types This tab displays all of the project types available in
InstallShield. It also includes any project templates that you
previously saved, as well as any templates that are available
in your repository.
Note: Running the Visual Basic 6.0 Wizard from this tab (or
the Windows Installer tab) creates a Basic MSI project. To
create an InstallScript project based on a Visual Basic
project, run the wizard from the InstallScript tab.
Option Description
Option Description
Create the project in Project Name Select this check box if you want InstallShield to
subfolder create a subfolder with your project’s name in
your Projects location.
Dialog Options
Operating Systems
Select the operating systems on which the component should be installed. Leaving all operating systems
unselected causes the component to be installed regardless of the target operating system.
• Preferences tab
• Quality tab
• Updates tab
• .NET tab
• Directory tab
• Resource tab
• Validation tab
• Repository tab
General Tab
The General tab on the Options dialog box enables you to set general project options.
Enforce Setup Best Basic MSI, Select this check box to indicate that you want InstallShield to monitor
Practices InstallScript MSI your installation design to ensure that you comply with Setup Best
Practices.
Help window on top All Select this check box to have the help window remain on top of the
InstallShield interface. If you want the help window to fall to the
background when focus is given to InstallShield, clear this check box.
Stop build process Basic MSI, Select this check box to abort the build process when a build error
when first error is InstallScript, occurs.
encountered InstallScript MSI
Automatically create Basic MSI, Select this check box to add the ISSetAllUsers action to your
ISSetAllUsers action InstallScript MSI sequences when your project contains one or more records in the
Upgrade table.
Table 38-29: File Locations Tab Options in the Options Dialog Box
Project Location All The project location becomes your Favorite folder for new installation
projects. All of your source and release files, such as your project (.ism) file,
installation package (.msi file), and disk image files, are stored in subfolders
of your Favorites location, currently [unknown]. You can enter a complete path
or click the Browse button to navigate to the folder.
By default, your project is stored in the following location:
Tip: Changing the project location does not move existing folders and files in
the previous project location. You must build a release with a new name or
manually move the folders to change their location.
Dialogs Location Basic MSI Enter the path where the Dialog Wizard should search for dialogs. Dialogs in
this location appear in the list presented in the Dialog Wizard’s Dialog
Template panel. Separate additional paths with a comma.
Always recommend Basic MSI, InstallScript, Select this option if you want InstallShield to automatically
path variables InstallScript MSI assign existing path variables to your files. For example, if
you are adding a file to your installation project that is stored
in your Program Files folder, InstallShield uses
<ProgramFilesFolder> rather than a hard-coded path.
Select the check box below this option to have InstallShield
automatically create a path variable for you. When a new
variable is created, it is titled <MYVAR#> (where # is a
successive number). You can change the name of this
variable in the Path Variables editor.
Don’t recommend Basic MSI, InstallScript, Select this option if you want to use hard-coded paths for all
path variables InstallScript MSI of your file links. InstallShield does not suggest path
variables for you if this option is selected.
Always display the Basic MSI, InstallScript, Select this option if you want the Path Variable
Path Variable InstallScript MSI Recommendation dialog box dialog box to be displayed
Recommendation every time you associate a file with your installation project.
dialog to me
Don’t ask me Basic MSI, Certain aspects of your installation require that a feature, a component,
InstallScript, or both exist before you can add that functionality. For example, you
InstallScript MSI cannot create a shortcut without first creating the component that will
contain that shortcut.
• Always create new components and features—If you want
InstallShield to automatically create components and features when
needed, select this check box. If you do not select this check box,
InstallShield prompts you to create components and features when
necessary.
• Always confirm feature, component, and release deletion—If
you want InstallShield to display a confirmation dialog box each time
you delete a feature, component, or release, select this check box.
• Always confirm script terminology conversion—If you want
InstallShield to display a confirmation dialog box when you open a
project created in InstallShield Professional, select this check box.
The dialog box asks if you want to convert your script to use the
InstallScript lexicon.
• Automatically determine best feature or component—If you
want InstallShield to automatically determine the feature or
component to associate registry data with, select this check box. If
this check box is cleared, you will be prompted for a feature or
component name when you create registry data for the All
Application data filter or Feature filter.
• Show Welcome panel for IDE wizards—If you want InstallShield
to display a Welcome panel every time you run a wizard, select this
check box.
• Warn about Web site deletion—If you want InstallShield to display
a warning message when you delete a Web site in the Internet
Information Services view, select this check box. The warning alerts
you that the Web site contains one or more virtual directories, and
the virtual directories will be deleted from your project when the Web
site is deleted.
Preferences Tab
The Preferences tab on the Options dialog box sets your program preferences. These settings are
maintained across all installation projects you create on this system.
Self-Registration Basic MSI, This section allows you to select the self-registration method that
InstallScript MSI InstallShield should use when you indicate that a file is self-registering.
Changing this setting applies only to future self-registration settings and
does not affect files that were previously designated as self-registering.
• InstallShield Self-Registration Table (ISSelfReg)—Select this
option to use the InstallShield Self-Registration table for all files
designated as self registering.
• Windows Installer Self-Registration Table (SelfReg)—Select this
option to use the Windows Installer Self-Registration table for all files
designated as self registering.
This section also allows you to select the default timing for COM extraction
of self-registering files. This is the default setting used if a self-registering
file is added via the Files and Folders view or through the Component
Wizard.
• COM Extraction will occur during the build—Select this option to
perform extraction during the build. COM information will appear in the
build log file.
• COM Extraction will occur immediately when the file is
added—Select this option to extract COM data right after you add a
COM file. When you select this option, InstallShield populates the
component’s COM Registration Advanced Settings view.
Run Commands Basic MSI Select the Uninstall before installing check box if you want InstallShield
to automatically uninstall your Basic MSI installation before running it when
you run your installation from the Build menu.
Referential Integrity Basic MSI, Select the Maintain referential integrity check box if you want
InstallScript, InstallShield to automatically maintain referential integrity when you are
InstallScript MSI working in the Direct Editor. For example, the Control table has a Dialog_
column, meaning that the column is a foreign key to the Dialog table. If you
rename the key in the Dialog table, the key in the Control table is also
renamed. Also, if you delete the entire dialog, all of the controls should be
deleted. This is true for any tables with this type of foreign key relationship.
Project Reload All Select the Reload last opened project on startup check box if you want
InstallShield to automatically reload the most recently opened project when
you launch InstallShield.
Table 38-33:
C:\MergeModules,C:\My Files\MergeModules
The first path you list is where the Release Wizard should copy a
merge module after it is built. The file is copied only if you select
Copy to Modules folder in the Merge Module Options panel or run
ISCmdBld.exe with the -e command-line option. The folder is
created if it does not exist.
The default location for copying new merge modules is under the
project location in the MergeModules folder.
Initially, InstallShield’s Modules folder is included in the merge
module location. InstallShield provides a number of freely
redistributable merge modules in InstallShield Program Files
Folder\Modules\i386.
Merge Module File Basic MSI, When you add a file to your project via the Best Practices
Search Behavior InstallScript MSI Component Wizard or the Files view (with Best Practices active),
InstallShield searches the merge modules to see if there is a module
that contains that file and notifies you of any matches.
In this section, you can select options that InstallShield uses to
determine whether the files match.
Quality Tab
The Quality tab on the Options dialog box provides the option to join the Customer Experience
Improvement Program, which works on improving the quality, reliability, and improvement of software
and services from Macrovision Corporation.
Participation is not mandatory, but Macrovision Corporation appreciates your input.
Updates Tab
The Updates tab on the Options dialog box enables you to configure how often FLEXnet Connect checks
for updates to InstallShield. It also lets you specify whether automatic update notification should be
enabled by default for all new projects that you create in InstallShield.
Check for software All Select an option from this list to indicate how often you want
updates InstallShield to check for software updates.
Enable automatic Basic MSI, Select this check box if automatic update notification should be
update notification in InstallScript, enabled in all new projects that you create in InstallShield. You can
all new projects InstallScript MSI override this automatic update notification setting for specific
projects if necessary.
.NET Tab
The .NET tab on the Options dialog box is where you specify preferences for .NET projects. It is also
where you specify the location of the Regasm.exe and InstallUtilLib.dll files, which are utilities that are
included with the .NET Framework. These utilities are used for COM interop and .NET custom actions.
Default .NET Scan at Basic MSI, In this list, select how the .NET Scan at Build property should be set
Build Component InstallScript MSI for new components. This applies to components that are
Setting automatically created when you add files to your project.
.NET Framework File Basic MSI, Regasm.exe and InstallUtilLib.dll are utilities that are included with
Locations InstallScript MSI the .NET Framework. These utilities are used for COM interop and
.NET custom actions.
• Regasm.exe location—Type the complete path or browse to
the location of Regasm.exe.
• InstallUtilLib.dll location—Type the complete path or browse
to the location of InstallUtilLib.dll.
Size
Select this check box to display a Size column in the following areas of InstallShield:
• For Windows Installer and InstallScript projects—Files and Folders view
• For Windows Installer and InstallScript projects—Files subview in the Components view
• For Windows Installer, InstallScript, and Compact projects—Application Files page of the Project
Assistant
Link To
Select this check box to display a Link To column in the following areas of InstallShield:
• For Windows Installer and InstallScript projects—Files and Folders view
• For Windows Installer and InstallScript projects—Files subview in the Components view
• For Windows Installer, InstallScript, and Compact projects—Application Files page of the Project
Assistant
Modified Date
Select this check box to display a Modified column in the following areas of InstallShield:
• For Windows Installer and InstallScript projects—Files and Folders vie
• For Windows Installer and InstallScript projects—Files subview in the Components view
• For Windows Installer, InstallScript, and Compact projects—Application Files page of the Project
Assistant
Destination
Select this check box to display a Destination column in Application Files page of the Project Assistant
for Windows Installer, InstallScript, and Compact projects.
Version
Select this check box to display a Version column in the following areas of InstallShield:
• For Windows Installer and InstallScript projects—Files and Folders view
• For Windows Installer and InstallScript projects—Files subview in the Components view
Note: Selecting the Version check box will slow the performance of the above views.
File Key
Select this check box to display a Key column in the Files subview of the Components view for Windows
Installer projects.
Project: The following options apply to both Windows Installer—based and InstallScript-based projects unless otherwise
noted.
• Use dialog for checkout—When this check box is selected, a checkout dialog box is displayed when you check out
a project through InstallShield. If this check box is cleared, InstallShield automatically checks out the file without a
comment when you select Check out project when edited (below) or if, on the Project menu, you point to Source
Control and then click Check Out.
• Get latest version when opening the project—Select this check box to retrieve the latest version of your project
from your source control program when you open the project in InstallShield. If you do not get the latest version, you
might edit an older version in your working directory—if someone else modified the project file that exists in source
control in the interim.
• Check out project when edited—Select this check box to have InstallShield automatically check your project file
out of your source control program whenever you modify it in InstallShield. If your project file is not checked out, it is
likely read only and you cannot save changes to it until you check it out.
• Add new projects to source control—Select this check box if you want new projects automatically added to
source control upon creating them in InstallShield.
• Use XML format when creating new Windows Installer or Mobile-based projects—When this check box is
selected, XML is the default file format for Windows Installer or Mobile-based projects you create using the New
Project dialog box. If this check box is cleared, binary is the default file format setting for Windows Installer or Mobile-
based projects. You can change the project’s file format at any time by changing the Project File Format property in
the General Information view.
Note: When a project file format is converted to either XML or binary format, the project file extension remains .ism.
Project: The Use XML Format when creating new Windows Installer or Mobile-based projects option only applies
to Windows Installer—based projects.
User name
Specify the name you use to log on to the source control project.
Advanced
Click this button to view the source control program’s Properties dialog box and make advanced
modifications.
Directory Tab
On the Directory tab of the Options dialog box, you can set various design-time directory options for
Windows Installer and InstallScript MSI projects.
Show INSTALLDIR Basic MSI, Select this check box to display INSTALLDIR as a predefined folder at
InstallScript MSI the root level of the folder structure. If the check box not cleared,
INSTALLDIR appears in its location relative to other folders. In the Files
and Folders view, it appears as a subfolder beneath the
ProgramFilesFolder and the “Your Company Name” folder.
Always show directory Basic MSI, In the Files and Folders view, the default behavior for displaying two
nodes with different InstallScript MSI directory identifiers with the same path is to display them as a single
IDs separately directory. To show different directory identifiers with the same path as
two separate directories in the Files and Folders view, select this
check box.
Clean up unused Basic MSI, Select this check box to remove unused user-defined directories from
directories InstallScript MSI your installation project. For example, if you set a component’s
destination to {MYDIR}[INSTALLDIR]MYDIR1 and subsequently change
the destination to [INSTALLDIR], MYDIR1 is automatically deleted from
your project if it is not used elsewhere in your project.
Resource Tab
On the Resource tab of the Options dialog box, you can specify the location of the resource compiler and
resource linker programs on your system. These programs are required in order to display modified
dialogs in an InstallScript MSI installation project
These fields are automatically populated with the default file locations and command-line options for
each program, but you can edit them if necessary.
Resource Compiler Basic MSI, In this section, you can specify the location of a resource compiler and
Settings InstallScript, provide command line options.
InstallScript MSI
• Resource compiler location—The default resource compiler
(rc.exe) location appears in this field. To edit the resource
compiler location, type or browse to the location of a resource
compiler that is currently installed on your system.
• Resource compiler command line options—To edit the
resource compiler command line options, type over the existing
command line options in the field. The default command line
option string is /r "%1".
Resource Linker Basic MSI, In this section, you can specify the location of a resource linker and
Settings InstallScript, provide command line options.
InstallScript MSI
• Resource linker location—The default resource linker
(link.exe) location appears in this field. To edit the resource
linker location, type or browse to the location of a resource linker
that is currently installed on your system.
• Resource linker command line option—To edit the resource
linker command line options, type over the existing command line
options in the field. The default command line option string is "%1"
/DLL /NOENTRY /NODEFAULTLIB /MACHINE:iX86 /OUT:"%2".
Validation Tab
On the Validation tab of the Options dialog box, you can specify the type of validation you want
InstallShield to perform after a successful build.
Perform Patching and Basic MSI, Select this check box to perform validation on both patches and
Upgrading Validation InstallScript MSI upgrades.
Perform validation Basic MSI, Select this check box to specify the validation suite that you
InstallScript MSI want InstallShield to use for installation projects. You can also
browse for a new validation module (.cub file).
Perform merge module Merge Module Select this check box to specify the validation suite that you
validation want InstallShield to use for merge module projects. You can
also browse for a new validation module (.cub file).
Click the Customize button to specify which internal consistency evaluators (ICEs) should be used for a
specific validation suite. For more information, see Specifying Which ICEs, ISICEs, and ISBPs Should
Be Run During Validation.
Repository Tab
Edition: The boxes on the Repository tab are available in the Premier edition of InstallShield only.
If you want to set up a network repository or change its location, name, or description, you can do so
through the Repository tab on the Options dialog box.
Option Description
Network Repository XML File This is the path and file name of the .xml file that InstallShield creates for
the network repository. InstallShield also automatically creates
subfolders in the same directory as the .xml file; these subfolders
contain items that are published to the network repository.
On the SQL Scripts tab of the Options dialog box, you can set one option for SQL script support.
Option Description
Generate unique Windows Installer To share Windows Installer properties between any new database
properties for new connections connections that you add to your project, clear this check box.
To use different Windows Installer properties for any new connections
that you add, select this check box.
This check box is cleared by default.
For more information, see Specifying Whether New SQL Connections
Should Share the Same Windows Installer Properties.
InstallShield user name Basic MSI, InstallScript, Type the user name that you use to log on to the
InstallScript MSI, InstallScript InstallShield Activation Service Publisher Web Site. Your
Object, Merge Module user account must have write access to the licensing
part of the Web site. To obtain a new user name or to
retrieve your password, visit the InstallShield Activation
Service Publisher Web Site
Password Basic MSI, InstallScript, Type the password for your user name. The password is
InstallScript MSI, InstallScript encrypted.
Object, Merge Module
Style Tables
Click a table type to learn about the window styles available for specific controls.
• Dialog
• Button Controls (Check Box, Radio Button Group, Push Button, Group Box, and Billboard Controls)
• Custom Controls
• Edit, List Box, Scrollable Text, Path Edit, and Masked Edit Controls
• Line Controls
Value Description
DS_SYSMODAL This style is obsolete and is included for compatibility with 16-bit
versions of Windows. If you specify this style, the system creates
the dialog box with the WS_EX_TOPMOST style.
This style does not prevent the user from accessing other
windows on the desktop. Do not combine with the DS_CONTROL
style.
DS_3DLOOK Displays text in the dialog box in non-bold font and draws three-
dimensional borders around control windows in the dialog box.
DS_CENTER Centers the dialog box in the working area of the end user’s
screen.
DS_LOCALEDIT Specifies that edit controls in the dialog box use memory in the
applications data section. By default, all edit controls in dialog
boxes use memory outside the applications data section.
Value Description
DS_SETFONT Indicates that the header of the dialog box template contains
additional data specifying the font to use for text in the client
area and controls of the dialog box. The font data begins on the
WORD boundary that follows the title array. It specifies a 16-bit
point size value and a Unicode font name string.
If this style is not specified, the dialog box template does not
include the font data.
DS_ABSALIGN Indicates that the coordinates of the dialog box are screen
coordinates.
DS_CONTEXTHELP Displays a question mark in the title bar of the dialog box. When
the end user clicks the question mark, the cursor changes to a
question mark with a pointer. If the end user then clicks a control
in the dialog box, the control receives a WM_HELP message. The
control should pass the message to the dialog box procedure.
The help application displays a popup window that typically
contains help for the control.
DS_CONTEXTHELP is only a placeholder. When the dialog box is
created, the system checks for DS_CONTEXTHELP and—if it is
there—adds WS_EX_CONTEXTHELP to the extended style of the
dialog box. WS_EX_CONTEXTHELP cannot be used with the
WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
DS_MODALFRAME Creates a dialog box with a modal dialog box frame that can be
combined with a title bar and window menu by specifying the
WS_CAPTION and WS_SYSMENU styles.
Table 38-43: Window Style Options for Bitmap, Icon, Label, and Text Controls
Value Description
SS_CENTERIMAGE Specifies that, if the bitmap or icon is smaller than the client
area of the static control, the rest of the client area is filled with
the color of the pixel in the top left corner of the bitmap or icon.
If the static control contains a single line of text, the text is
centered vertically in the client area of the control.
SS_RIGHTJUST Specifies that the lower right corner of a static control with the
SS_BITMAP or SS_ICON style is to remain fixed when the
control is resized. Only the top and left sides are adjusted to
accommodate a new bitmap or icon.
SS_REALSIZEIMAGE Prevents a static icon or bitmap control (that is, static controls
that have the SS_ICON or SS_BITMAP style) from being resized
as it is loaded or drawn. If the icon or bitmap is larger than the
destination area, the image is clipped.
SS_ENDELLIPSIS Windows NT/2000 or later: If the end of a string does not fit in
the rectangle, it is truncated and ellipses are added. If a word
that is not at the end of the string goes beyond the limits of the
rectangle, it is truncated without ellipses. Compare with
SS_PATHELLIPSIS and SS_WORDELLIPSIS.
SS_WORDELLIPSIS Windows NT/2000 or later: Truncates any word that does not
fit in the rectangle and adds ellipses. Compare with
SS_ENDELLIPSIS and SS_PATHELLIPSIS.
Value Description
Value Description
Value Description
Value Description
BS_AUTOCHECKBOX Creates a button that is the same as a check box, except that the
check state automatically toggles between checked and cleared
each time the user selects the check box.
BS_3STATE Creates a button that is the same as a check box, except that the
box can be grayed as well as checked or cleared. Use the grayed
state to show that the state of the check box is not determined.
Table 38-47: Window Styles for Combo Box and Directory Combo
Value Description
CBS_SIMPLE Displays the list box at all times. The current selection in the list
box is displayed in the edit control.
CBS_DROPDOWN Similar to CBS_SIMPLE, except that the list box is not displayed
unless the user selects an icon next to the edit control.
CBS_OEMCONVERT Converts text entered in the combo box edit control from the
Windows character set to the OEM character set and then back to
the Windows set. This ensures proper character conversion when
the application calls the CharToOem function to convert a
Windows string in the combo box to OEM characters. This style is
useful for combo boxes that contain file names and applies only to
combo boxes created with the CBS_SIMPLE or CBS_DROPDOWN
style.
CBS_UPPERCASE Converts to uppercase all text in both the selection field and the
list.
CBS_AUTOHSCROLL Automatically scrolls the text in an edit control to the right when
the user types a character at the end of the line. If this style is not
set, only text that fits within the rectangular boundary is allowed.
CBS_DISABLENOSCROLL Shows a disabled vertical scroll bar in the list box when the box
does not contain enough items to scroll. Without this style, the
scroll bar is hidden when the list box does not contain enough
items.
Table 38-47: Window Styles for Combo Box and Directory Combo (cont.)
Value Description
CBS_NOINTEGRALHEIGHT Specifies that the size of the combo box is exactly the size
specified by the application when it created the combo box.
Normally, the system sizes a combo box so that it does not
display partial items.
CBS_OWNERDRAWFIXED Specifies that the owner of the list box is responsible for drawing
its contents and that the items in the list box are all the same
height. The owner window receives a WM_MEASUREITEM
message when the combo box is created and a WM_DRAWITEM
message when a visual aspect of the combo box has changed.
CBS_OWNERDRAWVARIABL Specifies that the owner of the list box is responsible for drawing
E its contents and that the items in the list box are variable in height.
The owner window receives a WM_MEASUREITEM message for
each item in the combo box when you create the combo box and
a WM_DRAWITEM message when a visual aspect of the combo
box has changed.
Project: The custom control is available only for dialogs in InstallScript MSI installation projects.
These window style options are available for custom controls. See the MSDN Library for additional
information.
Value Description
Other Window Styles for Directory List, List View, and Volume
Cost List
These window style options are available for the directory list, list view, and volume cost list controls.
See the MSDN Library for additional information.
Table 38-49: Window Styles for Directory List, List View, and Volume Cost List
Value Description
LVS_NOLABELWRAP Displays item text on a single line in icon view. By default, item
text might wrap in icon view.
LVS_SHOWSELALWAYS Always shows the selection highlighted, even if the control is not
activated.
LVS_EDITLABELS Enables item text to be edited in place. The parent window must
process the LVN_ENDLABELEDIT notification message.
LVS_NOSORTHEADER Specifies that column headers do not work like buttons. This
style is useful if clicking a column header in report view does
not carry out any action, such as sorting.
LVS_OWNERDRAWFIXED Enables the owner window to paint items in report view. The list
view control sends a WM_DRAWITEM message to paint each
item; it does not send separate messages for each subitem.
The itemData member of the DRAWITEMSTRUCT structure
contains the item data for the specified list view item.
LVS_SHAREIMAGELISTS Specifies that the control does not destroy the image lists
assigned to it when it is destroyed. This style enables the same
image lists to be used with multiple list view controls.
Types
Value Description
Align
Value Description
LVS_ALIGNTOP Specifies that items are aligned with the top of the list view control in
icon view and small icon view.
LVS_ALIGNLEFT Specifies that items are left-aligned in icon view and small icon view.
Other Window Styles for Edit, List Box, Scrollable Text, Path
Edit, and Masked Edit Controls
Project: Other window styles properties are not used during run time for Basic MSI projects. They are exposed in
InstallShield so they are available if you export the dialog to a resource (.rc) file.
The scrollable text control is available only for dialogs in Basic MSI installation projects.
These window style options are available for the edit, list box, scrollable text, path edit, and masked edit
controls. See the MSDN Library for additional information.
Table 38-52: Window Styles for Edit, ListBox, Scrollable Text, Path Edit, and Masked Edit Controls
Value Description
WS_GROUP Specifies the first control in a group of controls. All controls defined
with this style after the first control belong to the same group.
LBS_NOTIFY The parent window receives an input message whenever the end
user clicks or double-clicks a string.
LBS_NODATA Specifies a no-data list box. Specify this style when the count of
items in the list box will exceed one thousand. A no-data list box
must also have the LBS_OWNERDRAWFIXED style, but must not
have the LBS_SORT or LBS_HASSTRINGS style.
A no-data list box resembles an owner-drawn list box except that it
contains no string or bitmap data for an item. Commands to add,
insert, or delete an item always ignore any specified item data;
requests to find a string within the list box always fail. The system
sends the WM_DRAWITEM message to the owner window when an
item must be drawn.
The itemID member of the DRAWITEMSTRUCT structure passed
with the WM_DRAWITEM message specifies the line number of the
item to be drawn. A no-data list box does not send a
WM_DELETEITEM message.
LBS_NOINTEGRALHEIGHT Creates a list box that is precisely the size specified by the
application when it created the list box.
LBS_MULTIPLESEL Toggles string selection each time the end user clicks or double-
clicks the string.
LBS_HASSTRINGS Specifies that a list box contains items consisting of strings. The
list box maintains the memory and addresses for the strings so that
the application can use the LB_GETTEXT message to retrieve the
text for a particular item. By default, all list boxes except owner-
drawn list boxes have this style. You can create an owner-drawn list
box either with or without this style.
LBS_USETABSTOPS Allows a list box to recognize and expand tab characters when
drawing strings.
Table 38-52: Window Styles for Edit, ListBox, Scrollable Text, Path Edit, and Masked Edit Controls (cont.)
Value Description
LBS_EXTENDEDSEL Allows the end user to select multiple items using the SHIFT key
and the mouse, or key combinations.
LBS_DISABLENOSCROLL Displays a disabled vertical scroll bar when the list box does not
contain enough items to scroll.
LBS_OWNERDRAWFIXED Indicates that the owner of the list box is responsible for drawing
the list box’s contents. Items in the list box are the same height.
LBS_OWNERDRAWVARIAB Indicates that the owner of the list box is responsible for drawing
LE the list box’s contents. Items in the list box are of variable height.
Value Description
SS_ETCHEDVERT Draws the left and right edges of the static control using the
EDGE_ETCHED edge style. For more information, see the DrawEdge
Windows API function in the MSDN Library.
SS_ETCHEDFRAME Draws the frame of the static control using the EDGE_ETCHED edge
style. For more information, see the DrawEdge Windows API function
in the MSDN Library.
SS_ETCHEDHORZ Draws the top and bottom edges of the static control using the
EDGE_ETCHED edge style. For more information, see the DrawEdge
Windows API function in the MSDN Library.
Value Description
SS_BLACKRECT Specifies a rectangle filled with the current window frame color. This
color is black in the default color scheme.
SS_BLACKFRAME Specifies a box with a frame drawn in the same color as the window
frames. This color is black in the default color scheme.
SS_WHITERECT Specifies a rectangle filled with the current window background color.
This color is white in the default color scheme.
SS_WHITEFRAME Specifies a box with a frame drawn with the same color as the
window background. This color is white in the default color scheme.
SS_GRAYRECT Specifies a rectangle filled with the current screen background color.
This color is gray in the default color scheme.
SS_GRAYFRAME Specifies a box with a frame drawn with the same color as the screen
background (desktop). This color is gray in the default color scheme.
WS_GROUP Specifies the first control in a group of controls. All controls defined
with this style after the first control belong to the same group.
SS_RIGHTJUST Specifies that the lower right corner of a static control with the
SS_BITMAP or SS_ICON style is to remain fixed when the control is
resized. Only the top and left sides are adjusted to accommodate a
new bitmap or icon.
SS_CENTERIMAGE Specifies that, if the bitmap or icon is smaller than the client area of
the static control, the rest of the client area is filled with the color of
the pixel in the top left corner of the bitmap or icon. If the static
control contains a single line of text, the text is centered vertically in
the client area of the control.
SS_REALSIZEIMAGE Prevents a static icon or bitmap control (that is, static controls that
have the SS_ICON or SS_BITMAP style) from being resized as it is
loaded or drawn. If the icon or bitmap is larger than the destination
area, the image is clipped.
SS_ENDELLIPSIS Windows NT, Windows 2000, or later: If the end of a string does not
fit in the rectangle, it is truncated and ellipses are added. If a word
that is not at the end of the string goes beyond the limits of the
rectangle, it is truncated without ellipses. Compare with
SS_PATHELLIPSIS and SS_WORDELLIPSIS.
Value Description
SS_WORDELLIPSIS Windows NT, Windows 2000, or later: Truncates any word that does
not fit in the rectangle and adds ellipses. Compare with
SS_ENDELLIPSIS and SS_PATHELLIPSIS.
Value Description
WS_GROUP Specifies the first control in a group of controls. All controls defined
with this style after the first control belong to the same group.
PBS_VERTICAL The progress bar displays progress status vertically, from bottom to
top.
Value Description
TVS_EDITLABELS Enables the user to edit the labels of tree view items.
TVS_HASBUTTONS Displays plus (+) and minus (-) buttons next to parent items.
The user taps the buttons to expand or collapse a parent
items list of child items. To include buttons with items at the
root of the tree view, you must also specify the
TVS_LINESATROOT style.
TVS_SHOWSELALWAYS Uses the system highlight colors to draw the selected item.
TVS_FULLROWSELECT Enables full-row selection in the tree view. The entire row of
the selected item is highlighted, and clicking anywhere on an
item’s row causes it to be selected. This style cannot be
used in conjunction with the TVS_HASLINES style.
TVS_LINESATROOT Uses lines to link items at the root of the tree view control.
This value is ignored if the TVS_HASLINES control is not also
specified.
Value Description
TVS_SINGLEEXPAND Causes the item being selected to expand and the item
being unselected to collapse upon selection in the tree view.
If the mouse is used to single-click the selected item and
that item is closed, it will be expanded. If the user holds
down the Ctrl key while selecting an item, the item being
unselected will not be collapsed.
TVS_NONEVENHEIGHT Sets the height of the items to an odd height with the
TVM_SETITEMHEIGHT message. By default, the height of
items must be an even value.
1. Select the Outputs property in the Properties window when a project output group is selected in
the File System Editor.
2. In the Files and Folders view, right-click an item in the Source computer’s files pane and click
Resolve Project Output.
3. In the Files and Folders view, right-click an item in the Destination computer’s files pane
and click Resolve Project Output.
Note: If multiple project output groups are selected, information is displayed only for the first group selected.
Dialog Options
Target Name
Displays the file name for the selected project output group as it will be displayed on a target computer.
This field is read only.
Source Path
Displays the path to the project output group files on the development computer. This field is read only.
Dialog Options
list box
Select whether files on the target system are always overwritten, never overwritten, or conditionally
overwritten based on date/time stamp or version number.
The following controls are enabled only if "Overwrite files BY VERSION" or "Overwrite files BY
VERSION THEN DATE (if necessary)" is selected in the list box.
Note: If a file on the target system has a version number and the file on your distribution media does not, or vice versa, the
file with no version number is treated as if it had a lower version number.
Version: Newer
A file on the target system is overwritten if the file on your distribution media has a higher version
number.
If the file on your distribution media and the file on the target system have the same version number, or
if neither file has a version number, and you selected Overwrite files BY VERSION THEN DATE (if
necessary) from the list box, then whether the file on the target system is overwritten is determined by
which Date/Time option you select.
If neither file has a version number and you selected Overwrite files BY VERSION from the list box, then
the file on the target system is not overwritten.
Version: Older
A file on the target system is overwritten if the file on your distribution media has a lower version
number.
If the file on your distribution media and the file on the target system have the same version number, or
if neither file has a version number, and you selected Overwrite files BY VERSION THEN DATE (if
necessary) from the list box, then whether the file on the target system is overwritten is determined by
which Date/Time option you select.
If neither file has a version number and you selected Overwrite files BY VERSION from the list box, then
the file on the target system is not overwritten.
The following controls are enabled only if Overwrite files BY DATE or Overwrite files BY VERSION
THEN DATE (if necessary) is selected in the list box.
Date/Time: Newer
A file on the target system is overwritten if the file on your distribution media has a more recent date and
time stamp.
Date/Time: Older
A file on the target system is overwritten if the file on your distribution media has a less recent date and
time stamp.
Option Description
Family Name Specify the name of the family of patches to which this
patch belongs. Windows Installer 3.0 and later uses the
patch family to compare small-update patches with all
of the other patches within the same family and
determine the order in which each of the patches
should be applied to the target machine.
To identify that a patch configuration belongs to
multiple families, create a separate row on the
Sequence tab for every patch family. You may want a
patch to belong to multiple families, for example, if the
patch can update more than one product.
Target Type the product code GUID in this box if you want to
associate the patch configuration with a specific
product. Entry in this box is not required.
To identify that a patch configuration should target
multiple GUIDs, create a separate row on the Sequence
tab for every GUID and family combination.
Option Description
Supersede previous versions If you want the patch to be used instead of all of the
patches that have a lower sequence value and that are
in the same patch family, select this check box.
Selecting this check box does not guarantee that the
patch will always supersede all earlier patches, since
the earlier patches might belong to multiple patch
families. Note that a small-update patch cannot
supersede a minor upgrade patch or a major upgrade
patch, regardless of whether this check box is
selected.
• InstallShield cannot recommend a path variable based on an existing path variable and you have not
selected the auto-create check box on the Path Variables tab.
Dialog Options
Use the following path variable-based folder representation for the source folder
This option provides suggested path variables or path variable combinations for you to use instead of an
absolute path. For example, if you have a path variable called <MyFiles> that points to C:\Work\Files
and you add a file to your installation from C:\Work\Files\Images, Macrovision recommends that you
use <MyFiles>\Images rather than the full hard-coded path C:\Work\Files\Images.
This option is available only if InstallShield can recommend a path variable for the source folder.
Caution: Do not enclose the path variable’s name in angle brackets. InstallShield automatically adds the angle brackets
when you click OK.
Dialog Options
Install without performing platform suite verification on the target system
If this option button is selected, the installation of the component’s files does not depend on the target
system’s suite.
Install when the target system has one or more of the specified platform suite(s)
If this option button is selected, the setup installs the component’s files only if at least one of the selected
suites exists on the target system.
Install only when the target system has all the specified platform suite(s)
If this option button is selected, the setup installs the component’s files only if all of the selected suites
exist on the target system.
Disabled if the Install without performing platform suite verification option button is selected. Lets you
select the suites that must exist on the target system for the setup to install the component’s files. To
toggle the selection status of a suite, click the box next to its name. To toggle the selection status of
multiple suites, hold down the SHIFT or Ctrl key, click the suite names with the mouse, then click a box
next to any of the selected names.
Project: Some of this information applies to InstallScript projects, and some of this information applies to InstallScript MSI
projects.
Depending on how you launch the Platforms dialog box, you can specify either of the following:
• The platforms that you want to be available when you to select operating system requirements for
components or releases in your project. This is available for InstallScript projects.
• The platform requirements for a component. This is available for InstallScript and InstallScript MSI
projects.
Note: Specifying platforms at the project level does not create target system requirements for running the installation. To
create target system requirements in an InstallScript project, you can use the SYSINFO structure to identify the operating
platform of the target system.
Setting Description
The project supports all platforms Select this option if you want InstallShield to list all of the supported run-time
supported by InstallShield platforms for the following settings:
• Operating Systems setting at the component level (InstallScript and
InstallScript MSI projects)
• Platform(s) setting at the release level (InstallScript projects)
If you select this option, you can designate that a particular component or
release in your project is targeted for any one or more supported platforms.
The project supports only Select this option if you want InstallShield to list only some platforms that are
platforms checked below displayed for the following settings:
• Operating Systems setting at the component level (InstallScript and
InstallScript MSI projects)
• Platform(s) setting at the release level (InstallScript projects)
Then select the platforms that should be displayed.
Tip: To select multiple consecutive operating systems, select the first file,
press and hold SHIFT, and select the last operating systems. To select multiple
non-consecutive operating systems, select the first operating systems, press
and hold CTRL, and select each additional operating systems.
In general, if a platform is not listed for this setting at the project level, you
cannot designate that a particular component or release in your project is
targeted for that platform.
Setting Description
Always show legacy platforms This check box determines whether the legacy operating systems are
displayed in all of the operating system lists throughout InstallShield. If you
select this check box, you can see whether the legacy operating systems are
selected, and you can remove any references to the no-longer-supported
platforms.
This check box is an InstallShield interface–wide setting. If you select this
check box from anywhere within any InstallShield project, InstallShield shows
the legacy operating system check boxes throughout InstallShield for all
projects that you open on your computer. Similarly, if you clear this check box,
InstallShield hides the legacy operating system check boxes throughout
InstallShield for all projects.
For more information, see Upgrading Projects from InstallShield 12 or Earlier.
Setting Description
The files in this component should If the selected component is operating system independent—that is, if none of
be installed when the setup is the component's data are specific to certain operating systems—select this
running in any platform option.
Setting Description
The files in this component should If the selected component is specific to one or more operating systems, select
be installed only when the setup is this option and then select the appropriate operating systems. If the target
running on one of the platforms machine's operating system does not match one of the operating systems that
checked below are specified for this setting, the component is not installed.
Tip: To select multiple consecutive operating systems, select the first file,
press and hold SHIFT, and select the last operating systems. To select multiple
non-consecutive operating systems, select the first operating systems, press
and hold CTRL, and select each additional operating systems.
Project: For InstallScript projects, the list of operating systems that are
displayed in this dialog box excludes any of the operating systems whose
check box is cleared at the project level.
Note that if the selected component supports platforms that are not supported
by a release, InstallShield does not include the component in the release at
build time.
Always show legacy platforms (if This check box determines whether the legacy operating systems are
supported by the project) displayed in all of the operating system lists throughout InstallShield. If you
select this check box, you can see whether the legacy operating systems are
selected, and you can remove any references to the no-longer-supported
platforms.
Note that a legacy platform is displayed for the selected component only if it is
selected at the project level.
This check box is an InstallShield interface–wide setting. If you select this
check box from anywhere within any InstallShield project, InstallShield shows
the legacy operating system check boxes throughout InstallShield for all
projects that you open on your computer. Similarly, if you clear this check box,
InstallShield hides the legacy operating system check boxes throughout
InstallShield for all projects.
For more information, see Upgrading Projects from InstallShield 12 or Earlier.
The Prerequisite Condition dialog box lets you define installation conditions that determine whether a
prerequisite is already installed on the target machine. Failure to do so causes problems because the
target system behaves as if the prerequisite was not properly installed. You can also create installation
conditions that specify operating system, registry, or file requirements.
Option Description
A registry key does If you select this option, type the name of the registry key and select the
or does not exist appropriate option for 64-bit machines.
If target machines that have this registry key should meet this installation
condition, select Found. If target machines that do not have this registry
key should meet this installation condition, select Not found.
A registry entry If you select this option, type the name of the registry key, the name of the
has a certain value value, and the value of the registry entry. Also, select the appropriate
option for 64-bit machines.
In addition, select the option that should be used to compare the registry
entry specified in this dialog box with the registry entry on the target
machine.
For example, if you specify 1.4.2 in the Value data box and select Greater
than, target machines that have a value greater than 1.4.2 for this registry
entry meet this installation condition.
A file does or does If you select this option, do one of the following:
not exist
• Specify the path and file name for the file. To specify a predefined path
variable, select the appropriate path in the list. The supported path
variables are [CommonFilesFolder], [ProgramFilesFolder],
[SystemFolder], and [WindowsFolder].
• Specify just the file name—without the path or a path variable. The
installation will search for the specified file in all directories defined for
the PATH environment variable on the target machine.
• Specify a registry key as a path variable. If you do this, the installation
will resolve the registry key with the registry value. Note that the last
element of the registry path variable is treated as a value name. If a
backslash is the last character of the path variable, the value of the
default registry entry for that registry key is used.
For example, if you type the following as the value, the installation
checks if the path specified as the value for the
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORACLE_HOME registry
entry contains a bin directory with a file named oci.dll:
[HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORACLE_HOME]bin\oc
i.dll
If target machines that have this file should meet this installation condition,
select Found. If target machines that do not have this file should meet this
installation condition, select Not found.
Option Description
A file with a certain If you select this option, do one of the following:
date exists
• Specify the path and file name for the file. To specify a predefined path
variable, select the appropriate path in the list. The supported path
variables are [CommonFilesFolder], [ProgramFilesFolder],
[SystemFolder], and [WindowsFolder].
• Specify just the file name—without the path or a path variable. The
installation will search for the specified file in all directories defined for
the PATH environment variable on the target machine.
• Specify a registry key as a path variable. If you do this, the installation
will resolve the registry key with the registry value. Note that the last
element of the registry path variable is treated as a value name. If a
backslash is the last character of the path variable, the value of the
default registry entry for that registry key is used.
For example, if you type the following as the value, the installation
checks if the path specified as the value for the
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORACLE_HOME registry
entry contains a bin directory with a file named oci.dll:
[HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORACLE_HOME]bin\oc
i.dll
In addition, type the date and—if appropriate—the time that the file was
last modified. For example:
4/26/2004 3:57:46 PM
A file with a certain If you select this option, do one of the following:
version exists
• Specify the path and file name for the file. To specify a predefined path
variable, select the appropriate path in the list. The supported path
variables are [CommonFilesFolder], [ProgramFilesFolder],
[SystemFolder], and [WindowsFolder].
• Specify just the file name—without the path or a path variable. The
installation will search for the specified file in all directories defined for
the PATH environment variable on the target machine.
• Specify a registry key as a path variable. If you do this, the installation
will resolve the registry key with the registry value. Note that the last
element of the registry path variable is treated as a value name. If a
backslash is the last character of the path variable, the value of the
default registry entry for that registry key is used.
For example, if you type the following as the value, the installation
checks if the path specified as the value for the
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORACLE_HOME registry
entry contains a bin directory with a file named oci.dll:
[HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ORACLE_HOME]bin\oc
i.dll
In addition, type the version number of the file. For example:
6.7.8.9
Option Description
Setup is running on If you select this option, click one of the predefined operating systems in
a particular the Select the operating system on which to run the setup
operating system requirement box, or click Custom to define your own operating system
requirements. If the prerequisite requires a particular service pack—or a
later version of that service pack—of the operating system, specify that
service pack number in the Minimum Service Pack box.
If you click Custom to define your own operating system requirements, you
can configure any one or more of the following settings in the Custom area:
• Platform Id—Select the required operating system platform.
If the value that you select matches the dwPlatformId member of the
OSVERSIONINFOEX structure of the target system’s operating system,
this part of the operating system condition evaluates as true.
• Major Version—Specify the required major version of the operating
system.
If the value that you specify matches the dwMajorVersion member of
the OSVERSIONINFOEX structure of the target system’s operating
system, this part of the operating system condition evaluates as true.
If you type 0 in this box, the operating system condition that
InstallShield creates does not include any major version or minor
version requirements; the behavior is the same if you leave the Major
Version and Minor Version boxes blank.
Option Description
Setup is running on • Minor Version—Specify the required minor version of the operating
a particular system.
operating system
If the value that you specify matches the dwMinorVersion member of
(cont.)
the OSVERSIONINFOEX structure of the target system’s operating
system, this part of the operating system condition evaluates as true.
Note that 0 is a valid value for this box.
• Product (OS) Type—Select the required operating system type.
If the value that you select matches the wProductType member of the
OSVERSIONINFOEX structure of the target system’s operating system,
this part of the condition evaluates as true.
Note that if the prerequisite supports both servers and domain
controllers, you can select the Server or Domain Controller option.
• Processor Architecture—Select the required processor architecture
(for example, 32-bit or 64-bit Windows).
If the architecture that you select matches the architecture of the
target system’s operating system, this part of the operating system
condition evaluates as true.
• Minimum CSD Version—Specify the minimum required service pack
or other version information for the operating system.
Note that this setting is provided for compatibility with prerequisites
that were created with earlier versions of InstallShield, and to enable
subversions of Windows 9x platforms to be distinguished. Using this
setting to specify a particular service pack is not recommended; if you
need to specify a particular service pack, use the Minimum Service
Pack box.
If the value that you specify is the same version as or an earlier
version than the szCSDVersion member of the OSVERSIONINFOEX
structure of the target system’s operating system, this part of the
operating system condition evaluates as true.
For example, if you specify “ A” and the szCSDVersion value on the
target machine is “ B”, this part of the operating system condition
evaluates as true. It evaluates as false if you specify “ B” but the value
on the target machine is “ A”.
Similarly, if you specify “Service Pack 1” and the value on the target
machine is “Service Pack 2”, this part of the operating system
condition evaluates as true. It evaluates as false if you specify
“Service Pack 2” but the value on the target machine is “Service Pack
1”.
Note that to prevent comparison problems, any leading and trailing
spaces in the version that you specify and in the value of the
szCSDVersion member on the target system are ignored.
Option Description
Setup is running on • Minimum Build No—Specify the minimum required build number of
a particular the operating system.
operating system
If the value that you specify is the same version as or an earlier
(cont.)
version than the dwBuildNumber member of the OSVERSIONINFOEX
structure of the target system’s operating system, this part of the
operating system condition evaluates as true.
For more information on specifying an operating system condition, see
Adding an Operating System Condition for a Prerequisite.
For details about the OSVERSIONINFOEX structure, see OSVERSIONINFOEX
on the MSDN Web site.
Dialog Options
Condition(s)
Double-click in the Condition column to create a new condition. Use the Properties and Operators drop-
down lists at the bottom of the dialog to assist you in building a conditional statement.
In the Message column, enter the text you want to display to the end user if one of your conditions fails,
forcing the installation to exit. Type a new message—which is automatically added to the string table—or
select an existing string by clicking the ellipses button to the right.
• No validation is made during design time. Use valid syntax and double-check to ensure that your statement evaluates
to the expected outcome. For more information, see Conditional Statement Syntax.
• Windows Installer dialog boxes, which display the text you specify in the Message column, do not recognize the
escape sequences \r (carriage return), \n (new line), or \t (tab).
Properties
This control lists all of the properties stored in the Property Manager. Select the property you want to
evaluate and click Add. The property appears in the Condition(s) window.
Operators
This control lists all of the valid operators recognized by the Windows Installer service. Select the
operator you want to use and click Add. The operator is appended to the conditional statement in the
Condition(s) window.
• Application Tab
• Platforms Tab
• Languages Tab
Project Tab
This tab displays basic information about the open project. This dialog box opens when you select the
Project menu’s Settings command.
Author
(Optional) Enter the name of the project author.
Comments
(Optional) Enter any comments about the project.
Application Tab
This tab lets you view and modify information about the application that is installed by the open project,
and the globally unique identifier (GUID) of the project. This dialog box opens when you select the
Project menu’s Settings command.
Product GUID
Displays and lets you change the open project’s GUID.
Change
Creates a new GUID for the open project.
Caution: Your setup uses the project GUID to associate an uninstallation or maintenance setup with the original setup. A
new GUID is automatically generated for each new project you create, including copies of existing projects. Once you have
changed a project’s GUID, its previous GUID cannot be recovered. For these reasons, changing a project’s GUID is typically
not necessary and should be approached with caution.
combo/edit boxes
Specify the information indicated by the edit box name, by either typing text or selecting an existing path
variable (or, for Application Type, an existing application type) from the combo box’s list. Specifying
information with a path variable lets you set that information at build time. (The values specified in the
Product Name, Product Version, and Company Name boxes are used to specify properties of a self-
extracting executable if you build one. You can view these properties by right-clicking the executable in
an Explorer window and selecting Properties.)
The following entries can be retrieved at run time by calling the MediaGetData function:
• Product Name
• Product Version
• Company Name
• Executable File
Caution: You must specify a non-null value in the Product Version combo box; otherwise your media build will fail with error
-7044.
Platforms Tab
Note: Specifying platforms at the project level does not create target system requirements for running the installation. To
create target system requirements in an InstallScript project, you can use the SYSINFO structure to identify the operating
platform of the target system.
The following table shows the settings that are displayed in the Platforms tab.
Setting Description
The project supports all platforms Select this option if you want InstallShield to list all of the supported run-time
supported by InstallShield platforms for the following settings:
• Operating Systems setting at the component level (InstallScript and
InstallScript MSI projects)
• Platform(s) setting at the release level (InstallScript projects)
If you select this option, you can designate that a particular component or
release in your project is targeted for any one or more supported platforms.
The project supports only Select this option if you want InstallShield to list only some platforms that are
platforms checked below displayed for the following settings:
• Operating Systems setting at the component level (InstallScript and
InstallScript MSI projects)
• Platform(s) setting at the release level (InstallScript projects)
Then select the platforms that should be displayed.
Tip: To select multiple consecutive operating systems, select the first file,
press and hold SHIFT, and select the last operating systems. To select multiple
non-consecutive operating systems, select the first operating systems, press
and hold CTRL, and select each additional operating systems.
In general, if a platform is not listed for this setting at the project level, you
cannot designate that a particular component or release in your project is
targeted for that platform.
Always show legacy platforms This check box determines whether the legacy operating systems are
displayed in all of the operating system lists throughout InstallShield. If you
select this check box, you can see whether the legacy operating systems are
selected, and you can remove any references to the no-longer-supported
platforms.
This check box is an InstallShield interface–wide setting. If you select this
check box from anywhere within any InstallShield project, InstallShield shows
the legacy operating system check boxes throughout InstallShield for all
projects that you open on your computer. Similarly, if you clear this check box,
InstallShield hides the legacy operating system check boxes throughout
InstallShield for all projects.
For more information, see Upgrading Projects from InstallShield 12 or Earlier.
Languages Tab
This tab lets you view and modify the list of languages included in the open project. This dialog box
opens when you select the Project menu’s Settings command.
check boxes
A checked check box next to a language indicates that the language is included in the project; an
unchecked check box indicates that the language is not included. To add or remove a language from the
project, click its check box to toggle it to the desired state.
Removing a language from the project also removes it from any components or releases that had been
using that language.
Maintenance Tab
Updates Tab
Object Wizard
This option allows you to specify the type of wizard, if any, that you would like to use for your object’s
default language. The following wizard choices are available:
• No Wizard—Select this option if your object does not require a wizard.
• Use InstallShield Object Stock Wizard—Select this option to have InstallShield create a wizard
for you based on the properties you created for your object. All read-only properties will be
displayed but will not be editable. All read/write properties will be changeable by the user. Write-
only properties will not be displayed.
Note: The InstallShield stock wizard does not support array properties. If your object’s properties require array
properties, you will need to create your own wizard.
• Use My Custom Wizard—Select this option to use a wizard you created. InstallShield allows you
to use a wizard created with either Visual C++ or Visual Basic. To use a wizard created with one of
these two programs, enter the path to the DLL you created, or click the browse (...) button to
navigate to that file.
The following controls are not displayed when you select the Project menu’s Settings command.
Company
Enter the name of the company responsible for creating this object.
Version
Enter the version of this object.
Media File
Enter the path to the object’s media file (Data1.hdr file), or click the browse button to navigate to that
file.
IDE Language
Select the language for which you want to specify object information. Currently, only English (default),
German, and Japanese are supported.
Use Default
Disabled if the default language, English, is selected. Check this box to specify that the object, when
displayed in the selected language, use the same information that you specified for the default language.
The following controls are enabled only if the Use Default check box is unchecked:
Display Name
Enter the name of your object as you would like it to appear in the object gallery.
Short Name
Enter a shortened version of your object’s name, if necessary. You can enter the same name as entered in
the Display Name field.
HTML Help
Enter the path to the help file for this object, or click the browse (...) button to navigate to this file. This
help file must consist of a single .htm file.
Icon File
Enter the path to the icon file for your object, or click the browse (...) button to navigate to this file. The
icon you choose will be displayed next to your object in the object gallery. The icon you use for your
object needs to be sized to 16x16 with a maximum of 16 colors.
Dialog Options
Option Description
Key Value Type a new key value or name for the item in this field and press OK
to rename the item.
Dialog Options
Required Features for <Current Feature>
Select the features that the current feature requires. (The current feature is automatically selected in
InstallScript MSI projects and automatically deselected in InstallScript projects; in either case, the
selection status cannot be changed and does not affect whether the feature is installed or not.)
Dialog Options
Option Description
Property Sheet This control lists all of the properties of the dialog, control,
component, or custom action. The existing value is the current
value in the project file to which you are exporting the item. The
new value is the value you want to replace it with from the project
you have open.
Key icons identify key columns in the record. If there is a conflict
between a new and existing value, that line appears in red. Your
selection for resolving the conflict determines whether or not the
existing item and its properties are overwritten.
Skip Select this option to continue exporting, but leave the current value
for the conflicting properties.
Skip all Select this option to continue exporting, but leave the current value
for the conflicting properties in this object and for all conflicts that
arise during this export. If you select this option, the Resolve
Conflict dialog is not displayed for any other conflicting records.
Overwrite Select this option and click OK to replace the existing value with
the new value for all properties in this object.
Overwrite All Select Overwrite all to overwrite the existing value for this object
and for all conflicts that arise in this export. If you select this
option, the Resolve Conflict dialog is not displayed for any other
conflicting records.
Rename Select this option and click Edit to display the Rename Key dialog
box.
Edit The Edit button is enabled when the focus is on one of the key
columns and the Rename option is selected.
Renaming Items
Task You can display the Rename dialog to rename an item in one of the key columns (identified with the key icon)
by doing any of the following:
Dialog Options
The Save As dialog box is a standard Windows dialog box. To display detailed help for any control except
the following ones, select the control and press F1.
Save as type
This list enables you to specify the type of file you are saving. To create a template from the current
project, select InstallShield Template (.ist). To save your InstallShield project (.ism) as an earlier version
of InstallShield, select the appropriate version.
• The ability to downgrade projects is available for the following project types: Basic MSI, InstallScript, InstallScript MSI,
Merge Module, Visual Basic 6.0 Wizard, Visual Basic .NET, C# .NET, and Visual C++ .NET, and Web.
• When you save your project to an earlier InstallShield version, the schema of your project is modified to conform to
the earlier version; any tables or columns that are available in the later version of the InstallShield product but not in
the earlier version are lost during the downgrade process.
• If you save an InstallScript project as an earlier schema version, the script file (.rul) is not downgraded to the earlier
version; only the .ism file is downgraded. If a script file created or modified in the later version of the InstallShield
product contains functions that are not available in the earlier version, your script will not compile in the earlier
version.
Create ‘Project Name’ subfolder and save the project in the created folder
This check box controls where the project file is located on your system. To create a <Project Name>
subfolder in the location specified in the Project Location box (on the File Locations tab of the Options
dialog box) and to save the project in that subfolder, select this check box. For projects that contain
InstallScript, the Script Files folder is also created in this subfolder.
To save the .ism project in the location specified in the Project Location box (see above), clear this check
box.
Update the project settings appropriately based on the new project name
To use the name that you specified in the File name box as the new project’s Name property (on the
Product Properties property sheet of the General Information view), select this check box. If the new
project’s Name property should be the same as that of the original project, clear this check box.
Note: The InstallShield Help Library and other documentation uses the InstallShield script terminology.
Dialog Options
Component
Select the component that contains the file you want to enter in this table.
Files (*.*)
Select the file that you want to include in this table.
1. In the File name box, type the path to the file that has the icon and press Enter. As an alternative,
you can click the Browse button to find the file. The Icon box shows all of the icons within the file.
2. When you specify an icon file, you can select the icon to be used with the mouse or the arrow keys.
Select the View large icons option or the View small icons option to preview the icons in the
box as they appear in the standard 32 × 32 and 16 × 16 sizes.
Note: The View large icons and View small icons options have no effect on the index of the icon selected. They are
used only to preview the icons in either size.
Project: For MSM Databases, the File Location options are disabled since merge modules require you to store your files in
a .cab file which is internal to the MSM.
Note: The option to extract COM information is only enabled when you drag files to a folder or when you add a single file
to a component that does not already have any existing files. This ensures that the COM file is the only file in the particular
component.
1. Place the cursor at the point in your script where you want the string ID to be inserted.
2. On the Edit menu, point to Insert and select String Table Entry.
3. Click in the row that contains the string ID you want to use in your script.
4. Click OK to place the string ID in the script at the point where your cursor was.
InstallShield places the string ID in your script preceded by the at (@) symbol.
Dialog Options
Option Description
Identifier Click in the value of this column to change the string identifier’s
name for all languages in your project.
Value Click in the value of this column to edit the string entry’s value for
the default language.
Comment Click in the value of this column to edit the string entry’s
comment for the default language.
(Context Menu) Right-click in the Select String dialog for additional options:
• New—Adds a string entry to the list at the point where the
cursor is located.
• Delete—Removes the selected string entry from your
project.
Table 38-64:
Option Description
URL to file’s parent folder Type the URL for the parent directory of the
selected file or files. This URL is the same
one that InstallShield uses when installation
authors use the Redistributables view to
download a setup prerequisite from the
Internet to their local machines.
For example, if you selected files called
Notepad.exe and Paint.exe, and the URLs for
these files are http://www.mywebsite.com/
Folder1/Notepad.exe and http://
www.mywebsite.com/Folder1/Paint.exe,
enter the following in this box:
http://www.mywebsite.com/Folder1
The following tabs are associated with this Settings dialog box:
• Compile/Link Tab
Compile/Link Tab
The Compile/Link tab on the Settings dialog box lets you specify settings for compiling your script.
These settings apply to Setup.rul and any files included in it.
Option Description
Preprocessor Defines Specify any preprocessor definitions. Use the following format,
with no spaces before or after equal signs or commas:
MYVARIABLE1=123,MYVARIABLE2=456
Such constants can be tested in the script by #if and #ifdef
statements that control the flow of the script. For example, type
MYVARIABLE in this box, and the code in the following #ifdef loop
will be executed:
#ifdef MYVARIABLE
// Commands
#endif
After you add or change a preprocessor definition in this box, you
must compile your script for the addition or change to take effect.
Option Description
Include Paths Specify which directories InstallShield should search for source
files that have been included in the main installation’s InstallScript
code through #include statements.
Use the following guidelines for this setting:
• To specify multiple paths, separate each one with a comma.
• You can use any valid path variable in a path.
• Do not use quotation marks to specify a path.
• Since the current directory is not necessarily constant, do not
use the dot (.) operator in the paths that you specify. Instead,
use an explicit path variable such as <ISProjectFolder> to
indicate a known folder location.
• When InstallShield passes the values that you have specified
in this setting to Compile.exe, InstallShield automatically
parses the specified string to determine comma-delimited
paths. In addition, InstallShield handles path variable
replacement, surrounds the paths with quotation marks, and
then passes each path separately to Compile.exe using
multiple /i switches. However, if you separate the paths with
semicolons instead of commas, InstallShield considers the
specified paths as a single path, and it passes the single path
string to the compiler as is. In this case, no path variable
substitution or quotation mark additions occurs.
For more information, see #include.
Max Warnings Specifies the maximum number of warning messages that are
displayed.
Maximum Errors Specifies the maximum number of error messages that are
displayed.
Warning Level Specifies the types of warnings that are displayed in the Output
window.
• None—Displays no warning messages.
• Level 1—Displays any system warning message that
InstallShield is unable to handle.
• Level 2—Displays Level 1 messages, plus a message if
string length exceeds the limit.
• Level 3 (Default)—Displays all warning messages.
For more information, see Defining Constants Through the
Compiler.
Option Description
Compile before build To compile your InstallScript automatically every time that you build
a release, select this check box. Note the following behavior that
occurs if you select this check box:
• If you select the Refresh Build command on the Build menu,
your script is recompiled only if changes have been made to it
since the last compile.
• If you select the Build <name of release> command on the
Build menu, your script is recompiled, even if no changes
have been made to it since the last compile.
Note: The compiled script is not copied to the disk images folder
before the build begins because the build process automatically
copies the compiled script to the folder during the build. If the
script fails to compile because of compiler errors, the does not
continue.
Generate inline debugging If this check box is selected, debugging information is included in
information the compiled script file so a debugging information file is not
needed.
If you want to debug an installation that includes an object that you
have created, and you want to obtain debugging information from
the object, you must have compiled the object's script with this
check box selected.
Caution: Selecting this check box makes the compiled script larger
and the installation slower, and it makes it easier for others to
reverse engineer your code. Therefore, in most cases, it should
not be used when you are creating your final installation for
distribution to end users.
Warnings as errors If warnings should be treated as errors (that is, if the installation
should not be run if there were any compile warnings when the
InstallScript was compiled), select this check box.
Libraries Specify the fully qualified path to an object library (a compiled .obl
file to which you want the compiler to link). Separate additional
paths with a comma.
Run/Debug Tab
The Run/Debug tab lets you configure settings relevant to the running and debugging of your
installation.
Option Description
Setup Command Line Arguments Text placed in this box is written to the system
variable CMDLINE when you run the installation from
within InstallShield; this variable can be accessed in
the script.
Generate MIF File If you select this check box, the installation
automatically generates a Management Information
Format (.mif) file when you run the installation from
within InstallShield. For information on generating
.mif files in the installation that you distribute, see
The [Mif] Section.
MIF Filename Specifies the name of the .mif file generated by the
installation when you run the installation from within
InstallShield. If you leave this box blank, the .mif file is
named Status.mif.
Product Serial Number If you specify a serial number, the installation adds it
to the .mif file it generates when you run the
installation from within InstallShield.
Log File
Type the name of the log file that will be created when your installation is run.
Project: For InstallScript MSI projects, you need to type the full path to the log file in this box.
Dialog Options
Option Description
Setting The full path and file name of the source file on the desktop computer
to be included in the installation.
The Setup Prerequisite dialog box also enables you to specify a location for the selected setup
prerequisite. To learn more, see Specifying the Location for Setup Prerequisites at the Release Level.
Setting Description
Build Location When you package an installation that includes setup prerequisites, you
can use any one several methods for supplying the prerequisite files to
end users:
• Download From The Web—Downloads all of the setup
prerequisite files included in your project (if necessary) from the
URL specified in the setup prerequisite (.prq) file for each
prerequisite.
• Extract From Setup.exe—Compress the setup prerequisite files
into Setup.exe, to be extracted at run time, if necessary.
• Copy From Source Media—Store the setup prerequisite files at
the root directory of the source media.
Note that if a setup prerequisite is added to a project as a dependency
of another prerequisite, the location for the prerequisite dependency
follows the location setting of the prerequisite that requires it.
Release Flags Type a string. The string can be any combination of letters or numbers.
To have more than one flag on a prerequisite, use a comma to separate
the flags
Note: If a setup prerequisite is added to a project as a dependency of another prerequisite, the location for the
prerequisite dependency follows the location setting of the prerequisite that requires it.
Dialog Options
Option Description
Display Name This is the name of the shortcut as it appears on the Windows
Mobile device or smart device. It is not necessary to add the
.LNK file name extension to the name of the shortcut.
Target This property indicates the full path and file name of the file on
the Windows Mobile device or smart device that is to be
executed when the shortcut is clicked. The list contains the
paths to all of the files being installed onto the Windows Mobile
or smart device. Select the appropriate file from the list.
Platform
Workaround Explanation
Using a Setup DLL Another way to work around this limitation is to write a
setup .dll that uses the SHGetSpecialFolderLocation() and
SHCreateShortcut() APIs to locate the Start
Menu\Programs folder and create the subfolder and
shortcut on the device. The setup .dll would also be
responsible for the removal of the subfolder and shortcut
during uninstallation.
Note: At runtime, InstallShield will verify that all database servers selected by the end user meet the specified
requirements.
Customize
Rarely, you will want to define your own database server version, but in the cases that you must, check
the Customize box and any of the following options that apply:
Table 38-71:
Option Description
Table 38-71:
Option Description
Service Pack Level This is the server pack level number returned by a
SQL Server. For example, SQL Server version 7
RTM returns 623.
Any Greater than Major Version Check this option to support future major versions.
Any Greater than Service Pack Level Check this option to support future service packs.
• Language/Tabs Tab
• Keyboard Tab
• Misc Tab
Color/Font Tab
The Color/Font tab lets you view and modify the foreground color and—in some cases—the background
color for various script elements. It also allows you to change the font, style, and size of script content.
Color
Option Description
Font style Displays the currently selected font of the script element selected
in the Item menu, if applicable.
Font
Displays sample text to which the currently selected font, style, and size are applied. Click the Change
button to display the Font dialog. The Font dialog allows you to view or modify the font, style, and size of
script content.
Language/Tabs Tab
The Language/Tabs tab lets you view and modify the auto indentation, tabs, and language settings for
the script.
Option Description
Option Description
Tabs This section allows you to specify tab behavior in the Script
Editor.
• Tab Size—Set the tab size as a multiple of the character
space size. For example, setting a tab space of 5 causes
the cursor to move five character spaces when you press
the Tab key.
• Convert tabs to spaces while typing—As tabs are
typed, they are converted to the number of spaces
specified in the Tab Size edit box.
Correct text case while typing Select this option to have text case automatically corrected
language keywords while you are typing in the Script Editor. For example, if you
have the InstallScript language selected and type
featuregetdata in the Script Editor, it will automatically
change to FeatureGetData when you finish typing the function
name.
Keyboard Tab
The Keyboard tab lets you view and modify keyboard shortcuts for various editing commands.
Option Description
Option Description
New Key Assignment Enter the keyboard shortcut to be assigned to the command
selected in the Commands list box. Press the keys, rather than
typing their names. For example, if you want the shortcut to be
Ctrl+Q, you should press the Ctrl and the Q keys simultaneously.
Assign the shortcut by clicking the Assign button.
If the keyboard shortcut you enter is already assigned to a
command, you are shown (below the New Key Assignment edit
box) what command to which the keyboard shortcut is assigned.
If you click the Assign button, the keyboard shortcut you entered
is added to the list of keyboard shortcuts for the selected
command and removed from the list of keyboard shortcuts for
the command to which that shortcut was previously assigned.
Assign Assigns the keyboard shortcut in the New Key Assignment edit
box to the command selected in the Commands list box.
Disabled if there is no keyboard shortcut in the New Key
Assignment edit box.
Misc Tab
The Misc tab lets you control miscellaneous Script Editor functionality.
Option Description
Smooth scrolling If selected, scrolling is smooth when you scroll the window
vertically by one line or horizontally by one character. If this
option is deselected, scrolling occurs in a single step.
Show left margin If selected, the Script Editor has a left margin in which you can
click to select an entire line of text and in which bookmarks, if
any, are displayed.
Line tooltips on scroll If selected, a tooltip showing the line number of the uppermost
line in the window is displayed while you press and hold the
mouse button over the vertical scroll box.
Allow drag and drop If selected, you can drag and drop selected text within the
Script Editor or between the Script Editor and any window
supporting OLE text drag and drop. Dragging the text moves
it—drag the text while pressing and holding the Ctrl key.
Option Description
Allow column selection If selected, you can select one or more columns by pressing
and holding the Alt key while selecting with the mouse. You can
select a column having a width of zero characters. This is
useful for inserting text in multiple lines.
Confine caret to text If selected, the caret will appear alongside the right end of the
text in the row in which you click. For example, if the following
code appears in the Script Editor:
szMsg = "";
...and you click anywhere to the right of the code text, the
cursor will appear immediately to the right of the semicolon in
the code.
Color syntax highlighting If selected, script elements are colored according to the
settings in the Color/Font tab’s Color area and the Language/
Tabs tab’s Language list box. If this option is deselected, only
the window and left margin are colored.
Show horizontal scrollbar If selected, a horizontal scroll bar is displayed when the width
of the script text exceeds the width of the Script Editor.
Show vertical scrollbar If selected, a vertical scroll bar is displayed when the height of
the script text exceeds the height of the Script Editor.
Allow horizontal splitting If selected, a split box is displayed at the left of the horizontal
scroll bar. To split the window horizontally, double-click the split
box or drag it into the desired position.
Allow vertical splitting If selected, a split box is displayed at the top of the vertical
scroll bar. To split the window vertically, double-click the split
box or drag it into the desired position.
Line numbering
In this section, you can indicate whether you want line numbering in the Script Editor and you can select
a line numbering style.
Option Description
Option Description
Start at The number in this field indicates the Script Editor line at which line
numbering should begin.
Option Description
Unlimited If selected, the number of editing actions that can be undone in the
Script Editor is unlimited.
Limited to If the option button is selected, the number of sequential editing actions
that can be undone is limited to the number entered in the edit box.
Selecting this option can save memory by limiting the size of the undo
buffer.
Tip: To undo an editing action, press the keyboard shortcut for the Undo command—Ctrl+Z or Alt+Backspace by
default—or right-click in the Script Editor and select Undo from the context menu.
InstallShield includes many wizards to assist you in creating your installation project.
Project: Not all wizards are available with all project types.
The following wizards are available in InstallShield.
• Access 2000/2002/2003 Object Wizard
• Component Wizard
• Dialog Wizard
• Function Wizard
• Palm OS Wizard
• Publish Wizard
• Release Wizard
• Transform Wizard
• Visual Studio .NET Wizard for Visual Basic .NET, C# .NET, and Visual C++ .NET
• Summary Panel
Welcome Panel
The Access 2000/2002/2003 Object Wizard allows you to configure a Microsoft Access 2000/2002/
2003 object that you have added to your setup project. In the Access 2000/2002/2003 Object Wizard,
you indicate the path to the Access 2000/2002/2003 redistributable disk image and specify a build
location for the redistributable.
The wizard provides your setup project with the functionality to run the Access 2000/2002/2003
redistributable, however it does not add specific database (.mdb) files to your project. You can include
the database (.mdb) files that your project requires in your setup design.
At build time, the Access 2000/2002/2003 object adds the Access 2000/2002/2003 redistributable
files to your setup’s disk image. The object also adds two nested install custom actions to your setup—
InstallAccess and UninstallAccess.
Caution: Your setup must be uncompressed on the source medium if you plan on including the Access 2000/2002/2003
object in your setup. If the setup is compressed, the setup cannot locate the Access 2000/2002/2003 redistributable
files.
Click Next to indicate the path to the Access 2000/2002/2003 redistributable disk image in the
Redistributable Path panel.
Note: You can find the Access 2000/2002/2003 redistributable disk image on Microsoft’s Access 2000/2002/2003
Developer CD or you can download the redistributable files from Microsoft’s Internet site.
Task In the Redistributable Path panel, indicate the location of the Access 2000/2002/2003 redistributable disk
image. Specify the absolute path to the disk image—including the name of the main .msi package—in either
of the following ways:
• Type the complete path to the disk image in the text box. You can use a path variable.
• Click the Browse button to navigate to the disk image’s location.
Click Next to indicate the build location for the Access 2000/2002/2003 redistributable in the next
panel.
Note: The object will be uncompressed on your setup project’s disk image. This is the only available release configuration
for the Access 2000/2002/2003 object.
Click Next to review the Access 2000/2002/2003 Object Wizard information in the next panel.
Summary Panel
In the Summary panel, review the information you supplied for the Access 2000/2002/2003
redistributable object.
If any of the information in the Summary panel is incorrect, click the Back button to return to the
previous panels. Otherwise, click the Finish button to close the wizard and add the Access 2000/2002/
2003 redistributable to your setup project.
Task To configure an Access application, launch the Access 97 Object Wizard as described below:
• Summary Panel
Welcome Panel
This object allows you to install the files required to run an Access application. You do not have to
configure the Access 97 object if all you want to do is install the Access run-time files, but not set up an
Access application.
Click Next to begin customizing the Access object to fit your needs in the next panel.
Panel Options
Database
Enter the fully qualified path to the .mdb file as it is stored on the target system. Instead of hard-coding
a path, you can select a Windows Installer folder property from the combo box.
For example, if you are installing MyApp.mdb to the destination folder [INSTALLDIR]Database, then
you can safely point to the following path as the location of your database:
[INSTALLDIR]Database\MyApp.mdb
It is your responsibility to make sure that the database exists on the target system or a network location.
The database file is not automatically added to your setup project when you enter its path into the
Database field.
Create shortcut
Select this option to add a shortcut to your Access 97 database on the Programs menu. Since a shortcut is
an element of a component’s data, a new component named Access97Shortcut is added to the Access
object’s feature after you complete the wizard. The shortcut has the default name AccessShortcut.
The shortcut is supplied with initial properties based on your settings in the Access 97 Object Wizard.
The most complex of these properties is the shortcut’s argument; the following table explains how the
command-line argument is constructed:
Parameter Description
[database] [database] contains the fully qualified path to the .mdb file that
you provided in the Database field (above).
Parameter Description
/profile [profile name] This parameter opens the database with the user profile you
enter in the Additional Information panel.
/wrkgrp [file name] This parameter instructs Access to use the specified workgroup
information (.mdw) file.
Panel Options
User profile
This is the name of the custom user profile you are creating. This field is required if you want to use a
custom user profile.
This profile applies to all users who open the Access application with the /profile <profile name>
command-line parameter. This profile name is supplied for the shortcut’s argument if you chose to
create a shortcut.
Title bar
Enter a new title for the title bar of your Access application. If you leave this field blank, the title bar
defaults to “Access 97.”
Icon
Enter the path and file name of the icon (.ico) file you want to be displayed to the left of the title bar. If
you leave this field blank, the default Access icon is used.
The path for the icon is the folder where it will be stored on the target system. Instead of hard-coding a
path, you can select a Windows Installer folder property from the combo box. If you are installing this
icon as one of your component’s files, use the same path as the component’s destination folder.
Help file
Enter the path and file name of the Windows help (.hlp) file, if any, that you have created for your Access
application.
Splash screen
Enter the path and name of the bitmap (.bmp) file that will be displayed as the splash screen for your
Access application. You can leave this field blank.
Panel Options
Workgroup file
Enter the path and name of the workgroup file as it can be found on the target system. Once you enter a
value into this field, the check boxes become enabled.
Instead of hard-coding a path, you can select a Windows Installer folder property from the combo box. If
you are installing this icon as one of your component’s files, use the same path as the component’s
destination folder.
Summary Panel
In this final step in the Access 97 Object Wizard, you can review the choices you made in the previous
steps. This dialog box displays the configuration you selected for the user profile and workgroup for your
Access database application.
If these settings are incorrect, click the Back button to return to the previous steps. If you are satisfied
with these choices, click the Finish button to close the wizard.
Tip: If you have not already done so, add your database, workgroup, and other files to your setup project.
In most cases, you should acquire a unique license for each version of your product. For more
information, see Acquiring a License.
The following panels are associated with the Acquire New License Wizard:
• Welcome Panel
Welcome Panel
The Welcome panel is where you create a user name and password to log on to the InstallShield
Activation Service Publisher Web Site if do not already have them. You need a user name and password
in order to be able to connect to the license server and download a license. Your user name must have
write access to the licensing part of the Web site.
Option Description
Description Type a description for the license that you are obtaining. The
description that you enter is for your reference only; it is not
displayed to end users of your product.
User name Type your user name for the InstallShield Activation Service Publisher
Web Site. The default value for this box is the value entered on the
Configure Trialware tab of the Options dialog box.
Password Type the password for your user name. The default value for this box
is the value entered on the Configure Trialware tab of the Options
dialog box.
Note: The BDE module is available only if a Borland tool was present on the system when you installed InstallShield.
Note: When you add the BDE merge module to an installation, a single-file installation cannot be created. You need to use
a utility like PackageForTheWeb to compress and package your installation into a single, self-extracting executable file.
• Summary Panel
Welcome Panel
The BDE designer allows you to customize the BDE run-time files installed on the target system. The
customization of these files is a crucial part of your setup and requires in-depth knowledge of BDE
architecture. This merge module requires that Borland Delphi be installed on your build machine.
Click Next in the Welcome panel to begin customizing your BDE installation.
Note: When you add the BDE merge module to a setup, a single file setup cannot be created. Instead, you need to use a
utility like PackageForTheWeb to compress and package your setup into a single, self-extracting executable file.
Panel Options
Create a new BDE configuration file
Select this option if you would like to create a new BDE configuration file. Click the Browse button to
navigate to the directory where you would like this file created.
Dialog Options
Alias
Select from the list the Alias you would like to include in your setup. If you have not created an alias yet,
click the Add button.
Add
Click the Add button to view the Add Alias panel and add aliases to your setup.
Edit
Click the Edit button to change the settings of an alias.
Delete
Click the Delete button to remove an alias from the list.
Driver
Check the box next to the driver or drivers you would like to install. If you know the necessary driver is
already on the target machine you can skip this step.
Panel Options
Alias Name
Select a pre-configured alias from the list or enter the name of a new alias.
Driver Name
If you selected a pre-configured alias, this field contains the appropriate driver. If you are creating a
custom alias, select the driver you would like your alias associated with.
Note: The driver you select here is not installed unless you check it in the BDE Merge Module Configuration Utility.
Parameter Overrides
If you selected a pre-configured alias the default parameter overrides appear in this text box. Type in
custom overrides or accept the defaults as needed by your application. For custom aliases, you can press
the Defaults button to show the default parameters for the driver you selected.
Defaults
Click the Defaults button to revert the parameter overrides to their default state.
Clear
Click the Clear button to clear the parameter overrides text box.
Summary Panel
The Summary panel displays all the configuration settings you supplied for your BDE installation.
Review these settings to ensure accuracy and click the Finish button to have the BDE merge module
added to your setup.
Note: When you add the BDE merge module to a setup, a single file setup cannot be created. Instead, you need to use a
utility like PackageForTheWeb to compress and package your setup into a single, self-extracting executable file.
Component Wizard
Although there are several ways to create Windows Installer components and specify advanced
settings for them, the Component Wizard simplifies the process. The wizard assists you
by organizing your files into components and making settings for files with advanced
installation requirements—often by automatically retrieving information about the
files.
When you launch the Component Wizard, you are presented with the following options in the Welcome
panel:
• Create components for me using Best Practices.
Welcome Panel
Project: This topic does not apply to the following project types:
• InstallScript
• InstallScript Object
Although there are several ways to create Windows Installer components and specify advanced settings
for them, the Component Wizard simplifies the process. The wizard assists you by organizing your files
into components and making settings for files with advanced installation requirements—often by
automatically retrieving information about the files.
Tip: The Component Wizard should not be used to modify existing components. When you have created your components,
you can edit their properties, files, and advanced settings in the Setup Design–Components view.
Panel Options
Create components for me using Best Practices.
Select this option to give the wizard all of your application’s files and have it create all of the necessary
components for you according to Setup Best Practices.
Destination Panel
The first step is to specify the folder where the components’ files will be installed on the target system.
Note: The Destination field is disabled if you launch the Component Wizard by right-clicking on a destination in the Files and
Folders view. The destination that you selected before launching the Component Wizard becomes the destination for the
component that you create.
Panel Options
Destination
The wizard uses the same destination folder for all of the components it creates. The destination you
select in this field becomes the Destination Folder property for every component created in this wizard
session.
Select a Windows Installer folder property, in square brackets, from the drop-down list of standard
destination folders. The default value points to the root of INSTALLDIR, which is initialized in the
product’s Destination Folder property.
Select “Browse, create, or modify a directory entry...” from the drop-down list to display the Browse for
Directory dialog.
Files Panel
In the Files panel, specify the files that should be grouped into components.
Panel Options
Files
The Files list displays information about each file associated with this component.
• Drag and drop files from Windows Explorer onto the file list.
• Click Add Files and browse to your application’s files.
Note: The path to each file is a hard-coded link. If the file is moved or renamed, the Link To value reads *** File Not Found
***, and the Release Wizard will be unable to resolve the file link when you build your setup package.
Add Files
Click Add Files to browse to the files you want to add to the list. In the resulting dialog you can select as
many files as you want from a single folder by pressing the SHIFT or CTRL key and clicking on the files.
You can also use the Insert key to add files.
Add Folder
Click Add Folder to browse to a folder that you would like to add to the list. All the files under this folder,
including any files in subfolders, will be added to your project.
Remove Files
Select one or more files and click Remove Files to permanently delete them from the list.
You can also use the Delete key to delete files.
Summary Panel
The Summary panel displays the components’ settings. Review the summary, and click Finish to
complete the component creation process and organize the files into components.
If you launched the wizard by right-clicking on a feature, the new components are associated with that
feature. Otherwise, you must go into the Setup Design view, right-click on one or more features, and
select Insert Components to associate your new components with features.
The Component Wizard provides smart defaults for most of your component properties and any
necessary advanced settings. To edit them, select a component in the Components or the Global view
and modify the component’s data and property sheet.
Note: Components that are not associated with a feature are displayed with the orphaned component icon.
Panel Options
Component Name
When you click a component type, the wizard suggests a unique name for your new component in the
Component Name field. To change the name, type a new name over the suggested name.
Note: Although you can specify a single component type for multiple font files or multiple NT services in one file, these are
all placed into a single component and require only one component name.
Component Types
The wizard can create one of the component types listed below. Click on a component type to view a
description.
• COM Server
• Install NT Service
• Control NT Service
• Fonts
Note: The PATH system variable on the build machine must be set to include the directories of all of the .dll files to which
the COM server links; otherwise, the file will fail to register and COM information will not be extracted.
The wizard asks if your COM server runs as an NT service, so you can specify installation parameters for
the service.
Panel Options
COM Server File
Enter the path and file name of your COM server (.exe, .dll, or .ocx) file, or click the Browse button to
navigate to the file.
You can specify only one portable executable per component according to Setup Best Practices. Launch
the wizard again to install additional COM servers, or create the components using the Component
Wizard’s Best Practices option.
Tip: If you are working on a Basic MSI project, an alternative to extracting the COM information through the wizard and
maintaining it in the COM Registration advanced setting is to have the data dynamically extracted at build time. If you are
working in Direct Edit Mode, COM information cannot be extracted at build time; it is extracted at design time.
If you do not select this option or if the wizard cannot read the file’s registration, the Classes panel is
displayed next.
Classes Panel
This panel is where you begin providing registration information for your COM server—including your
file’s classes, identified by their progIDs and CLSIDs.
This panel and the next few registration information panels are displayed only if you elected not to have
the wizard extract the information, or if the wizard failed for any reason (for example, if the .exe, .dll, or
.ocx file does not indeed contain a COM server). Otherwise, the wizard would continue with the NT
Service Executable panel—if the COM server is a service, or the Summary panel—if the COM server is
not a service.
Panel Options
ProgID
Enter the COM server’s programmatic identifier, or progID in this panel. Each progID corresponds to a
COM class in your file. To add a new progID in the format Program.Component.N, click the Add button
or press the Insert key.
Enter the same value in both the ProgID and Version-Independent ProgID fields if the progID is version
independent (in the format Program.Component).
All of the other information in this panel corresponds to the class you named in this field with a progID.
Click on each progID to set its class ID and version-independent progID and to check whether it is
DCOM/COM+ enabled.
Add
Click Add to register a new class for this COM server. To rename the service, type the new name
immediately after clicking the Add button, or press F2 and then type the new name.
You can also use the Insert key to add a new service.
Remove
Click Remove to permanently delete a progID from the list. You can also use the Delete key to remove a
service.
Class ID
Click on a progID to provide the corresponding class ID. Enter a string GUID for the CLSID that
Windows Installer will register for this class.
Version-Independent ProgID
Click on a progID to provide the corresponding version-independent progID, if any, in the format
Program.Component.
If the progID itself is version independent, enter the same progID in this field.
Panel Options
Context Type
Select a context type from the drop-down list.
• InprocServer—16-bit DLL or OCX
• InprocServer32—32-bit DLL or OCX
• LocalServer—16-bit EXE
• LocalServer32—32-bit EXE
Panel Options
Type Library Description
Provide a brief description of the type library.
This value is used in the component’s COM Registration advanced setting as the type library’s name in
the COM Registration Explorer. The description is registered as the default value under
HKEY_CLASSES_ROOT\TypeLib\<libID>\<version>.
Language
Enter the decimal value of the type library’s locale ID.
Since type libraries are usually language neutral, 0 (zero) is the most common language of type libraries.
Version
Provide the version number of the type library. If this field is blank, Windows Installer automatically
determines the version of the type library at run time.
Panel Options
AppID GUID
Enter the string GUID (AppID) for this COM+ or DCOM component. You can paste (Ctrl+V) the AppID
into this field.
Panel Options
Activate at Storage
Check this box to indicate that the distributed COM server resides on the same machine as its data.
When a DCOM file is activated at storage, its objects are instantiated on the same machine as the data it
uses, thereby reducing network traffic. Note that calling applications can override this default behavior
with DCOM API functions.
Note: If you indicated—in the COM Server Executable panel—that this file runs as an NT service, the next panel displayed
is the NT Service Executable panel, in which you must enter information about this file’s services.
Service Name
Enter the name of the service.
Service Parameters
Enter the parameters you want passed to the service when it is launched.
Summary Panel
Review the component’s description and click Finish to have the wizard create the described
components. Click Back if you need to change any of the information you provided.
All of the registration information that maps to the COM Registration advanced setting is written there.
The wizard creates any additional entries, such as the InProcServer32 ThreadingModel value, in the
component’s registry data.
If the wizard lists “Please enter this information in the IDE,” go to the component’s COM Registration
(or Install NT Services for components that also run as a service) advanced setting and provide the
values.
If you launched the wizard by right-clicking on a feature, the new components are associated with that
feature. Otherwise, you must go into the Setup Design view, right-click on each feature, and select Insert
Components to associate your new components with features.
Note: Components that are not associated with a feature are displayed with the orphaned component icon.
Launch the wizard again or modify the component’s Control NT Service advanced setting.
Launch the wizard again and select the Install NT Services component type or add the service’s file to the
Control NT Service component you have created in the wizard and edit its NT Services advanced setting.
Note: To control more than one service in the same component, you must modify the component’s Control NT Service
advanced setting.
Panel Options
Service is present on target system
Select this option to control a service that you are certain will be installed on the target system when
your setup runs or that will be when your product is uninstalled.
Service Name
Enter the name of the service. This is the name that InstallShield, Windows Installer, and the Service
Control Manager (which maintains the system’s database of services and exposes an interface for
controlling these services) use to identify a service—not its display name.
Note: This option is disabled if none of your components has a service in its NT Services advanced setting.
Panel Options
Trigger the following events when the component is installed
Click this option to enable the installation control events.
Arguments
Specify any arguments that you want passed to the service when it is started. Separate each argument
with a comma.
Panel Options
Trigger the following events when the component is uninstalled
Click this option to enable the uninstallation control events.
Arguments
Specify any arguments that you want passed to the service when it is started. Separate each argument
with a comma.
Summary Panel
Review the information the wizard has collected, and click Finish to create your Control NT Service
component.
If you launched the wizard by right-clicking on a feature, the new component is associated with that
feature. Otherwise, you must go into the Setup Design view, right-click on a feature, and select Insert
Components to associate your new component with a feature.
Note: Components that are not associated with a feature are displayed with the orphaned component icon ( ).
You can review and edit the new component’s properties in the Setup Design views.
After the wizard finishes, you can modify any of the control events in the component’s Control NT
Service advanced setting.
Tip: If the file also runs as a COM server, a better way to create the component is to select the COM Server component
type and specify that it contains an NT service. Once you have provided all the COM registration data, the Component
Wizard will the prompt you for the same information about the service that you must provide for the Install NT Services
component type.
The wizard takes you through a series of panels prompting you for information about the services you
want to install. Once you have completed the wizard, you have a new component consisting of your file,
the default component properties, and the advanced settings necessary for installing and uninstalling
the NT services.
You can edit the services’ installation information in the component’s NT Services advanced setting.
Windows Installer will pass these values to the Windows API function CreateService() to install each
service onto the target system and register it with the Service Control Manager (which maintains the
system’s database of services and exposes an interface for controlling these services).
Panel Options
NT Service Executable
Enter the fully qualified path to the executable file for the NT services in this component or click the
Browse button to navigate to the NT service’s executable file. In compliance with Setup Best Practices,
the component can contain only one executable. Launch the wizard again later to add another file to a
new component.
If you have arrived at this wizard panel as the result of having a COM Server component that contains
NT services, the NT Service Executable field is disabled. The wizard uses the same executable that you
entered in the COM Server Executable panel.
Caution: If you use the Browse button to navigate to and select a file, the new value overwrites anything that was entered
in the NT Service Executable field.
Services
This list contains all of the services found in the file.
Add
Click Add to add a new service. To rename the service, type the new name immediately after clicking the
Add button, or press F2 and then type the new name. This is the name that InstallShield, Windows
Installer, CreateService(), and the Service Control Manager (which maintains the system’s database of
services and exposes an interface for controlling these services) use to identify the service—not its
display name.
You can also use the Insert key to add a new service.
Remove
Select a service and click Remove to permanently delete it from the Services list. You can also use the
Delete key to remove a service.
Panel Options
NT Service
Select the services that you entered in the Services list of the NT Service Executable panel and then
specify the Display Name and Service Type installation properties for each.
Display Name
Enter a display name for the service. This is the name that is displayed to users in the SCM. If you leave
the Display Name field blank, the name you gave the service is used as the display name.
Note: Other service properties, such as the service description to display on Windows 2000 target systems (and later),
are available in the component’s advanced settings.
Service Type
Specify whether the service runs in its own process or shares a process with others. Select the “Service
shares a process with others” option only if there is more than one service in the component.
If you are familiar with the source code for the service, select “This service runs in its own process” if it is
of type SERVICE_WIN32_OWN_PROCESS, and “Service shares a process with others” if it is of type
SERVICE_WIN32_SHARE_PROCESS.
Note: You are limited to the options provided under Service Type. The Component Wizard does not support driver
services.
Arguments
Enter command-line arguments to pass to the service when it runs. Expressions of the form
[PropertyName] will be expanded to the value of the Windows Installer property called PropertyName.
Start Type
Select the service’s start type from the list.
• Automatically when the system starts up
• On demand through the Service Control Manager
• By the operating system loader (Boot)
• By calling the ToInitSystem function (System)
• Not started (Disabled)
Panel Options
NT Service
Select each of the services that you entered in the Services list of the NT Service Executable panel and
then specify its load-ordering and dependency information.
Load-Ordering Group
Enter the name of the load-ordering group of which this service is a member. Leave this field blank if the
service does not belong to a group.
Dependencies
List the service’s dependencies in the edit field. A service’s dependency can be another service—in which
case enter the service’s name, or it can be a load-ordering group—in which case precede the name of the
load-ordering group with a plus sign (+) so that the SCM can distinguish it from a service.
Separate each dependency with a comma.
Caution: Because of potential password conflicts, Microsoft recommends that all services log on under the local system
account.
Panel Options
NT Service
Select each of the services that you entered in the Services list of the NT Service Executable panel and
then specify how the service should log on.
This account
Select this option if you want the service to impersonate a specific user when it logs on. You must enter a
user name and password, or the local system account will be used.
Domain/User Name
Enter accounts in the form DomainName\UserName. You can use a dot for the built-in domain,
such as .\UserName.
Password
Enter the password for this account.
The password will not be used if you do not specify a user name, and the service will log on under the
local system account.
Summary Panel
Review the information the wizard has collected, and click Finish to create your NT services component.
The wizard provides smart defaults for all of your component’s properties. You can review the property
sheet in the Setup Design views. Of particular importance for an NT service is the Remote Installation
property, since Windows Installer cannot install a service that does not reside on the local system.
If you launched the wizard by right-clicking on a feature, the new component is associated with that
feature. Otherwise, you must go into the Setup Design view, right-click on one or more features, and
select Insert Components to associate your new component with a feature.
Note: Components that are not associated with a feature are displayed with the orphaned component icon.
After the wizard finishes, you can modify any of the installation options in the component’s NT Services
advanced setting.
InstallShield provides functionality for controlling this NT service or others on the target system. For
more information, see Controlling NT Services.
Font Type
Although you can create a component in one of several ways, the easiest way to install a font (a .ttf, .fon,
or .ttc file) in a setup is to create a Fonts component in the Component Wizard.
Unlike the other component types offered in the wizard, there is no corresponding advanced setting for
Fonts components. The setting that distinguishes a Fonts component and tells Windows Installer to
install it differently is the file’s Font Title property.
An alternative to creating a Fonts component is to select the Setup Best Practices option in the
Component Wizard and let InstallShield create a Fonts component for you from your font files.
Note: If you want a font to remain on the system after the application has been uninstalled, set its component’s Permanent
property to Yes.
Panel Options
Fonts
Select the fonts you want to include in your Fonts component.
Panel Options
Fonts
Drag and drop files into the list, or click Add Fonts to browse to and add new fonts to your component.
InstallShield reads the font title from the font file. If no title is specified within the font file, click on the
font title to specify a title in the format FontTitle (FontType)—for example, Marlett (TrueType).
Add Fonts
Click Add Fonts to browse to new font files.
Remove Fonts
Select a font in the list and click Remove Fonts to permanently remove the selected font from the
component.
Note: This panel is designed to allow you to add fonts to your installation that are not installed on your machine. For
example, you might have a font file that is stored on a network drive. As a result, you cannot select fonts from your Fonts
folder since those fonts are already installed on your local machine. If you want to add a font that is installed on your
machine to your installation, click Back and select the appropriate font from the list.
Summary Panel
If you launched the wizard by right-clicking on a feature, the new component is associated with that
feature. Otherwise, you must go into the Setup Design view, right-click on one or more features, and
select Insert Components to associate your new Font component with a feature.
Note: Components that are not associated with a feature are displayed with the orphaned component icon.
When the font’s feature is selected for installation, it is automatically registered by Windows Installer.
All Font components are installed by default to the location stored in the FontsFolder property. You can
edit the component’s Destination Folder or set additional properties by editing the component’s
property sheet.
Note: If you would like a font to remain on the system even after the program has been uninstalled, be sure to set the Font
component’s Permanent property to Yes.
Unlike the other component types offered in the wizard, there is no corresponding advanced setting for
Fonts components. The setting that distinguishes a Fonts component and tells Windows Installer to
install it differently is the file’s Font Title property.
Note: Components that are not associated with a feature are displayed with the orphaned component icon.
Note: In order to convert a ClickOnce package, you must have the .NET Framework redistributable and the Visual J# .NET
redistributable installed on your machine. Note that the version numbers of these two redistributables must match.
• At the command line, enter the full path of the ClickOnce2Dim.exe file in quotation marks. For
example, if you installed InstallShield to the default location, enter the following at the command
line:
"C:\Program Files\Macrovision\IS2008\System\ClickOnce2Dim.exe"
Tip: As an alternative, you can convert the ClickOnce manifest file without using the wizard by running the
ClickOnce2Dim.exe application from the command line and specifying the appropriate command-line parameters. For
more information, see ClickOnce2Dim.exe.
• Conversion in Process
• Conversion Complete
Welcome Panel
Use the ClickOnce Converter Wizard to convert a ClickOnce package to a Basic MSI project with an
associated .dim file.
Note: In order to convert a ClickOnce package, you must have the .NET Framework redistributable and the Visual J# .NET
redistributable installed on your machine. Note that the version numbers of these two redistributables must match.
See Also
Panel Options
Option Description
ClickOnce Deployment Specify the ClickOnce manifest file (.application) that you want to
Manifest convert.
Target Location Specify the location for the .dim file and the Basic MSI project
created by the wizard.
Copy the source files to If you want the ClickOnce source files copied to the target location
the target location that you specified, select this check box. The ClickOnce source files
are placed in a folder.
If you do not want the ClickOnce source files copied to the target
location, clear this check box.
See Also
See Also
See Also
Welcome Panel
The Convert Source Paths Wizard allows you to convert your setup’s hard-coded paths to path variables.
The wizard scans your project for any use of hard-coded paths and then replaces the paths with standard
path variables.
If you have files that evaluate to existing path variables, the wizard automatically converts these paths
without providing the option of selecting a new variable. For example, if you have a file in the Program
Files folder, this path is automatically converted to the predefined path variable <ProgramFilesFolder>.
Search Panel
The Search panel displays the search status. At this time the wizard is scanning the current project for
any absolute paths. If your files evaluate to existing path variables, these files are converted
automatically.
Panel Options
Path Variable Recommendation
Indicate the variables that you want to create by selecting the corresponding boxes. If you do not want to
create one of the suggested variables, clear the check box next to it.
Rename
Select the variable that you want to rename and click the Rename button. Type the new variable name in
the Path Variable Recommendation column.
Deselect All
Click the Deselect All button to clear the check boxes next to all the corresponding suggested path
variables.
Select All
Click the Select All button to select all the path variable suggestions. When you click Apply, these
variables are created and added to your project.
Project: This topic does not apply to the following project types:
• InstallScript
• InstallScript Object
A QuickPatch project is recommended for installation authors who want to ship small, single updates to
their users. QuickPatch authoring provides a simple alternative to creating a patch in the Patch Design
view, even though it provides less customization. Fundamentally, both patch creation methods produce
the same deliverable types: .msp and .exe files.
To create a QuickPatch project for an existing .msi file or an existing QuickPatch, use the Create New
QuickPatch Wizard. Completing the wizard ensures that all basic requirements for the QuickPatch
project are met.
Caution: Creating a QuickPatch project for an earlier QuickPatch without first building the earlier QuickPatch project may
cause unexpected behavior.
Create a new project in InstallShield and select QuickPatch Project as the project type.
The QuickPatch you create using this method can be used to patch an existing .msi file or an existing
QuickPatch.
Tip: You can use the Create New QuickPatch Wizard to create a QuickPatch project for an existing QuickPatch. As an
alternative, you can open the latest QuickPatch project in InstallShield and specify that you want to create a QuickPatch
project for the current QuickPatch. For more information, see Creating a QuickPatch Project for an Existing QuickPatch.
Welcome Panel
A QuickPatch project is recommended for installation authors who want to ship small, single updates to
their users. QuickPatch authoring provides an alternative to creating a patch in the Patch Design view,
even though it provides less customization. Fundamentally, both patch creation methods produce the
same deliverable types: .msp and .exe files.
To create a QuickPatch project for an existing .msi file or an existing QuickPatch, use the Create New
QuickPatch Wizard. Completing the wizard ensures that all basic requirements for the QuickPatch
project are met.
Note: If you click Cancel or Exit in the wizard, QuickPatch project creation will be incomplete, and the QuickPatch project
will not open in InstallShield.
Panel Options
Table 39-4: QuickPatch Project Base Panel Options
Option Description
Based on an MSI package Select this option to build a QuickPatch project for an
existing .msi file. Select this option if this is the first
QuickPatch created for the application.
Based an existing QuickPatch Select this option to build a QuickPatch project for an
project existing QuickPatch. This option creates a project that can
patch existing QuickPatch projects as well as the original
.msi file.
If you select the Based on an MSI package option and click Next, the Original Setup Package panel
opens. If you select the Based an existing QuickPatch project option and click Next, the Location of
Existing QuickPatch panel opens.
Note: Once your project has been created and opened in InstallShield, there is no way to change the path to the base
installation. Therefore, if you want to patch a different installation, you must run through the Create New QuickPatch
Wizard again to create a new QuickPatch project.
Panel Options
Option Description
Original Setup Specify the location of the original/base installation or click the
Browse button. The Create New QuickPatch Wizard creates a
project that can validate this installation.
If your original installation is uncompressed, click Finish to open
your QuickPatch project in InstallShield.
Decompress Path
Click Finish to close the Create New QuickPatch Wizard and open your new QuickPatch project in
InstallShield.
Caution: You cannot decompress installations that span multiple disks from a local or network drive. You will need to find
an alternate method of decompressing the installation.
Note: Once your project has been created and opened in InstallShield, there is no way to change the path to the existing
QuickPatch project. Therefore, if you want to patch a different QuickPatch project, you must run through the Create New
QuickPatch Wizard again to create a new QuickPatch project.
Panel Options
Existing QuickPatch Project
Specify the location of the QuickPatch project (.ism file) that you would like to patch or click the Browse
button.
Welcome Panel
This panel provides an introduction to the Create Table Wizard.
Windows Logo Guideline: The Windows Logo Quality Program requires that you avoid naming a custom table with
the MSI (in uppercase, lowercase, or mixed-case letters). The MSI prefix is reserved for future use in new standard
properties and tables.
2. Click Add Column to proceed to the Column Properties panel and add the first column to the
table.
Property Description
Column Type The available types are Binary, Long, Short, and String.
Nullable Check Box Select this check box if this column’s values are nullable.
Primary Key Check Box Select this check box to make this column the table’s
primary key.
Property Description
Localizable String Check Box Select this check box if the string is localizable.
External Key Table If this column references an external table, select it from
this list
Caution: The number provided in the String Length field must be longer than the number of characters in the name
provided in the Column Name field. For example, if you provide TestColumn as the column name, the number you provide
in the String Length field must be 11 or higher.
Click Add Another Column to define additional columns, or click Done with Columns to proceed to the
Summary panel.
Summary Panel
In the Summary panel, you can review your new table’s properties before you add it to your project. If
you need to change any of the settings, click Back until you see the appropriate panel, and make the
necessary changes.
Click Finish to add the custom table.
Task To add one of the Crystal Reports objects to your installation project:
1. In the Redistributables view, select the check box for the Crystal Reports 8, Crystal Reports 8.5,
or Crystal Reports 8.5SP object.
The corresponding Crystal Reports Object Wizard opens.
2. Customize the Crystal Reports object by selecting options in the wizard.
• Export Formats
• Export Destinations
• Database Connections
• Additional Components
• Summary
Welcome Panel
The Welcome panel is the first panel displayed in the Crystal Reports 8 Object wizard. Click Next to
proceed to the Engine Access Methods panel.
Option Description
Crystal Reports Automation Server 32-bit COM object model, dispatch only
(8.0 version)
Option Description
Report Designer Component (8.0 32-bit only COM object model, dual interface,
version) apartment model
Caution: Crystal ActiveX Control requires Mfcans32.dll to be present on the target machine. The Crystal Reports object
does not add this file by default. You can add this file to your installation project in the Files and Folders view.
Option Description
SQL Expressions (8.0 version) Select this option if you want to support SQL
expressions in your Crystal reports.
Summary Panel
The Summary panel provides a summary of selections made in the previous panels of the Crystal
Reports 8 Object Wizard. It provides a listing of merge modules that will be added to your project, and
those merge modules that will be removed. It also reports merge modules that are needed but missing.
• Export Formats
• Export Destinations
• Database Connections
• Additional Components
• Summary
Welcome Panel
The Welcome panel is the first panel displayed in the Crystal Reports 8.5 Object wizard. Click Next to
proceed to the Engine Access Methods panel.
Option Description
Crystal Reports Automation Server 32-bit COM object model, dispatch only
(8.5 version)
Report Designer Component (8.5 32-bit only COM object model, dual interface,
version) apartment model
Embeddable Designer Control ActiveX Control; allows design and editing Crystal
Reports at run time
Caution: Crystal ActiveX Control requires Mfcans32.dll to be present on the target machine. The Crystal Reports object
does not add this file by default. You can add this file to your installation project in the Files and Folders view.
Option Description
Charts You can include chart functionality in your reports. Select this
option to do so.
Maps (8.5 version) Crystal Reports supports the inclusion of geographic maps in
reports. Select this option to include this functionality.
SQL Expressions (8.5 Select this option if you want to support SQL expressions in your
version) Crystal reports.
User Function Libraries Select this option if you intend to support User Function Libraries
(a separate DLL or Automation server to which you add your own
custom functions).
Page Ranged Export This is required when exporting to a format that allows you to set
a page range. These formats include Rich Text Format (.rtf) and
the Adobe Acrobat PDF format.
HTML Translation Select option if you want to include the Crystal Reports
component used for translating the report into an HTML stream.
Visual Basic 6 Runtime If your reports require Visual Basic run-time components and you
do not know whether your target has them installed, you can
include them by selecting this option.
Summary Panel
The Summary panel provides a summary of selections made in the previous panels of the Crystal
Reports 8.5 Object Wizard. It provides a listing of merge modules that will be added to your project, and
those merge modules that will be removed. It also reports merge modules that are needed but missing.
• Export Formats
• Export Destinations
• Database Connections
• Additional Components
• Other Requirements
• Summary
Welcome Panel
The Welcome panel is the first panel displayed in the Crystal Reports 8.5 SP Object Wizard. Click Next to
proceed to the Specify Engine Access Methods panel.
Option Description
Crystal Reports Automation Server 32-bit COM object model, dispatch only
(8.5 version)
Embeddable Designer Control ActiveX Control; allows design and editing Crystal
Reports at run time
Report Designer Component (8.5 32-bit only COM object model, dual interface,
version) apartment model
Caution: Crystal ActiveX Control requires Mfcans32.dll to be present on the target machine. The Crystal Reports object
does not add this file by default. You can add this file to your installation project in the Files and Folders view.
Option Description
ASP ActiveX Viewer To include the ActiveX viewer with your installation, select this
check box.
ASP Java Viewer To include the Java viewer with your installation, select this
check box.
ASP Web Report Server If your application requires the ASP Web Report Server,
select this check box.
HTML Translation If you want to include the Crystal Reports component used
for translating the report into an HTML stream, select this
check box.
Maps (8.5 version) Crystal Reports supports the inclusion of geographic maps in
reports. To include this functionality, select this check box.
Page Ranged Export This is required when exporting to a format that lets you to
set a page range. These formats include Rich Text Format
(.rtf) and the Adobe PDF.
SQL Expressions (8.5 version) If you want to support SQL expressions in your Crystal
reports, select this check box.
User Function Libraries If you intend to support User Function Libraries (a separate
.dll file or Automation server to which you add your own
custom functions), select this check box.
Summary Panel
The Summary panel provides a summary of selections made in the previous panels of the Crystal
Reports 8.5 SP Object Wizard. It provides a listing of merge modules that will be added to your project,
and those merge modules that will be removed. It also reports merge modules that are needed but
missing.
Project: This information does not apply to the following project types:
• ClickOnce
• Compact
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
The Custom Action Wizard enables you to add custom actions to your Windows Installer installation.
These actions can include launching an executable file or calling a function from a .dll file.
1. In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic
MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or Custom Actions (in
Merge Module and MSM Database projects).
2. Right-click the Custom Actions explorer and click Custom Action Wizard.
The Custom Action Wizard consists of the following panels:
• Welcome
• Basic Information
• Action Type
• Function Definition
• Action Parameters
• In-Sequence Scripts
• Additional Options
• Respond Options
• Summary
Windows Logo Guideline: If you are applying for the Windows Vista logo, any custom actions in your installation must
follow best practices guidelines for custom action creation. You can use the Certified for Windows Vista Validation Suite
(plus InstallShield ICEs) to verify whether your installation package meets most of the custom action–related logo
requirements. However, some of the requirements cannot be verified through the validation suite. To learn more, see
Guidelines for Creating Custom Actions that Meet Requirements of the Certified for Windows Vista Program.
Welcome Panel
The Welcome panel provides a brief introduction to the Custom Action Wizard. The wizard helps you
build a custom action that will perform tasks not inherently supported by Windows Installer.
Windows Logo Guideline: If you are applying for the Windows Vista logo, any custom actions in your installation must
follow best practices guidelines for custom action creation. You can use the Certified for Windows Vista Validation Suite
(plus InstallShield ICEs) to verify whether your installation package meets most of the custom action–related logo
requirements. However, some of the requirements cannot be verified through the validation suite. To learn more, see
Guidelines for Creating Custom Actions that Meet Requirements of the Certified for Windows Vista Program.
Panel Options
Name
Enter the name of your custom action. The name can contain only letters, numbers, underscores, or
periods, and it must begin with a letter or an underscore.
Comment
You can enter any comments about your action in this box. This information is for your reference only
and is not displayed to the end user.
Panel Options
Type
The Type list provides options for several different ways of executing your custom action. For example,
your custom action can call an executable file, run VBScript code, or call a function from a .dll file. The
following options are available in this list:
• Launch an executable—Select this option to create a custom action that launches an executable
file.
• Call a function in a standard dynamic-link library—Select this option to create a custom
action that calls a function in a .dll file. Specify the function name, parameters, and return value in
the Function Definition panel.
Note: The Call a function in a standard dynamic-link library option is not available for Merge Module projects.
Important: Nested installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft Corporation
recommends that you avoid using nested installations and nested-installation custom actions to install products that are
intended to be released to the public. To learn more, see Concurrent Installations on the MSDN Web site.
Location
The code that your custom action calls can be stored in one of several places. Select the location where
the installer should look for that code. This list is not available if you select Set a property or Set a
directory in the Type list.
• Stored in the Binary table—Select this option to have your code base stored in the Binary table.
This option is useful if you do not want the file to be installed on the target system.
• Installed with the product—Select this option to call code from a file or executable file that is
going to be installed on the target system.
• Stored in the Property table—Select this option to reference a full path to the executable that
you want to launch. The path is stored in the Property table. This option is available only if you are
launching an .exe file, calling JScript code, or calling VBScript code as part of the custom action.
• Stored in the Directory table—Select this option to reference a path—without the file name—
that is stored in the Directory table.
• Stored directly in the custom action—Select this option to enter code directly into the wizard,
without having to associate a file. This option is available only if you are calling JScript or VBScript
as part of the custom action.
• Included within your main setup—Select this option if the .msi file that you want to launch is
stored within your main installation package. This option is available only when you launch a second
.msi package from within your installation.
• Stored on the source media—Select this option if the .msi file that you want to launch is stored
on the same media as your main installation package. This option is available only when you launch
a second .msi package from within your installation.
• An application that is advertised or already installed—Select this option to uninstall any
Windows Installer applications that are currently installed on the target system—for example,
applications that you previously installed with a custom action. You should have this custom action
launch only on uninstallation of your main installation. This option is available only when you
launch a second .msi package from within your installation.
• Destination machine search path—When you call a function in a standard .dll file, the file can
be present on the target system’s path.
• If you call a function in a standard .dll file that is stored in the Binary table, you cannot use deferred or rollback
execution for the action’s In-Script Execution property.
• If you call a function in a standard .dll file that is installed with the product and the action is scheduled as deferred (for
the In-Script Execution property), the .dll file that you are calling must be the component’s key file.
Note: The function must use the __stdcall calling convention. Functions with more than one parameter will not work
properly if this convention is not used.
Panel Options
Name
Specify the name of the function that you want to call. The .dll file can have a single entry point for each
custom action.
Arguments
Build the list of arguments—in order—that you want to pass to the function.
First, click the last row of the Arguments list to add a new argument. Next, complete the Type, Source,
and Value columns for each argument.
Type
In this list, select the data type of the parameter. Note that there are two special cases for argument
types, and these cases are identified below.
Task To set a handle to the .msi database or the Windows Installer window:
Source
Indicate how you want to pass the data to the function. The following options are available in this list.
Option Description
Constant The value that you want to pass is stored as a literal in your installation
project. After you select Constant for the argument’s source, enter its
definition in the Value column.
This “constant” does not require a name or identifier. Do not enclose
string literals in quotation marks.
Option Description
in Property Select in Property for the source to specify the name of a Windows
Installer property whose value will be passed to the function. This type
of argument is suitable for a ByVal parameter.
inout Property This source type is similar to a ByRef parameter. Select inout Property
for the source to specify the name of a Windows Installer property
whose value will be passed to the function and can be modified by the
function.
out Property An out property serves as a placeholder for a value that can be set by
the function. No value is passed to the function, but the function
requires the name of a property whose value it can modify.
When you select a property for the argument’s source, you must specify the name of the property in the
Value column.
Value
The value can be one of two types:
• A number or string literal that you enter when the argument’s source is a constant
• A Windows Installer property when the argument’s source is a property
Note: When you set the Type list to HANDLE and the Source list to Constant, the Value column contains two options:
MsiHandle and MsiWindowHandle. These constants can be used to get a handle to either the .msi database or the
Windows Installer window.
When the source is a property, the Value list provides the name of every property in the Property
Manager. You can select an existing property or enter a new name, in which case the new property is
added to the Property Manager.
Remember that a property is merely a container for a value. If your parameter stores its value in an in
property or inout property, ensure that you specify a value for the property in the Property Manager.
(Context Menu)
The context menu provides you with options for working with your arguments. To access the context
menu, right-click an argument in the Arguments grid. The context menu options are described below.
Option Description
Option Description
Move Up The arguments must be in the precise order in which the function
expects to receive them. Click Move Up to place the argument higher
in the list.
Move Down Click Move Down to place the argument lower in the list.
Return Type
Select the data type of the function’s return value. If you do not need to check the return value, you can
accept void.
Return Property
Select the name of a property whose value will be set to the function’s return value. If you are going to
check the return value elsewhere in your installation, you may want to initialize the return property’s
value.
Silent mode
Select this check box if you do not want InstallShield to display a warning message if the custom action
fails to load the .dll file and call the function.
Panel Options
Source
This box behaves differently depending on the options you selected for the Type and Location lists on
the Action Type panel. Below are the source values you can use, depending on the type and location of
each custom action.
Launch an executable Set the source for this custom action type according to its
location.
• Stored in the Binary table—Browse to the location of
the .exe file.
• Installed with the product—Click Browse to open the
Select File dialog box. In the Component list, select the
component in which the executable is located. In the Files
list, select the executable file.
• Stored in the Property table—Select a Windows Installer
property in the list. If you specify the name of a new
property, you must later open the Property Manager, enter
the property, and specify a value that points to the .exe
file.
• Stored in the Directory table—Select one of the
standard folders in the list, or enter the name of a new
entry into the Directory table—which you can later edit in
the Direct Editor.
Call a function in a standard Set the source for this custom action type according to its
DLL location.
• Stored in the Binary table—Browse to the location of
the .dll file.
• Installed with the product—Click Browse to open the
Select File dialog box. In the Component list, select the
component in which the .dll file is located. In the Files list,
select the .dll file.
• Destination machine search path—Browse to the
location of the .dll file. The wizard uses only the file name
and not the path.
Call a function in a Windows Set the source for this custom action type according to its
Installer DLL location.
• Stored in the Binary table—Browse to the location of
the .dll file.
• Installed with the product—Click Browse to open the
Select File dialog box. In the Component list, select the
component in which the .dll file is located. In the Files list,
select the .dll file.
Run VBScript or 64-bit Set the source for this custom action type according to its
VBScript code location.
• Stored in the Binary table—Browse to the location of
the VBScript source file.
• Installed with the product—Click Browse to open the
Select File dialog box. In the Component list, select the
component in which the .vbs file is located. In the Files list,
select the .vbs file.
• Stored in the Property table—Select one of the
properties in the list. If you specify a new property, you
must later open the Property Manager, enter the property,
and specify a value that points to the .vbs file.
• Stored directly in the custom action—You can use the
In-Sequence Scripts panel, which provides a text editor for
your VBScript code.
Run JScript or 64-bit JScript Set the source for this custom action type according to its
code location.
• Stored in the Binary table—Browse to the location of
the JScript source file.
• Installed with the product—Click Browse to open the
Select File dialog box. In the Component list, select the
component in which the .js file is located. In the Files list,
select the .js file.
• Stored in the Property table—Select one of the
properties in the list. If you specify a new property, you
must later open the Property Manager, enter the property,
and specify a value that points to the JScript file.
• Stored directly in the custom action—You can use the
In-Sequence Scripts panel, which provides a text editor for
your JScript code.
Run InstallScript code You cannot change the location of the InstallScript file. For an
InstallScript custom action, you must select the name of the
entry-point function in the list.
Set a property You cannot set the location when setting a property. You must
select the name of the property in the list, or enter a new name
and specify it in the Property Manager.
Set a directory You cannot set the location when setting a Directory. You must
select the name of a folder in the list, or enter a new name and
specify it in the Directory table (available in the Direct Editor).
Launch another .msi package Set the source for this custom action type according to its
location. (For more information about custom actions that
launch another .msi package, see Nested Installations.)
• Included within your main setup—Browse to the
location of the “child” .msi file. The Custom Action Wizard
automatically creates the appropriate entries in the Binary
table.
• Stored on the source media—Browse to the location of
the “child” .msi file. The Custom Action Wizard
automatically adds this file to the Disk1 folder in the
Support Files view.
• When you build a release, InstallShield copies the .msi file
(but not its uncompressed application and support files) to
the release location.
• An application that is advertised or already
installed—Browse to the location of the “child” .msi file.
The Custom Action Wizard extracts the product code from
the .msi package that you select.
Target
The value for the target depends on the custom action type.
Launch an executable If you are launching an executable file, you can enter command-
line arguments in this box. For example, if you want to launch a
readme file that is installed with you installation, you should
enter Notepad.exe [INSTALLDIR]Readme.txt.
Call a function in a standard The target displays the function definition. For information on
DLL this format, see Calling Functions in Standard .dll Files.
Call a function in a Windows Use this box to enter the name of the function that you want to
Installer DLL call. You do not need brackets or any other special formatting,
but note that the function name is case-sensitive.
A Windows Installer .dll function has a predefined parameter
and return type. For more information, see Passing Parameters
to a .dll File Function in a Custom Action.
Run JScript/64-bit JScript or Enter the function name that you want to call.
VBScript/64-bit VBScript
code
Run InstallScript code The target value is not applicable for InstallScript custom
actions.
Set a property or directory Enter a formatted text string that evaluates to the new value of
the property that you selected or created. See the Windows
Installer Library for more information on formatted text strings.
Launch another .msi package Specify any public properties that you would like to pass to the
.msi package.
Note: Both 64-bit JScript and VBScript custom actions require Windows Installer version 2.0.
Note: The In-Sequence Scripts panel is provided for backward compatibility only. A superior script editor is available in the
Script tab of the Custom Action and Sequences view (and the Custom Actions view).
If your custom action calls JScript or VBScript code that is stored directly in the custom action, you can
enter the script in the box that is displayed. Type your code into the text box and click Next to continue.
No validation is performed on your code to check syntax.
Option Description
Wait for the action to Select this check box if you want the installation to pause while the
finish executing action executes, and then start up again when the action has finished.
Option Description
Ignore custom action Select this check box if you want the installation to ignore the return
return code code provided by the custom action. If you do not want the installation
to fail if the custom action fails, select this check box to return the
error code.
Option Description
In-Script Execution Specify when you would like your action to execute.
• Immediate execution—Select this option to have the action
execute when it is encountered in the sequence.
• Immediate execution (Terminal Server Aware)—Select this
option to have the action execute when it is encountered in the
sequence. The custom action impersonates the user during per-
machine installations on terminal server machines.
• Deferred execution—Select this option to have your action wait
until the script begins to run.
• Rollback execution—Select this option to set your action to
execute only during rollback. If you changed something to the
system during the execute sequence using a custom action, you
need to undo that change with a rollback custom action.
• Rollback execution (Terminal Server Aware)—Select this
option to set your action to execute only during rollback. If you
changed something to the system during the execute sequence
using a custom action, you need to undo that change with a
rollback custom action. The custom action impersonates the user
during per-machine installations on terminal server machines.
• Commit execution—Select this option to have your action
delayed until the installation has successfully completed the
installation script.
• Commit execution (Terminal Server Aware)—Select this
option to have your action delayed until the installation has
successfully completed the installation script. The custom action
impersonates the user during per-machine installations on
terminal server machines.
• Deferred execution in system context—Select this option if
your action needs elevated system privileges for performing
tasks such as editing the registry. The action is deferred until the
script begins to run. When the action does run, it runs with
elevated system privileges. For more information on this
property, see In-Script Execution.
Option Description
Execution Scheduling This list lets you set how many times the action executes. For
example, if an action is listed in both the User Interface and Execute
sequences, it can be set to execute both times, or it can execute only
once.
If you selected anything other than Immediate execution in the In-Script
Execution list, the Execution Scheduling list is not available and is set
to Always execute.
• Always execute—Select this option to have the action execute
every time it is encountered. Therefore, it could execute in the
User Interface sequence and again in the Execute sequence.
• Execute only once—Select this option if your custom action
should execute only once—even if it exists in both the User
Interface and Execute sequences. The action is skipped in the
Execute sequence if the User Interface sequence has run.
Note: The Execute only once option does not work for InstallScript MSI
projects. If your custom action exists in both the User Interface and
Execute sequences, it is executed twice. This is because—in an
InstallScript MSI project—the InstallScript engine executes the User
Interface sequence and Windows Installer executes the Execute
sequence.
• Execute only once per process—On Windows NT–based
machines, the User Interface sequence and the Execute
sequence run in separate processes. Select this option to force
your custom action to launch at least once in the User Interface
sequence and once in the Execute sequence.
• Always execute at least once on the client—This action
executes at least one time on the client.
Panel Options
Sequences
Select where in the Installation User Interface or Installation Execute sequence you want to insert your
custom action.
Conditions
Click the ellipsis button (...) to launch the Condition Builder dialog box, where you can create a condition
that will be used to determine whether your custom action is launched.
Summary Panel
In the Summary panel, you can review your custom action’s settings before you add it to your
installation. If you need to change any of the settings, click Back until you see the appropriate panel, and
make the necessary changes.
When your action is complete, click Finish.
You can now insert this custom action into a sequence or specify it as the argument for a dialog’s control
event.
Note: The import database functionality applies to the Microsoft SQL Server Database. Oracle users should refer to the
Oracle Web page on Oracle Database Utilities for information on utilities that may work in conjunction with InstallShield.
The Database Import Wizard helps you import your Microsoft SQL Server Database and generate a SQL
script file from the database based on options you, the installation author, determine. The wizard can be
launched from the following nodes of the SQL Scripts explorer when you right-click in the SQL Scripts
view:
• SQL Servers
• New Connection
• New Script
The following wizard panels are associated with the Database Import Wizard:
• Welcome
• SQL Server
• SQL Database
• Database Tables
• Objects to Script
• Scripting Options
• Summary
Welcome Panel
Note: The import database functionality applies to the Microsoft SQL Server Database.
The Database Import Wizard helps you import your Microsoft SQL Server Database and generate a SQL
script file from the database based on options you, the installation author, determine.
The second paragraph of this wizard panel indicates what the wizard will create.
Note: The import database functionality applies to the Microsoft SQL Server Database.
Server Name
Specify a SQL Server from the list of servers below or click Browse to select the location of a server on
your network.
Note: The import database functionality applies to the Microsoft SQL Server Database.
Database Name
Choose a database found on the SQL Server you selected in the SQL Server panel. A script file will be
generated for the database you select in the Database Name drop down list.
Note: When the generated script is executed on a target machine, this database will be automatically created if not found
on the target server.
Note: The import database functionality applies to the Microsoft SQL Server Database.
In this panel, determine which tables in the database you want to include or exclude in the generated
script file. If you choose to include or exclude certain tables, then from the Available Tables list, click the
table(s) you want, and then click the “>” button to mark the tables.
Note: Selecting the Include All Tables option guarantees that new tables added to the database are imported every time
you reimport the database.
Note: The import database functionality applies to the Microsoft SQL Server Database.
The Objects to Script panel is where you select the objects that you want to import from the database.
Objects
Determine which objects to import from your SQL Database. Many of these objects represent and
expose attributes of a single Microsoft SQL Server database object.
Note: The Records option is unavailable if no tables are selected to be imported in the Database Tables wizard panel.
Note: The import database functionality applies to the Microsoft SQL Server Database.
The Scripting Options panel in the Database Import Wizard is where you specify whether your script
should be compatible with Microsoft SQL Server version 7.0. Other options on this panel let you specify
whether descriptive headers, extended properties, and other information should be included in your
script. Transact-SQL statements are generated as needed.
General Options
Option Description
Create Only If Missing To generate a Transact-SQL statement that creates a component prefixed by a check
for existence, select this check box. When the script is executed, a component is
created only if a copy of the named component does not exist.
Drop First If Exists To generate a Transact-SQL statement that removes a referenced component, select
this check box. The script tests for the existence of the component prior to an attempt
to remove the component.
Include Descriptive Headers To include explanatory header text before each Transact-SQL statement in the script,
select this check box.
Include Extended To include extended stored procedures in the SQL scripts that are created, select this
Properties check box.
Only Script 7.0 Compatible To generate a script that is compatible with Microsoft SQL Server version 7.0, select
this check box.
If you select this check box, the following SQL Server 2000 options are ignored:
• Column level collation
• User-defined functions
• Extended property
• INSTEAD OF trigger on tables and views
• Indexes on views (indexed views)
• Indexes on computed columns
• Reference permissions on views
• Descending indexes
Setting Description
Script Indexes To generate a Transact-SQL statement that creates indexes that currently exist for any
selected tables, select this check box.
Note: Selecting this check box is useful only if one or more tables are selected on the
Database Tables panel.
Setting Description
Script Full-Text Indexes To generate a Transact-SQL statement that creates full-text indexes, select this check
box.
Selecting this check box is useful only if one or more tables are selected on the
Database Tables panel.
Script Triggers To generate a Transact-SQL statement that creates triggers that exist for any selected
tables, select this check box.
Note: Selecting this check box is useful only if one or more tables are selected on the
Database Tables panel.
Script Check Constraints To generate a Transact-SQL statement that creates check constraints that exist for any
selected tables, select this check box.
Note: Selecting this check box is useful only if one or more tables are selected on the
Database Tables panel.
Script Foreign Keys To generate a Transact-SQL statement that creates FOREIGN keys that exist for any
selected tables, select this check box.
Note: Selecting this check box is useful only if one or more tables are selected on the
Database Tables panel.
Script Primary Keys To generate a Transact-SQL statement that creates PRIMARY keys that exist for any
selected tables, select this check box.
Note: Selecting this check box is useful only if one or more tables are selected on the
Database Tables panel.
Script Defaults To generate a Transact-SQL statement that creates defaults that exist for any selected
tables, select this check box.
Note: Selecting this check box is useful only if one or more tables are selected on the
Database Tables panel.
Note: The import database functionality applies to the Microsoft SQL Server Database.
The Advanced Scripting Options panel lets you specify security scripting options, as well as the file
format.
Setting Description
Script database Generate a Transact-SQL statement to create a script of the existing database
schema.
Script database users and Generate a Transact-SQL statement to create all users and roles that have
database roles access to the database.
Script SQL Server logins (Windows Generate a Transact-SQL statement to create all logins that currently have
NT and SQL Server logins) access to the server.
Script object-level permissions Generate a Transact-SQL statement to create all grant, revoke, and deny
permissions that currently exist for each object selected on the Objects to
Script panel.
File Format
Table 39-22: File Format Options
Option Description
Windows Text (ANSI) This is the default recommended option. Choose this file format to have the script in
ANSI format.
International Text (Unicode) International Databases can use the Unicode file format for the script, if necessary.
Note that the InstallShield SQL Script Editor cannot modify Unicode Scripts. To edit
the script using Microsoft’s SQL Query Analyzer, right click on the script in the
explorer of the SQL Scripts view and select that option.
Note: Consult your SQL-DMO help reference for more detailed information about script formatting and file formats.
Summary Panel
Note: The import database functionality applies to the Microsoft SQL Server Database.
Note: The Regenerate Script at Build option will slow down your build since a connection to the server needs to be
established, and the database needs to be reimported every time you rebuild your project.
Click Finish to generate the script file (.sql). Once the script is generated, you can edit it from the script’s
Script tab in the SQL Scripts view.
Project: The Device Driver Wizard is available in the following project types:
• Basic MSI
• InstallScript MSI
• MSI Database
The Device Driver Wizard simplifies the process of installing device drivers from a Windows Installer–
based installation using the Driver Installation Frameworks for Applications (DIFxApp) from Microsoft.
The wizard creates the necessary table and entries, custom actions, feature, and components.
For the latest available information on the Driver Installation Frameworks, visit Windows Hardware
and Driver Central at http://www.microsoft.com/whdc/.
• In the Setup Design view, right-click a feature and then click Device Driver Wizard. The
feature that the wizard creates will be a subfeature of the selected feature.
• On the Project menu, click Device Driver Wizard. The feature that the wizard creates will be a
root-level feature.
The following panels are associated with the Device Driver Wizard:
• Welcome
• Summary
Welcome Panel
The Device Driver Wizard simplifies the process of installing device drivers from a Windows Installer–
based installation using Microsoft’s Driver Install Frameworks for Applications (DIFxApp). The wizard
creates the necessary table and entries, custom actions, feature, and components.
Tip: You can disable the Welcome panel by choosing the Tools menu’s Options command and clearing the Options dialog
box’s User Interface tab’s Show Welcome panel in IDE wizards option.
Note: Clicking Next displays a warning message if the specified package file does not specify a security catalog, if the
specified security catalog is missing, or if the package file has been modified or corrupted since it was signed. For more
information, visit http://www.microsoft.com/whdc/winlogo/drvsign/drvsign.mspx.
Caution: Select the Remove binary files associated with driver during uninstall check box only if you can verify that
the driver’s binary files are not required by any other driver package or application.
InstallShield uses Microsoft Windows Driver Install Framework (DIFx) to install drivers. When your
device driver is installed, DIFx treats it as being a device driver of the type that is displayed in the Device
Driver Information panel.
To change the device driver type, change the value of the DriverPackageType entry in the package file’s
[Version] section to the desired value from the preceding table, and then re-sign the package file. (For
more information on signing package files, visit http://www.microsoft.com/whdc/winlogo/drvsign/
drvsign.mspx.)
If you clear this check box, the installation uses runtime dialogs for English only. The English runtime
.dll file is smaller than the localized .dll file, so if space is an issue and you do not need the extra language
runtime dialogs, clear this check box.
Summary Panel
The Summary panel displays the options that you have specified in the wizard. Click the Finish button to
complete the wizard.
Dialog Wizard
InstallShield provides a Dialog Wizard that enables you to add a new dialog to your installation and
configure it by stepping through the wizard panels.
• Dialog Template
Welcome Panel
This panel welcomes you to the wizard and briefly describes the Dialog Wizard’s function. Click Next to
begin using the wizard.
Panel Options
List of Dialogs
The box in the Dialog Template panel lists dialogs that are in the directory specified in the Dialog
Location box on the File Locations tab of the Options dialog box. It may also include dialogs that are
stored in a repository. In addition, several default dialog templates are listed:
Exterior Creates a dialog with a large bitmap along the left side of the
dialog—similar to the formatting of the Welcome dialog. This
dialog template is available only for Basic MSI projects.
Interior Creates a dialog with a small bitmap at the top of the dialog. This
dialog template is available only for Basic MSI projects.
LogonInformation Creates a set of dialogs that enable the end user to create or
browse for an existing user account in order to access
resources restricted to others.
Caution: If you add any controls to this dialog, do not set the
control ID to 52. If you do, the dialog skins will not work.
Browse
Click the Browse button if you want to select to a dialog (.isd) file that is not listed.
Note: If this option is not selected in a Basic MSI project, the wizard process ends and the new dialog is added to your
project. You need to manually add the dialog to a sequence to display it during installation.
Note: You need to manually insert a blank dialog into a sequence in order to display it during installation.
Panel Options
Table 39-25: User Interface Sequence Panel Options
Option Description
User Interface Sequence From the menu, select the sequence into which
you want to insert the new dialog.
Dialogs currently in this sequence Displays the dialogs that occur in the selected
sequence. Select the dialog that you want to
appear immediately before your new dialog in the
sequence.
Panel Options
Option Description
Dialog Position This pane displays the new dialog’s place in the sequence
selected in the User Interface Sequence panel. To move the new
dialog within the sequence, select it and click Move Up or Move
Down.
Condition Set a condition for the new dialog in this field. Click Build to
launch the Condition Builder dialog box.
Click Finish to exit the wizard. InstallShield adds the new dialog to your project and inserts it in the
specified sequence.
Project: The DirectX Object Wizard is available in the following project types:
• Basic MSI
• InstallScript MSI
The DirectX Object Wizard enables you to include the Microsoft DirectX 9c redistributable files in your
installation project and to set several options.
• For information about which files are included with the DirectX object, see Including the DirectX 9.0 Object.
• The optional ManagedDX component of DirectX 9c requires that the .NET Framework version 1.1 or later be installed
on the system.
• DirectX 9 is not supported on Windows 95 and Windows NT 4.
The following wizard panels are associated with the DirectX Object Wizard:
• Welcome
• Object Settings
• Summary
For more information about DirectX, visit http://msdn.microsoft.com/directx.
Welcome Panel
Project: The DirectX Object Wizard is available in the following project types:
• Basic MSI
• InstallScript MSI
The DirectX Object Wizard enables you to include the Microsoft DirectX 9c redistributable files in your
installation project and to set several options.
• For information about which files are included with the DirectX object, see Including the DirectX 9.0 Object.
• The optional ManagedDX component of DirectX 9c requires that the .NET Framework version 1.1 or later be installed
on the system.
• DirectX 9 is not supported on Windows 95 and Windows NT 4.
Project: The DirectX Object Wizard is available in the following project types:
• Basic MSI
• InstallScript MSI
The Object Settings panel enables you to set the following options:
Option Description
Place DirectX files in a folder If you select this check box, InstallShield creates a DirectX folder for your installation
in Disk1 at build time and places it in the Disk1 folder of your release.
If you clear this check box, InstallShield streams the DirectX redistributable files into
the .msi file. If you are creating a single-file executable installation, clear this check
box so that the files are included in the .msi file.
For information on the DirectX files that are included in the object, see Including the
DirectX 9.0 Object.
Show the Microsoft DirectX By default, the Microsoft DirectX EULA is displayed to the end user before the
EULA before starting the DirectX 9 installation begins. To prevent the EULA from being displayed, clear this
DirectX 9 installation check box.
Summary Panel
Project: The DirectX Object Wizard is available in the following project types:
• Basic MSI
• InstallScript MSI
The Summary panel enables you to review the options that you configured on the Object Settings panel.
Click Finish to accept the settings and add the DirectX 9 redistributable files to your project.
Welcome Panel
The Dynamic Scanning Wizard provides you with an easy path to add your application’s dependency
files to your setup. Before you begin using the scanner, you should add the target executable file to your
installation.
Click Next to begin using this wizard.
Panel Options
I would like to select an executable file from my project (recommended)
Select this option if the executable you would like to scan has already been added to your setup project.
Panel Options
Application
Specify which executable file you would like to scan. If you choose to scan a file that is already associated
with your project, select it from the list of executables present in your setup. If you choose to scan a file
that is not yet a part of your setup, enter the path to that file or click the Browse button to navigate to it.
Command Line
Enter any command-line parameters you would like to pass to the executable. These parameters are only
used during the scanning process and will not be used after the wizard has been dismissed.
Working Folder
Enter the path to the working folder for this application, or click the Browse button to navigate to this
directory. By default, this directory is set to the same folder in which the application you choose to scan
resides.
Deselect All
Select this option to have none of the displayed files added to your setup. You can then manually check
the files you would like added.
Select All
Select this option to have all the displayed files added to your setup. You can then manually deselect the
files you would not like to be added.
Project: The Export Components Wizard does not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
This wizard simplifies the process of exporting component from a file type (ISM, MSI, MSM) to any
existing project or a new one altogether. A common use of this wizard includes exporting components to
merge modules.
Note: You will not be able to export components from an .msi file to an .ism file.
When you export components to other projects, a copy of this component is added to the specified
project file, along with all of the component’s data, such as its files, shortcuts, registry entries, and
advanced settings.
Note: You can also access the Export Components Wizard from the Project menu in the IDE.
The following panels are associated with the Export Components Wizard:
• Welcome
• Summary
Welcome Panel
Project: The Export Components Wizard does not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
This wizard simplifies the process of exporting components from a file type (.ism, .msi, .msm) to any
existing project or a new one altogether. A common use of this wizard includes exporting components to
merge modules.
Note: You cannot export components from an .msi or .msm file to an .ism file. Also, you cannot export from an .ism file to
an .msi or .msm file.
Note: You can disable the Welcome panel by selecting the check box in the panel after viewing it the first time. You can
also disable the panel by choosing Options from the Tools menu and deselecting the option in the User Interface tab of the
Options dialog.
Project: The Export Components Wizard in not available in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
In this panel, all of the components in your existing project are listed. Select the components that you
want to export. You can filter the components list in this panel by feature or component destination.
Note: When you are exporting from an .msm or .ism file, the feature filter is not available because there are no features in
.msm files.
Project: The Export Components Wizard does not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
In this wizard panel, determine whether you want to export your file (.ism, .msi, or .msm) to an existing
or new Merge Module, MSI database, or .ism project file. The first option allows you to export to an
existing file. The second one allows you to export to a new file. In either case, browse for the file location.
Note: If the target .ism file already has a component of the same name with different properties, the Conflict dialog opens
to offer you options for resolving the conflicts.
There is also an option to export as a Merge Module project. Select this option to export the component
to this specific project type.
Project: The Export Components Wizard does not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
In this panel, specify information for the new project. Enter information in the product name, version,
and language edit fields, and determine whether or not you want to replace exported components in the
current project with the generated merge module. Replacing the component with the exported merge
module option will remove the component from the currently open file.
Summary Panel
Project: The Export Components Wizard does not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
The summary panel displays the results of the export process. The summary also lists any errors from
exporting. Click Finish to complete the process.
Note: After you have arrived at the Summary panel, you cannot click Back to return to previous panels.
Function Wizard
The Function Wizard automates the process of adding function calls to your scripts. After you complete
two brief wizard panels, your function call is inserted into your script at the caret location.
Panel Options
Function Category (list box)
Select a function category. The InstallScript functions belonging to the selected category are displayed in
the Function Name list box. Select “All” to display the names of all available InstallScript functions.
Task To specify function parameters and insert the function into your script:
1. Complete the arguments for each function. When you place the cursor in an edit field, the parameter
description appears at the bottom of the panel. If there are predefined options available for a
parameter, the edit field contains a drop-down menu. Note that you can select only one option from
a drop-down menu, even when the options are not exclusive.
Note: You can enter strings (or string identifiers) and numbers directly in the edit fields, but you must pay careful
attention to the purpose of the parameters. One clue is the InstallScript Hungarian notation in the variable name.
You must declare all variable names that you use in all function calls. The Function Wizard does not declare them for
you.
2. Click Finish to insert the function call into your setup script. If you need further help, place the
cursor in the function name and press the F1 key.
Note: If All Application Data is selected, the Registry view is read-only.InstallScript projects only: In the Destination
computer’s Registry view pane, open the registry set that should have the .reg file that you are importing.
3. In the Destination computer’s Registry view pane, right-click the registry key to which you
would like your registry data added, and then click Import REG File. The Import Reg File Wizard
opens.
When you import an .reg file into a component or registry set, that registry data is added to the
component’s or registry set’s registry data and written to the end user’s system if the component or
registry set is installed.
The Import REG File Wizard consists of the following panels:
• Welcome
• Progress
Welcome Panel
The Import REG File Wizard allows you to import existing registry data (.reg) into your InstallShield
project. This registry data is added to the target system’s registry during the setup project.
Click Next to continue to the next wizard panel to begin importing your REG file.
Note: Before you begin importing REG data be sure that you selected the proper feature to which you would like this data
added. To specify a feature, cancel the wizard and select the appropriate feature from the Feature list at the top of the
Registry view.
Panel Options
Registry File
Enter the path to the REG file you would like to import, or click the Browse button to navigate to this file.
Panel Options
Overwrite the registry data
Select this option if you would like data stored within the REG file you are importing to overwrite any
conflicting data already present in your setup project.
Important: The XML File Changes view is not designed to list a node for every node in an XML file. To improve
performance, the XML File Changes view should show only the settings that differ from the base XML file:
• If the XML file that you are modifying is part of your installation, the XML File Changes view should list only the nodes
and node sets that should be added, changed, or deleted after the XML file is installed at run time.
• If the XML file that you are modifying is a file that is already present on the target system, the XML File Changes view
should list only the nodes that need to be added, changed, or deleted at run time.
Therefore, when you use the Import XML Settings Wizard, import only the nodes in the XML file that you want to modify at
run time.
Note that the XML File Changes view does not enable you to specify the order in which new elements should be listed in
the XML file. Therefore, importing only the nodes that you want to modify at run time helps to avoid issues that may occur
if your product requires that the elements be listed in a particular order.
• XML File
• XML Element
Welcome Panel
The Import XML Settings Wizard enables you to add a reference for an XML file to the XML File
Changes view, where you can configure the changes that you want to be made to the XML file at run
time.
The Welcome panel is the first panel of the Import XML Settings Wizard.
Important: The XML File Changes view is not designed to list a node for every node in an XML file. To improve
performance, the XML File Changes view should show only the settings that differ from the base XML file:
• If the XML file that you are modifying is part of your installation, the XML File Changes view should list only the nodes
and node sets that should be added, changed, or deleted after the XML file is installed at run time.
• If the XML file that you are modifying is a file that is already present on the target system, the XML File Changes view
should list only the nodes that need to be added, changed, or deleted at run time.
Therefore, when you use the Import XML Settings Wizard, import only the nodes in the XML file that you want to modify at
run time.
Note that the XML File Changes view does not enable you to specify the order in which new elements should be listed in
the XML file. Therefore, importing only the nodes that you want to modify at run time helps to avoid issues that may occur
if your product requires that the elements be listed in a particular order.
Important: The XML File Changes view is not designed to list a node for every node in an XML file. To improve
performance, the XML File Changes view should show only the settings that differ from the base XML file:
• If the XML file that you are modifying is part of your installation, the XML File Changes view should list only the nodes
and node sets that should be added, changed, or deleted after the XML file is installed at run time.
• If the XML file that you are modifying is a file that is already present on the target system, the XML File Changes view
should list only the nodes that need to be added, changed, or deleted at run time.
Therefore, on the XML Element panel of the Import XML Settings Wizard, select only the nodes in the XML file that you
want to modify at run time.
Note that the XML File Changes view does not enable you to specify the order in which new elements should be listed in
the XML file. Therefore, importing only the nodes that you want to modify at run time helps to avoid issues that may occur
if your product requires that the elements be listed in a particular order.
System Requirements
Platforms supported are Windows 95, Windows 98, and Windows NT 4.0 Service Pack 4 and later. Disk
space requirement is 30 MB for the redistributable CAB file. Approximately 40 MB is typical for an
installation of the full MSDE engine.
Task To configure the MSDE object, launch the MSDE 1.0 Object Wizard:
3. Follow the instructions in the wizard panels to add your copy of the MSDE 1.0 redistributable to
your setup.
Welcome Panel
This panel provides a brief introduction to the MSDE 1.0 Object Wizard. This wizard walks you through
all the necessary steps required to configure how the MSDE 1.0 object is installed and run on your end
users’ systems.
Click Next in the wizard panel to begin using the wizard.
Panel Options
Option Description
Enter the SQL Data Root directory. Specify the path that will be entered as the string data
in the target system’s
HKEY_LOCAL_MACHINE\Software\Microsoft\MSSQLSer
ver\Setup\SQLDataRoot registry value. You can specify
a path explicitly or in terms of an InstallShield system
variable. To specify a path in terms of a system
variable, you can select a system variable from the list
and, optionally, type a subpath after it.
Enter the SQL Data Path directory. Specify the path that will be entered as the string data
in the target system’s
HKEY_LOCAL_MACHINE\Software\Microsoft\MSSQLSer
ver\Setup\SQLPath registry value. You can specify a
path explicitly or in terms of an InstallShield system
variable. To specify a path in terms of a system
variable, you can select a system variable from the list
and, optionally, type a subpath after it.
Panel Options
Option Description
Use Custom Response File Select this check box if you want to specify a custom
response (.iss) file. Specify the fully qualified file name of
your custom InstallShield Silent response file (.iss file) or
click Browse to navigate to the file. If you leave this field
empty, the MSDE setup uses the default response file,
Unattend.iss. You can specify a path explicitly or in
terms of an InstallShield system variable.
Add the -SMS switch to the If this check box is selected, the MSDE object passes
command line of the MSDE setup. the -SMS command line switch to the MSDE setup. If the
check box is not selected, the object does not pass the
switch. This switch prevents network connections from
closing before the MSDE setup is complete.
Summary Panel
Review the MSDE 1.0 redistributable information summary. Click Finish to close the wizard and add the
MSDE object to your setup, or click Back to return to previous panels and change your selections.
• Step 2
Tip: This object is not installed with InstallShield; you need to download it. For more information, see Obtaining Updates
for InstallShield.
Step 1 Panel
Setting Description
Select the version of Select which versions of the .NET Framework should be included in
.NET to include and the object.
install
Setting Description
For more information about this object, see the help pane that is displayed when you click the Microsoft
.NET Framework Object in the Objects view.
Tip: This object is not installed with InstallShield; you need to download it. For more information, see Obtaining Updates
for InstallShield.
Step 2 Panel
Setting Description
Select the .NET redists Select the check box for each version of the .NET Framework that
to include in the object should be included in the project. Note that the object can install only
one version of the .NET Framework at run time.
Setting Description
Allow the object to install To allow a language pack to be installed without first installing the
a .NET language pack corresponding version of the .NET Framework, select this check
without installing the box.
corresponding .NET
InstallShield uses this setting to configure the InstallLangPackOnly
Framework.
property for the object. This read-write numeric property indicates
whether the object should allow the installation of the language pack
without first installing the corresponding version of the .NET
Framework, which may occur if the framework is not being included
in the object.
By default, if the object is set to install a particular version of the
framework and that version of the framework is not included in the
object, the object sets a status of
DOTNET_STATUS_VERSION_NOT_IN_MEDIA. However, if the
InstallLangPackOnly property is set, the object does not set the
failure status, which allows the object to install the language pack, if
appropriate, without first installing the framework. This property is
typically set in the object wizard.
For more information about this object, see the help pane that is displayed when you click the Microsoft
.NET Framework Object in the Objects view.
Tip: This object is not installed with InstallShield; you need to download it. For more information, see Obtaining Updates
for InstallShield.
Note: The Microsoft MSDE 2000 merge modules and the InstallShield MSDE 2000 Merge Module Object have been
removed from the Redistributables view. Microsoft does not recommend use of these merge modules since instances of
MSDE 2000 installed cannot be upgraded using the Desktop Engine SP3a files. Desktop Engine (MSDE 2000) SP3a
provides merge modules to support existing applications that use merge modules.
The MSDE 2000 Object and the InstallShield MSDE 2000 Object for NT Platforms enable the
installation of support for MSDE 2000. If you are targeting only Windows 9x operating systems, include
the MSDE 2000 Object in your project. If you are targeting only Windows NT operating systems, include
the InstallShield MSDE 2000 Object for NT Platforms in your project. If you are supporting both types
of operating systems, include the Microsoft SQL Server 2000 Desktop Engine (MSDE 2000) setup
prerequisite in your installation.
Note: The InstallShield MSDE 2000 Object for NT Platforms works only on Windows NT-based operating systems. If end
users run the installation on a Windows 9x platform (and MSDE 2000 needs to be installed), they receive a message
saying that the installation cannot install the MSDE 2000 object on the machine. Then the installation exits. The end user
will have to install the MSDE 2000 object and then rerun the installation.
This limitation is because of a incompatibility of Windows Installer and the MSDE 2000 installation itself. The MSDE 2000
installation is a Windows Installer (.msi) installation. The only way one .msi can launch another .msi is as a nested .msi
custom action. However, the MSDE 2000 readme file specifically says that you cannot install MSDE 2000 as a nested
.msi custom action.
The only other option is to launch it in the InstallUISequence. With this method, the InstallUISequence installs the MSDE
2000 object and the InstallExecuteSequence installs your application. This works on Windows NT-based machines
because each sequence is run in a separate thread. However, on Windows 9x systems, both sequences are run in the
same thread. This makes the MSDE 2000 installation fail with an error of “another setup is currently in progress.”
Therefore, end users cannot install the MSDE 2000 object on a Windows 9x machine as part of your installation (if your
installation is Windows Installer based). This would be the case even if you tried to create your own custom action to install
the MSDE 2000 object on Windows 9x machines.
Task To add the MSDE 2000 Object or the InstallShield MSDE 2000 Object for NT Platforms to your installation
project:
1. In the Redistributables view, select the MSDE 2000 Object check box or the InstallShield
MSDE 2000 Object for NT Platforms check box. The MSDE 2000 Object Wizard opens.
2. Customize the object by selecting options in each of the wizard panels.
Welcome Panel
The MSDE 2000 Object wizard allows you to configure an MSDE 2000 object that you have added to
your setup project. In the MSDE 2000 Object wizard, you can customize MSDE installation locations,
alter default instance and collation settings, and indicate upgrade settings.
Click Next to select functionality.
Functionality Panel
In the Functionality panel, you can select the optional MSDE 2000 functionality that your application
requires. There are three options:
• Data Management Objects (DMOs)
• Replication
• Core Functionality
Note: An option appears only if all of the corresponding merge modules exist on the development system.
Directories Panel
This panel enables you to customize the MSDE 2000 installation locations.
• For the MSDE 2000 Object only: If you want to set <ProgramFilesFolder>MyDatabase as your system database
location, enter [ProgramFilesFolder]MyDatabase in this box.
• For the InstallShield MSDE 2000 Object for NT Platforms only: System variables cannot be used in this box. Only
hard-coded paths are valid.
• For the MSDE 2000 Object only: If you want to set <ProgramFilesFolder>Myengineloc as your desktop engine
executable files location, enter [ProgramFilesFolder]Myengineloc in this box.
• For the InstallShield MSDE 2000 Object for NT Platforms only: System variables cannot be used in this box. Only
hard-coded paths are valid.
Set an sa password
Selecting this option allows you to specify the sa password. You can use this option for new installations.
Unlike other properties, this property is hidden and the value is not written to the log file.
• If you specify both the “Set an sa password” and “Allow installation to proceed with a blank sa password,” setting an
sa password takes precedence and the blank sa password is ignored.
• If you are using an .ini file during setup, avoid storing credentials in the .ini file.
Summary Panel
The Summary panel lists the selections that you made in the previous MSDE 2000 Object Wizard
panels.
Click Finish to exit the wizard and commit the changes to your setup project. If you need to change any
of your selections, click Back until you arrive at the appropriate panel.
Task To install the MSDE 2000 merge module for another language:
1. Copy all of the required merge modules—including the *_RES.MSM modules—into Modules\i386.
2. When prompted to replace the .msm files already in that folder, click Yes to All.
Cautions
Caution: Follow these guidelines when installing MSDE 2000 for another language.
• Do not delete the English-specific merge modules that the MSDE 2000 Object Wizard places in Modules\i386\0409.
All of Microsoft’s non-.res merge modules depend on the English version of the corresponding .res merge module. For
example, the Italian REPL.MSM has a dependency on the English REPL_RES.MSM. A setup that does not contain the
English REPL_RES.MSM might install correctly, but it will trigger build errors.
• Do not use more than one set of MSDE 2000 modules at a time. They are not designed to support more than one
language at a time.
On the Tools menu, click Add New Language. You must first close any open projects, or the menu
item will not be available.
Edition: The New Language Wizard is available in the Premier edition of InstallShield. For more information, visit the
Macrovision Web site.
Welcome Panel
Because InstallShield does not support every language, you may find yourself targeting a language that
is not supported. If this is the case, you can add support for almost any language with the New Language
Wizard.
You can select the languages that you want to add, the projects to which you want to add them, and
whether you want all future projects to have support for the added languages.
Panel Options
Project Name
Select the projects to which you want to add the new languages. If your project is not stored in the
default project location, navigate to it by clicking the Browse button.
Update InstallShield
Select this option if you would like any new installation project you create to have optional support for
these languages. Clicking this option does not automatically include the new languages in future
projects. Instead, it makes the new languages available to be included in future projects.
Summary Panel
At this time your new languages have been added to the files that you specified. If you chose to include
your new languages in any future products, you will see them supported in any project you create from
this moment on.
Click the Finish button to return to the IDE.
1. Select the Open Project button on the toolbar. A browse dialog opens.
2. Select either Windows Installer Packages (*.msi) or Windows Installer Modules (*.msm)
from the Files of Type list.
3. Go to the setup package or merge module that you want to import and click Open.
Once you select a Windows Installer database, the Open MSI/MSM Wizard presents options for
converting the file, converts the project, and then opens the converted project.
Note: Any errors encountered by the wizard are displayed in the bottom panel of the IDE when the converted project is
opened. To solve any problems, see MSI/MSM Conversion Errors.
Welcome Panel
The Open MSI/MSM Wizard allows you to import setup packages (.msi) and merge modules (.msm)
into InstallShield. This functionality is useful for network administrators who need to build custom
setups for their users.
Panel Options
Open MSI/MSM in Direct Edit Mode
Select this option to view and edit the database directly, without creating a project file. If you select this
option, the selected database will open in the IDE, where you can view and edit its contents with the
Direct Editor.
Click Next to open the database in the Direct Editor.
Panel Options
Project Name
Type a name for the setup project that will be created when the wizard converts the existing .msi or
.msm project to an InstallShield (.ism) project. The .ism project is saved in the default location.
Note: Because the project name determines the name of the .ism file and the root for the project’s folder structure, use
only legal characters for a Windows file name.
Note: The wizard alerts you of any errors it encountered while creating the project. To resolve any problems, see MSI/
MSM Conversion Errors.
The Open MSP Wizard gathers the necessary file information, applies the patch to the base MSI, and
opens the patch project in the IDE in Direct MSP mode (which is similar to the Direct Edit mode). The
data you specify in the Open MSP Wizard is saved so the next time you open the MSP file, the patch
project opens in the IDE.
Welcome Panel
This panel welcomes you to the wizard and briefly describes the Open MSP Wizard’s function. Click Next
to begin using the wizard.
Panel Options
MSP File Name
Read-only field that provides the path and file name of the MSP file.
Task To launch the Open Transform Wizard when opening a transform for editing:
1. On the File menu, click Open. The Open dialog box opens.
2. Select the .mst file that you would like to open.
3. In the Open as box, select Wizard.
4. Click Open. The Open Transform Wizard opens.
Task To launch the Open Transform Wizard when creating a new transform:
1. On the File menu, click New. The New Project dialog box opens.
2. On the Windows Installer tab, click Transform.
3. In the Project Name box, type a name for your transform project.
4. In the Location box, type the path where your transform project should be stored or click the
browse button to find the location.
5. Click OK. The Open Transform Wizard opens.
The following panels are associated with the Open Transform Wizard:
• Welcome
• Transform Information
• Additional Transforms
Welcome Panel
This panel welcomes you to the Open Transform Wizard and briefly describes the wizard’s function.
Click Next to begin using the wizard.
Panel Options
MST File Name
Read-only field that provides the path and file name of the .mst file.
Adding a Transform
1. Select the transform in the list that you would like to remove.
2. Click Delete or press Delete.
Select a transform in the list and click the move up button or the move down button.
The transform that the Open Transform Wizard is creating is applied last.
Caution: When you are using multiple transforms, keep in mind that the order in which they are applied is critical. For
example, if you create a transform for a Windows Installer package that creates a new value for a property, and then you
create a second transform that changes the value created in the first transform, everything works correctly. However, if
you apply the second transform first, that transform is attempting to modify the property’s value, instead of creating it.
That will result in an error.
One simple example of where this may be a problem is with the default company name. If the value is not set by default,
and you set it in the first transform, a new value for the property is created. If you create a second transform that modifies
the combined original package and first transform, and the second transform changes the default company name, it is
only changing the property. However, if you try to apply the second transform without the first one, Windows Installer
interprets this as trying to change a null value to another value, which will result in an error.
Panel Options
Option Description
Create response If you want to create a response transform, select this check box.
transform
If you select this option, the user interface elements of the installation
are executed when you click Finish. No file transfer takes place, and
no changes to your machine occur. Complete this simulated
installation, customizing the options available in each panel of the
installation wizard as needed. When you reach the end of the
installation sequence and click Install, the simulated installation exits.
InstallShield saves all of the changes that you made during the
simulated installation as default installation values in the response
transform.
Command line If you are using a response transform, you can specify additional
properties (optional) command-line properties (in property name/value pairs separated by
semicolons) to pass to the response transform. These must be public
properties, and they control only how the dialog boxes are displayed
during creation of the response transform. They are not persisted
outside of the user interface sequence during creation. For example,
you can pass the property/value pair ARPHELPTELEPHONE=1-111-
111-1111 to set the value of the Help Telephone field of Add or
Remove Programs in Control Panel.
You might pass a property/value pair during the creation of a
response transform to display all dialog boxes during an installation
that may not be displayed based on your system configuration (for
example, to show Windows 9x–only dialog boxes on a Windows NT
platform). You can then make appropriate responses and have them
included in your transform.
Click Finish to exit the Open Transform Wizard and create your transform project. The transforms are
applied to the .msi file specified in the Transform Information panel, and the transform project (.mst
file) opens in Direct MST mode in InstallShield.
Palm OS Wizard
• Features
• Summary
Welcome Panel
1. Click Add or right-click anywhere in the Files box and select Add. The Browse for Shortcut
Target dialog box opens.
2. Browse to the file that you want to add and click Open. The Destination dialog box opens.
3. Select the Handheld option or the Storage Card option, depending on the target location.
4. Click OK.
1. In the Files box, select the file whose destination you would like to change.
2. Click Properties. The Destination dialog box opens.
3. Select the Handheld option or the Storage Card option.
4. Click OK.
1. In the Files box, select the file that you would like to remove.
2. Click Remove.
Features Panel
Summary Panel
In the Summary panel, you can review the settings for your Palm OS installation before you add it to
your project. If you need to change any of the settings, click Back until you reach the appropriate panel,
and then make the necessary changes.
When you are done, click Finish. A component is created for your Palm OS installation, and it is added to
all of the features that you selected to associate with the Palm OS application in the Features panel.
Publish Wizard
Use the Publish Wizard to save the selected installation element to a repository.
The following panels are associated with the Publish Wizard:
• Welcome
• Repository
• Publishing Information
• Summary
Welcome Panel
This panel welcomes you to the Publish Wizard. Click Next to begin using the wizard.
Repository Panel
The Repository panel of the Publish Wizard is where you specify the repository to which your
installation element should be published.
Panel Options
Name
Specify a name for the dialog, template, script file, or other installation element that you are publishing.
Publisher
Type your name.
Description
Type the description that should be displayed for this installation element.
Summary Panel
Use the Summary panel of the Publish Wizard to review the settings for the item that you are publishing
to the repository. If you need to change anything, click Back until you reach the appropriate panel, and
then make the necessary changes.
When you are done, click Finish. The Output window opens to inform you whether the installation
element was successfully published to the selected repository.
Project: This information does not apply to the following project types:
• InstallScript
• InstallScript Object
The Redistributable Downloader Wizard allows you to quickly download third-party redistributables,
merge modules, and other files to your local machine. You can launch the Redistributable Downloader
Wizard from the Release Wizard’s .NET Run-Time Options panel and from the Releases view (.NET 1.1/
2.0 Core Language and .NET 1.1/2.0 Language Packs settings).
1. In the Select Files to Download panel, select the redistributables that you want to download and
click Next to move to the Progress panel.
2. When the progress bars complete, click Next.
3. The final panel displays the list of redistributables that the wizard downloaded to your machine.
Click Finish to exit the wizard.
Note: Before you use the Reg-Free COM Wizard, you should add the COM libraries (.dll and .ocx files) and the executable
file that uses them to your InstallShield project. Note that the Reg-Free COM manifest file, the executable file, and the COM
libraries should all be installed to the same folder on the target machine.
Tip: To launch the Reg-Free COM Wizard in a ClickOnce project, click Add a Reg-Free COM .manifest file to include in
your deployment in the More Options area on the Application Files page of the ClickOnce Assistant.
The following panels are associated with the Reg-Free COM Wizard:
• Welcome
Welcome Panel
The Welcome panel provides a brief introduction to the Reg-Free COM Wizard. Click Next to begin
using the wizard.
Note: Select the Don’t show the welcome panel again check box if you do not want this panel to appear the next time
you open the wizard.
Panel Options
Executable FileKey
Select an executable file from the Executable FileKey list and click Next. Note that the file must already
be included in your installation project.
Panel Options
Create a new manifest file that will be added to the project
To create a new manifest file, select this option.
Summary Panel
Use the Summary panel of the Reg-Free COM Wizard to review the options that you selected. If you need
to change anything, click Back until you reach the appropriate panel, and then make the necessary
changes.
When you are done, click Finish. The wizard creates a new component with the manifest file set as the
key file. The manifest component has the same destination and condition as the associated executable-
file component. The following file naming convention is used for manifest files:
ExecutableFileName.exe.manifest
Release Wizard
The Release Wizard provides an easy way for you to build a release for your product and specify the
settings particular to that release.
Task To launch the Release Wizard and build your setup package, do one of the following:
• Right-click on a product name or a release name in the tree control in the Release view, and select
Release Wizard.
Task You can launch an abbreviated version of the Release Wizard by doing one of the following:
The Build option rebuilds the release that has focus in the Release view or builds the product’s first
release with default settings. The build feedback—and any build errors—appears in the Output window.
Another alternative to the Release Wizard is building a release at the command line.
Welcome Panel
This panel provides a brief introduction to the Release Wizard. This wizard walks you through all the
necessary steps required to build a distributable release of your product.
Click Next to begin using the wizard.
Panel Options
New product configuration
Select this option if you want to build this release under a new product configuration. Specify a name for
the new configuration.
Panel Options
New Release Name
If you would like to build a new release, select the New Release Name option and then enter a new name
in the field.
Panel Options
Release Flags
Enter the release flags that you would like to include in this release. If you are including more than one
flag, separate them with commas.
You have the option of including a subfeature but not its parent feature. In such a case, the subfeature is
built into the release as a top-level feature, and its parent is excluded from the release.
The release flags that you enter here are combined with the product configuration flags. For more
information on the relationship between the two, see Product Configuration Flags vs. Release Flags.
Project: The Release Flag option is not available for merge module projects.
Panel Options
Add to local merge module catalog
Select this option if you would like your new module to be immediately available to other projects. The
Merge Modules Locations field is located on the Merge Modules tab of the Options dialog.
Panel Options
Included Release Languages
From the list of this project’s supported languages, select each language that you want to create a
localized setup for. InstallShield includes in the release all of the resources necessary to run the setup in
that language.
Make Default
Select a language in the Included Release Languages list and click this button to make that language the
“default” for this release. This value determines the language that the setup runs in if you do not let the
user select a language in the Language dialog. If you do display the Language dialog by selecting the
option below, the Language dialog itself is displayed in the default language.
Project: Because the Language dialog is displayed by Setup.exe, in non-InstallScript projects you must select Create
SETUP.EXE in the Setup Launcher panel.
This panel affects only the user interface elements you include in your setup. To include components
based on the language of the application data (set in the component’s Languages property), see the
Release Filtering panel (which is not available in InstallScript projects).
Panel Options
Media type
Choose the type of media on which you will be distributing your setup program. You can select from the
following options:
Option Description
CD-ROM Select this option if you will be distributing your setup on a CD.
The maximum size for this type of media is 650 MB.
Custom Select this option if the media that you are distributing is not in the
list of media types. For example, you may be distributing your
setup on floppy disks or Zip disks. You will need to set the format
size and cluster size for this media, as it will change depending on
the media type you are using.
DVD-5 This option allows you to ship your release on a 4.38 GB DVD-
ROM.
DVD-9 Choose this option if you plan on shipping your setup on a 7.36
GB DVD-ROM.
DVD-10 This option allows you to ship your release on an 8.75 GB DVD-
ROM.
DVD-18 If you have an enormous setup, you can ship your release on
15.83 GB DVD-ROM media.
Network image If your setup is going to be placed on a network, you can choose
this option. There is no size limit for this media type.
3.5" Diskette (InstallScript projects only) This option allows you to ship your
release on 3.5" diskettes.
Project: If your installation requires more than one disk, InstallShield automatically splits it across as many disks as
needed. In a Windows Installer–based project, the wizard prompts you for more information about disk spanning later in
the sequence.
Format size
If you chose the Custom media type, you will need to specify the capacity of the media in this field. For
example, if you are shipping your installation program on a Zip disk, you will want to set the media size
to 100 MB. If you chose any other media type, the maximum size allowed for that media is displayed in
this field.
Panel Options
Automatic
Select this option to have the wizard automatically split your setup across as many disks as are
necessary. This option is the recommended way to span your setup across disks.
Custom
Select this option to manually define how many disks your setup requires, and set the breakpoints
yourself. This option requires you to specify which features will be stored on each disk in the Disk
Spanning Advanced Settings panel.
Caution: Multi-disk setups cannot be run from a non-removable media (for example, from a hard drive). If you want to run
test a setup that spans disks, you need to put the setup on your target media. If you do not, the setup will fail due to a
limitation of the Windows Installer service.
Panel Options
Disk Mapping
This dialog lists all the features included in the release when it was first built. Because a release is
designed to be a snapshot of your build settings, features created after a release will not be available for
disk mapping nor built into the current release. You must start a new release in order to map the new
features.
All features are on Disk 1 by default. To change the name of this disk, click the Rename Disk button and
type in the new name of the disk. To add a new disk, click the New Disk button.
Tip: Note the following when spanning your setup across multiple disks:
• A single feature cannot be spanned across multiple disks. If you have a feature that is too big to fit on one disk, you
need to divide it into smaller features or subfeatures.
• Any merge modules that are included in your setup must be on the first disk, because these files must be available
when Windows Installer first processes the database (.msi file).
If you add features to your setup after you have defined how you would like your setup to span across
multiple disks, those features are automatically added to the last disk of your setup. You can add new
disks to your setup at any time by using the Release Wizard.
Disk Prompt
Task To indicate the prompt you want displayed to end users when the next disk needs to be inserted:
The string that is displayed comes from a number of sources throughout your project, as described
below:
1. The complete prompt originates in the Error table (exposed in the Direct Editor) as Error record
1302.
2. This value in turn comes from the string table, and the default value for English reads “Please insert
the disk: [2].”
3. Windows Installer resolves [2] with the value of the property DiskPrompt, which is set to [1] in the
Property Manager.
4. Finally, Windows Installer evaluates [1] to the string you enter into the Disk Prompt field.
In most cases you should enter the same name as the disk volume (below). For example, assuming the
defaults are unchanged, a Disk Prompt entry of Disk8 would cause the user to be prompted with “Please
enter the disk: Disk8.”
Disk Volume
Select a disk and then enter the name for the resulting disk image folder. Repeat for each disk.
When you are building your release image for removable media (such as CD-ROM), be sure to create the
media with the same volume names specified here.
If you leave the names as DISK?, the Release Wizard numbers the disks sequentially (for example,
DISK1, DISK2, and so on).
Tip: Notice that the default name of the volume is in all uppercase letters. It is a good idea to keep the names as
uppercase to accommodate media types, such as CD-ROM, which require volume names in that format.
Panel Options
One Executable
Select this option if you want to build this release as a single self-extracting Setup.exe. This Web type is
ideal for a package that is to be downloaded from multiple Web or FTP sites, since the installation
package is self-contained, and it does not contain any configuration information that ties it to a specific
location.
Note, however, that the entire installation package will be downloaded, so the download size and time
will be greater than the Install from the Web type described below.
Downloader
Select this option to build this release as a combination of Setup.exe and your .msi database. With this
option, you can specify where your product’s data files should be stored: they can be streamed into the
.msi database or stored externally in cabinet (.cab) files. Any .mst and .ini files are embedded in the
Setup.exe file.
With the Downloader option, the end user downloads and runs Setup.exe, which in turn downloads and
runs the .msi database. If the .cab files are stored externally, only the .cab files that are required, based
on the end user’s setup type and feature selections, are downloaded and installed. This minimizes
download size and time.
The URL that you specify in the Downloader Options panel of the Release Wizard is used during product
maintenance and repair mode.
Setting Description
URL for your package Type the URL for your installation package—for example, http://
www.yourcompany.com/downloads. (The file name is not necessary.)
Create external .cab files To stream your product’s data files into the .msi package, clear this check box.
To store your product’s data files outside the .msi package (in external .cab
files), select this check box and then select the appropriate .cab Files option.
Setting Description
.cab Files If you select the Create external .cab files check box, specify how the (.cab
files should be created. Available options are:
• One .cab per component—Builds a separate cabinet file for each
component. At run time, only the cabinet files that are required by the end
user’s setup type and feature selections are downloaded.
• One .cab per feature—Builds a separate cabinet file for each feature. At
run time, only the cabinet files that are required by the end user’s setup
type and feature selections are downloaded.
• Multiple .cab files based on size—Enter a specific size, in kilobytes,
for each cabinet file.
Setting Description
URL to install files from the Web Type the URL for your installation package—for example, http://
www.yourcompany.com/downloads. The URL must begin with http:// or
ftp://.
.cab Files Specify how the (.cab files should be created. Available options are:
• One .cab per component—Builds a separate cabinet file for each
component. At run time, only the cabinet files that are required by the end
user’s setup type and feature selections are downloaded.
• One .cab per feature—Builds a separate cabinet file for each feature. At
run time, only the cabinet files that are required by the end user’s setup
type and feature selections are downloaded.
• Multiple .cab files based on size—Enter a specific size, in kilobytes,
for each cabinet file.
The One-Click Install panel is where you specify whether to generate an HTML page and cabinet file
from which an end user can begin installing your project.
Panel Options
Generate a One-Click Install
Select this option if you would like to create a One-Click Install, which is an installation program whose
initial user interface is an HTML page. When an end user visits your Web page and clicks a button on it,
the installation files are downloaded to the target system and then launched. The files that are
downloaded to the user’s system depends on your setting for the Web Type property for the current
release.
Type in the base name of the HTML file to generate, as in install. The “.htm” extension will be added to
the base name you specify.
Type in the base name of the cabinet (.cab) file and applet archive (.jar) file to generate, as in install.
Browsers to support
Browser Explanation
Netscape Communicator Generate a JAR (.jar) file based on your “CAB/JAR base
file name” setting.
Both Internet Explorer & Netscape Generate both the CAB and JAR files.
Communicator
Note: InstallShield supports Netscape Communicator versions 4.06 through 4.78 for Internet deployment.
3. Select Low for the Default security level or—if the end user has a custom security level defined—
set the Custom security level to allow Download unsigned ActiveX controls and Active
scripting.
Panel Options
Cache installation on local machine
Check this box if you would like your installation files to be cached on the target system. When the user
performs maintenance operations on your product, the cached location you specify here will be used as
the default installation source.
Note: Files cached on the target system using this option will not be automatically removed when the user uninstalls your
product.
Path
Specify the directory in which files should be cached on the target system. You can enter a hard-coded
path, as in C:\Cached Files, but it is recommended you include a destination variable from the drop-
down list in the path, as in [LocalAppDataFolder]Cached Files.
Note: Only the destination variables included in the Path list are available for use as download locations.
If you are rebuilding an existing release, the wizard remembers your previous build settings.
Setting Description
Compress all files Select this option to compress all of your product's files into either a
single executable file (Setup.exe) or a single Windows Installer package
(.msi file).
Leave files Select this option if your product's files should not be compressed, and if
uncompressed and they should be in a subfolder of the folder that contains your installation
separate from the package.
installation package
Tip: The output of the build process depends on your media type,
compression, and spanning settings.
Note: The output of the build process depends on your media type, compression, and spanning settings.
• If you choose a Network Image media type and the Compress all files option, all your data files are compressed into
Setup.exe or your .msi database, depending on whether you include the Setup.exe installation launcher.
• If you choose a CD-ROM, DVD-ROM, or Custom media type, along with the Compress all files option, each disk
image contains a DataN.cab file that contains your data files.
• If you choose a CD-ROM, DVD-ROM, or Custom media type, along with the Custom option compression, the data files
that you choose to compress are placed in cabinet files named ComponentName.cab.
• If you choose a Web media type, the build output is described on the Web Type panel of the Release Wizard.
Panel Options
Features to Compress
All of the features included in this release are displayed here. Select the features that you would like to
compress by selecting the check box next to each one.
A component or merge module can be associated with more than one feature. In such a case, the Release
Wizard applies the compression settings of the first feature with which the component or module is
associated. For example, if ComponentA belongs to both Feature1 (whose files are compressed) and
Feature2 (whose files are uncompressed), the compression settings are applied as follows. If Feature1 is
the first feature to be built into the release, ComponentA’s files will be compressed into the Windows
Installer package or Setup.exe.
Select All
Click this button to select all features for compression.
Clear All
Click this button to deselect all features, meaning that none of the features will be compressed into the
installation.
Panel Options
Create SETUP.EXE
Use this option to specify whether to create a Setup.exe installation launcher for the current release.
The Setup.exe installation launcher is required in the following cases:
• You are building a release for an InstallScript MSI project.
• You are building a multilanguage installation project.
• You want to automatically update or install the Windows Installer service on a target system, when
necessary.
The entire setup package and all of your application’s files will be compressed into Setup.exe if you
selected the Compressed and included within the installation package option on the Release
Configuration panel for a Network Image or Web—One Executable media type.
Setup.exe displays the Language dialog if you selected that option in the Setup Languages panel.
Note: There is no option to install the Windows Installer engine on Windows XP or 2003 because these operating systems
already have it.
Note: Windows Installer 4.0 is not available as a redistributable. It is available on all Windows Vista systems.
Version Description
Version 1.1 Allows you to target systems that have Windows Installer version 1.1
installed. This overrides the Schema property setting (in the Summary
Information Stream view) and sets the property to 110. It also
includes the 1.2 engine for cases where the target system does not
have version 1.1 installed.
Version 2.0 (under NT Installs Windows Installer 2.0 to the target system.
4, requires Service
Pack 6)
Version 3.0 (requires Installs Windows Installer 3.0 to the target system.
Windows 2003 SP3 or
greater)
Version Description
Version 3.1 (requires Installs Windows Installer 3.1 to the target system.
Windows 2003 SP3 or
greater)
Version 3.1 or 2.0 (best Installs Windows Installer 3.1 to a target system that is running
fit for system) Windows 2003 SP3 or later, and installs Windows Installer 2.0 to
other target systems.
Panel Options
Download engine from the Web
Select this option to download the Windows Installer engine installers (if necessary) from the URL that
is specified in the Release property sheet’s Win9x MSI Engine URL, WinNT MSI Engine URL, or MSI 3.1
Engine URL property. (The URL property that the installation uses is determined by the target operating
system and the value of the MSI Engine Version property, which you can set in the Release property
sheet or the Release Wizard’s Setup Launcher panel.)
Tip: This option is recommended if your installation will be downloaded from the Internet and you want to minimize the
package size and download time. The engine will not be downloaded if the correct version is already present on the target
machine.
Tip: Use this option if the entire installation must be self-contained in Setup.exe. Note that the Download engine from the
Web option results in smaller installations and shorter download time; however, this option provides for a completely self-
contained installation.
Tip: Use this option if the installation will be run uncompressed from fixed media—CD, DVD, or local network.
Option Description
Follow Individual Use the locations that are specified for each individual setup
Selections prerequisite’s properties in the Redistributables view. For more
information, see Specifying a Location for a Specific Setup
Prerequisite.
Download Setup Download all of the setup prerequisite files included in your project (if
Prerequisites from the necessary) from the URL specified in the setup prerequisite (.prq) file
Web for each prerequisite.
Extract Setup Compress the setup prerequisite files into Setup.exe, to be extracted
Prerequisites from at run time, if necessary.
Setup.exe
Option Description
Copy Setup Store the setup prerequisite files at the root directory of the source
Prerequisites from media.
source media
Tip: Use the Copy Setup Prerequisites from source media option
if the installation will be run uncompressed from fixed media—CD,
DVD, or local network.
This option overrides the locations that are specified in the
Redistributables view for each setup prerequisite’s properties.
Note: If a setup prerequisite is added to a project as a dependency of another prerequisite, the location for the
prerequisite dependency follows the location setting of the prerequisite that requires it.
Note: When you are building a release on a Windows 2000 machine, SP4 must be installed in order for you to digitally sign
the application.
Setting Description
Digital certificate file (SPC or Specify the location of your digital certificate file (.spc or .pfx)
PFX) provided by a certification authority. You can type the path to
the file or use the Browse button to navigate to the file
location.
If you specify an .spc file, you must also specify a .pvk file.
Private key file (PVK) If you are using an .spc file, you must also specify the location
of your private key file (.pvk) provided by a certification
authority. You can type the path to the file or use the Browse
button to navigate to the file location.
Setting Description
Certificate password If you would like to pass the password for the .pvk file or the
.pfx file to ISCmdBld.exe to digitally sign your application
while building the release from the command line, type the
password in this box. InstallShield encrypts this password and
stores it in your project (.ism) file.
If you do not specify a password in this box but you are
digitally signing the release while building it from the command
line, you will need to manually enter the password when you
are prompted each time that you build the release from the
command line.
Tip: You can also configure digital signature information for a release on the Signing tab in the Releases view.
Sign Windows Basic MSI, If you want to sign your Windows Installer package (.msi file), select this
Installer Package InstallScript MSI, check box.
Merge Module,
This check box is enabled only if .spc and .pvk files are specified, or if a .pfx
Web
file is specified.
Note: You can sign the Windows Installer package only if version 2.0 or later
is selected for the MSI Engine Version setting on the Setup.exe tab.
Table 39-10: Settings on the Digital Signature Options Dialog Box (cont.)
Sign Media InstallScript If you want to digitally sign the media header file (Data1.hdr), select this
(requires .spc and check box.
.pvk)
This check box is enabled only if .spc and .pvk files are specified, or if a .pfx
file is specified.
Project: InstallShield does not support using .pfx files to sign media header
files (.hdr files), which are used for the One-Click Install type of installation for
InstallScript projects. For this type of installation, consider one of the
following alternatives:
• Use .spc and .pvk files instead of a .pfx file for your digital signature.
• Build a compressed installation, which would enable you to sign with a
.pfx file.
Sign Setup.exe Basic MSI, If you want to sign your Setup.exe file, select this check box.
InstallScript MSI,
This check box is enabled only if .spc and .pvk files are specified, or if a .pfx
Web
file is specified. In addition, this setting is applicable only to releases that
meet the following criteria:
• Single-file Setup.exe
• Compressed files
• Network image media type
Sign package InstallScript If you want to sign the package (self-extracting single executable file), select
this check box.
This check box is enabled only if .spc and .pvk files are specified, or if a .pfx
file is specified. In addition, this setting is applicable only to releases that
meet the following criteria:
• Single-file Setup.exe
• Compressed files
• Network image media type
Sign files in Basic MSI, If you want to sign any of the files in your release, select this check box and
package InstallScript, then use the Include patterns and files and Exclude patterns and files
InstallScript MSI, boxes to indicate which files should be signed.
InstallScript
Object, Merge
Module, Web
Note: InstallShield signs a temporary copy of the file, and then it builds the
file into the appropriate media. InstallShield never modifies or signs the
original files.
Windows Logo Guideline: All executable files (including .exe, .dll, .ocx,
.sys, .cpl, .drv, and .scr files) in an installation must be digitally signed for the
Certified for Windows Vista program.
Table 39-10: Settings on the Digital Signature Options Dialog Box (cont.)
Include patterns Basic MSI, Specify the files and file patterns that you want to be digitally signed at build
and files InstallScript, time.
InstallScript MSI,
Note the following guidelines:
InstallScript
Object, Merge • You can type directly in the box. As an alternative, you can click the Files
Module, Web button, which launches the Browse for file dialog box. This dialog box
lists all of the static files that are currently in your project. It also lists file
patterns such as *.dll, which you can select.
• To indicate a wild-card character, use an asterisk (*).
For example, if you want to sign all .exe files, specify the following:
*.exe
Using wild-card characters is especially helpful if you include
dynamically linked files in your project and you want to sign all files that
match a certain pattern.
• Put each file and each file pattern on its own line, with each separated
by a carriage return.
• Note that the files and file patterns that should not be signed override
any files and file patterns that should be signed. For example, if you
specify *.exe in the Include patterns and files box and in the Exclude
patterns and files box, InstallShield does not sign any .exe files.
Exclude patterns Basic MSI, Specify any files and file patterns that you do not want to be digitally signed
and files InstallScript, at build time.
InstallScript MSI,
Note the following guidelines:
InstallScript
Object, Merge • You can type directly in the box. As an alternative, you can click the Files
Module, Web button, which launches the Browse for file dialog box. This dialog box
lists all of the static files that are currently in your project. It also lists file
patterns such as *.dll, which you can select.
• To indicate a wild-card character, use an asterisk (*).
For example, if you do not want to sign any .drv files, specify the
following: *.drv
Using wild-card characters is especially helpful if you include
dynamically linked files in your project and you want to avoid signing any
files that match a certain pattern.
• Put each file and each file pattern on its own line, with each separated
by a carriage return.
• Note that the files and file patterns that should not be signed override
any files and file patterns that should be signed. For example, if you
specify *.exe in the Include patterns and files box and in the Exclude
patterns and files box, InstallShield does not sign any .exe files.
Table 39-10: Settings on the Digital Signature Options Dialog Box (cont.)
Sign files that are Basic MSI, If any of the files in your project are already digitally signed, determine
already signed InstallScript, whether you want InstallShield to replace those existing digital signatures
InstallScript MSI, with the digital signature that you specify on the Signing tab. Note that this
InstallScript affects only files that meet the requirements that are specified in the Include
Object, Merge patterns and files and Exclude patterns and files boxes.
Module, Web
• To use the digital signature information that you are providing on the
Signing tab to sign a file instead of any existing digital signature
information that is already included with the file, select this check box.
• To leave the existing digital signature information intact for any files that
are already signed, clear this check box.
This check box is cleared by default.
Note: InstallShield signs a temporary copy of the file, and then it builds the
file into the appropriate media. InstallShield never modifies or signs the
original files.
Panel Options
Certificate ID
Enter your certificate ID.
Certificate Password
Enter the password for your digital certificate.
Panel Options
Password protect Setup.exe
Select this option to require the end user to enter a password in order for Setup.exe to run.
Password
Type the desired password into the Password field.
Tip: If you leave this box unchecked, you must enter your own code in the script to request the password from the end
user and check it by calling ComponentValidate.
Copyright notice
Panel Options
Include or set up .NET Framework
Select this check box to include the .NET Framework with your installation. If it is not available on the
target system, you can indicate the location where to find it and specify installation details.
.NET Version
Select the version of .NET Framework that you want to install to the target system.
Panel Options
Command line to pass to DotNetFx.exe
In the edit field, type a command line that you want to pass to DotNetFx.exe.
Panel Options
Command line to pass to LangPack.exe
Type a command line to pass to LangPack.exe.
Note: The version of Visual J# installed at runtime aligns with the version of the .NET Framework you selected in the .NET
Framework panel.
Panel Options
Include Visual J# run-time components
Select this option to include the Visual J# run-time components you select below
Panel Options
Release Settings
Location
Enter the directory where you would like your release to be saved. You may navigate to this directory by
clicking the Browse button. Alternatively, you may enter a path variable for your release location. To use
a path variable in this field, you can either navigate to the directory your path variable points to, or you
can enter the name of the path variable you would like to use, enclosed in angle brackets—for example,
<MyVariable>.
If your release will be stored on media that supports long file names, select this check box. If long file
names are not supported, or if you are uncertain what file name format your media supports, clear this
check box.
Optimize size
Select this check box to improve the compression of your data files. Selecting this check box will
generally decrease the size of your compressed files, but the build process may take more time to
complete.
If you used test values for any of your path variables, you can set those variables to their actual values at
this time.
Generate Autorun.inf
Choose this option if you are distributing your installation on a CD-ROM and want to support the
AutoPlay feature, a Windows logo requirement. A text file called Autorun.inf containing the instructions
to autoplay your installation will be created in the root of your disk images folder.
You can edit this file to add additional AutoPlay options or to pass command-line parameters to
MsiExec.exe or Setup.exe.
AutoPlay will not work in the disk image folders on your development system, because it is enabled only
in root drives. Note also that users can turn off AutoPlay on their own systems.
Select this check box to create a package definition (.pdf) file. Creating a .pdf file enables end users to
run your installation as an SMS job. This option creates a version 2.0 PDF file.
Panel Options
Build the Release
Select this option to build this release when you click Finish. Progress information for the build is
displayed in the Output window.
Note: The Build your Release option does not appear on the Summary panel if the Release Wizard was launched from
Microsoft Visual Studio.
Project: The General Options panel is available in the following project types:
• InstallScript
• InstallScript Object
Project: In an InstallScript object project, the Compiler Preprocessor Defines list and the Advanced button are available;
none of the other options on this panel are available.
File Name
Type a file name for the self-extracting executable file or select a path variable whose value defines the
password.
Icon
Optionally specify the fully qualified name of the file from which the executable file’s icon is taken at
build time; if no file is specified, a default icon is used. To specify a file, type an explicit path, select and
append to a path variable, or click the browse button to open the Change Icon dialog box, in which you
can click the Browse button to select a file. By default, the icon with index 0 is used; to specify a different
icon, either select an icon in the Change Icon dialog box or append the icon’s index or resource ID
(preceded by a minus sign) to the file name. For example, C:\Temp\MyLibrary.dll,2 indicates the
icon with an index of 2, and C:\Temp\MyLibrary.dll,-100 indicates the icon with a resource ID of
100.
Note: You can specify a non-default icon only when building on a Windows NT, Windows 2000, or Windows XP machine.
Such variables can be tested in the script by #if and #ifdef statements that control the flow of the script.
When you are creating an InstallScript object, enter IFX_OBJECTS.
Entering the name of a preprocessor variable in this box defines the variable. For example, if you enter
MYVARIABLE in this box, the script commands in the following #ifdef loop are executed:
#ifdef MYVARIABLE
// Commands
#endif
After you add or change a preprocessor variable definition in this box, you must compile your
installation project for the addition or change to take effect. To learn how, see Compiling Scripts.
Advanced
When you click this button, the General Options - Advanced dialog box opens. This dialog box lets you
specify a custom location for the built files, the space that is reserved in the disk images folders, and
whether the installation performs MD5 checking.
Features Panel
Project: This panel is not available for the following project types:
• Basic MSI
• InstallScript MSI
The Features panel allows you to specify which features are included in the built release.
Panel Options
Use the "Include in Build" property
If this option is selected, each feature whose Include in Build property is set to Yes is included in the
built release and each feature whose "Include in Build" property is set to No is not included.
Project: This panel is not available for Windows Installer–based or InstallScript MSI projects.
This panel allows you to specify, for individual features or for all features, whether the features’ files are
stored in cabinet files or placed uncompressed in the disk image.
Panel Options
Cabinet File(s)
Store all features’ files in cabinet files.
Note: You can specify in a component’s Compressed property whether the component’s files are compressed or
uncompressed when stored in a cabinet file.
CD-ROM Folder(s)
Place all features’ files uncompressed in the disk image. Files associated with a given feature are placed
in the disk image in the folder specified in the feature’s CD-ROM Folder property. If no folder is
specified, that feature’s files are placed in the root of the disk image.
Custom
If this option is selected, clicking the panel’s Next button displays the Custom Media Layout panel,
which lets you specify for individual features whether the feature’s files are stored in cabinet files or
placed uncompressed in the disk image.
Project: This panel is not available for the following project types:
• Basic MSI
• InstallScript MSI
This panel allows you to specify, for individual features or for all features, whether the features’ files are
stored in cabinet files or placed uncompressed in the disk image.
Panel Options
Features in cabinets
Lets you specify for individual components whether the component’s files are stored in cabinet files or
placed uncompressed in the disk image. To toggle a component’s storage mode, click the check box next
to the component. A checked box signifies that a component’s files are stored in cabinet files. An
unchecked box signifies that a component’s files are placed in the disk image in the folder specified by
the component’s CD-ROM Folder property. If no folder is specified, that component’s files are placed in
the root of the disk image.
Select All
Selects all features in the Features in cabinets box.
Clear All
Deselects all features in the Features in cabinets box.
Project: This panel is not available for the following project types:
• Basic MSI
• InstallScript MSI
This panel allows you to specify the look and feel of your setup’s end user dialog boxes.
Panel Options
Use project’s default
If this option is selected, the end user dialog boxes are displayed with the skin that is selected in the
Dialogs view’s Skins folder, as shown in the Dialog Preview graphic.
Dialog Preview
Displays a sample of how the end user dialog boxes will appear as a result of the selections you made
with the option buttons and list box.
• The dialog boxes that are displayed by the following functions cannot be displayed with a skin; they appear the same
regardless of whether you have specified a skin.
• AskYesNo
• EnterDisk
• MessageBox
• MessageBoxEx
• RebootDialog
• SdComponentDialog—the Available Disk Space dialog box
• SdComponentDialog2—the Select Subcomponents dialog box
• SdComponentDialogAdv—the Available Disk Space dialog box
• SdConfirmNewDir
• SdConfirmRegistration
• SdExceptions
• SdShowMsg
• SelectDir
• SelectDirEx
• SprintfBox
Note: Any release can be run over the Internet, regardless of its media type.
Setting Description
Generate One-Click To create a One-Click Install installation that end users can download from the Internet and
Install install, select this check box. If you select this check box, InstallShield includes with your
installation an external setup player (Setup.ocx file) that downloads and then launches
the Setup.exe file with the appropriate command line.
If you select this check box, the other settings on this panel are enabled.
To learn more, see One-Click Install Installations in InstallScript Projects.
Create a default Web Select this check box to indicate that you want InstallShield to create a default Web page
page for the setup (.htm file) in the Disk1 folder.
Enter the URL to launch Do one of the following to indicate what URL should be launched if you click the Run From
Web command on the Build menu:
• To launch the Setup.htm file that InstallShield creates at build time and places in the
Disk1 folder, leave this box blank.
• To launch a different Web page, type the URL in this box or click the browse button to
select the Web file.
Tip: If you enter a URL, do not include the name of the page, and do not include an ending
forward slash. For example, if the full URL for the Setup.htm file is http://
www.mypages.com/setup/Setup.htm, enter the following as the URL to launch:
http://www.mypages.com/setup.
When you click the Run from Web command on the Build menu, InstallShield launches the
appropriate URL (http://www.mypages.com/setup/Setup.htm, in the aforementioned
example).
Include Netscape If you want to include support for Netscape, select this check box.
Support
If you select this check box, InstallShield creates the files (Setup.zip and
Setupapplet.jar) that Netscape requires in order to launch the installation from the
Web page. These files are placed in the Disk1 folder.
If you clear this check box, the Setup.zip and Setupapplet.jar files are not created.
Update Panel
Project: This panel is not available for the following project types:
• Basic MSI
• InstallScript MSI
This panel allows you to specify the release format and the existing releases for which the current release
can be run as an update.
Tip: To create a setup that can be run on a system on which no version of your product is currently installed, select the Full
option and the Non-version specific option.
Panel Options
Full
Specifies that the current release is a full release.
Non-version specific
Enabled only if the Full option button is selected. Specifies that the current release can update any
existing version of your application (as long as it was installed by a setup that was created with
InstallShield Professional version 6.0 or later), or can install your application on a system on which no
version of your product is currently installed.
Version specific
Enabled only if the Full option button is selected. Specifies that the current release can update only the
versions of your application that are specified in the combo box.
combo box
Enabled only if the Version specific option is selected. Lets you specify the versions of your product to
which the update can be applied. Type a semicolon-delimited list of version numbers (for example,
1.2.3;1.2.4) or select a list of version numbers from the list box. If you leave this field blank, the update
can be applied to all earlier versions of your product.
Differential
Specifies that the current release is a differential release.
list box
Enabled only if the Differential option button is selected. Displays the existing releases to which the
current project is compared when creating the new differential release. A file in the current project is
excluded from the differential release if the same file (with the same date and time, size, and attributes)
exists in each of the specified releases; otherwise the file is included in the differential release. (Files in a
component whose Difference property is set to No are always included in the differential release.) You
specify these releases by clicking the Import and Add buttons.
Also displays the version information for each release.
Note: If the setup is unable to determine a specified release’s version information, that version of your product cannot be
updated by the setup. If no version information is displayed for a release, select the release, click the Modify button, then
select the Specify the version information below option and type or select a version number.
Add
Enabled only if the Differential option is selected. Opens the Existing Media dialog box, in which you can
specify a release that is in the current project.
Import
Enabled only if the Differential option is selected. Opens the Media File Properties dialog box, in which
you can specify a release that is not in the current project.
Modify
Enabled only if the Differential option is selected and a single release is selected in the list box. Opens
the Media File Properties dialog box, in which you can change the release selection and the version
information that is associated with the release.
Remove
Enabled only if the Differential option is selected and one or more releases are selected in the list box.
Removes the selected release from the list.
Objects
Enabled only if the Differential option is selected. Opens the Object Difference dialog box, in which you
select the conditions for including InstallScript objects in your differential release.
Dialog Options
Include All
Specifies that the differential build will include all objects that would have been included in a full (non-
differential) build. (This excludes, for example, objects that are associated with a feature whose Include
In Build property is set to No or that is deselected in the Release Wizard’s Features panel.)
Include If Changed
Specifies that the differential build will include only those objects that would have been included in a full
build and are absent from, or have an earlier version number in, all the specified comparison media.
Note: If the current project and all specified comparison media include the InstallShield Object Installer object, the media
builder compares the files packaged by the InstallShield Object Installer in the current project to the packaged files in the
specified media. The media builder includes in the InstallShield Object Installer only those files that are absent from—or
have an earlier date and time, different size, or different attributes in—all the specified comparison media.
Exclude All
Specifies that the differential build will include no objects.
Project: The Postbuild Options panel is not available for the following project types:
• Basic MSI
• InstallScript MSI
The Postbuild Options panel enables you to copy disk image folders to a folder or FTP site, or execute a
batch file, after the release build is complete.
Setting Description
Upload release files to To automatically distribute your release to an FTP site, select this
the FTP site specified check box and enter the FTP location. Also enter the user name and
below password, if applicable.
• FTP Location—Specify the FTP URL for the location.
If you need to distribute your release to a path outside the FTP
default folder, use a double slash (//). For example, to
distribute your release to a root-level folder called myproduct,
where the URL of the FTP server is ftp://ftp.mydomain.com,
enter ftp://ftp.mydomain.com//myproduct for the FTP
location.
• User Name—If a user name is required to upload to the FTP
location, enter the user name.
• Password—If a password is required to upload to the FTP
location, enter the password.
Copy the built media files If you want to be able to automatically distribute your release to a
to the folder specified folder, select this check box and specify the FTP URL for the
below location. Existing folders with the same names as copied folders are
overwritten, but no folders are deleted. Specify the folder path by
typing the path in the box, or click the browse button to browse to
the location.
If the media format of the selected release is a network image,
which creates only one disk image folder, the contents of the disk
image folder, rather than the folder itself, are copied. If you chose to
create a self-extracting executable file, the executable file, rather
than the disk image folders, is copied.
Setting Description
Execute the batch or To launch a batch file (.bat) or executable file (.exe) after the release
executable file specified has been built, select this check box and specify the path in the box.
below after building the You can either type the path or click the browse button to browse to
media files the file. In addition, you can select a path variable in the list and then
type the rest of the path.
If you select this check box, InstallShield sets environment variables
with the same names (including the angle brackets) and values as
the project’s build variables. InstallShield also sets the environment
variable <ISMEDIADIR>, whose value is the path to the folder in
which the release’s Disk Images, Log Files, and Report Files folders
are created. You can refer to the value of an environment variable in
a batch file by surrounding the variable name with percent signs (%);
for example:
set PATH = %<ISPROJECTDIR>%;%PATH%
When the file is finished, InstallShield deletes the environment
variables that it set.
Welcome Panel
The wizard is informing you that by adding files to a component you have violated one of the following
Setup Best Practices:
Components Should Not Each component should contain only one “portable executable”
Contain Multiple EXEs, file (an EXE, DLL, or OCX) or help file (CHM or HLP). Windows
DLLs, OCXs, CHMs, or HLPs Installer components are designed such that all of the advanced
settings and component properties, such as the code GUID, refer
ideally to a single portable executable or help file. Place other
EXEs, DLLs, OCXs, CHMs, or HLPs into new components.
A File Cannot Be Associated This Best Practice is extremely important for shipping reusable
with More than One components and ensuring resiliency. Microsoft recommends that
Component no file be shipped in more than one component, “even across
products, product versions, and companies.”
Use Merge Modules Merge modules contain all of the files, registry entries, and logic
necessary to install a distinct piece of functionality. You should
not distribute a file for which a merge module is available. Using
merge modules also helps you comply with two related
requirements—the Best Practice to avoid associating a file with
more than one component and the Windows logo guideline not to
ship any core components.
If the Best Practices monitoring option is enabled, the Setup Best
Practices Wizard alerts you whenever you try adding to a
component any file that is part of the merge modules that
InstallShield provides.
Panel Options
Please do not warn me of other Setup Best Practice conflicts
Selecting this option if you do not want the Setup Best Practices Wizard to notify you of Best Practices
violations. You can reverse this action later in the Tools | Options panel.
Compliance Panel
This panel tells you which files violate the Setup Best Practices listed in the Welcome panel by placing a
warning icon next to the file and citing the specific Best Practice rule violated.
Panel Options
Files
The list contains all of the files you added to the component and tells you which of them violates Best
Practices. You can ignore the wizard’s recommendations by clicking Finish (or Cancel to exit the wizard
altogether), or you can correct the Best Practices conflict by clicking the Remove button.
Remove
Select a file and click the Remove button to prevent the file from being added to this component.
How the .NET Scan at Build Component Property Affects Static Scanning
The setting of the .NET Scan at Build component property (Windows Installer projects only) affects how
the Static Scanning Wizard scans the files in your installation project in the following ways:
Table 39-14: Settings for Determining How the Static Scanning Wizard Scans Files
Setting Description
None The Static Scanning Wizard does not scan the .NET portion of the
component for dependencies or properties. For example, if your
component contains Notepad.exe and a .NET assembly file, the Static
Scanning Wizard scans Notepad.exe for dependencies and does not scan
the .NET assembly file for dependencies or properties.
Properties Only The Static Scanning Wizard scans the entire component—all files in the
component, including .NET assemblies—for properties, but it does not
identify dependencies for the .NET portion of the component. For example,
if your component contains Notepad.exe and a .NET assembly file, the
Static Scanning Wizard scans both files for properties, but it does not
identify dependencies for the .NET assembly file.
Dependencies and The Static Scanning Wizard scans the entire component—all files in the
Properties component, including .NET assemblies—for dependencies and properties.
Any dependencies found during the scan are presented in the File Selection
panel. If any properties are found for .NET files, the .NET Assembly grid
under the component’s .NET Assembly node under Advanced Settings is
populated.
Welcome Panel
The Static Scanning Wizard scans any .exe, .dll, .ocx, .sys, .com, .drv, scr, and .cpl files in your
installation project and adds their dependencies to your installation. These dependency files are added
to the same feature as the files that require them, ensuring that all necessary files are installed when
needed.
Click the Next button to begin scanning your setup files for any dependencies.
Panel Options
File
Indicate the files you want added to your setup by selecting the appropriate boxes. Additional
information about each of these files is also displayed in this field such as the feature it will be added to,
the location of the dependency file, and the file that requires it. The meaning of each type of icon is
described in the following table:
Icon Description
This icon indicates the file is a system or driver files. They are normally not
redistributed as part of a setup, and can potentially cause destination machines to
become inoperable. Ensure these files are necessary before including them.
This icon indicates a non-system file. Select the check box to the left of the icon to
include the file in your setup.
This icon indicates a merge module. Select the check box to the left of the icon to
add the specified merge module to your project.
This icon indicates a file that the Static Scanner has detected but is already in the
project.
Deselect All
Select this option to have none of the displayed files added to your setup. You can then manually select
the files you would like added.
Select All
Select this option to have all the displayed files added to your setup. You can then manually deselect the
files you would not like to be added.
Project: The System Search Wizard is not available in the following project types:
• InstallScript
• InstallScript Object
The System Search Wizard provides the Windows Installer capability to search for a particular file,
folder, Registry Key, .xml file or .ini value on a target system prior to installation. To access the wizard,
click System Search in the view list under Behavior and Logic.
The System Search Wizard consists of the following panels:
• Welcome
Welcome Panel
The Welcome panel is the first panel displayed in the System Search Wizard, which allows you to add or
modify a system search in your setup project. Click Next to add or modify a system search.
Task In this panel, specify the item you want to search for on the target system and the location of that item. To do
so:
1. Choose the appropriate item/search method combination from the drop-down list in the dialog.
This indicates what type of item you are searching for and where to conduct that search on the target
system.
2. Click Next to continue.
Note: If you are searching for a registry entry that contains a file path or folder, then the file or folder must exist on your
system in order for the search to be successful. Otherwise, the value from the search will not be set to a property.
If you are searching for a file or folder, the full path to that item is stored in the property. If you are searching for a registry
value, the data of that value will be stored in the property. The same holds true for .ini files. For components, the key path
to the component will be in the property.
To get the property using script, see MsiGetProperty in the Windows Installer Help Library.
Option Description
File Name Enter the full name and extension of the file or application you
want to locate.
Note: Once you have entered a file name, the Details button is
enabled. To modify your search to include any particular
version, date, size or language, click Details to display the File
Details dialog.
Look In The information in this field references where your setup will
look for items on the target system.
Option Description
Number of subfolder levels to Specify the number of subdirectory levels to search for the file
search on the target system.
Option Description
File Name Enter the full name and extension of the file or application
you want to locate.
Note: Once you have enter a file name, the Details button
next to that field is enabled. If you want to modify your
search to include any particular version, date, size or
language, click the Details button to enhance your search.
Look In: In this section, you can either specify a full path or choose a
path found in a previous search. When specifying a full path,
the browse button next to the edit field is enabled. Clicking
the browse button will bring up the "Browse for Directory"
dialog in which you can select an existing directory or create
a new one. When specifying a path from a previous search,
make a selection from the drop-down list.
Number of subfolder levels to In this field, specify the number of subdirectory levels to
search search for the file on the target system.
Option Description
Folder Name Enter the full name of the folder you want to locate.
Once you have entered a folder name, the Details button
next to that field is enabled. If you want to modify your
search to include any particular version, date, size or
language, click the Details button to enhance your
search.
Number of subfolder levels to In this field, specify the number of subdirectory levels to
search search for the file on the target system.
Option Description
Folder Name Enter the full name and extension of the folder you want
to locate.
Look In: In this section, you can either specify a full path or
choose a path found in a previous search. When
specifying a full path, the browse button next to the edit
field is enabled. Clicking the browse button launches the
"Browse for Directory" dialog, in which you can select an
existing directory or create a new one. When specifying a
path from a previous search, select from the drop-down
list.
Number of subfolder levels to Specify the number of subdirectory levels to search for
search the file on the target system.
Option Description
File Name Enter the full name and extension of the file or application you
want to locate.
Note: Once you have entered a file name, the Details button is
enabled. To modify your search to include any particular
version, date, size or language, click Details to display the File
Details dialog.
Look In The information in this field references where your setup will
look for items on the target system.
Number of subfolder levels to Specify the number of subdirectory levels to search for the file
search on the target system.
Option Description
File Name Enter the full name and extension of the file or application you
want to locate.
Note: Once you have enter a file name, the Details button next
to that field is enabled. If you want to modify your search to
include any particular version, date, size or language, click the
Details button to enhance your search.
Look In: In this section, you can either specify a full path or choose a
path found in a previous search. When specifying a full path, the
browse button next to the edit field is enabled. Clicking the
browse button will bring up the "Browse for Directory" dialog in
which you can select an existing directory or create a new one.
When specifying a path from a previous search, make a
selection from the drop-down list.
Option Description
Number of subfolder levels In this field, specify the number of subdirectory levels to search
to search for the file on the target system.
Note: Ensure that the syntax is correct by copying the correct key name from the Windows Registry Editor.
• Registry Value—This field allows you to search for a specific registry value. If you want to add this to
your search, enter the Registry value exactly as it appears in the Registry.
Note: If this field contains no data, the system search will look for the registry key’s default value.
Option Description
Field Description
INI File Name Specify the INI file name as it should appear on the target
system.
INI Section Name Obtain this information from the INI file. If you need to add a
section to an INI file, refer to INI File Changes view.
INI Key Name Enter the INI file key that can be found within the section.
Read entire line checkbox This option will search for data in the field column of an INI file’s
IniLocator Table if it is null or 0.
Specify the Data That You wish to Find in the XML File
This wizard panel is where you specify which .xml element you want to search for in an .xml file on the
target system. The settings in this panel allow you to search by attribute value, contents, or existence of
the element you specify.
Note: You can add a new property to your setup project via the Property Manager. Any new properties you create must be
public properties and have an identifier that consists of all uppercase letters. Save changes to your project after you add
a new property, so you can access that new property in your project. For example, the new property is listed in the
System Search Wizard.
You also have the option to use the property in an Install Condition by choosing the option in the
Additional Options section of the panel. Click Finish when you are done making your selections.
InstallShield automatically launches the Condition Builder if you have chosen to use the property in an
Install Condition.
Note: You can add a new property to your project via the Property Manager. Any new properties you create must be public
properties and have an identifier that consists of all uppercase letters. Save changes to your project after you add a new
property, so you can access that new property in your project. For example, the new property is listed in the System
Search Wizard.
Additional Options
Select from the options listed below.
Option Description
Just store the value in the property Stores the value in the property you select in this
dialog.
Use the property in an Install This will trigger the condition builder after you click
Condition Finish.
Use the property as the destination Selecting this option enables the component list. You
for a component can then choose a component with which to associate
the property.
Transform Wizard
The Transform Wizard walks you through the steps of creating and applying transforms for your
installation projects. Transforms represent the difference between two similar installation projects.
When you apply a transform to one project, you are updating or changing it to incorporate the changes
between the two projects.
On the Tools menu, click Create/Apply Transform. It is not necessary to have a project open in
InstallShield.
• Specify Files
• Validation Settings
• Summary
Welcome Panel
The Transform Wizard walks you through the steps of creating and applying transforms to your setup
project. A transform represents the differences between two setup projects. For example, network
administrators may want to distribute different configurations of a product to the various departments
in the company. As a result, you can create a transform for every configuration of the product, then apply
the appropriate transform as needed.
Panel Options
Create a transform
Select this option to compare two similar setup projects and create a transform that represents the
differences between them. This transform can then be applied at run time or before the final setup is
built.
Apply a transform
Select this option to apply a transform to an existing Windows Installer setup. This may be useful for
network administrators who will be customizing a product for everyone.
Panel Options
Base package
This field will contains the path to the project that is currently open. If you want to change this value,
enter the path to a different project or click the Browse button to navigate to one. If you are applying a
transform, this field should contain the path to the file that you would like the transform applied to.
Target Package
This option is only available if you are creating a transform. Enter the path to the MSI file that you would
like to compare to your base file, or click the Browse button to navigate to this file. The differences
between these two files will be compared and a transform will be created that will update the base
package to the target package.
Transform
This option is only available if you chose to apply a transform. Enter the path to the transform (*.mst)
file that you would like to apply, or click the Browse button to navigate to that file.
The Validation Settings panel prompts you for information on how you would like to validate your
transform. These validation items must be met in order for the transform to execute.
Panel Options
Do not perform validation prior to applying the transform to the base package
Select this option if you do not want to perform any validation prior to applying the transform.
Validate the following prior to applying the transform to the base package
Select this option to check for certain conditions before the transform is applied. If these conditions are
not met, the transform will not be applied.
Option Description
Default language must match base Select this option to ensure that the language of the
package transform matches the language of the package to
which the transform is being applied.
Product must match base package Select this option if you want your transform to be
applied only to .msi files that have the same product
code as the base package.
Platform must match base package Select this option to ensure that the platform for which
the base package is intended matches the target
platform of the transform.
Upgrade Code must match base Select this option if you want the transform to be
package applied only if the upgrade code of the .msi file
matches that of the transform.
Product Version Select the version type that you would like to validate
against. You can choose between a combination of
major version, minor version, or upgrade version. You
can also choose to not validate against the product
version.
Option Description
Version Relationship Specify how you would like to validate the product
version. The choices are outlined below:
• None—Do not validate against the product
version.
• Applied Version < Base Version—Apply the
transform only if the product version of the .msi
file to which the transform is being applied is less
than the version number of the base .msi file.
• Applied Version <= Base Version—Apply the
transform if the product version of the .msi file to
which the transform is being applied is less than
or equal to the version number of the base .msi
file.
• Applied Version = Base Version—Apply the
transform only if the product version of the .msi
file to which the transform is being applied is
equal to the version number of the base .msi file.
• Applied Version >= Base Version—Apply the
transform only if the product version of the .msi
file to which the transform is being applied is
greater than or equal to the version number of
the base .msi file.
• Applied Version > Base Version—Apply the
transform only if the product version of the .msi
file to which the transform is being applied is
greater than the version number of the base .msi
file.
Panel Options
Do not suppress error conditions when the transform is applied to the base package
Select this option if you do not want to hide the errors reported during the application of the transform.
Suppress the following error conditions when the transform is applied to the base package
Select this option to hide certain error codes from your end users. You can choose to suppress the
following errors:
Error Description
Adding an existing row If your transform tries to add a row to the MSI
database that already exists, an error is generated.
Select this option to suppress that error.
Deleting a row that does not exist Select this option to suppress any errors that occur as
a result of your transform trying to delete a row from
the MSI database that does not exist.
Adding an existing table Select this option to suppress errors caused by your
transform trying to add a table to the MSI database
that already exists.
Deleting a table that does not exist Select this option to suppress any errors that occur as
a result of your transform trying to delete a table from
the MSI database that does not exist.
Updating a row that does not exist If your transform tries to update a row to the MSI
database that does not exist, an error will be
generated. Select this option to suppress that error.
Transform and database code pages Select this option to suppress error codes caused by
do not match code pages in the transform not matching those in the
target database.
Panel Options
Folder location and file name
If you are creating a transform, enter the path and file name of the transform file that you would like to
create. If you are applying a transform, enter the path and file name of the new MSI package that you are
creating as a result of applying the transform.
Summary Panel
The Summary panel displays all of the settings you selected throughout the Transform Wizard. If you
need to change any of these settings, click the Back button until you reach the appropriate panel.
Tip: For more information about the errors that can occur when a transform is being applied to an .msi database, see the
MsiDatabaseApplyTransform topic in the Windows Installer Help Library.
Project: This wizard does not apply to the following project types:
• InstallScript
• InstallScript Object
On the Build menu, point to Validate, and then click Upgrade Validation Wizard.
• Settings
• Summary
Welcome Panel
The Upgrade Validation Wizard performs a set of tests to determine if your setup will properly upgrade
older versions of your setup.
Click Next to continue.
Settings Panel
Specify the following basic configurations for the upgrade validation:
Table 39-26:
Configuration Description
Specify the latest version of Click the browse button to locate the file.
your setup
Specify any previous versions of Click Add to append to the existing list. You can add *.msi or
your setup you want to validate *.exe Windows Installer Setup files. You can also specify
against multiple previous versions of your setup. To remove an item
from the previous versions list, you must first select it in the
list control and then click Remove.
Summary Panel
The Summary panel allows you to view the results from validation. You can also view the results
externally by opening the corresponding log file stored in <ISProjectDataFolder>\Upgrade Validation
Log\Results.log.
Note: You can run validation again with different settings by clicking the Back button and changing your settings.
The following table describes the icons next to each log file entry.
Button Description
Note: The wizard requires that Visual Basic is installed on your system. If you do not have it installed, and would like to
import a Visual Basic project, you need to install Visual Basic before you launch the wizard.
• On the File menu, click New. The New Project dialog box opens. Select the Visual Basic 6.0
Wizard project type.
Welcome Panel
The Visual Basic Wizard allows you to import Visual Basic projects into your setup project. The wizard
scans your Visual Basic project, detects any dependencies, and lets you determine which files you want
added to your setup.
Click Next to begin using the wizard.
Panel Options
Create a new project
Type the file name for a new setup project. The new project will be located in your default setup project
location.
Setting Description
Visual Basic Project There are three different ways to specify the project that you want
to import:
• Select a recently used project from the list by clicking the
arrow next to the list. This list shows recently used Visual
Basic projects—not necessarily the projects recently used by
the Visual Basic Wizard.
• Enter the fully qualified path to the project that you want to
import.
• Click the browse button and navigate to the project.
Rebuild project before Select this option if you want to rebuild your project before the
scanning wizard scans it for dependencies. It is a good practice to rebuild
the project just in case you have made changes since the last time
that you rebuilt it.
Filter files The Visual Basic Wizard may list as dependencies certain files that
you do not want added to your installation. For example, common
system files that are already present on target machines usually do
not need to be reinstalled. To avoid having these files added to your
installation when you run the scanner, select the Filter files check
box.
To learn how to customize the list of files that are excluded from
scans, see Filtering Files in Dependency Scanners.
Table 39-28: Specify Visual Basic Project File Panel Settings (cont.)
Setting Description
Add files from Microsoft’s Select this check box to add files from a specified .dep file. Enter
Package and Deployment the fully qualified path to the .dep file or use the browse button to
Wizard navigate to the .dep file.
Note: The Visual Basic Wizard does not offer the option to compare the files detected by the scan to only the files in
selected installation features.
Panel Options
Visual Basic executable
Enter the full path to the Visual Basic executable, or click the Browse button to navigate to the file.
Note: You cannot import Visual Basic projects if Visual Basic is not installed on your system. If you do not have Visual
Basic installed, exit the wizard and run the Visual Basic setup. After installed Visual Basic on your system, you can reopen
the wizard and import your Visual Basic project into your setup project.
Panel Options
File
To add dependency files to your setup, select the check boxes in front of the appropriate files. If you did
not deselect Filter Files in the “Specify Visual Basic Project File panel, you should be able to safely
include all files listed.
See Filtering Files in Dependency Scanners for more information.
Deselect All
Click this button to clear the selection of all displayed files. You can manually select the files you want
added to your setup.
Select All
Click this button to select all of the displayed files. You can manually deselect the files you do not want
added to your setup.
Click Next to view the Scan Results panel.
Note: The Visual Studio .NET Wizard is available only if Microsoft Visual Studio is installed on your system.
When you are creating the InstallShield installation project, the Visual Studio .NET Wizard does the
following:
• Creates a new InstallShield project (with the file name specified on the New Project dialog box) and
adds it to the solution (.sln file).
• If you have the Scan at Build option set to Dependencies and Properties (on the .NET tab of the
Options dialog box), the wizard adds all dependencies to your project at build time.
• Adds the primary outputs from every project in the solution to the InstallShield project.
• Updates the release settings to deploy the appropriate version of the .NET Framework via download.
To launch the wizard, select the appropriate project type in the New Project dialog box.
The following panels are associated with this wizard:
• Welcome Panel
Solution Panel
Welcome Panel
The Visual Studio .NET Wizard enables you to add an InstallShield installation project to a Microsoft
Visual Studio .NET solution.
Note: The Visual Studio .NET Wizard is available only if Microsoft Visual Studio is installed on your system.
Solution Panel
In this panel, type the path or browse to the Visual Studio solution to which you want to add the
InstallShield installation project.
Click Finish to create a new InstallShield project and add it to the selected solution.
Note: The Windows Installer 3.x Engine object automatically excludes features from the build based on the selections in
this wizard. The object determines this based on the name of the feature. If you customize the object source, be careful
when changing the names of the features to avoid unexpected effects. The object does not exclude features with names
other than the known feature names that are included in the base object template.
Tip: This object is not installed with InstallShield; you need to download it. For more information, see Obtaining Updates
for InstallShield.
When you launch this wizard from the Mobile Devices view, it is called the Windows Mobile Wizard.
When you launch this wizard by creating a new Smart Device project, it is called the Smart Device Setup
Wizard.
Note: Microsoft ActiveSync 3.x or later must be installed on the desktop computer in order to provide a desktop-to-device
installation. Active Sync 4.x is required for Windows Mobile 5.x devices.
Note: You can also use the Smart Device Setup Wizard with purely native code if you are targeting a storage card.
Wizard Panels
The following panels are associated with the Windows Mobile Wizard and the Smart Device Setup
Wizard:
• Welcome
• Application Information
• Add CABs (available only if Existing Mobile Device Cabinets is selected in the Project Type list of the
Application Information panel in the Windows Mobile Wizard)
• Destination Folder
• Project Outputs (available only if either wizard is launched from Microsoft Visual Studio and the
solution contains one or more Smart Device Application projects)
• Device Files (called Additional Files if the Project Outputs panel is displayed)
• Shortcuts
• Setup DLLs
• Registry Information
• XML Files
• Summary
Welcome Panel
The Welcome panel provides a brief introduction to the wizard. The wizard helps you build and
customize installations for Windows Mobile devices.
Note: When you launch this wizard from the Mobile Devices view, it is called the Windows Mobile Wizard. When you launch
this wizard by creating a new Smart Device project, it is called the Smart Device Setup Wizard.
The Application Information panel is used to specify information needed to install the application onto
the Windows Mobile or smart device.
Setting Description
Project Type Select the type of application that you want to support in your
project.
Note: You cannot change this option once you complete the wizard.
You will have to create a new application via the wizard to add to
your project.
Application Name Provide the name of your application for Windows Mobile devices or
smart devices.
Company Name Provide the name of your company or the company that produced
the application.
Project: This information applies to Windows Installer projects. The Desktop Settings panel is not displayed if you are
using the Smart Device Setup Wizard.
Select the location to which you want to copy the Windows Mobile or Smartphone application files.
Setting Description
Target Desktop Directory Select a target directory from this list or click the folder button to
launch the Browse for Directory dialog box.
Delete device media from Select this check box to delete the Windows Mobile media files
desktop during desktop from the desktop when the desktop installation is uninstalled.
setup uninstall
Note: If you would like to add more than one .cab file to a single Windows Mobile installation, see Special Considerations
for Adding Multiple .cab Files.
This panel is displayed only if you select Existing Mobile Device Cabinets in the Project Type list on the Application
Information panel of the Windows Mobile Wizard. It is not displayed if you are using the Smart Device Setup Wizard.
1. Click Add or right-click anywhere in the .cab box and select Add. The Open dialog box opens.
2. Browse to the file you want and click Open. The file is added to the list of .cab files.
Windows Logo Guideline: The recommended location for the destination folder is the following:
Program Files Folder\Company Name\Application Name
where Company Name and Application Name are the values set on the Application Information panel. This folder is
created and selected by default for new Windows Mobile installations.
Specifying Folders
Select the folder that you want to serve as the destination and then click Next.
The folder that is highlighted when you click Next becomes the destination folder for your application.
Adding Folders
1. Select the folder under which you want to add a new folder.
2. Click New. A new folder is created directly beneath the existing folder.
3. Type a name for the new folder.
Note: You can also add a new folder by right-clicking an existing folder and selecting New Folder.
Renaming Folders
Note: You can also rename a folder by right-clicking it and selecting Rename.
Removing Folders
Note: This panel is displayed only if the Windows Mobile Wizard or Smart Device Setup Wizard is launched in Visual Studio
and the solution contains one or more Smart Device Application projects.
Setting Description
Project Outputs Use this box to specify which project output groups you want to
associate with your smart device installation. In most cases, you
would select the Primary output group.
For each output group, click Properties to display the property
sheet for the selected group. The property sheet lets you to set
various attributes for the installation, including whether the
application should be installed to the Global Assembly Cache (GAC).
Note: This panel is called Additional Files if the Project Outputs panel is displayed.
Setting Description
Files This Files is where you add application files to your Windows Mobile
installation or your Smart Device project. When you add a file to this box,
you also need to specify its properties, such as which platforms and
processors support it. You must add at least one file in order to continue
with the wizard.
Setting Description
Suppress Display Some legacy mobile device platforms include support for portrait mode but
Warning not landscape mode. Therefore, in some circumstances, the installation for
a mobile device displays the following warning:
To prevent this warning from ever displaying, select this check box.
For more information, see Suppressing the Display Warning for Legacy
Mobile Device Applications.
Adding Files
1. Click Add or right-click in the Files box and click Add. The Open dialog box opens.
2. Browse to the file that you want to add and click Open. The Path Variable Recommendation
dialog box opens.
3. Indicate whether you want to use a path variable or an absolute path.
4. Click OK to close the Path Variable Recommendation dialog box. The Device Files dialog box
opens.
5. Specify the properties for the file you are adding and then click OK.
Note: To change the properties of a file after you have added it, select the file and then click Properties. The Device Files
dialog box opens.
Note: Microsoft ActiveSync has a 4-MB limit on file transfers. If your application files exceed this limit, you may need to
break your installation into smaller subcomponents in order to get it to transfer and install correctly.
Removing Files
Task To remove a file from the Files box, do one of the following:
Shortcuts Panel
Adding Shortcuts
1. Click Add or right-click in the Shortcuts box and select Add. The Shortcut Properties dialog
box opens.
2. Specify the settings for the shortcut that you are adding and then click OK.
Note: It is recommended that shortcuts not be created on the desktop unless the application is included in ROM; this may
also be a future Designed for Windows logo requirement.
Removing Shortcuts
Task To remove a shortcut from the Shortcuts box, do one of the following:
1. Click Add or right-click in the Setup DLLs box and select Add. The Open dialog box opens.
2. Browse to the file that you want to add and click Open. The Setup DLL Properties dialog box
opens.
3. Specify the properties for the file you are adding and then click OK.
Note: The Properties button is available for Windows Mobile devices only.
Task To remove a file from the Setup DLLs box, do one of the following:
• In the Setup DLLs box, select the file and click Remove.
Note: Only executable files with an .exe file extension can be associated with a document type. This panel is displayed only
if you have at least one executable file set to be installed into the folder specified on the Destination Folder panel.
When you add a file association to your project, a series of registry entries is automatically created on the
Registry Information panel under HKEY_CLASSES_ROOT. You could make all the necessary registry
entries yourself, but it is much easier to create them using this panel.
Caution: Windows CE Version 2.x has a limit on the amount of registry data that can be created in a single installation. If
you experience problems with registry entries being created incorrectly, you may need to decrease the number of file
associations and other registry entries. You can also use a setup .dll file with your installation to create the registry entries.
Adding Associations
1. Click Add or right-click in the File Associations box and click Add. The File Association
Properties dialog box opens.
2. Specify the properties for the file association that you are adding and then click OK.
Modifying Associations
• In the File associations box, select the file association and click Properties.
Removing Associations
Task To remove a file association from the File associations box, do one of the following:
• In the File associations box, select the file association and click Remove.
Caution: Windows CE Version 2.x has a limit on the amount of registry data that can be created in a single installation. If
you experience problems with registry entries being created incorrectly, you may need to decrease the number of file
associations and other registry entries. You can also use a setup .dll file with your installation to create the registry entries.
Note: Some registry keys and values are created by the Windows Mobile installation mechanism, or by any file
associations you have added to your project. Since these keys and values are created automatically, you will not be able
to delete, rename, or modify them in this panel.
Adding Keys
A new key is added under the selected key, and you are prompted for the key name.
Removing Keys
Right-click the key that you would like to remove and click Delete.
The selected key, all of its values, and all of its subkeys are removed.
Renaming Keys
Right-click the key and select Rename. Type the new name.
Adding Values
• Right-click the appropriate key, point to New, and click String Value, Binary Value, or
DWORD Value.
• Right-click an empty area in the box on the right, point to New, and click the appropriate type of
value.
Depending on which type of value you select, the Edit String Value dialog box, the Edit Binary
Value dialog box, or the Edit DWORD Value dialog box opens.
Removing Values
Renaming Values
Modifying Values
Depending on what type the value is, the Edit String Value dialog box, the Edit Binary Value dialog
box, or the Edit DWORD Value dialog box opens.
Note: Because the icon must be installed onto the desktop computer before it can be displayed in the Windows Mobile
Application Manager and Mobile Devices Explorer windows, this option is useful for desktop-to-device installations only.
Note: Only files with an .exe extension can be associated with the icon.
Panel Options
Specify Pre XML and Post XML files
To add XML to the .cab file, select this check box.
No Uninstall
Select this check box only if you are performing an upgrade of an existing installation. Never select this
check box if you are not upgrading.
Note: The options in this panel are not mandatory but recommended for security.
Panel Settings
Sign CAB
To sign a .cab file, select this check box.
Note: The Generate setup launcher (Autorun.exe) check box is available in the Smart Device Setup Wizard for
Smartphone only.
Note: This Generate Setup Launcher (Autorun.exe) option is available in the Smart Device Setup Wizard only.
Select this option to include Autorun.exe, which provides you with the ability to run installations from
storage cards. The Autorun.exe file that InstallShield generates is currently limited to running on Pocket
PC devices only.
Advanced
You can include the .NET Compact Framework and SQL redistributables for only specific processor and
platform combinations. Click this button to launch the Target Devices dialog box, which lists the
processor and platform combinations. Select the combinations that you want your installation to
support and click OK.
Features Panel
Project: This information applies to Windows Installer projects. The Features panel is not displayed if you are using the
Smart Device Setup Wizard.
In the Features panel, select the feature or features to which your Windows Mobile installation belongs.
Summary Panel
In the Summary panel, you can review the settings for your Windows Mobile or smart device installation
before you add it to your project. If you need to change any of the settings, click Back until you reach the
appropriate panel, and then make the necessary changes.
When you are done, click Finish. If you are creating a desktop-to-device installation, a component is
created for your mobile device installation, and it is added to all of the features that you selected to
associate with the mobile device application in the Features panel.
The appropriate installation files are automatically generated the next time that you build your
InstallShield project.
The InstallShield installation development environment (IDE) is organized into views that incorporate
various areas of functionality. The View Reference section describes each of those views in the
InstallShield interface.
Project: The Installation Information view is not available in the following project types:
• QuickPatch
• Smart Device
The Installation Information view contains links to other views that you can use to specify general
properties about your installation.
General Information
The General Information view contains basic information about your project, your company, and your
application, as well as string tables, which let you easily reuse and translate end-user text. Some of the
information you enter in this view is for your reference only, some is necessary to comply with Windows
logo requirements, and the rest is for setting basic project properties.
Project: The General Information view is not available in the following project types:
• QuickPatch
• Smart Device
Update Notifications
In the Update Notifications view, you can add FLEXnet Connect to your installation project. FLEXnet
Connect enables you to provide automatic application updates to your end users.
Project: The Update Notifications view is not available in the following project types:
• MSI Database
• QuickPatch
• Smart Device
Trialware
In the Trialware view, you can protect your product from piracy by including a license with it. The
license enables you to create a fully functional trial version of your product that expires after a
predetermined number of days or uses. No changes to your product’s source code are required.
Project: The Trialware view is not available in the following project types:
• MSI Database
• MSM Database
• QuickPatch
• Smart Device
• Transform
Edition: The Try and Die type of trialware is available in the Premier edition of InstallShield only. For more information
about the Premier edition, visit the Macrovision Web site.
Property Subview
Property Subview
Subviews
The General Information view contains the following subviews:
Name All This is a read-only setting that shows the name of your InstallShield
project file.
Type All This is a read-only setting that shows the type of project.
Location All This is a read-only setting that shows the location where the current
InstallShield project is stored.
Project File Format All Select the file format to use for your project file. The Binary format is
best for the speed of opening and saving the project file. It also enables
you to manipulate the project file using the Windows Installer API. The
XML format is best for use with source control systems. It enables you
to manipulate the project file using XML utilities.
Author Name All Specify your name or the name of the person who is creating the
installation package. This information is for your reference only and is
not displayed to end users.
Setup Languages All When you click this property, language information for your installation
is displayed in the Setup Languages pane. In this pane, select the
languages that you would like to support in your installation. For more
information, see Modifying Installation Languages.
Platforms InstallScript, Select the operating systems that you want to support in your
InstallScript Object installation.
Maintenance InstallScript, Select the behavior that occurs when a target machine already has
Experience InstallScript MSI your product installed and the end user reruns your installation. Valid
options are:
• Standard—Select this option if the maintenance user interface
should be displayed when a target machine already has your
product installed and the end user reruns your installation. Only
one entry for the product is listed in Add or Remove Programs.
• Multi-Instance—If end users should be able to rerun an
installation multiple times as a first-time installation rather than as
a maintenance installation, select this option. Each time that an
end user runs the installation, a separate entry is added to Add or
Remove Programs. By default, this option lets end users install the
product to a different location each time that they run the
installation. This is useful for a product that an end user may want
to install to different locations in order to experiment with different
product configurations and then later remove only specific
instances. The maintenance user interface is displayed only if an
end user reruns the installation from Add or Remove Programs.
• No uninstall or maintenance—If the end users should not be
able to uninstall the product or run it in maintenance mode, select
this option. No entry is created for the product in Add or Remove
Programs.
Update Mode InstallScript If this property is set to Yes, the default script code calls the
Supported OnUpdateUIBefore or OnUpdateUIAfter event handler functions
when appropriate (as determined by the OnSetUpdateMode and
OnShowUI event handlers). If this property is set to No, the default
script code never calls the OnUpdateUIBefore or OnUpdateUIAfter
event handler functions.
The value of the Update Mode Supported property is detected by the
following default code for the OnSetUpdateMode event handler:
MediaGetData( MEDIA, MEDIA_FIELD_MEDIA_FLAGS,
nMediaFlags, szIgnore );
if( ! ( nMediaFlags & MEDIA_FLAG_UPDATEMODE_SUPPORTED )
) then
Comments All Enter comments about this project. These comments are not displayed
to the end user.
If you are going to save this project as a template, note that the
comments are displayed as a description for the template in the New
Project dialog box.
Windows Installer databases (.msi and .msm files) are stored as COM structured storage files that
generally contain a summary information stream. To update information in the Summary panel for your
.msi or .msm file, set the Summary Information Stream properties. The Summary Information Stream
property sheet contains the following properties:
Property Description
Title This field contains the type of setup that is being created, such as an Installation
Database. Information entered in this field appears when a user right-clicks on your .msi
file, selects Properties, and clicks the Summary tab.
Subject Enter the name of the software application for which you are creating an installation.
Author Specify your name or the name of the person who is creating the setup package. When
you build a release, the author’s name supplies the value for the Author field in the
Summary Information Stream.
Keywords Type in any keywords that describe your product. Separate multiple keywords with a
semicolon. Information entered into this field is displayed when an end user right-clicks on
an .msi file, selects Properties, and clicks the Summary tab.
Package Code The package code is the globally unique identifier (GUID) for your setup package. Click the
generate GUID button to change the default GUID provided by InstallShield.
Note: Because Windows Installer requires any two .msi databases with identical package
codes to have identical contents, you should change the package code before releasing a
modified package. In the Releases view, you can specify that you want to generate a new
package code every time you build a release.
Property Description
Template Summary Use this property to set conditions on the installation of your product based on the user’s
processor type. For more information, see Using the Template Summary Property.
Schema Specify the integer that identifies the minimum Windows Installer version that is required
for your installation package. For example, if your package requires at least version 1.1 of
the Windows Installer engine, enter 110 for this setting.
If the end user’s system has a Windows Installer version earlier than the minimum
requirement specified in the Schema setting—for example, if you specify a schema value
of 120 and the end user has Windows Installer 1.0—the installation displays an error
message and exits.
Tip: If you are including the Windows Installer 1.2 engine with your installation, enter 110
for this setting.
The value that you enter for the Schema setting is used for the Page Count Summary
property of your .msi file.
Note: You can override this value for all of the releases that are associated with a
particular product configuration in your project by setting the Schema setting for the
product configuration in the Releases view.
Require Administrative Specify whether your .msi package requires administrative privileges for the execute
Privileges sequence of your installation. The default is Yes.
If you set this to No, InstallShield sets bit 3 in the Word Count Summary property to
indicate that elevated privileges are not required to install the .msi package. Note that if
you select No but your .msi package tries to perform a task for which it does not have
adequate privileges, Windows Installer may display a run-time error.
This setting applies to installations that are run with Windows Installer 4.0 on Windows
Vista systems. Earlier versions of Windows Installer ignore this setting.
Note that an end user’s installation experience is more secure when installations are run
with only the permissions that they need. Unless an application is designed to be run only
by system administrators, it should be run with the least privilege.
To learn how this setting and other InstallShield settings affect whether Windows Vista
displays a User Account Control prompt to elevate privileges, see Minimizing the Number
of User Account Control Prompts During Installation.
Setting Description
Display Icon Select the icon that is displayed for this product in the Add or Remove Programs panel
on systems running Windows 2000 or later. Enter the path to the icon, or click the
Browse button to navigate to the .ico or .exe file that contains the icon resource.
Display Icon Index If the icon file that you specify contains more than one icon resource, enter the index in
the Icon Index setting.
• A nonnegative integer refers to the order of the icon resources in the executable
file. For example, 0 refers to the first icon in the file, 1 refers to the second icon,
and 2 refers to the third icon.
• Use a negative number to refer to a specific resource ID. For example, the icon
index -12 points to the icon with a resource ID of 12.
Disable Change Button Set this option to Yes to hide the Change button on the Add or Remove Programs
panel. This button allows end users to change the installation options after the product
has been installed. The end user can remove or add features as needed.
Disable Remove Button The Remove button allows end users to remove the product by clicking one button,
which runs your uninstaller with a reduced user interface. Select Yes to hide this button.
Project: If the end user removes your Windows Installer-installed application with the
Remove button in the Add or Remove Programs panel, actions in the User Interface
sequence of the project are executed.
Setting Description
Publisher
Windows Logo Guideline: If you want to meet the requirements of the Certified for
Windows Vista program, you must enter the publisher.
Publisher/Product URL Enter a general URL for your company or product—for example, http://
www.macrovision.com. When an end user clicks the Support Information link in the
Add or Remove Programs panel (on systems running Windows 2000 or later), the
publisher/product URL is provided as a hyperlink.
Windows Logo Guideline: If you want to meet the requirements of the Certified for
Windows Vista program, you must enter a valid URL.
Support Contact Enter the name of the person or department that end users should contact for technical
support. This information is displayed to end users on the Support Information dialog of
the Add or Remove Programs panel on systems running Windows 2000 or later.
Windows Logo Guideline: If you want to meet the requirements of the Certified for
Windows Vista program, you must enter a support contact.
Support URL The Support URL is the address of the Web site where end users can find technical
support information for your product. This URL appears as a hyperlink on the Support
Information dialog of the Add or Remove Programs panel on systems running Windows
2000 or later.
Windows Logo Guideline: If you want to meet the requirements of the Certified for
Windows Vista program, you must enter a valid URL.
Setting Description
Support Phone Number This field should contain the technical support phone number for this product. This
information is displayed to end users on the Support Information dialog of the Add or
Remove Programs panel on systems running Windows 2000 or later, and must be
populated in order to achieve logo compliance.
Read Me Enter the name of the readme file for this product. This name appears in the Support
Information dialog of the Add or Remove Programs panel on systems running Windows
2000 or later. For more information, see Specifying a Readme File.
Product Update URL The Update URL should point to the Web site where end users can get information
about product updates or download the latest version. This URL appears as a hyperlink
on the Support Information dialog of the Add or Remove Programs panel on systems
running Windows 2000 or later. This field must be set to a valid URL in order to achieve
logo compliance.
Comments Enter comments about your application in this field. This information is displayed to end
users on the Support Information dialog of the Add or Remove Programs panel on
systems running Windows 2000 or later. This field must be populated in order to
achieve logo compliance.
Project: In an InstallScript MSI project, you can hide your application’s entry in Add or Remove Programs by setting the
Hide Add/Remove Panel Entry property in the Releases view to Yes.
Property Description
Name Enter the name of the product for which you are creating this installation. For more
information, see Specifying a Product Name.
Version Enter the complete product version for this product. The setup registers the major and
minor version numbers as required by Windows logo guidelines. For more information,
see Specifying the Product Version.
Application Type Select the type of application from the drop-down list or type the name of an application
type if it is not listed. This information is stored in the project file and is for your reference
only. It is never displayed to the end user.
Product Code/Product Enter a GUID that uniquely identifies this product. Click the Generate GUID button to
GUID generate a GUID for any new product. The setup registers this GUID as required by
Windows logo guidelines. For more information, see Setting the Product Code.
Property Description
Upgrade Code
Install Condition
INSTALLDIR
Property Description
Note: If the value of this setting is Custom and you change it to Yes, any custom
parameters that you defined for the MsiLogging property in the Property Manager will
be overwritten with the default value. If you change it to No, InstallShield deletes any
custom parameters from the MsiLogging property.
For more information, including details on how to customize the types of messages that
are logged, see Specifying Whether Windows Installer Installations Should Be Logged.
Company Name
Executable File
URL
Property Description
Font Registration
Task The string tables are found in the General Information view:
Every new installation project contains a string table for each supported language. InstallShield provides
all of the default string table entries necessary for the standard end-user dialog boxes and other user
interface elements. Each one begins with IDS_.
You will also see the string table for the default language while you are working throughout
InstallShield, such as in the shortcut Description property. You can edit this string table using the same
method that you would use to edit the default language’s string table in the Project view. For more
information, see Editing a String Table Entry.
Except for InstallScript custom actions, the string tables and identifiers themselves are not available at
run time. When you run a release, InstallShield resolves all of the string values for the language in which
the installation is running and writes only the values necessary for the current language into the
installation package.
Open the General Information view and click Server Locations. Server Locations is available in
Transform projects only.
FLEXnet Connect provides a mechanism that enables you to automatically notify your Web-connected
end users when patches, updates, and product information for your application are ready for release.
Using FLEXnet Connect is simple. When you enable FLEXnet Connect, InstallShield includes the
Software Manager in your installation. This desktop tool ships with your application and provides a tool
for your end users to view available updates. To publish updates to your end users, you need to use a
Web-based management portal called the FLEXnet Connect Publisher site.
FLEXnet Connect includes a variety of options that can be purchased together for a complete solution,
or separately for a customized solution. To learn more, visit the Macrovision Web site. To access the
FLEXnet Connect documentation, see the FLEXnet Connect Help Library.
Trialware View
Project: This view does not apply to the following project types:
• MSI Database
• MSM Database
• QuickPatch
• Smart Device
• Transform
• Compact
• ClickOnce
Note: Try and Die technology is available in the Premier edition of InstallShield only. For more information about the
Premier edition, visit the Macrovision Web site.
With the Trialware view, you can configure a license for trialware. InstallShield uses the license to wrap
a trialware shell around your product’s executable file (.exe, .dll, .ocx, or .scr file). The file can be
unwrapped and used only according to the license settings that you configure, such as the trial limit (a
specified number of days or a specified number of uses).
To obtain a license for an executable file in your project, you begin by right-clicking the Trialware Files
explorer in the Trialware view and then clicking New File Configured for Trial Usage.
Two tabs are associated with the file selected in the Trialware Files explorer:
• General
• Advanced
Two different types of icons are available for files in the Trialware Files explorer:
Icon Description
InstallShield displays this icon for a file in the Trialware Files explorer if a
corresponding executable file (.exe, .dll, .ocx, or .scr file), trialware type, and
license have been specified on the General tab.
Icon Description
InstallShield displays this warning icon for a file in the Trialware Files explorer if
the file still needs to be configured: a corresponding executable file (.exe, .dll,
.ocx, or .scr), trialware type, or license needs to be specified on the General tab.
If you build your project when this warning icon is displayed, a build error occurs
(unless you have chosen to exclude trialware protection from the release).
General Tab
The Trialware view has a General tab. InstallShield displays this tab when an item is selected in the
Trialware Files explorer.
The General tab is where you select an executable file (.exe, .dll, .ocx, or .scr file), a trialware type, and a
corresponding license for your trialware.
Setting Description
Trialware File (.exe, .dll, .ocx, or .scr) Select the .exe, .dll, .ocx, or .scr file in your
project that you would like to protect.
InstallShield will wrap a trialware shell around
this file. The file can be unwrapped and used
only according to the license settings that you
configure on the Advanced tab.
Once you have configured the above settings for a trialware file, the icon in the Trialware Files explorer
changes from a warning icon ( ) to a protected trialware icon ( ). If you build your project when the
warning icon is displayed, a build error occurs (unless you have chosen to exclude trialware protection
from the release).
Advanced Tab
The Trialware view has an Advanced tab. InstallShield displays this tab when an item is selected in the
Trialware Files explorer.
The Advanced tab is where you configure settings such as the trial limit (number of trial days or number
of uses) for your trialware. It is also where you set the hyperlinks for the trialware run-time dialogs and
access the InstallShield Activation Service Publisher Web Site.
Note: The default values for the URL-related properties listed below are for pages on the Macrovision Web site. You must
change these default values or delete them before releasing your trialware. Otherwise, hyperlinks to the Macrovision Web
site will be included in your trialware run-time dialogs.
Property Description
Manage Licenses Online Double-click the Manage Licenses Online property to access
the Publisher Web Site for the InstallShield Activation Service.
The Publisher Web Site is a Web-based tool that enables you to
configure license settings for Try and Buy/Product Activation
trialware.
Visit this Web site to perform tasks such as the following:
• Add to your licenses the serial numbers that end users will
use to activate your product.
• Modify license and serial number properties such as
number of activations allowed and enabled vs. disabled
status.
• Perform offline activations for your end users.
• Run reports to track the number of activations, gather
metrics on the success of a new product introduction,
identify serial numbers that end users might be abusing,
and much more.
Product Name Specify the name that you want to be displayed for your
product in the trialware run-time dialogs.
If you leave this property blank, the name that is listed in the
Product Properties view is used in the trialware run-time
dialogs. The Product Properties view is available from the
General Information view.
Type of Trial Limit Select the type of trialware limit: either number of days or
number of uses.
The type of trial limit that you select here is used as the unit of
measure for the Trial Limit Quantity and Extension Limit
Quantity properties. Note that it is impossible to have an
extension trial limit type that does not match the standard trial
limit type. For example, if you set the trial limit to a specific
number of days, you cannot set the extension trial limit to a
specific number of uses.
For the Try and Buy/Product Activation type of trialware, end
users need to activate the product if they have not already
done so once they have reached the trial limit. End users can
extend the trial only if trial extensions are allowed and if they
enter the correct extension serial number.
For the Try and Die type of trialware, end users can continue
using the product only if trial extensions are allowed and they
enter the correct extension serial number.
Property Description
Trial Limit Quantity Specify the number of days or the number of uses (depending
on the value of the Type of Trial Limit property) for the trial
limit:
• If the Type of Trial Limit property is set to Days, the trial
period starts on the day that the end user launches your
trialware product for the first time. The trial period starts
on that first day even if the end user clicks the Cancel
button on one of the trialware run-time dialogs and does
not start using the product.
• If the Type of Trial Limit property is set to Uses, the
countdown for the number of trial uses starts with the first
time that the end user launches your product. If an end
user clicks the Cancel button on one of the trialware run-
time dialogs and does not start using the product, the
number of uses does not change.
Serial Number Format Specify the format for your product’s trialware serial number
and—if trial extensions are allowed—the extension serial
number:
• Type a question mark (?) to represent each character in
your product’s trialware serial number. For example, if a
serial number consists of seven characters, type seven
question marks in this field.
• To split the serial number into groups of characters, type
a dash (-) between each group of question marks. The
dash indicates a break in the serial number, where one
group of characters ends and another begins.
For a serial number format of ???-????, the serial number field
on the trialware run-time dialog would consist of two boxes;
end users would be able to type only three characters in the
first box and only four characters in the second box.
If the type of trialware is Try and Buy/Product Activation, the
format for the serial numbers entered at the InstallShield
Activation Service Publisher Web Site must match the format
specified in the Serial Number Format property. Note that the
Publisher Web Site does not check to make sure that the serial
numbers match the format specified in InstallShield.
If you allow trial extensions, the serial number that you specify
for the Extension Serial Number property must fit the format
specified in the Serial Number Format property.
Property Description
Allow Trial Extension Specify whether end users are allowed to extend the trial for
your product. If you select Yes, enter values for the Extension
Limit Quantity and Extension Serial Number properties.
Note: Note that if you allow trial extensions, end users can
extend the trial only once. They cannot continually extend the
trial.
Extension Limit Quantity Specify the number of days or the number of uses (depending
on the value of the Type of Trial Limit property) that an end user
is allowed to extend the trial if they enter the correct extension
serial number.
If the Type of Trial Limit property is set to Days, the countdown
for the number of days in the trial extension period starts the
day after the initial trial period ends. This occurs even if the
end user does not immediately extend the trial, but instead
waits several days after the trial period is over to extend it. For
more details, see Trial Limits and Extensions.
Extension Serial Number Specify the serial number that end users need to enter if they
want to extend the trial. Use a dash (-) to indicate a break in the
serial number, where one group of characters starts and
another begins. The serial number that you specify must fit the
format specified in the Serial Number Format property.
Property Description
Note: The expiration date does not affect how long the Try and
Buy/Product Activation type of trialware can remain activated.
Activating this type of trialware before the expiration date will
make it permanently activated, unless end users deactivate the
product by uninstalling it. If they deactivate the product after
the expiration date, they will not be able to reactivate it.
Product Purchase URL Specify the URL for a page on your Web site that end users
can visit to find information about purchasing your product.
Note that the default value for this property is a page on the
Macrovision Web site. You must change this default value or
delete it before releasing your trialware.
When an end user clicks the hyperlink for more information on
purchasing your product on one of the trialware run-time
dialogs, this Web page is opened in a Web browser. If you
delete the URL in this box, the purchasing link is not displayed
in the trialware run-time dialogs.
Property Description
Feedback URL Specify the URL for a page on your Web site that end users
can visit to submit feedback to you. Note that the default value
for this property is a page on the Macrovision Web site. You
must change this default value or delete it before releasing
your trialware.
When an end user clicks the Feedback hyperlink on one of the
trialware run-time dialogs, this Web page is opened in a Web
browser. If you leave this box empty, the Feedback link is not
displayed in the trialware run-time dialogs.
If you want end users to submit feedback through email
messages instead of through your Web site, you can configure
this property with a mailto URL. If an end user clicks a mailto
URL hyperlink in one of the trialware run-time dialogs, a new
email message is opened in the end user’s email application,
and the destination address is populated in the To field.
For example, if you type the following text in this property, an
email message will open with feedback@mycompany.com in
the To field.
mailto:feedback@mycompany.com
You can also specify the text for the Subject line with the
following code, using %20 in place of spaces:
mailto:feedback@mycompany.com?Subject=My%20Subje
ct
Serial Number Information Specify the URL for a page on your Web site that end users
URL can visit to read information about where they can find their
serial number.
When an end user clicks the Where is my serial number?
hyperlink on one of the trialware run-time dialogs, this Web
page is opened in a Web browser. If you leave this box blank,
the Where is my serial number? hyperlink is not displayed in
the run-time dialogs.
This property applies to the Try and Buy/Product Activation
type of trialware only.
Help URL Specify the URL for a page on your Web site that end users
can visit to learn more about the trial of your product. Note
that the default value for this property is a page on the
Macrovision Web site. You must change this default value or
delete it before releasing your trialware.
When an end user clicks the Help hyperlink on one of the
trialware run-time dialogs, this Web page is opened in a Web
browser. If you delete the URL in this box, the Help link is not
displayed in the trialware run-time dialogs.
Property Description
Privacy Policy URL Specify the URL for a page on your Web site that end users
can visit to learn more about your company’s privacy policy.
Note that the default value for this property is a page on the
Macrovision Web site. You must change this default value or
delete it before releasing your trialware.
When an end user clicks the Privacy Policy hyperlink on one of
the trialware run-time dialogs, this Web page is opened in a
Web browser. If you delete the URL in this box, the Privacy
Policy link is not displayed in the trialware run-time dialogs.
Offline Activation Email If you want end users to be able to activate your product by
email, specify the email address that end users should use to
request an offline activation. This email address is typically a
distribution-list email address that your customer support staff
monitors often. Note that the default value for this property is a
sample email address. You must change this default value or
delete it before releasing your trialware.
If you do not want end users to be able to activate your
product by email, leave this property blank. The Activate by
Email option will not be displayed on the trialware run-time
dialogs.
For details on how to set this property, see Allowing Offline
Email Activations.
This property applies to the Try and Buy/Product Activation
type of trialware only.
Property Description
Offline Activation Phone If you want end users to be able to activate your product by
phone, specify the phone number that end users should call to
request an offline activation. The phone number that you enter
should be your own organization’s phone number—typically,
the phone number for your customer support staff. For more
information about the offline activation, see Overview of the
Activation Process.
If you do not want end users to be able to activate your
product by phone, leave this property blank. The Activate by
Phone option will not be displayed on the trialware run-time
dialogs.
Caution: The request codes and response codes that are used
with phone activations are shorter than the ones that are used
with offline email activations; the shorter length of the codes
makes it possible to read the codes over the phone. However,
short codes are not as secure as the longer codes used with
email activations. Therefore, Macrovision recommends that
you carefully consider the security risks associated with offline
phone activation before offering it as an offline activation
method. Use of this option is at your own risk, and Macrovision
accepts no responsibility if your company experiences security
issues.
This property lets you specify the following:
• One or more phone numbers.
• One or more locations. For example, if you have offices in
North America and Europe, you might want to provide one
phone number for customers calling from North America
and a different phone number for customers calling from
Europe.
• Other text strings, such as hours of operation.
For details on how to set this property, see Allowing Offline
Phone Activations.
This property applies to the Try and Buy/Product Activation
type of trialware only.
Organization View
The first step in building anything is to lay a solid foundation. The base of your project is formed by
specifying application information through the General Information view and—for installation
projects—creating features in the Features view.
Setup Design
The most important step in designing any setup is to lay out the various elements, the “building blocks”
of the installation. You need to think both from your user’s perspective as well as your own. The Setup
Design view gives you a full look at your setup and all the features, components, and redistributables
associated with it.
Features
Features are the building blocks of your installation. They represent a distinct piece of your application—
such as program files, help files, or clip art—to your end users. You can create features and subfeatures
in the Features view.
Components
Components are setup-authoring tools that help you organize similar application data, such as files,
registry entries, and shortcuts, into logical groups. Unlike features, they constitute the developer’s view
of a project.
Setup Types
Setup types offer your customers multiple configurations of your applications. Generally, these
configurations include Complete and Custom. Setup types allows your users to choose the best
configuration for their needs. This view is available only for InstallScript and InstallScript MSI setup
projects.
Project: This view and its subviews do not appear in the following project types:
• Merge Module
• MSM Database
• QuickPatch
• Smart Device
The most important step in designing any installation is to lay out the various elements, the building
blocks of the installation. You need to think both from the end user’s perspective, as well as your own.
You can design the entire installation hierarchy for your application visually under the Setup Design
view. This is the only view in which you can associate components with features and subfeatures.
Features
Features are the building blocks of your application from the end user’s perspective. They can be
installed or uninstalled based on the end user’s selections. Your entire application should be divided into
discrete features that perform a specific purpose. Features can be created in both the Setup Design view
and the Features view.
Components
Components enable you to group your application data together. Unlike features, components constitute
the developer’s view of a project—containing data such as files, registry entries, and shortcuts.
Components are associated with features in the Setup Design view, and a component may belong to
more than one feature. Components can be created in both the Setup Design view and the Components
view.
Tip: The Components section contains the Files, Registry Entries, and Shortcuts nodes, in addition to the Advanced
Settings for the component. If you do not want to see the subordinate nodes when they do not contain data, right-click
Setup Design and select Show Only Nodes with Data. When this option is selected, only the nodes that contain data are
displayed.
Redistributables
Redistributables enable you to install distinct, pre-existing pieces of functionality. For example, if your
application requires Visual Basic run-time .dll files, you can include the Visual Basic Virtual Machine
merge module, rather than add a file to your installation project and trying to determine its installation
requirements.
Note: Redistributables—including merge modules and objects—can be added to your installation in the Redistributables
view (or the Objects view in InstallScript projects).
Advanced Settings
Advanced Settings let you handle installation of components with special requirements. By specifying
the advanced settings, you can publish your component and register COM servers, file extension servers,
MIME types, and so on. You can also use the component’s advanced settings to create an application
paths entry in the registry.
Features View
Project: This view and its subviews do not appear in the following project types:
• Merge Module
• MSM Database
• QuickPatch
• Smart Device
A feature is a building block of an application from the end user’s perspective. It represents a specific
capability of your product—such as its help files or a part of a product suite that can be installed or
uninstalled based on the end user’s selections. Your entire application should be divided into features
that perform a specific purpose.
Subfeatures
Subfeatures are further divisions of a feature. Because features should be self-contained elements of an
application or application suite that a user can selectively install, it might make sense for you to organize
portions of your application as subfeatures of a “parent” feature. If all features are visible, your end user
can then select which portions of a feature to install in the custom Setup Type dialog that corresponds to
your project type.
• Basic MSI Project—Custom Setup
Note: Although you can create many levels of subfeatures, you should keep the design as simple as possible for
organizational purposes.
Components View
Project: This view and its subviews do not appear in the following project types:
• QuickPatch
• Smart Device
Components are installation-authoring tools that help you organize similar application data, such as
files, registry entries, and shortcuts, into logical groups. Unlike features, components constitute the
developer’s view of a project.
You can create and modify components in the Setup Design view (for installation projects) or the
Components view.
Tip: In the Setup Design view, the Components section contains the Files, Registry Entries, and Shortcuts nodes, in
addition to the Advanced Settings for the component. If you do not want to see the subordinate nodes when they do not
contain data, right-click Setup Design and select Show Only Nodes with Data. When this command is selected, only the
nodes that contain data are displayed.
Component-Feature Relationships
Components are associated with features in the Setup Design view. For more information, see
Associating New Components with Features.
Files
Expand a component’s tree and click Files to view a list of all files associated with that component. To
learn how to add files, see Adding Files to Components.
Note: To improve performance, the list displayed in the Files view truncates when there are more than a predefined
number of files in a dynamically linked file with subfolders. **List Truncated** appears as the first item in the file list when
this occurs. All files contained in the subfolders are built into your project.
Project: The Setup Types view is available only for InstallScript and InstallScript MSI installation projects. If your
installation is a Basic MSI project, the Setup Types view does not appear in the InstallShield interface. To create setup
types for a Basic MSI project, use the feature’s Install Level property.
Setup types enable you to provide different versions of your installation to your end users. For example,
the default setup types are Complete and Custom (Minimal, Typical, and Custom for an InstallScript
MSI project). Complete and Typical setups install all of the files included in your installation. Minimal
installs only those files necessary for your application to run. Such things as multimedia demos are not
installed in order to preserve hard disk space. The custom setup type lets the end user select which
features are installed.
Setup types are based on features. You select the features you would like to associate with each setup
type. Then, when an end user selects a certain setup type, only those features you associated with that
setup type are installed.
By default, each project you create contains predefined setup types. You can add or remove setup types,
rename existing setup types, and change which features are associated with each one.
Complete InstallScript The Complete setup type includes all of your installation
program’s features.
Typical InstallScript MSI The Typical setup type normally includes most, if not all,
of a program’s features. For example, if your installation
includes multimedia tutorials, they would be included as
part of the Typical setup.
Minimal InstallScript MSI The Minimal setup type usually only includes those
features absolutely necessary in order for your
application to run. This setup type is designed for those
people who have limited disk space, such as notebook
computers.
Custom InstallScript and The Custom setup type lets end users select which
InstallScript MSI features they would like to install. Required features
should be marked as such, to ensure that they are
always installed. However, features such as the online
help may not need to be installed. In these cases, the
end user can select which of the optional features to
install.
Project: The DIM References view is available in the following project types:
• Basic MSI
• Merge Module
is available for Visual Studio development environments, or InstallAnywhere Collaboration, a tool that
is available for Eclipse development environments. Both tools enables a developer to create or edit a
.dim file in the built-in editor. The software developer can also edit a .dim file using a third-party XML
editor. In any case, once the developer creates a .dim file, then you, the release engineer, can reference it
in an installation and wrap the package with a chosen installer technology.
Within InstallShield, you can use the DIM References view to manage all DIM references in your project.
DIM references are a grouping of similar application data items such as files, shortcuts, and registry
entries organized from the developer’s perspective. Your users will never see DIM references during the
installation; the data will be set up on their systems depending on which features are selected for
installation.
Project: In Basic MSI projects, DIM references must be associated with a feature.
Merge Module projects do not contain features. If you add a merge module that contains DIM references to an installation
project, InstallShield associates the DIM references with the feature in the installation project that contains the merge
module.
Several tabs are associated with the DIM reference that is selected in the DIM References view:
• General
• Variables
• Meta Info
• Data
• Dependencies
Understanding the Difference Between the DIM References View and the Setup
Design View in Basic MSI Projects
Although the DIM References view appears to be an exact subset of the Setup Design view, and, in fact,
you can create and modify DIM references in precisely the same way in both views, there is one major
difference between them. The Setup Design view is different because it allows you to associate DIM
references with features.
General Tab
Project: The DIM References view is available in the following project types:
• Basic MSI
• Merge Module
The General tab in the DIM References view displays the following properties associated with a
particular DIM reference:
Table 40-11: Settings on the General Tab in the DIM References View
Setting Description
Name This required property represents the name of the feature or subsystem that this DIM represents.
The name of your DIM defaults to the value of this property, that is, Name.dim.
UUID This property is required. A default universally unique identifier (UUID) is automatically generated in
this field for the DIM.
Version This required property represents the version of this DIM. The default value is 1.0, which means that
this is the first version. You can specify up to four places for this value, for example, 1.0.0.0.
Description This optional property is a description of the functionality or subsystem that this DIM represents.
Author This optional property is the name of the author of this DIM.
Note: You will need to add SQL scripts and virtual directories that you have defined in a DIM to your installation project and
maintain them in the SQL Scripts and Internet Information Services views. For more information, see Inserting SQL Script
Files Associated with a Referencing DIM File and Inserting DIM Virtual Directories.
Variables Tab
Project: The DIM References view is available in the following project types:
• Basic MSI
• Merge Module
The Variables tab in the DIM References view displays all of the build and run-time variables defined in
a DIM. All of the values in the Value field are writable and should be set in order for them to be resolved
properly. Changing the value overrides the value for the Unit Test Value setting. The Unit Test Value
setting is read-only and is the value set by the DIM author in the DIM.
Project: The DIM References view is available in the following project types:
• Basic MSI
• Merge Module
The Meta Info tab displays all of the meta tags defined in a DIM. The information on this tab is read-
only.
Meta information is optional and can describe the content, dependencies, and version of the DIM. The
information you specify here is added to the metaInfo element, which is a child of the root element in the
DIM.
Data Tab
Project: The DIM References view is available in the following project types:
• Basic MSI
• Merge Module
The Data tab in the DIM References view displays a listing of all installation elements included in a
particular DIM. It shows the name of an element and the total number of records associated with it. The
information in this tab is read-only.
Dependencies Tab
Project: The DIM References view is available in the following project types:
• Basic MSI
• Merge Module
The Dependencies tab in the DIM References view displays all of the DIMs that are required by a
particular DIM reference. Each dependency is identified by its UUID and Version property values.
On this tab, you must browse for the corresponding source file for each required DIM or dependency.
Project: This view and its subviews do not appear in the following project types:
• QuickPatch
• Smart Device
Application data includes all of the files you add to your project.
Project: Not all items apply to every project type. Refer to the View list to see which views are available.
Redistributables/Objects
The Redistributables view—or in InstallScript projects, the Objects view—enables you to add objects and
merge modules to your installation project. Including redistributables to your project lets you add
distinct pieces of functionality to your installation. Examples of these types of functionality include
Visual Basic run-time .dll files and the Microsoft C run-time libraries.
You can also use the Redistributables view to add setup prerequisites to your project. A setup
prerequisite is a base application or component that must be installed on the target machine before your
application can be installed. You can include in a Basic MSI project the setup prerequisites that are
included in InstallShield. You can also use the Setup Prerequisite Editor in InstallShield to create your
own prerequisites.
Mobile Devices
If your installation requires that a desktop component be installed along with a mobile device
component, use the Mobile Devices view to add the mobile device components to your project.
Project: This view and its subviews do not appear in the following project types:
• QuickPatch
• Smart Device
The main purpose of most installation programs is to transfer files from the source medium to the target
destination. With InstallShield, adding files to your project is a simple drag-and-drop process.
Note: The Files and Folders view from within Microsoft Visual Studio differs from the Files and Folders view in InstallShield.
For more information, refer to Adding References to Visual Studio Solutions.
Adding Files
You can add files to your installation project in one of three different ways. Each of these methods is
described below:
You can drag source files from the top pane to the destination folder in the bottom pane. InstallShield
also provides a context menu with additional drag and drop options that allow you to drag folder only
and to preserve the source structure.
Note: To improve performance, the list displayed in the Files and Folders view truncates when there are more than a
predefined number of files in a dynamically linked file with subfolders. **List Truncated** appears as the first item in the
file list when this occurs. All files contained in the subfolders are built into your setup project.
Dependency Scanning
The final way to add files to your setup is accomplished through the Dependency Scanners view. This
view contains three wizards that can scan your setup project, a running application, or a Visual Basic
project for all dependency files and add them to your setup. All three of these wizards can also be
launched from the Project menu.
Note: The Extract COM Data for Key File and Refresh COM Data for Key File options are enabled only if the file is a
self-registering .dll, .ocx, or .exe file, and if the file is the component’s key file.
1. Right-click on a folder in the Destination computer’s folders pane and select New Folder.
2. Type a name for the folder.
Note: To change the folder’s location in the Destination computer’s folders tree structure, drag and drop the folder to a
different location.
Note: This list box is only for selecting the feature (or component) with which new components will be associated. It is not
used to associate files directly with a specific feature.
If no features exist, you have the option of creating one when you first add files in this view.
Note: To display components in the Files and Folders view, right-click on a destination folder (in the lower-left pane of the
view) and select Show Components from the context menu.
Project: This view and its subviews do not appear in the following project types:
• Merge Module
• MSM Database
• QuickPatch
• Smart Device
The Redistributables view (or in InstallScript projects, the Objects view) contains all of the InstallShield
objects and third-party merge modules that are included with InstallShield. In Windows Installer
projects, this view also contains setup prerequisites that you can add to your project.
Project: (Windows Installer projects only) To see only the redistributables that are included in your installation project, right-
click any redistributable and select Show Only Selected Items. To specify which types of redistributables—all types,
merge modules, objects, or setup prerequisites—should be displayed, select the appropriate option in the Object types
to display list.
Merge Modules
A merge module (or .msm file) contains all of the logic and files needed to install distinct pieces of
functionality. For example, many applications require Microsoft Visual Basic run-time .dll files. Instead
of having to include the file in a component and figure out its installation requirements, you can simply
attach the Visual Basic Virtual Machine merge module to one of your project’s features.
Note: Many of the merge modules included in the Redistributables view are authored by Microsoft or another third party.
InstallShield distributes these modules as a courtesy to assist you in creating your installation project. However,
InstallShield cannot modify or fix any problems that may exist within third party-authored modules. You are encouraged to
contact the vendor regarding issues with specific third party-authored modules.
Objects
Like merge modules, objects contain logic and files needed to install distinct pieces of functionality.
Some objects, such as the Microsoft Access object included with InstallShield, require customization
through a wizard. As soon as you add such an object to your installation, its customization wizard opens.
You can either customize your object at the time you add it, or cancel the wizard and customize your
object later by right-clicking the object and selecting Change Objects Settings.
Redistributables view, the Merge Module Configurable Values dialog box is displayed to enable you to
configure the module at the time you add it. To customize the merge module later, right-click it and click
select Configure merge module.
Project: This view and its subviews appear in the following project types:
• Basic MSI
• InstallScript MSI
• Web
Use the Mobile Devices view if you are creating an installation that requires a desktop component to be
installed along with a mobile device component. When you add a mobile device installation to your
project through this view, InstallShield automatically creates a corresponding component and adds that
component to all of the features that you selected to associate with the mobile device application.
This view enables you to do the following:
• Create an installation package for a Windows Mobile device such as the Microsoft Smartphone or a
handheld PC. You can use Microsoft eMbedded Visual Tools 3.0 or Microsoft eMbedded Visual C++
4 to author your application. The package installs the necessary Windows Mobile .cab files to the
end user’s desktop computer first, and then either launches the Windows Mobile Application
Manager or uses Microsoft ActiveSync to copy the correct files onto the Windows Mobile device. It
can also optionally register an icon file on the desktop computer with Windows CE Services, so that
the icon is displayed within the Windows Mobile Application Manager window.
• Create an installation package for Palm OS devices. The application files can be deployed via
HotSync to the Palm OS device. You can target either the device’s memory or a storage card.
• Add .cab files that have already been built to a Basic MSI project. The .cab files can be created by
using the Windows Mobile Wizard/Smart Device Setup Wizard, or they can be some other Windows
Mobile–compatible .cab files that you have on your machine.
The Windows Mobile Wizard/Smart Device Setup Wizard or the Palm OS Wizard launches when you
add a mobile device installation to your project. These wizards help you to customize the settings for the
devices that you want to target.
Note: Either Windows CE Services 2.x or ActiveSync 3.x must be installed on the desktop computer in order to provide a
desktop-to-device installation. If Windows CE Services is not available, the mobile device package is automatically
disabled.
Tip: To create a dedicated installation for a smart device application, use the Smart Device project type.
Every installation changes the target system in some way. The simplest installations might only copy
files. More in-depth installations make registry changes, edit .ini files, or create shortcuts. InstallShield
provides the following subviews for making advanced configurations.
Shortcuts
Project: The Shortcuts view is not available in the following project types:
• InstallScript Object
• QuickPatch
• Smart Device
Shortcuts offer quick access to your installed application. You can create shortcuts and program folders
on the desktop, the Start menu, and various other locations.
Registry
In the Registry view, you can create registry entries or import existing registry data into your setup.
ODBC Resources
Project: The ODBC Resources view is not available in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
In the ODBC Resources view, you can add drivers, translators, and data sources to one or more of your
application’s features. Select from installed ODBC resources or add new ones to the list, associate them
with features, and then customize their attributes.
Project: The INI File Changes view is not available in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
The InstallScript language includes several initialization file functions for manipulating .ini files.
Although editing system .ini files is not recommended in Windows 2000 or later, you can edit these files
in the INI File Changes view. This view allows you to create sections and keywords, or edit an .ini file on
the target system.
Environment Variables
Project: The Environment Variables view is not available in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
The InstallScript language includes the GetEnvVar function for retrieving the current value of an environment variable, and
it enables you to create an environment variable.
If you need to create, modify, or remove environment variables from the target system, you can define
their properties in the Environment Variables view.
Shortcuts View
Project: The Shortcuts view does not appear in the following project types:
• InstallScript Object
• QuickPatch
• Smart Device
The Shortcuts view provides a simple, visual way to create shortcuts to your application on the target
system. This view contains a Shortcuts explorer that shows a set of predefined destination folders under
which you can create shortcuts and subfolders. InstallShield offers the following standard shortcut
destinations.
Programs Menu and Programs Menu and Startup are located in the Start menu. The Programs Menu folder is the
Startup industry standard and Microsoft’s suggested method. The Startup folder should contain
shortcuts to only those items that need to be launched whenever Windows starts.
Send To
Desktop The end user’s desktop. When you create a shortcut in the desktop folder, your application’s
icon is displayed on the end user’s desktop.
When you add a new shortcut, InstallShield adds it as a new node to the Shortcuts explorer in this view.
The new shortcut node is displayed with the same icon that is selected in the Icon File setting for the
shortcut—which is the icon that is used when the shortcut is added to target systems at run time—unless
either of the following conditions is true:
• The project type is InstallScript.
• The shortcut is for a preexisting file on the target system.
For both of the aforementioned conditions, the icon file is not known until run time. Therefore,
InstallShield shows the following icon for each shortcut in the Shortcuts explorer, instead of displaying
the icon that is used at run time on target systems.
InstallShield also uses this icon for a shortcut in the Shortcuts explorer if the icon file does not contain
an icon.
Registry View
In InstallScript projects, groups of registry keys and values are called registry sets. There is no limit to
the number of registry sets you can create (or the number of keys and values inside a single registry set).
The installer automatically creates certain registry entries based on values you provide for your project
and product properties. These informational keys are required by Windows logo guidelines. Also, all of a
component’s advanced settings are used to register files on the target system.
Project: This view and its subviews do not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
One of the more complex areas of system configuration involves setting up ODBC drivers, data source
names (DSNs), and translators. The ODBC resource must be properly registered on the system with all
of the required attributes and, in the case of drivers and translators, install the necessary files, including
any installation .dll files. This process is simplified in the ODBC Resources view, in which you can select
the drivers, data sources, and translators installed on your development system.
Project: For installation projects: The ODBC Resources view is exclusively for installing ODBC-related resources. To install
the core ODBC files, select the MDAC 2.5 merge module in the Redistributables (Objects) view.
For merge module projects: The Merged Feature check box in the upper-right corner of this view is selected when you add
an item and cleared when you remove an item in the ODBC Resources pane. It does not affect your project.
Project: This view and its subviews do not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
The INI File Changes view enables you to specify changes that should be made to initialization (.ini) files
on the target system. These types of files serve as a database in which you can store and retrieve
information between the uses of your applications. Some .ini files, such as Boot.ini and Wininit.ini, are
used by the operating system. Although you can edit any .ini file found on the target system, editing
system .ini files is not recommended.
Project: This view and its subviews do not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
Environment variables are name and value pairs that can be set on the target system with your
installation program and can be accessed by your application and by other running programs.
In the Environment Variables view, you can create, set (or modify), and remove environment variables
on the target system via your installation program. You can also specify environment variable properties
in this view.
Note: For target systems running Microsoft Windows 95 or 98, the environment variables are modified in, created in, or
removed from Autoexec.bat. Environment variables are stored in the registry on systems running Windows NT 4.0 or
Windows 2000 and later.
Project: The XML File Changes view is available in the following project types:
• Basic MSI
• InstallScript MSI
• InstallScript
• MSI Database
The XML File Changes view is where you add references for nodes and node sets of XML files that you
want to change at run time. The XML files can be part of your installation, or they can be files that are
already present on target systems.
Two key parts of this view are the View Filter (a list of the project’s features and components) and the
XML Files explorer (a tree view):
• The View Filter enables you to filter data by feature or component.
• The XML Files explorer is where you add references to XML files and XML data that you want to
create, modify, or remove at run time. Each node represents an XPath expression that your
installation carries out at run time to select existing nodes or node sets in an XML file.
Important: The XML File Changes view is not designed to list a node for every node in an XML file. To improve
performance, the XML File Changes view should show only the settings that differ from the base XML file:
• If the XML file that you are modifying is part of your installation, the XML File Changes view should list only the nodes
and node sets that should be added, changed, or deleted after the XML file is installed at run time.
• If the XML file that you are modifying is a file that is already present on the target system, the XML File Changes view
should list only the nodes that need to be added, changed, or deleted at run time.
Therefore, when you are importing a file, import only the nodes in the XML file that you want to modify at run time.
Note that the XML File Changes view does not enable you to specify the order in which new elements should be listed in
the XML file. Therefore, importing only the nodes that you want to modify at run time helps to avoid issues that may occur
if your product requires that the elements be listed in a particular order.
The XML File Changes view also displays different tabs in the right pane, depending on what is selected
in the XML Files explorer. For reference information about each of the settings on these tabs, see the
following:
• General Tab for an XML File
Table 40-13: General Tab Settings for a File in the XML File Changes View
Option Description
File Name The file name represents the XML file name as it appears in the
explorer. Click Browse to launch the string table associated with your
project. The string table is available for any necessary string
translation.
XML File Destination Specify the location of the XML file on the target machine. Click
Browse to locate an existing directory or to add or create a new one.
Select the Features the Select or clear the features that you want to associate with the XML
XML File Belongs to file. InstallShield automatically associates a feature with an XML file
when it is added to the XML File Changes view.
Option Description
Always create XML file if it If an XML file does not exist on the target system at run time,
doesn’t already exist then one will be created based on the specifications for that file in
the XML File Changes view.
Remove XML file on Select this setting if you want to remove the XML file on the
uninstall target system upon uninstallation.
Encoding Specify the encoding that should be used for the XML file.
XPath Query
This read-only grid displays the XPath expressions to be executed on the target machine at run time
based on the XML format you have configured in the XML File Changes view.
Tip: For more information about XPath expressions, consult the World Wide Web Consortium (W3C) Web site. Another
relevant article entitled Things to Know and Avoid When Querying XML Documents with XPath can be found in the MSDN
Library.
Option Description
Prefix Specify the prefix that should be added to elements that are
associated with this namespace.
URI Specify the uniform resource identifier that identifies the Internet
resource for the namespace. The URI can be a URL or a string of
characters.
Note: The MSXML parser does not use the URI to look up information
about the namespace. The only purpose of the URI is to give the
namespace a unique name within the XML file.
Element Name
The element name represents the declared element type for the XML file. Click the browse button to
launch the string table associated with your project. The string table is available for any necessary string
translation.
Attributes
Option Description
Value Enter the value for the attribute type. Click the browse button to
launch the string table associated with your project. You can add MSI
properties here.
Scheduling Specify when to apply the attribute changes in this table by selecting
from the following scheduling options: Install, Uninstall, and Both.
Tip: You can use dynamic values from Windows Installer properties or text substitution to store different values into the
XML file.
Option Description
Update first matching To modify only the first matching element in the target XML file, select
element only this check box.
If you clear this check box, every matching element in the target XML
file is changed.
Always create this To always create this element on the target machine if it does not
element if it doesn’t already exist, select this check box.
already exist
Remove element on To remove this element from the XML file when the component
uninstall containing this XML file change is uninstalled, select this check box.
Option Description
Set Element Content To add text content to the element, select this check box and enter
the text in the Content box. To use a string in the string table, select
the ellipsis button (...).
In the following XML example, feature is the content for the element
product:
<product>feature</product>
Content Enter a string with which to update the element. There is a 255-
character limitation.
Project: This view and its subviews do not appear in the following project types:
• InstallScript Object
• QuickPatch
• Smart Device
InstallShield makes it easy to configure server side installations by providing the following sub-views
under Server Configuration in the view list.
Component Services
To add component services to your installation project, go to the Component Services view.
SQL Scripts
The SQL Scripts view provides a central location for managing and organizing all SQL scripts by
connections and settings.
Project: The Internet Information Services view and the tabs in this view are available in the following project types:
• Basic MSI
• InstallScript
• InstallScript MSI
• Web
The Internet Information Services view enables you to create and manage new IIS Web sites, virtual
directories, application pools, and Web service extensions.
The View Filter list at the top of the Internet Information Services view contains the names of all of the
features and components in your project. This list lets you show and hide virtual directories, application
pools, and Web service extensions that are included in specific components in your installation. The
View Filter list is not used to filter Web sites because Web sites are not tied directly to features or
components. For more information about the View Filter list and about IIS components, see Feature and
Component Associations for IIS Support.
The Internet Information Services view contains several areas:
• Web Sites
• Application Pools
Web Sites
Use the Web Sites item in the Internet Information Services view to add and delete Web sites, and to
configure system-wide settings for the Web server.
When you select the Web Sites explorer in the Internet Information Services view, the following Web
server settings are displayed.
Setting Description
Restart web server after To restart the IIS service (W3SVC) after the installation has completed making IIS changes
configuring IIS (IIS 6 and to the target system, select Yes for this setting.
earlier only)
This setting applies to IIS 6 and earlier. IIS 7 ignores this setting.
Setting Description
SSIEnableCmdDirective Specify how you want the SSIEnableCmdDirective registry value for the
Registry Value HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters registry
key to be set on the target system. The SSIEnableCmdDirective registry value controls
whether the Web server allows the #exec CMD directive of server-side includes (SSIs) to
be used to execute shell commands. Valid options are:
• Ignore—Do not change the SSIEnableCmdDirective registry value on the target
system. This is the default option.
• FALSE (0)—Set the SSIEnableCmdDirective registry value on the target system to 0.
This prevents the #exec CMD directive of server-side includes to be used to execute
shell commands. Note that if you select this value and an IIS Web server has
applications that rely on #exec CMD directives, those applications may stop working
properly after your installation project's Web site and virtual directory are installed.
• TRUE (1)—Set the SSIEnableCmdDirective registry value on the target system to 1.
This allows the #exec CMD directive of server-side includes to be used to execute
shell commands.
If you select the FALSE or TRUE options, InstallShield stores the value—either 0 for FALSE
or 1 for TRUE—in the INSTALLSHIELD_SSI_PROP property.
For IIS 4, the SSIEnableCmdDirective registry value is set to TRUE (1) by default. Because
of security concerns, the default value is FALSE (0) starting with IIS 5; the FALSE (0) value
prevents end users from running unauthorized server-side executable files.
Note: The aforementioned Web server settings are not updated on a target system at installation run time if no IIS items
(virtual directories, application pools, or Web service extensions) are installed.
When you select a Web site in the explorer, you can use the following tabs to configure IIS settings
associated with that Web site:
• General
• Web Site
• Home Directory
• Documents
• Directory Security
• Custom Errors
• Advanced
Most of the settings are also configurable through the IIS Microsoft Management Console. Therefore,
consult the IIS Snap-in help from within the Microsoft Management Console for the latest information
on specific IIS settings.
General Tab
When you select a Web site in the Internet Information Services view, InstallShield displays several tabs.
The General tab displays some Web settings.
Setting Description
Delete Web Site on Select this check box if you want to delete the specified Web site upon uninstallation.
Uninstall
For more information, see Uninstalling Web Sites and Virtual Directories.
ASP .NET Version To set the ASP.NET version for the Web site, enter the complete version number.
For example, to specify version 2 of ASP.NET, type 2.0.50727. To specify version 1.1 of
ASP.NET, type 1.1.4322.
If you specify an ASP.NET version for a Web site, IIS uses that same version number for
any of the Web site’s virtual directories.
Important: If your installation may be run on a Windows Vista system, you may not want
to set the ASP.NET version. Also note that if you specify version 3 of ASP.NET, an error
occurs at run time. For more information, see Setting the ASP.NET Version for a Web
Site or Virtual Directory.
Setting Description
TCP Port The TCP Port setting for an IIS Web site indicates the port number on which the service
is running on the target machine. Some versions of the IIS Web server can host multiple
Web sites. Each Web site is associated with a unique port number.
If you do not know what the port number on the target system should be, you can enter
0 for this setting.
To learn which port and site numbers are used for the virtual directory when it is
installed, see Configuring the TCP Port and Site Numbers.
Setting Description
Host Header Name To specify the host header name that identifies the IIS Web site that is installed during
your installation, type it in this box. For example:
www.mycompany.com
Host headers (also known as domain names) enable you to assign more than one Web
site to an IP address on a Web server.
Site Number The Site Number setting indicates the number in the path at which the Web server will be
created (that is, w3svc/3). The default value is 0.
If you do not know what the site number on the target system should be, you can enter 0
for this setting.
To learn which port and site numbers are used for the virtual directory when it is
installed, see Configuring the TCP Port and Site Numbers.
Setting Description
A directory located on this If the content for the IIS Web site is on the target machine, select this option.
computer
A share located on another If the content for the IIS Web site is not on the target machine, select this option.
computer
Local Path This box displays the path to the directory that stores your default Web site files. By
default, these files are stored in IISROOTFOLDER. If you want to store these files in a
different directory on the IIS Web server, select the desired directory from the list, or
select Browse, create, or modify a directory entry.
The Local Path box is displayed if you select the A directory located on this
computer option.
Tip: Each Web site should have a unique physical path, especially if the Web site is
going to be installed on a Windows Vista or Windows Server “Longhorn” system. To
learn more, see Run-Time Requirements for IIS Support.
Setting Description
Network Directory The Network Directory box is pre-populated with the following path:
\\{server}\{share}
Change this path as appropriate.
This box is displayed if you select the A share located on another computer
option.
Tip: Each Web site should have a unique physical path, especially if the Web site is
going to be installed on a Windows Vista or Windows Server “Longhorn” system. To
learn more, see Run-Time Requirements for IIS Support.
Script source access To allow end users to access source code if either Read or Write permissions are set,
select this check box. Source code includes scripts in ASP applications.
Read To provide end users with read access to the Web site, select this check box.
Write To provide end users with write access to the Web site, select this check box. This
means that end users can change the Web site’s properties on the target machine.
Directory browsing To allow the end user to see all the virtual directories and subdirectories below this
Web site, select this check box.
Log visits To record visits to this Web site in a log file, select this check box. Visits are recorded
only if logging is enabled for this Web site.
Index this resource (IIS 6 To allow Microsoft Indexing Service to include this directory in a full-text index of your
and earlier only) Web site, select this check box.
This setting applies to IIS 6 and earlier. IIS 7 ignores this setting.
Application Settings To customize the directory’s application mappings or specify timeout parameters,
click the Configuration button in the Application Settings area. This opens the
Application Mappings dialog box, which enables you to add, edit, and delete a mapping
between a file name extension and the application that processes those files. This
dialog box also enables you to specify the session timeout and the ASP script timeout.
Application pool (IIS 6 and To associate the selected Web site with an application pool, select it in the list. As an
later only) alternative, you can click the Browse button to select or create the appropriate string
table entry. You can specify an application pool that is already present on the target
system, or one that is part of your installation.
This setting applies to IIS 6 and later. Earlier versions of IIS ignore this setting.
Important: The application pool that you specify should be on the target system at
run time or part of your installation; otherwise, the server may generate an error such
as error 403.18.
Documents Tab
When you select a Web site in the Internet Information Services view, InstallShield displays several tabs.
The Documents tab has one box that enables you to establish one or more default pages for your Web
site for client requests that do not specify a document name.
• Secure communications
The settings in the Anonymous access area are as follows.
Setting Description
Enable anonymous To allow users to establish an anonymous connection, select this check box and enter the
access appropriate Windows user account information.
If you do not need the Web server to confirm the identity of end users before they can
access the content, clear this check box.
Allow IIS to control Select this check box to automatically synchronize your anonymous password settings
password with those set in Windows on the target system. If the password you type for the
anonymous account differs from the password that Windows has, anonymous
authentication will not work.
Note: Password synchronization should be used only with anonymous user accounts
defined on the local computer, not with anonymous accounts on remote computers.
Password Type the anonymous user account password. You need to clear the Allow IIS to control
password check box in order to enter a password. The password is used only within
Windows. Anonymous users do not log on by using a user name and password.
Setting Description
Basic authentication To enable the basic authentication method for collecting user name and password
information for end users who access the Web site, select this check box.
Important: With the basic method of authentication, user names and passwords are not
encrypted when they are transmitted across the network. An unscrupulous end user who
has network monitoring tools could intercept user names and passwords.
Integrated Windows To enable integrated Windows authentication, select this check box. Integrated Windows
authentication authentication uses a cryptographic exchange with the end user’s browser to confirm the
identity of the user.
When integrated Windows authentication is enabled, the Web site will use it only under the
following conditions:
• Anonymous access is disabled.
• Anonymous access is denied because Windows file system permissions have been
set, requiring end users to provide a Windows user name and password before
establishing a connection with restricted content.
Setting Description
SSL certificate To specify a server certificate that should be installed on the target system, select
Browse to certificate file from this list, and then select the appropriate security
certificate file (.cer or .pfx). InstallShield stores the .cer file in the Binary table.
If no certificate is configured to be installed, Not selected is displayed for this list.
SSL certificate password If the certificate that you specified has a password, enter it in this box.
Advanced Tab
When you select a Web site in the Internet Information Services view, InstallShield displays several tabs.
The Advanced tab is where you specify values for IIS settings that are not displayed on the other tabs in
this view.
The advanced settings apply to IIS 6 and earlier. IIS 7 ignores these settings.
For help on specific settings, see “Metabase Property Reference” on the MSDN Web site.
Virtual Directories
You can add virtual directories to your Web site in the Internet Information Services view. When you
select a virtual directory in the Internet Information Services view, you can use the following tabs to
configure IIS properties associated with it:
• General
• Virtual Directory
• Documents
• Directory Security
• Custom Errors
• Advanced
Most of the settings are also configurable through the IIS Microsoft Management Console. Therefore,
consult the IIS Snap-in help from within the Microsoft Management Console for the latest information
on specific IIS settings.
General Tab
When you select a virtual directory under a Web site in the Internet Information Services view,
InstallShield displays several tabs. The General tab is where you configure the following settings:
Setting Description
Name Provide a display name for the virtual directory to be created on the target machine.
The name will be associated with a string ID, which can be translated. Click the Browse
button to locate an existing string, or create a new one once the Select String dialog
box has been launched.
Component Specify the component with which the virtual directory is associated. You can also
click Browse to locate an existing component in the project.
Setting Description
ASP .NET Version To set the ASP.NET version for the virtual directory, enter the complete version
number.
For example, to specify version 2 of ASP.NET, type 2.0.50727. To specify version 1.1
of ASP.NET, type 1.1.4322.
If you specify an ASP.NET version for a Web site, IIS uses that same version number
for any of the Web site’s virtual directories.
Important: If your installation may be run on a Windows Vista system, you may not
want to set the ASP.NET version. Also note that if you specify version 3 of ASP.NET, an
error occurs at run time. For more information, see Setting the ASP.NET Version for a
Web Site or Virtual Directory.
Setting Description
A directory located on this If the content for the virtual directory is on the target machine, select this option.
computer
A share located on another If the content for the virtual directory is not on the target machine, select this option.
computer
Local Path This box displays the path to the directory that stores your default Web site files. By
default, these files are stored in INSTALLDIR. If you want to store these files in a
different directory on the IIS Web server, select the desired directory from the list, or
select Browse, create, or modify a directory entry. The [IISROOTFOLDER]
directory is available if you select Browse, create, or modify a directory entry.
The Local Path box is displayed if you select the A directory located on this
computer option.
Tip: Each virtual directory should have a unique physical path, especially if the Web
site is going to be installed on a Windows Vista or Windows Server “Longhorn” system.
To learn more, see Run-Time Requirements for IIS Support.
Setting Description
Network Directory The Network Directory box is pre-populated with the following path:
\\{server}\{share}
Change this path as appropriate.
This box is displayed if you select the A share located on another computer
option.
Tip: Each virtual directory should have a unique physical path, especially if the Web
site is going to be installed on a Windows Vista or Windows Server “Longhorn” system.
To learn more, see Run-Time Requirements for IIS Support.
Script source access To allow end users to access source code if either Read or Write permissions are set,
select this check box. Source code includes scripts in ASP applications.
Read To provide end users with read access to the virtual directory, select this check box.
Write To provide end users with write access to the virtual directory, select this check box.
This means that end users can change the virtual directory’s properties on the target
machine.
Directory browsing To allow the end user to see all the virtual directories and subdirectories below this
virtual directory, select this check box.
Log visits To record visits to this virtual directory in a log file, select this check box. Visits are
recorded only if logging is enabled for this virtual directory.
Index this resource (IIS 6 To allow Microsoft Indexing Service to include this directory in a full-text index of your
and earlier only) Web site, select this check box.
This setting applies to IIS 6 and earlier. IIS 7 ignores this setting.
Application name Specify the name of the application in the virtual directory.
Execute permissions This list determines what level of program execution is allowed for the selected virtual
directory.
• Scripts and Executables—All file types can be accessed or executed.
• Scripts Only—Only scripts, such as ASP scripts, can be run.
• None—Only static files, such as HTML or image files, can be accessed.
Setting Description
Application protection (IIS 5 Select the appropriate level of protection for applications:
and earlier only)
• Low—Applications are run in the same process as Web services.
• Medium—Applications are run in an isolated pooled process in which other
applications are also run.
• High—Applications are run in an isolated process separate from other
processes.
This setting applies to IIS 5 and earlier. Later versions of IIS ignore this setting.
Application Pool (IIS 6.0 and To associate the selected virtual directory with an application pool, select it in the list.
later only) As an alternative, you can click the Browse button to select or create the appropriate
string table entry. You can specify an application pool that is already present on the
target system, or one that is part of your installation.
This setting applies to IIS 6 and later. Earlier versions of IIS ignore this setting.
Important: The application pool that you specify should be on the target system at
run time or part of your installation; otherwise, the server may generate an error such
as error 403.18.
Documents Tab
When you select a virtual directory under a Web site in the Internet Information Services view,
InstallShield displays several tabs. The Documents tab has one box that enables you to establish one or
more default pages for your Web site for client requests that do not specify a document name.
Setting Description
Enable anonymous To allow users to establish an anonymous connection, select this check box and enter the
access appropriate Windows user account information.
If you do not need the Web server to confirm the identity of end users before they can
access the content, clear this check box.
Allow IIS to control Select this check box to automatically synchronize your anonymous password settings
password with those set in Windows on the target system. If the password you type for the
anonymous account differs from the password that Windows has, anonymous
authentication will not work.
Note: Password synchronization should be used only with anonymous user accounts
defined on the local computer, not with anonymous accounts on remote computers.
Password Type the anonymous user account password. You need to clear the Allow IIS to control
password check box in order to enter a password. The password is used only within
Windows. Anonymous users do not log on by using a user name and password.
Setting Description
Basic authentication To enable the basic authentication method for collecting user name and password
information for end users who access the virtual directory, select this check box.
Important: With the basic method of authentication, user names and passwords are not
encrypted when they are transmitted across the network. An unscrupulous end user who
has network monitoring tools could intercept user names and passwords.
Integrated Windows To enable integrated Windows authentication, select this check box. Integrated Windows
authentication authentication uses a cryptographic exchange with the end user’s browser to confirm the
identity of the user.
When integrated Windows authentication is enabled, the virtual directory will use it only
under the following conditions:
• Anonymous access is disabled.
• Anonymous access is denied because Windows file system permissions have been
set, requiring end users to provide a Windows user name and password before
establishing a connection with restricted content.
Advanced Tab
When you select a virtual directory under a Web site in the Internet Information Services view,
InstallShield displays several tabs. The Advanced tab is where you specify values for IIS settings that are
not displayed on the other tabs in this view.
The advanced settings apply to IIS 6 and earlier. IIS 7 ignores these settings.
For help on specific settings, see “Metabase Property Reference” on the MSDN Web site.
Application Pools
Note: Application pools are available only on machines with IIS 6.0 or later installed.
Use the Application Pools item in the Internet Information Services view to add and delete application
pools. When you select an application pool in the explorer, you can use the following tabs to configure
IIS properties associated with that Web site:
• General
• Recycling
• Performance
• Identity
Most of the settings are also configurable through the IIS Microsoft Management Console. Therefore,
consult the IIS Snap-in help from within the Microsoft Management Console for the latest information
on specific IIS settings.
General Tab
When you select an application pool in the Internet Information Services view, InstallShield displays
several tabs. The General tab is where you configure the following settings.
Setting Description
Name Provide a display name for the application pool that you want to configure. The name
will be associated with a string ID, which can be translated. Click the Browse button to
locate an existing string, or create a new one once the Select String dialog box has
been launched.
Component Specify the component with which the application pool is associated. You can also
click Browse to locate an existing component in the project.
Mark Component as If the component associated with the application pool should not be removed if the
Permanent component’s feature is uninstalled, select this check box. For more information, see
Feature and Component Associations for IIS Support.
Recycling Tab
When you select an application pool in the Internet Information Services view, InstallShield displays
several tabs. The Recycling tab is where you configure the recycling of worker processes. In worker
process isolation mode, you can configure IIS to periodically restart worker processes in an application
pool, enabling you to manage precisely those worker processes that are faulty. This ensures that
specified applications in those pools remain healthy and that system resources can be recovered.
For help on specific settings, consult the IIS Snap-in help from within the Microsoft Management
Console.
Performance Tab
When you select an application pool in the Internet Information Services view, InstallShield displays
several tabs. The Performance tab is where you specify the way that IIS shuts down idle worker
processes, the number of requests waiting to be processed, CPU monitoring, and the number of
processes in a Web garden.
For help on specific settings, consult the IIS Snap-in help from within the Microsoft Management
Console.
Identity Tab
When you select an application pool in the Internet Information Services view, InstallShield displays
several tabs. The Identity tab is where you configure security settings for the application pool.
The identity of an application pool is the name of the account under which an application pool’s worker
process runs. By default, application pools operate under the NetworkService account, which has the
fewest user rights that are required to run Web applications. This account provides the most security
against attackers who might attempt to take over the computer on which the World Wide Web
Publishing Service (WWW service) is running. You can configure application pools to run as
LocalSystem, which is an account with more assigned user rights. This account provides a more serious
security risk.
For example, suppose that an Internet service provider (ISP) wants to allow customers to upload
Common Gateway Interface (CGI) applications and then add them to an application pool. Running the
CGI-enabled applications in a separate application pool under the NetworkService account—with its
minimal user rights—prevents these applications from being used to take over the server.
For help on specific settings, consult the IIS Snap-in help from within the Microsoft Management
Console.
Tip: In Windows Installer–based projects, you can specify properties in the User name and Password fields. To prevent the
password from being logged, you will need to set the MsiHiddenProperties property. For more information, see
MsiHiddenProperties in the Windows Installer Help Library.
Note: Web service extensions are available only on machines with IIS 6.0 or later installed.
On systems with IIS 7, Web service extensions require that the IIS Metabase and IIS 6 Configuration Compatibility feature
be installed. For more information, see Version-Specific Information for IIS Support in InstallShield.
Use the Web Service Extensions item in the Internet Information Services view to add and delete Web
Service Extensions. When you select a Web service extension in the explorer, you can use the Web
Service Extension tab to configure IIS settings associated with that Web service extension.
Note: Web service extensions are available only on machines with IIS 6.0 or later installed.
On systems with IIS 7, Web service extensions require that the IIS Metabase and IIS 6 Configuration Compatibility feature
be installed. For more information, see Version-Specific Information for IIS Support in InstallShield.
When you select a Web service extension in the Internet Information Services view, InstallShield
displays the Web Service Extension tab for that extension. This tab enables you to specify required files
and to customize security and other settings for the designated Web service extension.
Setting Description
Description Type the name of the new Web service extension file. The name is associated with a
string ID, which can be translated. Click the Browse button to locate an existing string,
or create a new one once the Select String dialog box has been launched.
Setting Description
Tip: You can use directory IDs to specify a file. For example, you can specify a
directory and a file as [INSTALLDIR]file.exe.
Group Type the name of Web service extension’s group. Groups enable you to classify
different DLLs and common gateway interfaces (CGIs) and have dependencies for the
applications.
Component Specify the component with which the application pool is associated. You can also
click Browse to locate an existing component in the project.
Mark Component as If the component associated with the application pool should not be removed if the
Permanent component’s feature is uninstalled, select this check box. For more information, see
Feature and Component Associations for IIS Support.
Allow Select this check box to automatically set the status of the new Web service extension
to Allowed.
UI Deletable Select this check box to allow the Web service extension file to be deleted using IIS
Manager.
Overwrite Existing Select this check box to enable existing extensions to be overwritten.
Extensions
Project: This view and its subviews do not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
The Component Services view enables you to manage COM+ applications and components for your
installation package. You can manage both COM+ server applications and application proxies. A COM+
application proxy consists of a subset of the attributes of the server application, and it enables remote
access from a client machine to the machine where the application resides.
• The Component Services functionality is available only if you are using InstallShield on a machine running Microsoft
Windows 2000 or Microsoft Windows XP.
• Only non-system COM+ applications can be added to your project. Therefore, InstallShield displays only non-system
COM+ applications under the COM+ Applications node in the Component Services view.
• COM+ server applications can be installed on only Windows 2000 operating systems and later. COM+ application
proxies can be installed on any operating system that supports distributed component object model (DCOM); this
includes machines that are running Windows NT or Windows 9x if DCOM is also installed. However, if DCOM is not
installed, the application proxy will not work. InstallShield does not have the ability to check if DCOM is installed on a
client machine.
• An application proxy is available for COM+ server applications only, not for library applications.
The look and feel of the Component Services view is similar to that of the Component Services
administrative tool in the Control Panel for systems running Windows 2000 and Windows XP.
Project: The SQL Scripts view is available in the following project types:
• Basic MSI
• InstallScript
• InstallScript MSI
• Web
The SQL Scripts view provides a central location for managing and organizing all SQL scripts by server
connections and settings. The current implementation provides support for the latest versions of
Microsoft SQL Server, MySQL, and Oracle. You will be able to perform most of the following major
functions to configure your SQL servers from the SQL Scripts view. Some limitations may apply to
certain server types.
• Connect to SQL servers.
• Import catalog schema and/or data.
• Associate SQL scripts with features.
• Set required SQL server/script properties (server name, database name, authentication method,
etc.).
• Set SQL script for execution during installation or uninstallation.
• Edit SQL scripts.
• Require and/or target specific versions of SQL Server, MySQL, or Oracle.
• Define SQL script text replacement.
• Open scripts in Microsoft SQL Query Analyzer.
Note: The import database functionality applies to the Microsoft SQL Server Database. Oracle users should refer to the
Oracle Web page on Oracle Database Utilities for information on utilities that may work in conjunction with InstallShield.
Microsoft SQL Query Analyzer is part of the Microsoft SQL Server installation. This tool can be run only on SQL Server
databases.
To run an installation project with SQL support on a Windows 95 or 98 machine, your system will need to support MDAC
setup prerequisites.
SQL Connections
In the SQL Scripts view, scripts are organized by connection, since no script can run on a server until a
connection has been established. Furthermore, the grouping of connections with corresponding scripts
facilitates the sharing of connection settings to different scripts.
When you create or select a SQL connection in the SQL Scripts view, the following tabs are available:
• General tab
• Requirements tab
• Advanced tab
General Tab
You can configure the following properties for a SQL connection on the General tab in the SQL Scripts
view.
Catalog Name
Note: Creating a new application catalog based on Oracle database settings is equivalent to creating a new database
based on SQL Server settings in InstallShield. However, terminology is slightly different in reference to Oracle. In Oracle,
the catalog is equivalent to the schema being used for every new application catalog. Therefore, note the semantic
differences between “catalog” and “database” when understanding the differences between SQL Server and Oracle
support in the help.
Enter the name of the SQL catalog to which you want to create a connection during the installation. If
you leave this blank, the installation will attempt to connect to the default catalog during the connection
test phase at run time. If the catalog you specify is not found at that time, then InstallShield 2008 will
still create the specified catalog upon connection verification. This is because the Create Catalog If
Absent option is selected in the InstallShield interface by default.
Note: You should note that when the Create Catalog If Absent option is selected, different SQL commands are issued
for the various supported server types. For Microsoft SQL Server and MySQL, selecting this option will issue the following:
CREATE DATABASECatalogName
CatalogName is what you specify in the Catalog Name box in the General tab at the connection level within the SQL Scripts
view.
For Oracle, selecting the Create Catalog If Absent option will issue the following:
CREATE USER CatalogName IDENTIFIED BY CatalogName DEFAULT TABLESPACE USERS QUOTA UNLIMITED on
USERSGRANT CONNECT TO CatalogNameGRANT DBA TO CatalogNameALTER USER CatalogName DEFAULT ROLE
ALL
Therefore, you should note that for Oracle the schema name serves as the user name and password for the selected
catalog by default.
Tip: If you do not wish to use the Create Catalog If Absent option to create a catalog, you can run a customized script
to create a catalog. When you run a custom script, you can schedule the execution of the script during login in the Run-
time tab of the SQL Scripts view at the script level.
For more information about running a customized script, see the following help topics for instructions
on creating sample projects that will create a SQL Server or Oracle catalogs and tables by running
sample SQL scripts:
• Creating a Sample Installation that Creates a SQL Server Database by Running Customized SQL
Script
• Creating a Sample Installation that Creates an Oracle Schema by Running Customized SQL Script
In the case where the Create Catalog If Absent option is cleared during installation design and the
catalog is not found at run time, then the installation behavior will slightly differ for the following project
types at run time.
For MSI projects: InstallShield will connect to the default catalog at the SQLLogin dialog during run
time to test the connection. This enables the installation to run custom code during the
InstallExecuteSequence. However, the presence of the catalog needs to be guaranteed when the SQL
Scripts specified in your project are executed. The run time will re-establish the connection with the
specified catalog to run the scripts. If the catalog is absent at this point, the connection will fail.
For InstallScript projects: The catalog needs to be present at the SQLLogin dialog since the run time
holds the connection until the installation ends, once the connection is established. In this scenario, you
can run a custom InstallScript code to create the catalog before the SQLLogin dialog shows up to
override the default behavior.
The following is an example of what you would type to connect to a specified remote oracle machine:
//sch01jsmithrxp.macrovision.com:1521/ORCL
You can also specify a local net service name if you have tnsnames.ora configured on the client machine.
Consult the Oracle Support Web site for more details.
Connect Using
Select the type of authentication you want to use to connect to the specified catalog. For SQL Server
Authentication, you will need to enter login and password information for the targeted server.
Comments
Enter any comments you may have regarding this connection.
Requirements Tab
In this tab, you can select a database server and specify version requirements for the type of server that
InstallShield will target at run time. You have the option to add, delete, or edit existing version
requirements associated with a particular database server.
Task To select a database server and specify version requirements for the type of server that InstallShield will
target at run time:
Note: Multi-selection of items in the version requirements section of the table applies only to the Delete operation.
Advanced Tab
This tab provides advanced settings that should only be set by expert users to expand and customize the
default functionality provided by InstallShield.
Setting Description
Command Timeout Specify the command timeout period. The default is 30 seconds.
(seconds) The valid range of this value is 0 to 2147483647. A value of 0
indicates no limit. Once this period of time has elapsed without
completing the command, an error occurs and ADO cancels the
command.
Setting Description
Batch Separator Specify the appropriate batch separator for the selected
connection. The batch separator is used for all SQL scripts that
are associated with this connection.
The default value is GO, which is the same default that is used in
Microsoft products. Oracle utilities use a slash (/) as the default
value.
A batch separator is a command that is recognized by SQL
utilities such as osql, isql, and SQL Query Analyzer, as well as
InstallShield. The run time interprets a batch separator as a signal
that it should send the current batch of SQL statements to a
database server.
Target Server Property This setting enables you to select a property that determines the
Name behavior of the target server.
Target Catalog Property This setting enables you to select a property that determines the
Name behavior of the target catalog.
Authentication Type This setting enables you to select a property that determines the
Property Name behavior of the authentication type.
Server Authentication Login This setting enables you to select a property that determines the
ID Property Name behavior of the server authentication login.
Server Authentication This setting enables you to select a property that determines the
Password Property Name behavior of the server authentication password.
Note: The default properties for SQL login settings are as follows:
• IS_SQLSERVER_SERVER
• IS_SQLSERVER_DATABASE
• IS_SQLSERVER_AUTHENTICATION
• IS_SQLSERVER_USERNAME
• IS_SQLSERVER_PASSWORD
If you want to hold different settings across the connections, then you will need to create new properties
for each connection.
Note: If you change the SQL Properties in the Advanced tab of a SQL Connection, these values are not automatically
updated in the corresponding SQL Login dialog in the Dialogs view. Therefore, you must manually change the values in the
dialog to match the values entered into the Advanced tab of the SQL Connection.
• General tab
• Script tab
• Runtime tab
General Tab
You can configure the following settings on the SQL script level in the General tab within the SQL Scripts
view.
Schema Version
Specify a version number to enable script versioning. For more information on this setting, see
Specifying a Version Number for a SQL Script File.
Tip: When you specify a number for the Schema Version setting and InstallShield adds the custom InstallShield table for
storing the schema version number on the target database, the data is not automatically removed upon uninstallation.
Therefore, if you want the installation to be able to roll back the changes, you need to create a custom script upon
uninstallation to drop the InstallShield table.
Script Tab
This view is intended for advanced users. To create a script from an existing database with step-by-step
instructions, use the Database Import Wizard.
Note: Currently, this feature applies to the Microsoft SQL Server Database.
Runtime Tab
You can configure the following options for SQL scripts in this tab:
Script Execution
Determine when you want the installation to execute a SQL script. You can select one of the following
script execution options:
• Run Script During Install—This option enables you to run a custom script during installation. This
option is also associated with component state because each script is tied in with a feature by design.
Therefore, you can specify conditional statements in conjunction with this setting in the Script
Condition (only available for Basic MSI and InstallScript MSI projects) section of this tab.
In Basic MSI and InstallScript MSI projects, the ISSQLServerInstall action is associated with this
option.
In InstallScript projects, the SQLRTComponentInstall script function is associated with this option.
• Run Script During Uninstall—This option enables you to run a custom script during uninstallation.
This option is also associated with component state because each script is tied in with a feature by
design. Therefore, you can specify conditional statements in conjunction with this setting in the
Script Condition (only available for Basic MSI and InstallScript MSI projects) section of this tab.
In Basic MSI and InstallScript MSI projects, the ISSQLServerUninstall action is associated with this
option.
In InstallScript projects, the SQLRTComponentUninstall script function is associated with this option.
• Run Script During Rollback—This option enables you to run a custom script during rollback.
InstallShield does not roll back the changes automatically. You will have to run a custom script
allowing rollback when you select the Run Script During Rollback option.
In Basic MSI and InstallScript MSI projects, the ISSQLServerRollback action is associated with this
option.
• Run Script During Login—This option enables you to run your script during login. Some limitations
associated with the Run Script During Login option are:
• When you set this option during installation design, you should be aware that the script changes
are irreversible once the end user clicks Next in the SQLLogin dialog at run time, even when the
end user attempts to cancel the installation before clicking the Install button on the
ReadyToInstall dialog.
• The script is executed after credentials and requirements are verified and before a connection
has been made to the catalog. Therefore, any schema version requirements that you set for the
script during installation design will not have taken place at run time.
In Basic MSI projects, the ISSQLServerValidate action is associated with this option. In InstallScript
MSI projects, the SQLRTServerValidate script function is associated with this option. In InstallScript
projects, the SQLRTConnect script function is associated with this option.
Script Condition
You can specify conditional statements for SQL scripts that are run during installation or uninstallation.
Tip: The Database Import functionality currently is only available for Microsoft SQL Server. Oracle users should refer to
the Oracle Web page on Oracle Database Utilities for information on utilities that may work in conjunction with InstallShield.
You can run the Database Import Wizard from this tab to view and modify your import settings. The
wizard will walk you through the process of generating a SQL script which recreates part or all of an
existing Microsoft SQL Database. Once you complete the wizard, you can click the Regenerate button in
this tab to refresh your script.
The Regenerate SQL Script at Build option allows you to ensure that the script is regenerated each
time you build the project. Regenerating a script every time you build your project can slow down the
entire build project.
Project: The Behavior and Logic view is not available in the following project types:
• QuickPatch
• Smart Device
By adding custom actions; sequencing actions and dialogs; adding support files; using InstallScript;
searching the target system for required files, folders, or other elements; or configuring Windows
Installer properties, you can design any custom functionality that your installation requires.
InstallScript
InstallScript is an installation authoring language that is similar to the C programming language. The
InstallScript view provides you with a script editor pane in which you can create and edit your scripts.
Project: The Custom Actions and Sequences view is available in the following project types:
• Basic MSI
• InstallScript MSI
• MSI Database
• Transform
• Web
Sequences direct all the actions that are performed during installation, from file transfer to displaying
the user interface. Use the Custom Actions and Sequences view to sequence the actions and dialogs in
your project.
If Windows Installer does not directly support functionality that is required by your installation
program, you can extend your installation program through the use of custom actions in the Custom
Actions and Sequences view.
Custom Actions
Project: The Custom Actions view is available in the following project types:
• Merge Module
• MSM Database
Although merge modules do support the use of custom actions, sequences are not defined through a
dedicated view in merge module projects.
Tip: You can control the launch of custom actions in a merge module by modifying the ModuleInstallExecuteSequence
table in the Direct Editor. When you add the merge module to your installation project, all custom actions and dialogs
included in the merge module are available for you to insert in the installation's sequences via the Custom Actions and
Sequences view.
Support Files/Billboards
Project: The Support Files view is available in the following project types:
• Basic MSI
• InstallScript Object
• Web
The Support Files/Billboards view is available in the following project types:
• InstallScript
• InstallScript MSI
Support Files
The Support Files view lets you add, sort, and delete support files—files that are required by your
installation project only during the installation process.
Billboards
The Billboards area in the Support Files/Billboards view lets you add billboards to your project.
Billboards are images that are displayed for a specified amount of time while your installation runs. You
can use billboards to provide information about the product being installed or to entertain the end user
during the installation process.
System Search
Project: The System Search view is available in the following project types:
• Basic MSI
• InstallScript MSI
• Merge Module
• MSI Database
• MSM Database
• Transform
• Web
Use the System Search view to search for a particular file, folder, registry key, or .ini value on the target
system prior to an installation.
Property Manager
Project: The Property Manager view is available in the following project types:
• Basic MSI
• InstallScript MSI
• Merge Module
• MSI Database
• MSM Database
• Transform
• Web
The Property Manager view enables you to edit the Property table from within the InstallShield
interface. Windows Installer properties give you access to many machine-specific variables such as the
user’s name or company.
InstallScript View
• InstallScript
• InstallScript MSI
• InstallScript Object
• Merge Module
• Web
The InstallScript view enables you to customize your setup script using the InstallScript language.
Files Basic MSI, Merge The Files folder lists all of your script (.rul) files. Click a script file to display
Module, InstallScript its contents in the script editor.
MSI, InstallScript,
InstallScript Object
Functions Basic MSI, Merge The Functions folder lists all of the InstallScript functions contained in all of
Module, InstallScript the script files listed under the Files folder. Click a function to display that
MSI, InstallScript, function in the script editor.
InstallScript Object
Properties InstallScript, The Properties folder lists all of the InstallScript properties contained in all of
InstallScript Object the script files listed under the Files folder. Click a property to display that
property’s declaration in the script editor. (The property’s procedures are
listed under the Functions folder.)
Methods InstallScript, The Methods folder lists all of the InstallScript methods contained in all of
InstallScript Object the script files listed under the Files folder. Click a method to display that
method’s definition in the script editor.
Script Editor
Clicking an item under any of the folders in the InstallScript view displays the script editor in the right
pane in the InstallShield interface. To learn more, see Script Editor.
Script Editor
The script editor displays the text of the selected InstallScript file (in the InstallScript view) or the
selected SQL script file (in the SQL Scripts view). You can modify or edit the script using commands
from the Edit and Tools menus.
Project: The script toolbar is not available in the following project types:
• Basic MSI
• Merge module
InstallScript event handlers are not available in these project types because they use custom actions to run InstallScript.
The script toolbar is displayed across the top of the script editor in the InstallScript view; it contains an
event category list box, as well as an event list box. The script toolbar lets you paste installation event
handler function blocks in your script files. Event handlers in your script files override the default
actions that are associated with installation events. You can modify the event handler code to change the
actions performed during the installation.
BookmarkToggle CTRL+F2 Toggles a bookmark on and off for the current line.
CharLeft LEFT ARROW Moves the cursor one character to the left.
CharLeftExtend SHIFT+LEFT ARROW Extends the text selection one character to the left.
CharRight RIGHT ARROW Moves the cursor one character to the right.
CharRightExtend SHIFT+RIGHT ARROW Extends the text selection one character to the right.
Cut CTRL+X Deletes the selected text and puts it in the clipboard.
SHIFT+DELETE
CutSelection CTRL+ALT+W Deletes the selected text and puts it in the clipboard.
Home HOME Moves to either the start of the current line or the start
of the text on that line.
HomeExtend SHIFT+HOME Extends the selection to either the start of the current
line or the start of the text on that line.
IndentSelection TAB Indents the selected text to the right one tab stop.
LineCut CTRL+Y Deletes the selected line and places the text on the
clipboard.
LineEnd END Moves the cursor to the end of the current line.
LineEndExtend SHIFT+END Extends the selection to the end of the current line.
SetRepeatCount CTRL+R Sets the repeat count for the next command.
TabifySelection CTRL+SHIFT+T Replaces the spaces in the selected text with tabs.
UntabifySelection CTRL+SHIFT+SPACE Replaces the tabs in the selected text with spaces.
WindowScrollDown CTRL+UP ARROW Scrolls the file contents down one line.
WordLeft CTRL+LEFT ARROW Moves backward to the start of the previous word.
WordLeftExtend CTRL+SHIFT+LEFT ARROW Extends the selection backward to the start of the
previous word.
WordRight CTRL+RIGHT ARROW Moves forward to the start of the next word.
WordRightExtend CTRL+SHIFT+RIGHT ARROW Extends the selection forward to the start of the next
word.
Table 40-34: Commands Available from the Script Editor Context Menu
Command Description
Cut Moves the selected text from the script to the Windows clipboard.
Table 40-34: Commands Available from the Script Editor Context Menu (cont.)
Command Description
Find Opens a standard Find dialog box, in which you can specify text to
search for.
Replace Opens a standard Find and Replace dialog box, in which you can
specify text to search for and text with which to replace the found
text.
Show Whitespace Switches the display of white space in the script. If a check mark
appears next to this command, each space character in the script
is displayed as a middle dot (·) and each tab character is
displayed as a double angle bracket (>>). (If the script is
displayed in Terminal font, special characters are displayed for
spaces and tabs.)
Make Uppercase Converts characters in the selected text to uppercase. To use this
command, select text, then right-click the selected text and click
this command on the context menu.
Make Lowercase Converts characters in the selected text to lowercase. To use this
command, select text, then right-click the selected text and click
this command on the context menu.
Project: The Custom Actions and Sequences view is available in the following project types:
• Basic MSI
• InstallScript MSI
• MSI Database
• Transform
• Web
Note that the Custom Actions view is available in the following project types:
• Merge Module
• MSM Database
The Custom Actions and Sequences view has two separate areas: a Custom Actions area and a Sequences
area.
Custom Actions
Microsoft enables you to add flexibility to your installation that is not directly supported by Windows
Installer. This additional functionality is achieved through the use of custom actions.
InstallShield supports calling a .dll file function; launching an executable file (.exe); running VBScript,
JavaScript, or InstallScript code; displaying an error message; setting a directory or a property; and
running another installation package as custom actions.
The Custom Actions explorer in the Custom Actions and Sequences view behaves the same was as the
Custom Actions explorer in the Custom Actions view. For more information, including a list of the
different icons that are displayed in these views for each type of custom action, see Custom Actions View.
Sequences
Sequences direct all of the actions performed during the installation process—from file transfer to user
interface display (for Basic MSI projects). These actions are given a number on the sequence, which then
executes from the lowest number to the highest. Rather than having to manually provide a numeric
value for every action, you can use the Custom Actions and Sequences view to insert actions into a
sequence, or edit the sequence timeline.
Project: In InstallScript MSI projects, the installation’s user interface is generated through your script. In InstallScript
projects, all of the actions are driven by your script.
If you are creating a custom action or custom dialog in a merge module, you need to first import that module into an
installation project and then add it to a sequence through the Custom Actions and Sequences view.
There are three main sequences into which you can insert your dialogs (in Basic MSI, MSI Database,
Transform, and Web projects) and custom actions.
• Installation Sequence
• Advertisement Sequence
• Administration Sequence
Each of these sequences plays a different role. The Installation sequence is run during a normal
installation. The Advertisement sequence runs when an application is being advertised rather than
installed. The Administration sequence is run during an administrative installation.
• When you select a dialog or standard action in the Sequences explorer, the Sequence tab on the right
enables you to change the sequence number and add or modify the associated conditions.
• When you select a custom action in the Sequences explorer, more than one tab is displayed on the
right:
• Sequence tab—Use this tab to change the sequence number and to add or modify any conditions
for the action.
• Action tab—Use this tab to change any settings for the custom action.
• Script tab—This tab is displayed for VBScript and JScript custom actions. It has a script editor
that lets you edit your VBScript or JScript code.
• To edit the layout or behavior of a dialog, right-click the dialog in the Sequences explorer and then
click Edit Behavior or Edit Layout.
Note: A custom action cannot be called twice in the same sequence, since the custom action name is the key in the
CustomAction table. Therefore, you cannot move or copy a custom action to a sequence that already contains that
custom action.
Dialogs and standard actions cannot be moved to a different type of sequence through a drag-and-drop operation.
Project: The Custom Actions view is available in the following project types:
• Merge Module
• MSM Database
Note that the Custom Actions and Sequences view is available in the following project types:
• Basic MSI
• InstallScript MSI
• MSI Database
• Transform
• Web
Microsoft enables you to add flexibility to your installation that is not directly supported by Windows
Installer. This additional functionality is achieved through the use of custom actions. InstallShield
includes support for several kinds of custom actions:
Project: This type of custom action is not available for merge module projects.
Call a function in a DLL that was written specifically for Windows Installer.
The entry point of the .dll file must have a predefined parameter and return value.
Project: This type of custom action is not available for merge module projects.
Display a specified error message, return failure, and end the installation.
For example, you may want to add an error custom action to your project to handle
scenarios where an end user tries to install the current version of your product over a
future major version. For more information, see Preventing the Current Installation from
Overwriting a Future Major Version of the Same Product.
For details about each of the InstallShield custom actions that are added automatically to InstallShield
projects to support different functionality, see InstallShield Custom Action Reference.
Windows Logo Guideline: If you are applying for the Windows Vista logo, any custom actions in your installation must
follow best practices guidelines for custom action creation. You can use the Certified for Windows Vista Validation Suite
(plus InstallShield ICEs) to verify whether your installation package meets most of the custom action–related logo
requirements. However, some of the requirements cannot be verified through the validation suite. To learn more, see
Guidelines for Creating Custom Actions that Meet Requirements of the Certified for Windows Vista Program.
Important: Nested installations is a deprecated feature of the Windows Installer. Applications installed with nested
installations sometimes fail because they are difficult for end users to service correctly. Microsoft Corporation
recommends that you avoid using nested installations and nested-installation custom actions to install products that are
intended to be released to the public. To learn more, see Concurrent Installations on the MSDN Web site.
Support File
Lets you add, sort, and delete support files—files that are required by your installation project only
during the installation process.
Item Description
English (United States) Add support files that are specific to English-
language installations.
Splash Screen
Place your startup graphic (the graphic displayed at the same time as the startup dialog) in the
appropriate language folder. You can add a bitmap (.bmp) to be displayed when the end user begins the
installation. Only one file is displayed. If you add multiple files to this item, only the first file in the list is
displayed.
Project: This option is not available if you are designing a merge module.
Item Description
Note: If you have splash screen files within a language-specific item—English (United States) or another language node—
and within the Language Independent item, the file within the language-specific item is displayed.
Disk1
The Disk1 item enables you to indicate files and folders that you want to go on Disk1 of your installation
media. These files and folders are not automatically installed to the target system when your installation
is run. Rather, you can link to the installation media from your application or from the installation. For
example, you might include a large redistributable file with your application that you do not want
included in the application installation. This file should be placed in the Disk1 folder.
Disk1 Node
The purpose of the Disk1 feature is to allow setup developers to add additional files to the root of the
source media. Disk1 Files are taken into account when calculating the size of the media, meaning that
the addition of a Disk1 file will not cause the build to exceed the disk size specification for that release.
This feature is useful if you want to store a redistributable on your disk image so that your installation
can launch it from the source media at install time.
See Adding Files and Folders to the Disk1 Folder to learn how to work with the Disk1 node.
The Advanced Files node’s Disk1, Last Disk, and Other subnodes let you place files on any disk of the
media. See Adding Files and Folders to the Disk1 Folder, Adding Files and Folders to the Last Disk
Folder, and Adding Files and Folders to the Other Disk Folder to learn how to work with these nodes.
Support Files
Lets you add, sort, and delete support files—files that are required by your installation project only
during the installation process.
In your script, files within the Support Files item are uncompressed into a temporary directory and then
deleted when the installation is complete. In your InstallScript code, you can refer to the temporary
directory with the SUPPORTDIR variable.
Item Description
English (United States) Add support files that are specific to English-
language installations.
Billboards
The Billboards item enables you to specify bitmap (.bmp) files that you want to display to the end user
during the installation process. You can use billboards to educate, inform, and entertain your customers
during the installation process.
Splash Screen
Place your startup graphic (the graphic displayed at the same time as the startup dialog) in the
appropriate language folder. You can add a bitmap (.bmp) or .gif file to be displayed when the end user
begins the installation. Only one file is displayed. If you add multiple files to this item, only the first file
in the list is displayed. The file must be named Setup.bmp or Setup.gif.
Note: This option is not available if you are designing a merge module.
Item Description
Note: If you have splash screen files within a language-specific item—English (United States) or another language node—
and within the Language Independent item, the file within the language-specific item is displayed.
Advanced Files
The Advanced Files item enables you to indicate files and folders that you want to go on a disk of your
installation media. These files and folders are not automatically installed to the target system when your
installation program is run. Rather, you can link to the installation media from your application or from
the installation. For example, you might include a large redistributable file with your application that
you do not want included in the application installation. This file should be placed in the Disk1, Last
Disk, or Other item.
Item Description
Support Files
Lets you add, sort, and delete support files—files that are required by your installation project only
during the installation process.
In your script, files within the Support Files item are uncompressed into a temporary directory and then
deleted when the installation is complete. In your InstallScript code, you can refer to the temporary
directory with the SUPPORTDIR variable.
Item Description
English (United States) Add support files that are specific to English-
language installations.
Billboards
The Billboards item enables you to specify bitmap (.bmp) files that you want to display to the end user
during the installation process. You can use billboards to educate, inform, and entertain your customers
during the installation process.
Splash Screen
Place your startup graphic (the graphic displayed at the same time as the startup dialog) in the
appropriate language folder. You can add a bitmap (.bmp) to be displayed when the end user begins the
installation. Only one file is displayed. If you add multiple files to this item, only the first file in the list is
displayed. The file must be named Setup.bmp.
Note: This option is not available if you are designing a merge module.
Item Description
Note: If you have splash screen files within a language-specific item—English (United States) or another language node—
and within the Language Independent item, the file within the language-specific item is displayed.
Disk1
The Disk1 item enables you to indicate files and folders that you want to go on Disk1 of your installation
media. These files and folders are not automatically installed to the target system when your installation
is run. Rather, you can link to the installation media from your application or from the installation. For
example, you might include a large redistributable file with your application that you do not want
included in the application installation. This file should be placed in the Disk1 folder.
Project: This view and its subviews do not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
InstallShield provides the Windows Installer capability in the System Search view to locate a particular
file, folder, registry key, .ini file value, or .xml file value on a target system prior to installation.
Essentially, this feature lets you perform application, version, and configuration data searches.
The System Search view displays a grid listing each search that you want to conduct on the target
system. You can use this view to add a predefined system search—whether it is a search that is included
with InstallShield or one that is stored in a repository—to your project. You can also use the System
Search view to customize any predefined searches or define your own system searches for your
installation.
Whenever you define your own search, the System Search Wizard is launched. From there, you can
select from a list of search options and specify search details, such as the number of subfolder levels to
search. When you modify an existing search, you can alter your initial selections in the System Search
Wizard.
Property Manager
Project: This view and its subviews do not appear in the following project types:
• InstallScript
• InstallScript Object
• QuickPatch
• Smart Device
The Property Manager allows you to edit the Property table within the InstallShield IDE. Windows
Installer properties enable you to further customize your setup by setting properties such as the
telephone number for technical support that appears in the Add/Remove programs dialog on an end
user’s machine.
Properties that appear in all capital letters are called public properties, and can be changed by the end
user on the command line at run time. All others must be set before the release is built or—at run time—
through a custom action or dialog’s behavior.
Project: This view does not appear in the following project types:
• QuickPatch
• Smart Device
The appearance of your installation is one of the main aspects that differentiates your product from that
of your competition. You can easily customize the way your installation looks and behaves by modifying
the dialogs displayed to the end user.
Dialogs
In the Dialogs view, you can select dialogs to display at run time. The way in which you control a dialog’s
behavior depends on which engine controls the user interface: the Windows Installer engine displays the
dialogs for Basic MSI projects, and the InstallScript engine displays the dialogs for InstallScript and
InstallScript MSI projects. For more information, see:
• Dialogs View (InstallScript and InstallScript MSI Projects)
The Dialogs view contains a list of the standard end-user dialogs. The dialogs are identified by their
function names. Click a dialog in this view to view a sample dialog in the right pane.
The dialog names in the list are ghosted until you edit the layout. A ghosted name means that the default
dialog (from isres.dll) will be used in the user interface. If you edit the layout of a dialog, its name
appears in bold in the list, and the dialog is pulled from isuser.dll at run time.
If your installation project supports additional languages, those languages appear as nodes beneath the
edited dialog. You can edit the layout for each language separately.
Themes
The Themes folder contains a list of all of the dialog themes that you can use for the dialogs in your
project. A dialog theme is a predefined set of images that give your end-user dialogs a unified and
distinctive look.
All Dialogs
The All Dialogs folder contains a list of the dialogs in your project. Each dialog item in the Dialogs
explorer contains a Behavior item, which enables you to configure the behavior that is associated with a
dialog, and at least one language item, which displays the dialog in the Dialog Editor of the selected
language. The Dialog Editor enables you to edit the layout for each language separately.
When you create a new Basic MSI project, InstallShield provides a series of default dialogs for the two
User Interface sequences in which a Windows Installer package typically displays dialogs: the
Installation sequence (which runs when the installation is launched in the default mode, for example, by
double-clicking an .msi file)—with separate dialogs depending on whether the package is being installed
for the first time, reinstalled, or uninstalled—and the Administration sequence (the list of actions that
are executed when you launch the installation with the /a command-line option). (End-user dialogs are
not usually displayed in the Advertisement sequence, which contains the list of actions that are executed
when you launch the installation with the /j command-line option.)
Project: Although you can create dialogs in a merge module project, you cannot add them to a sequence until you
associate your module with an installation project. Then, all the dialogs included in your module are available to be
included.
Media View
Project: This view and its subviews do not appear in the following project types:
• MSI Database
• MSM Database
• Transform
• QuickPatch
• Smart Device
The final step in creating your installation project is to build and test your installation. InstallShield
provides you with many different media types to choose from, as well as the ability to test your
installation from within InstallShield.
Path Variables
With path variables, you can define commonly used paths in a central location so that you do not need to
change every source file’s path each time you move the project or change the directory structure.
Upgrades
The Upgrades view provides a visual, integrated method for adding and authoring settings within the
Upgrade table of your .msi database.
Releases
The Releases view enables you to build different configurations of your installation, test the user
interface, or launch your installation for a trial run.
Patch Design
In the Patch Design view, you can create a Windows Installer patch package (.psp) to update your
application on an end user’s system.
Project: This view and its subviews do not appear in the following project types:
• MSI Database
• MSM Database
• Transform
• Smart Device
The traditional way to link to source files in an installation project is to create a reference to that file
using a hard-coded path. For example, you might have a source file called Program.exe located at
C:\Work\Files that you want to include in your installation.
Note: Path variables are used during the development of your installation project. These paths do not apply to the target
machines where the application is being installed. Rather, they are used to link to source files for your installation project.
When the project is built, those links are evaluated and the files they point to will be built into the installation.
You also have the option of converting existing static links to path variables with the Convert Source
Paths Wizard. This wizard scans your installation project for static links and changes those links to path
variables, which makes your project more easily portable.
Upgrades View
Project: This view and its subviews appear only in the following project types:
• Basic MSI
• InstallScript MSI
• Web
The Upgrades view provides a visual, integrated method for adding and authoring settings within the
Upgrade table of an .msi database.
To add an upgrade item, right-click the Upgrade Windows Installer Setup node. Other available options
are described below.
Option Description
Minor Upgrade Item Small updates and minor upgrades are functionally
identical except the product version changes for a minor
upgrade, but not a small update. A minor upgrade installs
over an existing application while a major upgrade
effectively uninstalls the existing installation of a product,
and then installs the newer product version.
The functionality required to install a minor upgrade is in
the Setup.exe installation launcher, which you must
include in your release in order for a minor upgrade to
work properly. The installation specified at build time will
also be used to perform upgrade validation. The build will
also verify that the referenced installation can indeed be
updated using a minor upgrade. Note that the build will
warn you if you do not include Setup.exe when you build
your release. For more information, see Creating Minor
Upgrades.
Option Description
Major Upgrade Item A major upgrade will effectively uninstall the existing
installation of a product, and then install the latest
product version. A major upgrade is appropriate for
substantial installation architecture changes that may or
may not change the major version number of the product
(such as upgrading version 1.1.0 to version 2.0.0). A
major upgrade is required if any of the following are true:
• The upgraded project contains new components in
existing features. (This restriction does not apply to
Windows Installer version 2.0 or later.)
• An existing component’s Component Code property
has changed, or a component has been removed
from the product tree.
• An existing feature has been moved in the product
tree, or deleted from the product tree.
• The name of the .msi file has changed.
For more information, see Creating Major Upgrades.
Validate All Items This option will allow you to perform validation on the
latest release or browse for a particular package to
validate against a different release. For more information,
see Validating Upgrades and Patches.
Common Tab
The Common tab exposes some global settings for both major and minor upgrades.
Note: Small and minor upgrades are functionally identical except the product version does not change for a minor
upgrade. A minor upgrade installs over an existing application while a major upgrade effectively uninstalls the existing
installation of a product, and then installs the newer product version.
Option Description
Don’t prompt the user; just install the This option will automatically start the setup
upgrade in minor upgrade mode.
Option Description
Completely uninstall old setup before This is the most reliable setting, however, it is
installing new setup the least efficient. It will first remove all the
files, registry entries, shortcuts, and settings
of the old setup. Then it will apply new data
from the latest version of your setup
Option Description
Install setup and then remove This is the most efficient setting, but it
unnecessary files requires that you follow certain authoring
rules. This option will first install the setup, and
then remove all unnecessary files, registry
entries, shortcuts, and settings after installing
the latest version of your setup.
Rollback all changes if removal of old In the event of upgrade failure, the machine will
files fails be returned to its previous good state. This
option will undo the changes made by the
uninstallation of a previous version and the
installation of the latest version.
Note: This setting controls the sequencing of the RemoveExistingProducts action in the Install Execute Sequence. For
more details, see RemoveExistingProducts in the Windows Installer Help Library.
Advanced Tab
The Advanced tab presents specific settings for major and minor upgrades in addition to some shared
settings.
Property Description
Upgrade Code The upgrade code identifies a family of products for upgrade purposes. It is
especially important for major upgrades.
Property Description
On Upgrade The functionality required to install a minor upgrade is in setup.exe. You must
include Setup.exe for a minor upgrade to work properly. When setup.exe
detects different product codes for matching products, then it will prompt the
“do you want to continue” dialog. This is an inherent feature of Setup.exe.
Choose from the following options to configure this Setup.exe functionality:
Note: Small and minor upgrades are functionally identical except the product
version does not change for a minor upgrade. A minor upgrade installs over
an existing application while a major upgrade effectively uninstalls the
existing installation of a product, and then installs the newer product version.
• Disable—When you choose this option, you are required to detect the
upgrade scenario and ensure that the latest version of your setup is
running in upgrade mode.
• Don’t prompt the user; just install the upgrade—This option will
automatically start the setup in minor upgrade mode.
• Prompt—Choosing this option will prompt the “do you want to continue”
dialog. If you choose yes, the setup will begin in upgrade mode. If you
choose no, you will cancel the setup in upgrade mode.
Property Description
Note: In the event of upgrade failure, the Rollback option will return the
machine to its previous good state. This option will undo the changes made
by the uninstallation of a previous version and the installation of the latest
version.
• Install Then Remove Unused Files—This is the most efficient setting,
but it requires that you follow certain authoring rules. This option will first
install the setup, and then remove all unnecessary files, registry entries,
shortcuts, and settings after installing the latest version of your setup.
Note: This is the preferred method for configuring upgrade settings. This option takes into account any potential future
changes in the product code and handles both major and minor upgrades. If you do not know the difference between
upgrade types and/or do not care, then choose this upgrade option.
When you add an automatic upgrade item, the build engine determines which settings need to be
populated into your setup to perform a successful upgrade of your previous setup. This option does not
require any additional authoring of advanced settings on your part.
You can configure the following options for an automatic upgrade item in the Upgrades view:
Option Description
Setup to Upgrade Enter the path to the setup project that needs to
be upgraded or click the browse button to
browse for it.
Note: If you move a component from one feature to another, you are essentially deleting that component from the first
feature and therefore must change the product code.
For upgrade scenarios in which the setup’s product code has changed, you must apply a major upgrade.
This tab exposes the following settings:
Option Description
Common Tab
A major upgrade is required when the product code for a setup differs from the product code of the setup
that it needs to upgrade. You are not required to change the product code of a setup unless you delete a
component from a feature or you delete a feature from a setup.
Note: If you move a component from one feature to another, you are essentially deleting that component from the first
feature list and therefore, must change the product code.
At run time, a major upgrade effectively uninstalls the previous version of your application before
installing the newest version of your application.
The Common tab exposes the most frequently used settings of a major upgrade item. For more detailed
settings, use the Advanced tab.
Major Upgrade
Major upgrades use an upgrade code to detect previous versions of an application. The upgrade code for
a setup groups that setup into a specific product family. If you want to target specific setups within that
product family, you can configure the product version attribute of this upgrade item.
Option Description
Products Sharing My Upgrade Code When this option is selected, the upgrade code
of this major upgrade item is read from the
currently open project file.
Products Having Another Upgrade Code When this option is selected, you will have the
ability to edit the upgrade code that this major
upgrade item will target. Selecting this option
also enables a Browse button allowing you to
browse for the setup that you intend to upgrade.
In this case, the upgrade code will be extracted
from the setup which you have selected in the
browse dialog.
Product Version
Choose a particular product version to target or define a range. You can choose from the following
selections:
Option Description
Any earlier version When you select this option, the major upgrade
item will try to upgrade any setup in the
specified product family that has a version
number lower than the product version of the
currently open project file.
Option Description
Within a specific range of versions Selecting this option will allow you to specify a
range of product versions that should be
targeted for upgrade. For instance, a minimum
version of 1.00 and a maximum version of 4.00
will result in a setup that will upgrade any
existing setup in the specified product family
that has a version number falling between 1.00
and 4.00.
Version range Inclusive When you select this option, the range specified
will include the upper and lower bounds.
With a specific version Selecting this option will allow you to target only
a single previous version of a setup.
Advanced Tab
The Advanced tab exposes more advanced level configurations, in addition to the settings in the
Common tab. Click on each setting in the properties grid to configure the following settings.
Property Description
Include Minimum Version This setting is useful when you are specifying
upper and lower bounds for a range of product
versions which your upgrade will support.
Choose Yes to include the min version value in
the range of product versions to upgrade.
Include Maximum Version This setting is useful when you are specifying
upper and lower bounds for a range of product
versions which your upgrade will support.
Choose Yes to include the max version value in
the range of product versions to upgrade.
Property Description
Exclude Specified Languages When set to No, the setup only will perform an
upgrade if the target setup language matches
one of the languages listed in the Language
attribute.
When set to Yes, the setup only will perform an
upgrade if the target setup DOES NOT match
one of the languages in the Language attribute.
Detect Only If Detect Only is set to Yes, the setup will detect
that an upgrade needs to occur, but it will not
actually perform the upgrade. Additionally, the
property specified in the Detect Property
attribute will be set to the product code of the
detected setup.
Migrate Feature States When you select Yes, the upgrade will install
using the feature states of the setup being
upgraded. When you select No, the upgrade will
use the default states for the setup.
Releases View
Project: The Releases view is not available in the following project types:
• ClickOnce
• Compact
• MSI Database
• MSM Database
• Transform
• QuickPatch
• Smart Device
After you have completely designed your project in InstallShield, you are ready to build a release for
testing and, ultimately, distribution to end users. The Releases view contains settings that indicate how
InstallShield should build your release. To learn more about the settings in the Releases view, see the
following:
• Product Configuration Settings (available for Basic MSI, InstallScript MSI, Merge Module, and Web
projects)
• Build Tab (available for Basic MSI, InstallScript, InstallScript MSI, InstallScript Object, Merge
Module, and Web projects)
• Setup.exe Tab (available for Basic MSI, InstallScript, InstallScript MSI, and Web projects)
• Signing Tab (available for Basic MSI, InstallScript, InstallScript MSI, InstallScript Object, Merge
Module, and Web projects)
• .NET/J# Tab (available for Basic MSI, InstallScript MSI, and Web projects)
• Internet Tab (available for Basic MSI, InstallScript, InstallScript MSI, and Web projects)
• Postbuild Tab (available for Basic MSI, InstallScript, InstallScript MSI, InstallScript Object, Merge
Module, and Web projects)
When you build a release, InstallShield takes all of the information from your project and compiles it
into a Windows Installer installation package (.msi file), merge module (.msm file), or an executable file
and related files, depending on the project type, that are capable of installing your product onto any
supported Windows platform.
Tip: You can also use the Release Wizard to configure the settings for your release.
Project: Product configuration settings are available in the following project types:
• Basic MSI
• InstallScript MSI
• Merge Module
• Web
Each product configuration has the following settings, primarily for the purpose of overriding other
settings in the resulting releases:
Setting Description
Product Name Specify a new name to override the product name in each release that you build under this product
configuration.
Product Enter a new version number to override the product version in each release that you build under this
Version product configuration.
Package Code Click the Generate GUID button or type a new GUID to override the package code in each release
that you build under this product configuration. Neither the package code that you enter in this
setting nor the Summary Information Stream’s package code is used when the Generate Package
Code setting is set to Yes (its default value).
Generate A value of Yes indicates that a new package code will be generated with every build of this
Package Code configuration. This code is generated at build time and is part of the .msi package. The code
displayed in the Summary Information Stream’s Package Code field does not change.
If you want to retain the same package code when you rebuild the configuration, select No.
InstallShield uses the package code that appears in the Summary Information Stream’s Package
Code field for every build of this configuration.
Product List the feature release flags that you want to include in the installation. Separate multiple flags with
Configuration a comma. These flags are in addition to the release flags that you set for the release.
Flags
Subject Enter a new subject to override the subject in each release that you build under this product
configuration. Since this setting is localizable, it must use a string table entry.
Title Specify a new title to override the title in each release that you build under this product configuration.
Since this setting is localizable, it must use a string table entry. In fact, if the setting is empty and you
enter a new value, it is added as a string table entry.
Template Specify the processor type and the default language that your installation supports. For more
Summary information, see Targeting 64-Bit Operating Systems Using the Template Summary Property.
Comments Specify new comments to override the title in each release that you build under this product
configuration. Since this setting is localizable, it must use a string table entry.
Setting Description
Schema The schema version is an integer that identifies the minimum Windows Installer version that is
required for the installation package.
To override the schema version that is specified for your project in the Summary Information Stream
area of the General Information view, enter the appropriate integer. The value that you enter for the
product configuration overrides any value that you specify in the General Information view.
For example, if your package requires at least version 1.1 of the Windows Installer engine, enter 110
for this setting.
If the end user’s system has a Windows Installer version earlier than the minimum requirement
specified in the Schema setting—for example, if you specify a schema value of 120 and the end
user has Windows Installer 1.0—the installation displays an error message and exits.
Tip: If you are including the Windows Installer 1.2 engine with your installation, enter 110 for this
setting.
The value that you enter for the Schema setting is used for the Page Count Summary property of
your .msi file.
Product Code Click the Generate GUID button or type a new GUID to override the product code in each release that
you build under this product configuration.
Upgrade Code Click the Generate GUID button or type a new GUID to override the upgrade code in each release that
you build under this product configuration.
Preprocessor The Preprocessor Defines property enables you to specify any preprocessor definitions. Use the
Defines following format, with no spaces before or after equal signs or commas:
MYVARIABLE1=123,MYVARIABLE2=456
MSI Package Specify the file name that InstallShield should use for .msi, .cab, and .pdf files that are generated at
file name build time. If this setting is blank, the product name is used.
Setup file Specify the file name—without the .exe file extension—that InstallShield should use for the setup
name launcher file that it generates at build time. If this setting is blank, InstallShield uses the default value
of Setup, and the setup launcher file is called Setup.exe.
Setting Description
Include Custom Specify whether InstallShield should stream the contents of each of the custom action help files into
Action Help the .msi file every time that a release in the selected product configuration is built. The path to a
custom action’s help file is indicated in the Help File Path setting in the Custom Actions and
Sequences view (in Basic MSI, InstallScript MSI, MSI Database, Transform, and Web projects) or the
Custom Actions view (in Merge Module and MSM Database projects).
Selecting Yes is helpful if system administrators deploy your product to enterprise environments;
they sometimes need to know what the custom actions do. If you select Yes, the following tasks
occur at build time:
• InstallShield adds the ISCustomActionReference table to the .msi file that is being built. The
contents of all of custom actions’ help files that are specified in the Custom Actions and
Sequences view are streamed into the Description column of this table.
• If your project includes any merge modules that contain custom actions, the contents of the
help files that are specified in the Custom Actions view of the merge module projects are also
included in the ISCustomActionReference table.
For more information, see Documenting the Behavior of Custom Actions.
Build Tab
The Build tab is where you configure how InstallShield should package your release.
Release Location Basic MSI, Enter the path to the top-level directory where your release will start to be
InstallScript, built, or click the ellipsis button (...) to browse to the location.
InstallScript MSI,