by Robert Dickau, Principal Technical Training Writer, Flexera Software
This white paper describes some of the types of custom actions supported by Windows Installer (MSI). These types include:
- Launching executables
- Calling DLL or script functions
- Setting Property-table properties and Directory-table properties
- Error actions
It also highlights how InstallShield® from Flexera Software assists you in working with custom actions.
Learn More about InstallShield
If you wish to learn more about the capabilities of InstallShield, please visit the Flexera Software Web site at www.flexerasoftware.com/installshield
Using the InstallShield Environment
This white paper frequently refers to the InstallShield development environment. It is assumed you are familiar with the general layout of the InstallShield interface, which contains a list of views with which you can modify different portions of your installation project.
For example, the General Information view is where you set general product and project properties; the Setup Design view enables you to edit the features, components, and component data used by your project; the Registry view enables you to modify the registry data installed by your installation program; and the Direct Editor view gives you access to the raw MSI database tables.
It is also assumed you are familiar with some of the wizards available with InstallShield, such as the Release Wizard and Component Wizard.
- The Release Wizard, available under the Build menu and also from the Releases view, lets you describe the properties—media type, compression settings, and so forth—of a release, and then builds the specified release image.
- The Component Wizard, available by right-clicking a feature in the Setup Design view, lets you create special types of components, such as components for COM servers, fonts, and Windows services.
The InstallShield Help Library contains information about using every view and wizard in the InstallShield environment. The InstallShield Help Library is available when you press F1 with any view selected; you can also select Contents from the Help menu to view the help library.
In addition to the graphical environment, InstallShield provides several tools for modifying and building projects from the command line or an external script. For example, to build a project from the command line, batch file, or other automated process, you can use the executable IsCmdBld.exe. The IsCmdBld executable is located in the System subdirectory of the InstallShield distribution directory.
To rebuild a project, you pass IsCmdBld the project file path, the product configuration name, and the release name that you want to rebuild. A sample command appears as follows:
iscmdbld -p C:\ProductName.ism -a BuildConfig -r ReleaseName
In addition, InstallShield provides an Automation interface, with which you can modify the contents of a project file without using the graphical environment.
Custom Action Basics
There are two steps involved for each custom action you want to use:
- Define the action: Specify what the action does (launch an executable, call a DLL function, set a property, and so forth) and its other behavior (whether to test the return value, and so forth).
- Schedule the action: Specify where the action runs relative to other actions, which installation phase (immediate execution, deferred execution, and so forth) the action uses, and under what conditions the action runs.
A general principle is that you should not use a custom action when a standard action performs the desired task. One reason is that the effects of custom actions are not automatically removed when your application is uninstalled or rolled back.
For each custom action that performs system changes, you should create corresponding uninstall and rollback actions.
Executable Custom Actions
One of the most commonly used types of custom actions is an action that launches an executable. This type of action is commonly used to open documents installed by the current installation, or to launch system executables to perform system changes that Windows Installer does not directly support. The executable that you launch with this type of custom action can be installed by the current installation, already located on the target system, or streamed into the Binary table of the MSI database.
For example, suppose you want to launch the copy of Notepad from the target system’s Windows directory. You begin by opening the Custom Actions and Sequences view, right-clicking the Custom Actions icon, and selecting New EXE > Path referencing a directory.
In the Working Directory setting, enter WindowsFolder, the Directory property representing the location of the executable. In the Filename & Command line setting, enter the executable name notepad.exe.
If the executable being launched is in a directory on the target system, the custom action must be placed after the standard CostFinalize action. The CostFinalize action sets the values of Directory properties, and an attempt to reference a Directory property (such as WindowsFolder or SystemFolder) will cause run-time error 2732, which is described in the Windows Installer Help Library as “Directory Manager not initialized”.
In this case, because Notepad.exe is present on the target system, this custom action can be placed in either the User Interface sequence or Execute sequence (or both), after the CostFinalize action. It is not necessary to specify deferred execution, or for the InstallFiles action to have run first.
An executable custom action does not have access to installation properties, other than those passed as command-line arguments. A typical use of a command-line argument is to pass the path to a document to the executable being launched. For example, suppose you want to launch a Readme file with Notepad.exe after data transfer takes place. In this case, the Filename & Command line setting for the custom action might read:
The quotation marks around the argument are required by most executables in case the file path contains any spaces.
An action that launches an executable being installed, or one that opens a document being installed, must be scheduled for deferred execution after the standard InstallFiles action. During immediate mode, data transfer has not yet begun; and in deferred mode before InstallFiles, documents and executables will not have been placed on the target system.
The condition Not Installed ensures the action runs—that is, the Readme file is displayed—only during a first-time installation, and not during maintenance mode or uninstallation.
To ensure the action runs only during a first-time, full-UI installation, you could use the condition (Not Installed) and (UILevel=5). A further possible refinement is to associate the action with the component containing the Readme file, using a component-action condition ($ComponentName=3).