Custom Actions List

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 an 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 an MSI package to an installation.
• Action Data - represents the value of the CustomActionData property. This property can be retrieved as a regular property inside Deferred custom actions and it is available only for DLL, JScript and VBScript custom actions. A common usage scenario is to use the CustomActionData property in Rollback Custom Actions since they are also deferred.

Deferred custom actions can receive information about the installation process, mostly only embedded in the CustomActionData property. However, this type of custom actions do not have access to installer properties.

Properties

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

Properties

• File To Launch - field should contain the full path of the file you want to launch. This field is of Formatted Type and thus it can include references to files, folders, and properties. For example, if the file is called "MyBatchFile.bat" and it is added as a regular file, then you can add a reference to it in the "File to launch" field like this:

[#MyBatchFile.bat]

For a temporary file, the "File to launch" field would look like this:

[&MyBatchFile.bat]

• Command Line - you can specify command line parameters that will be passed to the target file.
• Working Directory - set a custom working directory for the target file.
• Hide program's window - the main window or console of the launched program will not be visible.
• 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, 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 a 64-bit process.

If the package is running with Administrator privileges, the Launch File custom action does not inherit the elevated privileges from the package. If you need to run your custom action with elevated privileges, you need to check "Run as Administrator" option for the custom action in question.

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.

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.

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.

When you create a custom action for Install, Uninstall, Rollback or Commit you must also change the Action parameter to the correspondent method.

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

You can't remove predefined parameters.

Debug the method of the .NET Installer Class Action

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

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.

To affect a property used in a condition on a component or feature, the custom action must come before the "Paths Resolution" action group from "Install Execution Stage".

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.

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 "Paths Resolution" action group from "Install Execution Stage".

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.

You can change the order of arguments using the [ Move Up ] and [ Move Down ] context menu options.

Properties

Code example

          {
  public class MyCustomActionsClass
  {
    public static int MyFunctionName(string MyCustomActionData)
    {
    }
  }
        

Properties

• 64-bit script - specify whether this is a 64-bit script.
• Action Data - represents the value of the CustomActionData property. This property can be retrieved as a regular property inside Deferred custom actions and it is available only for DLL, JScript and VBScript custom actions. A common usage scenario is to use the CustomActionData property in Rollback Custom Actions, since they are also deferred.

Deferred custom actions can receive information about the installation process, mostly only embedded in the CustomActionData property. However, this type of custom actions do not have access to installer properties.

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

Any return value of the script functions is interpreted as success by this custom action type.

"Wait for custom action to finish before proceeding" option from "Execution Options" field is mandatory for script custom actions and cannot be disabled.

Properties

• Script parameters - this field contains the list of parameters passed to the script. This field is of Formatted Type, so you can pass in the script results from other custom actions or values entered by the user.
• 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.
• Test script - use the button to check the functionality of your PowerShell script by running it and returning a TXT file that contains the Return Code and the Script Output.
• Powershell Script Options - click on this hyperlink to open Powershell Script Options Dialog. This will allow you to configure script options like used platform, digital signature setting or preferred launch folder.

Getting a property value into a script (for immediate custom actions)

To get a property simply include a line with the following syntax in your script:

$propValue = AI_GetMsiProperty YOUR_PROP

Where YOUR_PROP is the property name.

Getting a property value into a script (for deferred custom actions)

This can be done through the "Script Parameters" field as follows:

-firstPsParam [FIRST_MSI_PROP] -secondPsParam [SECOND_MSI_PROP]

FIRST_MSI_PROP and SECOND_MSI_PROP are MSI installer public properties. Their values will be assigned to the $firstPsParam and $secondPsParam parameters in the PowerShell script.
You need to update the Param() block of the script, which must be on the first line, as follows:

Param($firstPsParam, $secondPsParam)
# your script code here

Setting a property value temporarily from script for testing purposes

Use the "Test script" button and the "-testvalue" tag to change the value of a property temporarily in your script.

AI_GetMsiProperty YOUR_PROP -testvalue <VALUE>

Setting a property value from a script (for immediate custom actions)

To set a property simply include a line with the following syntax in your script:

AI_SetMsiProperty YOUR_PROP <VALUE> 

Where YOUR_PROP is the property and <VALUE> is the value assigned to it.

Setting MSI installer property values works only when the PowerShell script has "Immediate" execution time. It does not work if the execution time is set to "When the system is being modified(deferred)". Also, the properties will be updated after the powerShell script runs.

"Wait for custom action to finish before proceeding" option from "Execution Options" field is mandatory for script custom actions and cannot be disabled before proceeding"

When there exists a GPO (Group Policy Object) restricting the execution of scripts, the digital certificate must be present in the Trusted Publishers in order for the script execution to succeed.

When passed as a function parameter the, AI_GetMsiProperty statement must be enclosed between a set of parentheses, for instance:
myFunction(parameter1, (AI_GetMsiProperty PROPERTY_NAME), parameter3)

• Script from disk - specify the file path of the PowerShell script that will be available on the target machine hard drive during the installation when the custom action runs. This field has Formatted Type so you can insert references to files, folders and properties.
  

This path can point to an installed file from the Files and Folders Page - Installer Project if the custom action:
- is scheduled with sequence after InstallFiles standard action from Add Resources action group
- has execution time set to When the system is being modified (deferred)

• Attached script - use the [ ... ] button on the right to select a PowerShell script file from your hard drive. This file will be attached to the installation so it can be used by the custom action. It won't be installed on the target machine.
• Test script - use the button to check the functionality of your PowerShell script by running it and returning a TXT file that contains the Return Code and the Script Output.
• Powershell Script Options - click on this hyperlink to open Powershell Script Options Dialog. This will allow you to configure script options like used platform, digital signature setting or preferred launch folder.

To get/set MSI properties on Immediate execution time, please use the approach from Run Inline PowerShell Script custom action.

It is not possible to get/set properties on this custom action type on Deferred execution time

"Wait for custom action to finish before proceeding" option from "Execution Options" field is mandatory for script custom actions and cannot be disabled.

Certificate

• Thumbprint property - specify the thumbprint property

Store

• Location - specify if the certificate should be placed under Current User store or under Local Machine store.
• Name - specify the name of the list to include the certificate, for example, TrustedPublisher

Properties

Error message - the message that will be displayed to the user. This field has Formatted Type so you can use the [ Edit ] button to insert reference to files, folders and properties. Localize it by referencing properties as described in How to localize the value of a property based on the OS language? article.

Properties

• Title - the message box's title. This field is of Formatted Type and can be edited using Smart Edit Control.
  Please note that if your title contains a special character like the pipe "|" character, it must be escaped using "\" character so, for example, instead of My|Value, you should enter My\|Value.
• Message - this is the message that will appear in the message box. This field is of Formatted Type and can be edited using Smart Edit Control.

Both Title and Message fields can be localized by referencing properties as described in How to localize the value of a property based on the OS language? article.

• 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

Properties

• Domain - this field needs to be set to the target user domain name. (DOMAIN_NAME property)

Leave the "Domain" field empty when checking a local user account.

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

Name and Domain are associated with the "User Name" and "Domain" edit controls on "LogonInformationDlg". After adding this dialog you can simply add the custom action as an Execute custom action published control event on its [ Next ] button.

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.

Properties

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 0.0.0.0 default value.
• TCP port - TCP port to check. Equivalent to setting AI_BIND_TCP_PORT.

This custom action can only be used to check local machine TCP port connections.

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

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

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

Both properties must be set in order to successfully add the network location

Properties

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

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

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

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.

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

Properties

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

Input

• Text - This field is of formatted type and aside text you can also reference properties that will be resolved to their values at install time.

Operation

• Removal
  • What to remove - configure what will be removed from the input.
    • Trailing Backslashes - removes backslashes from the end of the text.
    • Leading Whitespaces - removes whitespaces from the beginning of the text.
    • Trailing Whitespaces - removes whitespaces from the end of the text.
    • All Whitespaces - removes all whitespaces from the text.
    • Custom - removes all characters selected by the regular expression defined in Removal regex field.
  • Removal regex - shows the regular expression of the predefined criteria or in case of Custom criteria you can define your own removal pattern.
• Insertion
  • Where to insert at - configure where to insert the text.
    • Beginning
    • End
    • Custom - specify the exact insertion position.
  • Text to insert - this text will be inserted in the input text based on the selected criteria.
  • Position - when the Custom criteria is selected, the text will be inserted in this position.
• Replacement
  • What to replace - configure what to replace in the input text.
    • Backslashes with slashes
    • Slashes with backslashes
    • Custom - perform the replace based on a matching regular expression.
  • Matching regex - shows the regular expression of the predefined criteria or you can define your own search pattern when the Custom criteria is selected.
  • Formatting regex - this string will replace the Matching regex selection when the Custom criteria is selected.
  • Convert - select the conversion criteria.
    • To Lower Case - replaces all upper case letters with lower case letters.
    • To Upper Case - replaces all lower case letters with upper case letters.
• Extraction
  • What to extract - select what to extract from the input text.
    • Substring - extracts a substring with the specified length from the input text starting from the specified position.
  • Position - the start position for Substring criteria.
  • Length - when the Substring criteria is selected, this number will determine how many characters will be extracted from the input text starting from the specified position.
  • Tokenize using - configure a delimiter to tokenize the output properties.
    • Delimiter - extracts values from the input text established by the specified string delimiter to several(tokenized) output properties.
    • Custom delimiter - extracts values from the input text established by the specified regex pattern to several(tokenized) output properties.
  • Delimiter - this string will establish what values will be extracted from the input text. See the Output section for more details.
  • Extraction regex - the regex pattern that will establish what values from the input text will be extracted.
• Matching
  • What to match - matches the input text against the text or regex. The result(0 or 1) will be saved in the output property.
    • Text - specify the matching text. The corresponding field is of formatted type and aside text, you can also reference properties that will be resolved to their values at install time.
    • Regex - if the regex pattern matches the input text entirely, the output property will be set to 1.

Output

• Overwrite - the output processed data will overwrite the value of the input property.
• Set new property - the property specified in the Property name field will be set to the output formatted data. Root property field is explained in the note below.

When using the Extraction operation with Delimiter or Custom delimiter, the output properties will be tokenized based on the Root property (e.g. ROOT_PROPERTY_1, ROOT_PROPERTY_2, etc). AI_CUSTOM_EXTRACTION_PROP_COUNT Advanced Installer property is set to how many properties are output after extraction.

When using the Matching operation the output property will be set to 1 if a match is found or 0 otherwise.

Properties

• MSIX Path - specifies the path to the MSIX.
• External location - choose an external location for the MSIX.
• Apply to all users - Provision the MSIX package per machine (to All Users) on an Windows machine. Digital Signature and Run as Admin option are required when using this flag.
  Please see this article for more information regarding per machine MSIX packages.

Properties

• Name - Name of the company and application, specified in the certificate used to sign the MSIX (e.g. YourCompany.YourApplication).
• Version - The version of your application.
• Architecture - Architecture required by the platform to run the MSIX.
• Publisher ID - The Publisher ID, specified in the certificate used to sign the MSIX(e.g. CN=TestCert, O=MyCompany, L=MyCity, S=MyState).
• Apply to all users - Remove the MSIX package per machine (All Users) on an Windows machine.Digital Signature and Run as Admin option are required when using this flag.
  Please see this article for more information regarding per machine MSIX packages.

Certificate

• Path - specifies the path to the certificate.

Store

• Location - the system area where to install the certificate.
• Name - the name of the certificate store.

Can only install certificates that have the CER extension.

Certificate

• Thumbprint - the thumbprint of the digital certificate; to select and extract it from the file use the [ ... ] button.

Store

• Location - the system area where the certificate is kept.
• Name - the name of the certificate store.