Custom Actions

The Windows Installer provides many built-in actions for performing the installation
process.
You want to launch an executable during installation that is installed on the user's
machine or that is being installed with the application.
You want to call special functions during an installation that are defined in a
dynamic-link library (DLL).
You want to defer the execution of some actions until the time when the
installation script is being executed.
You want to run a nested installation.
Custom actions cannot be used in the sequence tables used for advertisement, the
AdvtUISequence table and the AdvtExecuteSequence table.
AdvtUISequence Table
The installer does not use this table. The AdvtUISequence table should not exist in the
installation database or it should be left empty.
AdvtExecuteSequence Table
The AdvtExecuteSequence table lists actions the installer calls when the top-level
ADVERTISE action is executed.
Only the following actions can be used in the AdvtExecuteSequence table. Custom
actions cannot be used in this table.
CostFinalize, CostInitialize, CreateShortcuts, InstallFinalize, InstallInitialize,
InstallValidate,
ADVERTISE Action
The ADVERTISE action is a top-level action called to install or remove advertised
components.
CostFinalize Action
The CostFinalize action ends the internal installation costing process begun by the
CostInitialize action.

Sequence Restrictions:Any standard or custom actions that affect costing should be sequenced before the
CostInitialize action. Call the FileCost action immediately following the CostInitialize
action and then call the CostFinalize action to make all final cost calculations available to
the installer through the Component table.
The CostFinalize action must be executed before starting any user interface sequence
which allows the user to view or modify Feature table selections or directories.
Costing
Method used by the installer to determine disk space requirements for installation.
Costing takes into account factors such as whether existing files need to be overwritten.
File Costing
Costing is the process of determining the total disk space requirements for an installation.
The elements calculated in the file costing process include the amount of disk space in
which files are installed or removed, as well as the amount of disk space taken up by
registry entries, shortcuts, and other miscellaneous files. Existing files scheduled to be
overwritten are also calculated in the disk cost totals.
Total costs are accumulated on a per-component basis and consist of three separate parts:
local costs, source costs, and removal costs. These parts correspond to the disk cost that is
incurred if the component is installed locally, installed to run from the source media, or
removed.
CostInitialize Action
The CostInitialize action initiates the installation costing process.
Sequence Restrictions:Any standard or custom actions that affect costing should be sequenced before the
CostInitialize action. Call the FileCost action immediately following the CostInitialize
action. Then call the CostFinalize action following the CostInitialize action action to
make all final cost calculations available to the installer through the Component table.

CreateShortcuts Action
The CreateShortcuts action manages the creation of shortcuts.
Sequence Restrictions:The CreateShortcuts action must come after the InstallFiles action and the
RemoveShortcuts action.
InstallFinalize Action
The InstallFinalize action runs a script that contains all operations spooled since either
the start of the installation or the execution of the InstallExecute or InstallExecuteAgain
actions. This action marks the end of a transaction that begins with the InstallInitialize
action.
Sequence Restrictions:The InstallInitialize action must come before the InstallFinalize action.
InstallInitialize Action
The InstallInitialize action and InstallFinalize action mark the beginning and end of a
sequence of actions that change the system.
Sequence Restrictions:The InstallInitialize action must be sequenced before any actions that change the system,
such as the InstallFiles action, the WriteRegistryValues action, the SelfRegModules
action, and the ProcessComponents action. The InstallInitialize action must therefore be
sequenced before the InstallFinalize action and the InstallExecute action.
InstallFiles Action
The InstallFiles action copies files specified in the File table from the source directory to
the destination directory.
Sequence Restrictions:The InstallFiles action must come after the InstallValidate action and before any filedependent actions.
WriteRegistryValues Action
The WriteRegistryValues action sets up an application's registry information. The registry
information is gated by the Component table. A registry value is written to the registry if
the corresponding component has been set to be installed either locally or as run from
source.
Sequence Restrictions
The InstallValidate action must come before the WriteRegistryValues action. If there is a
RemoveRegistryValues action, then it must come before the WriteRegistryValues action.
InstallValidate Action

