Working with a PowerShell Script for an Action in a Suite/Advanced UI Installation

InstallShield 2016

Project • This information applies to Suite/Advanced UI projects.

Edition • The Advanced UI project type is available in the Professional edition of InstallShield. The Suite/Advanced UI project type is available in the Premier edition of InstallShield. For information about the differences between these two project types, see Advanced UI Projects vs. Suite/Advanced UI Projects.

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 Suite/Advanced UI installations actions that run PowerShell scripts (.ps1). You may want to add this type of 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 Action

To add an action that runs a PowerShell script in a Suite/Advanced UI installation:

1. In the View List under Behavior and Logic, click Events.
2. Right-click the Actions explorer and then click New PowerShell. InstallShield adds a PowerShell action to the Actions explorer.
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 action from other actions in your project.
4. Configure the action’s settings as needed.

If you select a PowerShell action in the Actions explorer or the Events explorer, InstallShield displays a PowerShell Script tab on the right; you can use this tab to edit your script.

Once you have added the action to your project, schedule it as needed. For more information, see Scheduling a Suite/Advanced UI Action.

Run-Time Requirements for a PowerShell Action

You can use the Suite/Advanced UI property IS_CLR_VERSION to identify a semicolon-delimited list of .NET Framework versions that the action should attempt to load to run your PowerShell script. To learn more about the IS_CLR_VERSION property, see Advanced UI and Suite/Advanced UI Property Reference.

Interacting with the Running Suite/Advanced UI Installation

Several cmdlets that let you interact with the running Suite/Advanced UI installation are available:

Cmdlets that Interact with a Running Suite/Advanced UI Installation

Cmdlet

Description

get-suiteproperty -name [Property Name]

This cmdlet gets the value of a Suite/Advanced UI property. The Name parameter is a positional parameter.

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

$Value = get-suiteproperty -name MYPROPERTY

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

This cmdlet sets the value of a Suite/Advanced UI property.

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

$Value = get-suiteproperty -name MYPROPERTY

set-suiteproperty -name NEWPROPERTY -value $Value

format-suiteproperties -Value [format string]

This cmdlet expands the value of a formatted expression. The Name and Value parameters are positional parameters.

The following sample code resolves a string that contains a Suite/Advanced UI property called NEWPROPERTY. The property name and its surrounding square brackets are replaced by the value of the property at run time.

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

resolve-suitestring -StringId [string ID]

This cmdlet resolves a Suite/Advanced UI string identifier with its corresponding string value in the currently selected UI language. If no such string identifier exists, the returned string is empty. The StringId parameter is a positional parameter.

The following sample code resolves a string identifier called IDS_MY_MESSAGE:

$StringValue = resolve-suitestring -StringId IDS_MY_MESSAGE

trace-suiteinfo -LogMessage [log string]

This cmdlet writes any information that is needed to the Suite/Advanced UI debug log, making it available for debugging or other information purposes. The LogMessage parameter is a positional parameter.

The following sample code resolves a string identifier called IDS_MY_MESSAGE and then writes its value to the Suite/Advanced UI debug log.

$StringValue = resolve-suitestring -StringId IDS_MY_MESSAGE

trace-suiteinfo -LogMessage $StringValue

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)

Once you have added a PowerShell action in the Events view of your project, you can select it in the Actions explorer or the Events explorer, and use the PowerShell Script tab that InstallShield displays on the right to edit your script.

See Also