Types Of Custom Actions

Below is a description of the custom actions used in Advanced Installer.

1. Attached Custom Action
2. Installed Custom Action
3. Predefined Custom Actions
4. Script Inline
5. Error Message
6. Property Source
7. Property Set with Formatted
8. Directory Set with Formatted
9. EXE with Working Dir
10. MSI Database Relative to Package
11. MSI Database with Product Code
12. Installed .Net Assembly

Attached Custom Action

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.

Description of the fields:

• Source Path - the path to the custom action file. You can use the [ ... ] button to change the custom action's file.
• Source 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 Name / 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.

Installed Custom Action

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.

Description of the fields:

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

Predefined Custom Actions

Launch File or Open URL

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 and that page will be opened in the default browser on the target computer. This action is performed by a program that comes with Advanced Installer, called viewer.exe.

Description of fields:

• Source Path - this contains the file that executes the action, in this case viewer.exe. You don't need to change this field.
• Source Type - this is the type of the file, in this case an 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.

You can specify command line parameters that will be passed to the launched file.

Command Line Examples:

http://www.example.com

or

[#filekey] command line parameters

Usually, a file (or folder) path will contain spaces so you should include the file (folder) path within quotes, as follows:

"[#filekey]" command line parameters

Resolve Known Folders

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).

On an earlier Windows versions this predefined custom action will not be able to resolve any Known Folder, so you should condition the installation of all components in that folder, based on the OS version. (eg. VersionNT >= 600)

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

1. In the Install Parameters page, create a new public property (only upper-case letters in its name), for instance MY_VISTA_FOLDER_PROP.

2. Set the value of the property to a known folder GUID. The complete list of known folder constants can be found here. For instance, if the per-user folder FOLDERID_SavedGames ("%USERPROFILE%\Saved Games") is required, you will set the value of the property to the following GUID:

{4C5C32FF-BB9D-43b0-B5B4-2D72E54EAAA4}

3. In the Files and Folders page create a new property based folder, specifying the property you have defined above. You can now add content to this property based folder.

4. The Resolve Known Folders predefined custom action can be added under any standard action before CostFinalize. We shall sequence it after AppSearch, for instance.

5. In the Custom Actions page, make sure that the AppSearch standard action is visible in the tree control under both InstallUISequence and InstallExecuteSequence. If it is not, use the "Show Standard Action" toolbar button or context-menu entry to make it visible.

6. Add the predefined Resolve Known Folders custom action under "InstallUISequence -> AppSearch".

7. Keeping the SHIFT key pressed, drap-and-drop the custom action in tree control, under "InstallExecuteSequence -> AppSearch". This will create a copy of the action in the InstallExecuteSequence.

8. For both instances of the custom action set the "Action Data" field to the name of the property you have defined in step 1 above (MY_VISTA_FOLDER_PROP in the example, NOT the formatted value [MY_VISTA_FOLDER_PROP]).

9. Set the Scheduling Option for the custom action to " Execute only once if present in both sequence tables".

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.

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.

Browse SQL servers on the network

You can use this UI custom action when you want to let the installing user pick an SQL Server to connect to, from the available Microsoft SQL Servers on the network. Advanced Installer can automatically browse the network to discover any SQL Server (instances) online and populate input parameters for an SQL ODBC Connection from within the "SQLConnectionDlg" dialog. For details please see: Browse for SQL Servers.

Browse For File

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

Predefined custom actions for working with ComboBox controls

Populate ComboBox, 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.

Script Inline

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

Description of the fields:

• 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.

Usually this script is made up of a single line. If it is longer and needs to be placed on several lines just edit the "Script Text" field with the body of the script and use the ":" character (without the quotes) to mark the place where a line ends and another begins.

A custom action that 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 "Script Inline" custom action written in VBScript:

MsgBox Session.Property("APPDIR")

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

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 has happened.

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

Description of the fields

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.

Property Source

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.

Description of the fields:

• Property Name - the name of the property that contains the path to the executable file. The name of the property is not placed between brackets ( ] ).
• Source 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.

Property Set with Formatted

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

Description of the fields:

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

To affect a property used in a condition on a component or feature, the custom action must come before the CostFinalize action in the action sequence.

Directory Set with Formatted

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

Description of the fields

• Directory - the folder who's path is to be modified. Use the [ ... ] button to change it.
• Formatted text - 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.

The formatted text must be expanded into a valid absolute path, in order for the custom action to work.

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".

This custom action can be scheduled only after the CostFinalize action.

EXE with Working Dir

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

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

Description of the fields:

• Working Dir - the working directory for the executable file. Use the [ ... ] to change it.
• Path to EXE - 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.

MSI Database 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 it's subfolders).

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 subfolder of this folder - "c:\packages\test\subfolder\nested.msi"

Description of the fields

• Source Path - the location of the MSI file
• Properties - properties representing settings for the installation process. Usually they will specify some features that are to be installed.

This type of custom action has been deprecated and it is not recommended to use it. If your package requires another application to be installed you can use Software Prerequisites or Merge Modules (for creating a part of the installation package).

MSI Database with 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.

You cannot use this type of custom action for products previously installed by any other means.

Description of the fields

• Product Code - 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.
• Properties - properties representing settings for the installation process. For example, to remove a product set the REMOVE property to the value ALL (REMOVE=ALL).

This type of custom action has been deprecated and it is not recommended to use it.

Installed .Net Assembly

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.

Description of the fields:

• Action Data - represents the parameters received by the assembly and can be edited using the Edit .Net Custom Action page.

When you create a custom action under Install, Uninstall, Rollback or Commit tree items the Action parameter defaults to the correspondent method. You can change the Action parameter if you want other method to be called.