Custom Actions List

Launch attached file

Using this type of custom action you can execute an application (EXE or DLL) or run a script (VB or Java script) which is not among your project files. This usually happens when this functionality is only useful in the installation process, but not for the installed application itself.

This source file will be embedded in the MSI file but will not be deployed at install time with the other application files.

Properties

• Attached File - the path to the custom action file. You can use the [ ... ] button to change the custom action's file.
• File Type - contains the type of the custom action file. By default, this type is set depending on the extension of the file. You can change this type if you know for sure that the extension of the file doesn't reflect the type of its content. This only works for attached custom actions.
• Function / Command Line / Properties - represents:
  • The name of a function (if the custom action is of DLL, JavaScript or VBScript type). In the case of a DLL the list will be automatically populated with the names of the functions included in it.
  • The command line arguments (in the case of a custom action of EXE type). In this case, the command line arguments are actually of Formatted Type and thus they can include references to files, folders and properties. Use the [ Edit ] button to include references to a file, a folder or a property.
  • Properties (in the case of a MSI installation) representing settings for the installation process. Usually they will specify some features that are to be installed. Note that it is not recommended to attach a MSI package to an installation.
• Action Data - this filed is described in Custom Action Properties article.

Launch installed file

This custom action is an application (EXE or DLL) or a script (VB or Java script) included in the MSI package. It behaves as an attached custom action ,but it must be scheduled after the files have been deployed on the target computer.

Properties

The usage of the fields is identical to the one described for the Attached Custom Actions.

Launch file

This is a predefined attached custom action. It allows the launching of a file into execution or opening of a folder (the same action that occurs when you double-click it in Explorer).

You can also supply an URL to open a page in the default browser on the target computer. This action is performed by a program that comes with Advanced Installer, called viewer.exe.

Properties

• File To Launch - this contains the file that will execute the actions, in this case viewer.exe. You don't need to change this field.
• Command Line - this is where you specify the file, the folder or URL to be opened. Since this is of Formatted Type you can use the [ Edit ] button to include a reference to a file, a folder or a property.
• Working Directory - set a custom working directory for the target file.
• Run As Administrator - launch the target file as an Administrator (the equivalent of Run As... or Run As Administrator Windows Shell options). When setting this option through a button control, you should set the Elevation Shield control property to True. This will make the OS (Vista, and above) show an elevation shield on the button when the installation runs, in order to warn the installing user that an elevation request is about to happen when the button is pressed.
• Use 64-bit Launcher - the file is launched using the 64-bit version of the viewer.exe program.

Command line options

This is the command line syntax:

<file_to_launch> <parameters>

Command Line Example:

"[#MyFile.bat]" param1 param2

Open URL

This custom action uses the supplied URL to open a page in the default browser on the target computer.

Launch file from property

This custom action calls an executable or a script launched with a command line. The path to the executable file is specified through a property.

Properties

• Property - the name of the property that contains the path to the executable file. The name of the property is not placed between brackets ( ] ).
• File Type - select the type of the executable file from the drop-down list.
• Command Line - edit this field with the command line options for the executable file. This field is of Formatted Type so you can use the [ Edit ... ] button to insert reference to files, folders and properties.

Launch EXE with working directory

This custom action calls an executable file. This file has a designated folder as Working Directory.

When creating a "Launch EXE with working directory" type of custom action you will be prompted with a window that will allow you to choose the working directory for the executable file.

Properties

• File Path - the full path to the executable file. Quotation marks must be used around long file names or paths. This field is of Formatted Type. Use the [ Edit ... ] button to insert a reference to file, folder or property.
• Command Line - specify the command line parameters which will be passed to the EXE file.
• Working Directory - the working directory for the executable file. Use the [ ... ] to change it.

.NET Installer Class action

This is a custom action that launches a .NET Assembly. The assembly must have a class that inherits the Installer class with the RunInstaller attribute set to true.

Assembly Target Platform

Custom actions are created and conditioned depending on your assembly target platform:

