Running custom code from the package

Custom Actions

Windows Installer comes with a number of standard actions. These actions are basically pieces of code included by default in the operating system to handle operations like installing files, registry and so on. But in some cases, these are not enough. When you need more control, (e.g. when launching an executable during installation on the machine, calling a special function from a dll, etc), you can resort to .Dll, .js, .vbs, .exe, and .ps1 files as sources of various custom actions.

In these scenarios, it is most common to use VBS files, run by the Windows Scripting Host service, which is available with any Windows version.

You can add these types of files as binaries included directly in the package, and pass the source code of VBS directly in a custom action.

Once you have chosen the type of file and the reference method, you must schedule the custom action in a running sequence (you cannot run a file if it has not been copied to the machine yet).

Custom Actions sequence scheduling

1. InstallUISequence - via the graphical user interface
2. InstallExecuteSequence - via the graphical interface or silently
3. AdminExecuteSequence - when performing an administrative installation
4. AdvExecuteSequence - when installing or uninstalling advertised components

All the standard and custom actions from an MSI package are grouped in several sequences. Each of them must be scheduled as part of at least one sequence.

This is mostly done automatically by the MSI authoring tool you use, but when you add a custom action in the package, you will have to manually choose the sequence where you will schedule it, so, the following information is essential knowledge for any packager.

The above Microsoft docs links and the one below from the Advanced Installer team provide detailed explanations on the purpose and characteristics of each sequence.

More details can be found here.

Custom Actions running modes

Custom action properties can be set in just a few mouse clicks in Advanced Installer.

Depending on the sequence you choose when scheduling a custom action, you will also be able to configure additional properties for each custom action.

One of the most important properties of a custom action is the user account under which the Windows Installer service executes the custom action code. Any MSI package can schedule a custom action that runs under the current user account performing the installation or under the SYSTEM account from that machine.

This in turn, affects the permissions the custom actions have. Usually, those running under the current user have limited permissions (and we use them just to control the installation logic, but not to modify machine resources) and those running under the SYSTEM account can change any resource from the machine, like files or registry.

Immediate Execution

The action :

• is executed under the account of the user who started the action
• can be placed anywhere in the sequences list
• has the advantage that it uses the user’s account, and you can directly access its specific settings
• the disadvantage is that the user’s account often has limited rights which can block some actions
• It can read and write MSI properties

Deferred Execution / System Context

The action:

• is executed under the system account
• can be placed in the InstallExecute sequence list, only between InstallInitialize and InstallFinalize
• has the disadvantage that if you try to write in the user’s profile, it will not succeed because it will be written in the “profile” of the system
• It cannot read and write MSI properties. CustomActionData property management is the only way to pass parameters to this type of custom actions.

Deferred Execution / User Context

The action:

• is executed under the account of the user who started the action
• can be placed in InstallExecute sequence, between InstallInitialize and InstallFinalize
• has the advantage that compared to Immediate Execution, it can be sequenced more correctly
• It cannot read and write MSI properties. CustomActionData property management is the only way to pass parameters to this type of custom actions.

Rollback

This type of action is performed when the installation fails before it finishes. The rollback is executed under the account of the user who started the installation and it can be placed between InstallFinalize and InstallExecuteSequence, but it cannot run asynchronously.

Commit

This Commit action:

• is performed when the installation is successful.
• it is executed under the account of the user who started the action
• can be used to clean the temporary resources left after a successful installation

Advanced Installer offers a quick and easy way to add your custom actions, and it includes popular built-in solutions. More details about this can be found here.

Custom Actions Processing

1. Synchronous
2. Synchronous, ignore exit code
3. Asynch, Wait at end of sequence
4. Asynch, No Wait

Custom Actions processing can be executed synchronously and asynchronously.

The synchronous Custom Actions are executed in the same thread in the order of the sequence. The following ones in the sequence must wait for the completion of the previous one.

The asynchronous Custom Actions are those that open a new thread and run in parallel with the main thread.

The two options check whether the installation has been completed successfully or not.

In a package, custom actions are performed during all three phases (installation, uninstallation, repair). To avoid this, a specific condition must be set:

1. Installation Only: NOT Installed
2. Repair Only: REINSTALL
3. Uninstall Only: Installed AND REMOVE ~ = ”ALL”

To combine these, use the “OR” operator. Other properties such as “AND” may be included in the conditions.

Some frequently asked questions about Custom Actions can be found here.

System Search

Sometimes, during the installation of an MSI, it is necessary to perform various checks on the system to determine a few things: if an application is installed on the machine, or if we need a path to the prerequisite in case we have to change a configuration, etc.

You can use a feature called System Search to perform these checks.

Windows Installer can search for a file, directory, registry, or component while installing a package, this is done through an AppSearch action.

The AppSearch action searches the system for the signature of a file that is specified in the AppSearch table. If the AppSearch action finds the file or directory on the system, it sets an appropriate property with the location of the file or directory (also specified in the AppSearch table).

When searching for a file, the signature of the file must also be specified in the Signature table. If the file Signature is listed in the AppSearch table but not listed in the Signature table, then it searches for a directory, registry, or INI.

The tables that populate when creating a system search (depending on the type of system search that you want) are: AppSearch, CompLocator (for components), DrLocator (for directories), IniLocator (for INI files), RegLocator (for registry), Signature (for files).

Easily add searches with Advanced Installer. Here is how.