Using Custom Actions

InstallShield 2019 Express Edition

Windows Installer provides many standard actions that execute an installation. However, there may be times where your installation needs expanded functionality. In these cases, custom actions let you extend the capabilities of standard actions. This can be done through including dynamic-link libraries, executable files, or script in your installation. The following table describes the different types of custom actions that you can add to your projects.

Types of Custom Actions

Type of Action

Description

Windows Installer DLL (MSI DLL)

This type of action is a C-callable library that exports functions with a fixed prototype.

Benefits of this action type include:

•

Windows Installer DLLs usually have minimal dependencies.

•

Much Windows functionality is exposed in system libraries.

•

Unlike executable-file actions, this type of action can use the Windows Installer API to access the running Windows Installer session and work with properties, directories, and so on.

Note that writing MSI DLLs requires C/C++ and Windows API coding skills.

Standard DLL

This type of action is an InstallShield extension that lets you call functions from C-callable DLLs. The type of function prototype that you select for the action (classic or new) determines which signature you must use for your function.

•

Classic—The prototype in this type of DLL must follow the same format that was used in early versions of InstallShield Express.

•

New—The prototype in this type of DLL uses the same signature that is required for MSI DLL custom actions. If you want to use this type of signature for a new custom action that you are adding to your project, it is recommended that you use an MSI DLL custom action instead of a standard DLL, since an MSI DLL action offers more flexible scheduling options.

Important • Note that for standard DLL custom actions, a non-zero return value indicates success, and a return value of zero indicates failure. For MSI DLL custom actions, a return value of zero indicates success; non-zero return values indicate statuses such as failure or cancellation.

Executable File

This type of action launches an executable file that is included in your installation (as a temporary support file or installed with the product) or that already exists on the target system.

A benefit of this action type is that a lot of operating system functionality is exposed in executable files. For example, this type of action lets your installation open text files and other common file types, set permissions on existing directories, and launch batch files.

Executable-file actions do not have access to the running installation session. Thus, you cannot pass Windows Installer properties in to the executable file (except as command-line arguments) or back from the executable file (except through external storage, such as the registry or a file).

Note that to open a document or launch a batch file, you must explicitly refer to an executable file that handles that type of document.

VBScript or JScript

This type of action runs VBScript or JScript code.

Benefits of this action type include:

•

Script actions are often easy to implement.

•

Unlike executable-file actions, this type of action can use the Windows Installer API to access the running Windows Installer session and work with properties, directories, and so on.

•

This type of action can be useful for simple tasks such as string manipulation.

Note that VBScript and JScript actions often trigger antivirus or antispyware programs when they access or modify the target system.

Edition • The Premier and Professional editions of InstallShield include support for several custom action types that are not available in the Express edition. These extra custom action types enable you to do the following: run InstallScript code, set a property, set a directory, call a public method in a managed assembly, or display an error message under certain conditions and abort the installation.

Using Custom Actions

InstallShield 2019 Express Edition Help Library

April 2019