The InstallValidate action verifies that all volumes to which cost has been attributed have
sufficient space for the installation. The InstallValidate action ends the installation with a
fatal error if any volume is short of disk space.
The InstallValidate action also notifies the user if one or more files to be overwritten or
removed are currently in use by an active process.
Volume
Storage medium, such as a disk or tape, that is formatted to contain files and directories.
SelfRegModules Action
The SelfRegModules action processes all modules listed in the SelfReg table and
registers all installed modules with the system. The installer does not self-register EXE
files.
Sequence Restrictions:The InstallValidate action must be called before calling the SelfRegModules action. If an
InstallFiles action is used, it must appear before the SelfRegModules action in the
sequence. Because the SelfRegModules action changes the system, SelfRegModules
should come after the InstallInitialize action.
ProcessComponents Action
The ProcessComponents action registers and unregisters components, their key paths, and
the component clients. The ProcessComponents action queries the KeyPath column of the
Component table to determine keypaths. This registration is used by
MsiGetComponentPath to return the path of a component for a product client.
Sequence Restrictions:The ProcessComponents action must come after the InstallInitialize action.
MsiGetComponentPath
The MsiGetComponentPath function returns the full path to an installed component. If
the key path for the component is a registry key then the registry key is returned.
The MsiGetComponentPath function returns the following values.
Value
Meaning
INSTALLSTATE_NOTUSED
The component being requested is disabled on the
computer.
INSTALLSTATE_ABSENT
The component is not installed.
INSTALLSTATE_INVALIDARG
One of the function parameters is invalid.
INSTALLSTATE_LOCAL
The component is installed locally.
INSTALLSTATE_SOURCE
The component is installed to run from source.
INSTALLSTATE_SOURCEABSENT The component source is inaccessible.
INSTALLSTATE_UNKNOWN
The product code or component ID is unknown.
InstallExecute Action

The InstallExecute action runs a script containing all operations spooled since either the
start of the installation or the last InstallExecute action or InstallExecuteAgain action.
The InstallExecute action updates the system without ending the transaction.
Sequence Restrictions:The InstallExecute action comes between the InstallInitialize action and the
InstallFinalize action.
Tables:1. CustomAction Table
The CustomAction table provides the means of integrating custom code and data into the
installation. The source of the code that is executed can be a stream contained within the
database, a recently installed file, or an existing executable file.
2. InstallExecuteSequence Table
The InstallExecuteSequence table lists actions that are executed when the top-level
INSTALL action is executed.
Actions in the install sequence up to the InstallValidate action, and any exit dialog boxes,
are located in the InstallUISequence table. All actions from the InstallValidate through
the end of the install sequence are in the InstallExecuteSequence table. Because the
InstallExecuteSequence table needs to stand alone, it has any necessary initialization
actions such as the LaunchConditions, CostInitialize, FileCost, and CostFinalize
actions.
INSTALL Action
The INSTALL action is a top-level action called to install or remove components. This
action queries the InstallUISequence Table and InstallExecuteSequence Table for the
action to execute, the condition for action execution, and the place of the action in the
sequence.
LaunchConditions Action
The LaunchConditions action queries the LaunchCondition table and evaluates each
conditional statement recorded there. If any of these conditional statements fail, an error
message is displayed to the user and the installation is terminated.

3. InstallUISequence Table
The InstallUISequence table lists actions that are executed when the top-level INSTALL
action is executed and the internal user interface level is set to full UI or reduced UI. The
installer skips the actions in this table if the user interface level is set to basic UI or no UI.

4. AdminExecuteSequence Table
The AdminExecuteSequence table lists actions that the installer calls in sequence when
the top-level ADMIN action is executed.
ADMIN actions in the install sequence, up to the InstallValidate action and any exit
dialog boxes, are located in the AdminUISequence table.
ADMIN actions from the InstallValidate action through the end of the install sequence
are in the AdminExecuteSequence table. Because the AdminExecuteSequence table needs
to stand alone, it also contains any necessary initialization actions such as
LaunchConditions, CostInitialize, FileCost, and CostFinalize.
ADMIN Action
The ADMIN action is a top-level action used to perform administrative installations.
5. AdminUISequence Table
The AdminUISequence table lists actions that the installer calls in sequence when the
top-level ADMIN action is executed and the internal user interface level is set to full UI
or reduced UI. The installer skips the actions in this table if the user interface level is set
to basic UI or no UI.
ADMIN actions in the install sequence up to the InstallValidate action, and any exit
dialog boxes, are located in the AdminUISequence table. All actions from the
InstallValidate through the end of the install sequence are in the AdminExecuteSequence
table. Because the AdminExecuteSequence table needs to stand alone, it also contains any
necessary initialization actions such as LaunchConditions, CostInitialize, FileCost, and
CostFinalize. It also has the ExecuteAction action.
ExecuteAction Action
The ExecuteAction action initiates the execution sequence using the
EXECUTEACTION property to determine which type of installation to perform.

EXECUTEACTION Property
The EXECUTEACTION property is set to determine which top-level action the
ExecuteAction action initiates.
The top-level actions, such as the INSTALL action, ADVERTISE action, and ADMIN
action set the EXECUTEACTION property to the name of the top-level action.
ADVERTISE Action
The ADVERTISE action is a top-level action called to install or remove advertised
components.

Custom Action Types

Basic custom action type

Type

Source

DLL file stored in a Binary table

stream.

Key to Binary table.

DLL file that is installed with a

product.

17

Key to File table.

EXE file stored in a Binary table

