Calling a PowerShell Custom Action

InstallShield 2020

Project:This information applies to the following project types:

Basic MSI
InstallScript MSI
Transform

Windows PowerShell is a .NET Framework–based command-line shell and script language that enables system administrators to automate system configuration tasks. InstallShield lets you include in your installations custom actions that run PowerShell scripts (.ps1). You may want to add this type of custom action to a project to perform system configuration tasks at installation run time. Note that PowerShell actions require PowerShell 2.0 or later on target systems.

Adding a PowerShell Custom Action to Your Project

To add a PowerShell custom action to your project:

1. In the View List under Behavior and Logic, click Custom Actions and Sequences.
2. Right-click the Custom Actions explorer, point to New PowerShell, and click one of the following commands:
Stored in Binary table—To have your code base stored in the Binary table, select this command. This location is useful if you do not want the file to be installed on the target system.
Installed with product—To call code from a script file that is going to be installed on the target system, select this command.

InstallShield adds a PowerShell custom action with a default name.

3. Enter a new name, or right-click it later and click Rename to assign it a new name. Use a name that helps you distinguish this custom action from other actions in your project.
4. In the PowerShell Script File Name setting, select the PowerShell script file (.ps1) in the list of files that are stored in the Binary table or that are included in your project. If the location that you specified is stored in the Binary table, you can click this ellipsis button (...) in this setting to browse to the file.
5. Configure the action’s other settings as needed.

Once you have added the custom action to your project, schedule it as needed. For more information, see Inserting Actions into Sequences.

Run-Time Requirements for a PowerShell Custom Action

PowerShell is installed on only some operating systems by default. If an installation launches a PowerShell custom action but PowerShell is not installed, the custom action fails.

To check that PowerShell is installed on a target system, you can add the predefined system search for PowerShell to your project, and configure your PowerShell custom action to run only if the system search determines that PowerShell is installed. You can also use this system search to determine which version of PowerShell is installed, and you can include a condition for the custom action that triggers its launching only on appropriate target systems. By default, the predefined system search for PowerShell sets the value of the POWERSHELLVERSION property to the version of PowerShell.

You can use the Windows Installer property IS_CLR_VERSION to identify a semicolon-delimited list of .NET Framework versions that the custom action should attempt to load to run your PowerShell script.

To learn more about the POWERSHELLVERSION and IS_CLR_VERSION properties, see Windows Installer Property Reference.

Interacting with the Running Basic MSI or InstallScript MSI Installation

Several cmdlets that let you interact with the running Basic MSI or InstallScript MSI installation are available:

Cmdlets that Interact with a Running Basic MSI or InstallScript MSI Installation

Cmdlet

Description

get-property -name [Property Name]

This cmdlet gets the value of a Windows Installer property. The Name parameter is a positional parameter.

The following sample code gets the value of the property called MYPROPERTY:

$Value = get-property -name MYPROPERTY

set-property -name [Property Name] -value [value]

This cmdlet sets the value of a Windows Installer property. The Name and Value parameters are positional parameters.

The following sample code uses the value of the MYPROPERTY property to set the value of a second property called NEWPROPERTY:

$Value = get-property -name MYPROPERTY

set-property -name NEWPROPERTY -value $Value

format-properties -Value [format string]

This cmdlet expands the value of a formatted expression. The Value parameter is a positional parameter.

The following sample code formats a string that contains a Windows Installer property called NEWPROPERTY. The property name and its surrounding square brackets are replaced by the value of the property at run time.

$myFormat = format-properties -Value "This is a text string with [NEWPROPERTY] embedded."

trace-info -LogMessage [log string]

This cmdlet writes any information that is needed to the Windows Installer log, making it available for debugging or other information purposes. The LogMessage parameter is a positional parameter.

The following sample code writes the string, I am a PowerShell custom action to the Windows Installer log.

trace-info -LogMessage “I am a PowerShell custom action”

To indicate that your script has succeeded, ensure that it returns 0. For example, you may want to end your script with the following:

exit(0)

See Also