• x86 - A single custom action will be created to run on any platform.
• x64 - A single custom action will be created to run only on 64-bit platforms.
• Any CPU - Two custom actions will be created and conditioned (one to run on 32-bit platforms and the other for 64-bit platforms)

You can also modify the execution conditions as desired.

Assembly

• Dll Path - Represent the assembly that will be launched with the parameters specified below. It must have a class that inherits from the Installer classes and the RunInstaller attribute set to true.
• Configure file path - This path represents the location where the .NetCustActLauncher will create the assembly's configuration file. The configuration file contains the .NetFramework required version. This field is of Formatted Type and can be edited using Smart Edit Control.

Installer Class Parameters

The assembly custom action requires some predefined parameters. In addition, you can add new parameters in order to pass information to your .NET custom action.

You can add or edit parameters using the .NET Installer Class Argument Dialog.

Predefined parameters:

• Action - specifies the Installer class method that will be called. It can have one of the following values: "Install", "Rollback", "Commit", "Uninstall". If you move the custom action under another standard action you may want also to change the Action parameter.

• InstallType.
• LogFile - specifies the name of the log file where install progress is recorded. If empty then no log will be created.
• ReqVersion - specifies the version of the .NET Framework required by the assembly. Advanced Installer automatically determines the required version, but you can overwrite that value.

Debug the method of the .NET Installer Class Action

A quick way to Debug the .Net Installer Custom Action can be found here.

Set installer property

This custom action sets a property from a formatted text string.

Properties

• Property - the name of the property to be formated. The name of the property is not placed between brackets ( ] ).
• Value - the formatted string. This field is of Formatted Type so you can use the [ Edit ... ] button to insert reference to files, folders and properties.

Set directory path

This custom action enables setting a folder from a formatted text string.

Properties

• Directory - the folder who's path is to be modified. Use the [ ... ] button to change it.
• Value - the text which forms the path for the folder. This is of Formatted Type. Use the [ Edit ] button to insert a reference to file, folder or property.

Example:

• "[WindowsVolume][USERNAME]" is a valid string as it will be expanded into "C:\Fred\" (when the windows volume is c: and the user is Fred).
• "[USERNAME]\SubFolder" is a bad string as it will be expanded into a relative path: "Fred\SubFolder".

Call function from attached native DLL

Using this type of custom action you can call a function from a native DLL. You can find a sample DLL and its project in the Serial Number Validation DLL article.

The target DLL will be embedded in the MSI file but will not be deployed at install time with the other application files. This action has the same options as the Launch attached file custom action.

Call function from installed native DLL

Using this type of custom action you can call a function from a native DLL. You can find a sample DLL and its project in the Serial Number Validation DLL article.

The target DLL must be installed by your package and must exist on disk when this custom action is executed. This action has the same options as the Launch attached file custom action.

Call function from standard DLL

This predefined custom action can be used to call a function from a dll file. Unlike native dll custom action where the called function must have a predefined signature, this custom action allows you to call a function with any signature.

DLL

• Path - specifies a formatted string that resolves to an absolute path of a DLL.
• 64-bit - this option configures the custom action to call a function from a 64-bit DLL file.

Function

• Return Type - specifies the type of value returned by the function.
• Return Property - the name of the property where will be stored the result returned by the function - if function type is other than void.
• Calling Convention - the calling convention to use when the function will be called.
• Name - the name of the function from DLL to be called.

Arguments

The list with the function's arguments. There can be any number of arguments.

Execute inline script code

This custom action is basically a small VBScript or JScript that is ran during the install process.

Properties

• 64-bit script - specify whether this is a 64-bit script.
• Action Data - this filed is described in Custom Action Properties article.
• Source Type - select the type of the script from the drop-down list.
• Script Text - edit this field with the body of the script. This is a plain text field, so you can't add references to files, folders or properties.

A custom action which is written in JScript or VBScript requires the install Session object. The installer attaches the Session Object to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script does not have access to all the methods and properties of the Session object.