stream.

Key to Binary table.

EXE file that is installed with a

product.

18

Key to File table.

19

blank

Displays a specified error message

and returns failure, terminating the
installation.

EXE file having a path specified by a 50

property value.
EXE file having a path referencing a 34
directory.
JScript file stored in a Binary table
stream.

Property name or key to Property table.

Key to Directory table. This is the working
directory for execution.
Key to Binary table.

JScript file that is installed with a

product.

21

Key to File table

JScript text specified by a property

value.

53

Property name or key to Property table.

JScript text stored in this sequence

table.

37

null

VBScript file stored in a Binary table 6

stream.

Key to Binary table.

VBScript file that is installed with a 22

product.

Key to File table.

VBScript text specified by a property 54

value.

Property name or key to Property table.

VBScript text stored in this sequence 38

table.

null

Property set with formatted text.

Directory set with formatted text.
Installation of a package nested
inside of the first package. Nested
Installation Actions.

51
35

Installation of a package that resides 23

in the first application's source tree.
Installation of an application that is
advertised or already installed. See

39

Property name or key to the Property table.

This property is set by the formatted string in
the Target field.
A key to the Directory table. The designated
directory is set by the formatted string in the
Target field.
Name of the substorage containing database of
nested application.
Path of nested package specified relative to the
root of the source location.
Product code for the application.

Custom Action Sources

Custom action source
Custom action stored in the Binary table.
Custom action copied during installation.
Custom action referencing a directory.

Associated custom
action types
1, 2, 5, 6
17, 18, 21, 22
34

Custom action referencing a property.

Custom action stored as literal script code in
database table.
Custom action displaying an error message.

50, 53, 54
37, 38
19

SEQUENCE
1. Normal User Interface
2. Normal Execute Immediate/Deferred
3. Administrative User Interface
4. Administrative Execute Immediate/Deferred
5. Advertisement Execute Immediate/Deferred

Conditions:Place a custom action between conditional If Statements to run it only if a certain

condition is true. A condition can check whether the product is installed, the value of
a property is true, if specific system requirements are met, and more.
To Run Only During Initial Installation

The Execute sequences under the Normal Installation mode run during initial installation
and later during maintenance and uninstall installations. To run a custom action during
the initial installation only, set its condition to NOT Installed. Installed is a Windows
Installer property that is true if the product is installed.
Example: If you add a custom action that opens a Readme file and set the action's
condition to NOT Installed, then the Readme opens during initial installation, but does
not open during maintenance installations (reinstall, modify, and repair operations).
To Run Only During Uninstall

If the product is being uninstalled, the REMOVE property is set to All or ALL. To run a
custom action during uninstall only, set its condition to REMOVE~="ALL". (The ~
causes the comparison to be case-insensitive.)

Custom Action In-Script Execution Options

These options copy the action code into the execution, rollback, or commit script.

Immediate execution: Execution Immediately

Deferred Execution Custom Actions
The purpose of a deferred execution custom action is to delay the execution of a system
change to the time when the installation script is executed.
The installer does not execute a deferred execution custom action at the time the
installation sequence is processed. Instead the installer writes the custom action into the
installation script.
A deferred execution custom action must be scheduled in the execute sequence table
within the section that performs script generation. Deferred execution custom actions
must come after InstallInitialize and come before InstallFinalize in the action sequence.
Rollback Custom Actions
When the installer processes the installation script, it simultaneously generates a rollback
script. In addition to the rollback script, the installer saves a copy of every file it deletes
during the installation. These files are kept in a hidden system directory. Once the
installation is complete, the rollback script and the saved files are deleted. If an
installation is unsuccessful, the installer attempts to rollback the changes made during the
installation and restore the original state of the computer.
A rollback custom action must always precede the deferred custom action it rolls back in
the action sequence. A rollback custom action should also handle the case where the
deferred custom action is interrupted in the middle of execution. For example, if the user
were to press the Cancel button while the custom action was executing.
Commit Custom Actions
Commit Custom actions are executed upon successful completion of the installation
script. If the InstallFinalize action is successful, the installer will then run any existing
Commit Custom actions.
A commit custom action is the complement to a rollback custom action and can be used
with rollback custom actions to reverse custom actions that make changes directly to the
system.
Custom Action Return Processing Options
The option flags can be used to control the processing of the custom action thread. They
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).

Synchronous:Synchronous execution. Fails if exit code not 0. If the flag

msidbCustomActionTypeContinue is not set then the custom action must return one
of the return values described in Custom Action Return Values.
Synchronous, Ignore exit code:Synchronous execution Ignores exit code and continues.
Asynch, Wait at end of sequence:Asynchronous execution. Waits for exit code at sequence end.
Asynch, No wait:Asynchronous execution. No wait for completion. Execution continues after
installer terminates.