Here is an example of a "Execute inline script code" custom action written in VBScript:

MsgBox Session.Property("APPDIR")

This custom action will prompt a message box containing the value of the APPDIR property.

Display error message

This custom action enables the stopping of the installation process if some condition is satisfied or not. An error message will be displayed to let the user know what happened.

The condition for stopping the install process must be entered in the "Execution Condition" field.

Properties

Error message - the message that will be displayed to the user. It is of Formatted Type so you can use the [ Edit ] button to insert reference to files, folders and properties.

Display message box

This custom action will display a message box.

Properties

• Title - the message box's title. It supports '\\' (backslash character) and '\|' (pipe character).
• Message - this is the message that will appear in the message box. It supports the following sequence of special characters: '\n' (new line character), '\\' , '\|'.
• Icon - choose the appropriate icon to be displayed inside the message box.
• Buttons - specify the button combination for the message box.
• Default Button - this button will be selected by default when the message box is shown.
• Output Property - this is the name of the property that will be set to different values depending on which button on the message box the user will press. When set to Deferred type this parameter should not be used because deferred custom actions can not set properties. The property will be set to one of the following values:

• The text is right justified - align text to the right margin.
• Displays message and caption text using right-to-left reading order on Hebrew or Arabic systems

Close application

This custom action allows you to close an application which uses a user Interface. It basically sends WM_CLOSE messages to all windows created by the application process.

After adding the custom action, in its Custom Action Properties pane the Process Name field should be set to the name of the main EXE of your application.

By default the custom action closes windows which have a title-bar, a border and a system menu. If you want to specify custom style flags you can select them in the Windows Flags list or set the AI_CLOSEAPP_WINDOW_FLAGS property to the flags you want. For example, the property can be set to:

WS_SYSMENU | WS_OVERLAPPED | WS_VISIBLE

Detect process

This custom action allows you to detect a running process on the target machine. For more details please see the Detect or stop a process How-To.

Terminate process

This custom action allows you to stop a running process on the target machine. For more details please see the Detect or stop a process How-To.

Detect service

This custom action allows you to detect a service on the target machine. For more details please see the Detect a service How-To.

Check if user exists

This custom action allows you to check if a specific user account exists on the target machine or inside the installer. It was designed to work with the "LogonInformationDlg" dialog, but it can also be used separately.

Properties

• Domain - this field needs to be set to the target user domain name. (DOMAIN_NAME property)
• Name - this field needs to be set to the target user name. (USER_NAME property)
• Search in users/groups - choose whether the custom action will check in user groups or accounts. (equivalent to setting AI_USER_IS_GROUP property to 1 for checking user groups instead of accounts)
• Check only user names and ignore profile names - if this option is set, the custom action will search only user account names (profile names are ignored). (equivalent to setting AI_USER_IGNORE_FULLNAME property to 1)
• Ignore user accounts configured by this package - if this option is set, the custom action will ignore user accounts configured inside the installer. (equivalent to setting AI_USER_IGNORE_MSI property to 1)
• Check user account's password - if this option is set, the custom action will validate the user account password. Please note that by default Windows does not allow validation of empty passwords. (equivalent to setting AI_USER_CHECK_PASSWORD property to 1)

Custom action return properties

• AI_USER_EXISTS - after the custom action is executed, this property will be set to Yes if the user account exists or to No otherwise
• AI_USER_VALID_PASSWORD - after the custom action is executed, this property will be set to Yes if the user account password is correct or to No otherwise. Please note that empty passwords may not be validated, so this property can be empty if a password is not provided.

Query SQL database for data

This predefined custom action executes an SQL query. Use the Choose SQL query link button to execute an SQL query added from the SQL Scripts Page.

Test ODBC connection

You can use this UI custom action when you want to validate user input parameters for an SQL ODBC Connection by testing the connection from within the "SQLConnectionDlg" dialog. For details please see: Test SQL Connection.

Send install information to your web server

You can use this UI custom action when you want to collect installation data and send it to your web server for processing. Install information can only be collected through Windows Installer properties (their values). For details please see: Collect installation data and send it to a web server.

Properties

• Web Server URL - the URL where to submit the collected information. This field actually sets the value of HttpPostUrl property.
• Suppress spawned message box - suppress the "Please wait..." message box during the HTTP POST request.
• Property list - each property listed here will be sent as a POST variable, with its value set according to the installation state. This list control sets the value of HttpPostCollectData property.

Browse for file

This UI custom action will display an Open File dialog during the installation. See the Browse for file how-to article for details on how to configure your project.

Predefined custom actions for working with ComboBox controls

Populate combo box, Delete from ComboBox and Extract ComboBox Data are UI-only custom actions that can be used to populate, delete from and extract data from ComboBox controls. See the ComboBox and ListBox controls tutorial for details and sample projects.

Predefined custom actions for working with ListBox controls

Populate ListBox, Delete from ListBox and Extract ListBox Data are UI-only custom actions that can be used to populate, delete from and extract data from ListBox controls. See the ComboBox and ListBox controls tutorial for details and sample projects.

Update MSI edit controls

This UI-only custom action provides a workaround for a Windows Installer issue. For more information on how to use it please see: Set Edit control text on button push.

Resolve known folder path

This predefined custom action can be used to resolve a property based folder to the path of a known folder in Windows Vista (or later operating systems).

In order to use this predefined custom action in your project, follow the steps below:

a) Add the predefined Resolve known folder path custom action under "Wizard Dialogs Stage -> Searches".

b) Keeping the SHIFT key pressed, drag-and-drop the custom action in tree control, under "Install Execute Stage -> Searches". This will create a copy of the action in the Install Execution Stage.

c) For both instances of the custom action add MY_VISTA_FOLDER_PROP property (for example) and associate it with the folder you need from the Edit Property Folder Association Dialog.

d) select “Advanced execution scenarios...” link button and set the scheduling option for the custom action to “Skip action in Install Execution Stage if executed in Dialogs Stage”.

e) In the Files and Folders page create a new property based folder, specifying the property from step c. You can now add content to this property based folder.

Start image slideshow

This custom action will start an image slideshow configured in the Slideshow page. Please note that the custom action requires at least an Enterprise or Architect project when using a custom trigger for the start option. Also, excepting the "Expression" field in the " Execution Condition" section, it is recommended to keep the default settings of the custom action.

Stop image slideshow

This custom action will stop an image slideshow configured in the Slideshow page. Please note that the custom action requires at least an Enterprise or Architect project when using a custom trigger for the stop option. Also, excepting the "Expression" field in the " Execution Condition" section, it is recommended to keep the default settings of the custom action.

Check TCP port

This custom action allows you to check if a TCP port is free. This custom action runs only on Windows 2000 or greater systems. For more details see the Check TCP port How-To.

Properties

• Host name or IP (Optional) - the local computer's host name or IP (Optional). Equivalent to setting AI_BIND_TCP_HOST property. If not set, it will be assigned with localhost default value.
• TCP port - TCP port to check. Equivalent to setting AI_BIND_TCP_PORT.

The custom action returns the check's result in the Windows Installer property AI_PORT_TEST_RES. The property can have the following values:

• FreePort - the port is free
• UsedPort - the port is used
• SockError - an error occurred

Get a free TCP port

This custom action allows you to get a free TCP port. This custom action runs only on Windows 2000 or greater systems. For more details see the Get a free TCP port How-To.

Properties

• Host name or IP (Optional) - the local computer's host name or IP (Optional). Equivalent to setting AI_BIND_TCP_HOST property. If not set, it will be assigned with localhost default value.
• TCP port - this field must be set to the port from which the search is started and it will also contain the free port returned by the search. Equivalent to setting AI_SEARCH_TCP_PORT.

If the port is free then the AI_SEARCH_TCP_PORT property will contain the port number of the free port and AI_PORT_TEST_RES will be set to FreePort. In case of an error, AI_PORT_TEST_RES will be set to SockError.

Preserve Install Type of the old version

This predefined custom action allows your package to use the same installation type as the version it upgrades through the automated upgrade feature. For example, your package will be installed per-user if it upgrades a per-user installation or it will be installed per-machine if it upgrades a per-machine installation.

Uninstall previous versions

With this custom action you can uninstall the older versions of your product, no matter what Installation Type they use (per-user or per-machine). It can be used as a custom action without sequence or under Wizard Dialogs Stage.

Add network location

This predefined custom action allows you to automatically add a new shortcut to a shared network resource on the machine that runs the installer. In case the network location shortcut was previously created on the target machine, the custom action will overwrite it.

Properties

• Name - specify the name under which the network path will be displayed (e.g. "My Location")
• Path - specifies the network path for which the shortcut will be created (e.g. "\\Server\Shared")

Remove network location

This predefined custom action allows you to automatically delete an existent network location shortcut from the target machine. In case the network location shortcut doesn't exist this custom action will not make any modifications to the system.

Properties

• Name - specify the name of the network location shortcut that will be deleted.

Get free disk space

This custom action retrieves the available disk space for a specific drive.

The target drive can be set in the Disk Path field from the custom action properties pane. Here are some examples of valid drives:

C

D:

E:\

[WindowsVolume]

The available disk size in MegaBytes is saved in the AI_FREE_DISK_SPACE installer property. You can use this property during installation, for example to compare it with a minimum disk size in a custom launch condition.

Play audio file

This custom action allows you to play an audio file during the installation. For more details please see the Play an Audio file How-To.

Install MSI relative to package

This custom action installs a MSI file. This operation is also called a nested installation. The location of the MSI file must be relative to the location of the main MSI (in the same folder or one of its sub-folders).

Example:

Your package is named Main.msi and is located in "c:\packages\test" and your nested install package is named Nested.msi. The Nested.msi can be located:

• in the same folder - "c:\packages\test"
• in a sub-folder of this folder - "c:\packages\test\subfolder\nested.msi"

Properties

• MSI File - the location of the MSI file
• Command line - command line parameters to be passed to the MSI file

Configure MSI with specific Product Code

This custom action is used to modify or remove a product installed by the current package. It may also be used to install a product that has been previously installed as advertised. The MSI is identified by it's product code.

Since this type of custom action is usually used for uninstalling a product previously installed by the current package, Advanced Installer will automatically add a custom action for this purpose every time you add a nested installation.

Properties

• MSI File - the product code of the MSI. You may enter it directly or you can use the [ ... ] to select the MSI and let Advanced Installer to automatically extract it.
• Command line - command line parameters to be passed to the MSI.

Collect features without CAB

Its role is to append the IDs of all features with no associated .CAB files to the AI_DISABLED_FEATURES property. By using "One CAB archive per feature" option, associated implies:

• each feature ID to match its .CAB file name
• every .CAB file to be in the same location as the .MSI

This custom action has the following default settings which shouldn't be changed:

• scheduled after LaunchConditions standard action
• shared in both stages with "Advanced execution scenarios..." -> "Skip action in Install Execution Stage if executed in Dialogs Stage" option enabled

Disable Features

This custom action gets all features (by ID) from AI_DISABLED_FEATURES property and sets their InstallLevel to zero. This means that the features will not be visible in selection tree and they will not be installed.

It has the following default settings which shouldn't be changed:

• scheduled before CostInitialize standard action
• shared in both stages with "Advanced execution scenarios..." -> "Skip action in Install Execution Stage if executed in Dialogs Stage" option enabled

Properties

• Features - the comma separated list of features to be disabled. Choose the available features by pressing the [ Edit ] button.

Update Features Install States

This custom action updates all features' states by re-evaluating their conditions. A common usage scenario is to condition the features using public properties changed by the installing user when interacting with the package UI.