Open topic with navigation
Calling a PowerShell Custom Action
InstallShield 2014
Project: This information applies to the following project types:
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.
Target System Requirements for Running PowerShell Scripts
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.
The PowerShell execution policy, which determines whether PowerShell scripts can be run on a target system, is set to restricted by default. This default execution policy does not permit PowerShell scripts to be run. If an installation launches a PowerShell custom action but the execution policy does not permit scripts to be run, the PowerShell custom action fails.
If you want your installation to override the target system’s execution policy with an appropriate one for your installation’s PowerShell custom actions, you can set the Windows Installer property IS_PS_EXECUTIONPOLICY equal to the name of the appropriate execution policy. Setting this property affects how the PowerShell custom actions are run in your installation; however, it does not alter the policy of the target system. Thus, any PowerShell scripts that are run subsequently outside of your installation, or during other subsequent installations, are not affected by use of the IS_PS_EXECUTIONPOLICY property.
Some of the execution policies require that the PowerShell script (.ps1) be digitally signed. InstallShield does not include support for digitally signing PowerShell scripts.
Tip: You can sign your PowerShell scripts from the PowerShell command prompt. To learn more, enter the following command at the PowerShell command prompt: Get-Help About_Signing
Adding a PowerShell Custom Action to Your Project
The following procedure describes how to include and configure a PowerShell custom action in your project. The procedure includes adding the PowerShell system search to your project and defining the IS_PS_EXECUTIONPOLICY property.
To add a PowerShell custom action to your project:
|
1.
|
Add to your project the predefined PowerShell system search that checks to ensure that PowerShell is installed: |
|
a.
|
In the View List under Behavior and Logic, click System Search. |
|
b.
|
Right-click the grid in this view and then click Add Predefined Search. The Add Predefined Search dialog box opens. |
|
c.
|
Select the PowerShell search and then click OK. |
If PowerShell is installed on a target system, the PowerShell system search sets the POWERSHELLVERSION property.
|
2.
|
To indicate which execution policy you want your installation to use for your PowerShell custom actions, define the IS_PS_EXECUTIONPOLICY property: |
|
a.
|
In the View List under Behavior and Logic, click Property Manager. |
|
b.
|
Click the New Property button. InstallShield adds a new row at the bottom of the view. |
|
c.
|
In the Name column, enter the following: |
IS_PS_EXECUTIONPOLICY
|
d.
|
In the Value column, enter the name of the execution policy that you want to use to run PowerShell custom actions in your installation. Available options are: |
|
•
|
AllSigned—This policy allows only digitally signed PowerShell scripts to be run. |
|
•
|
Bypass—This policy allows all PowerShell scripts to be run, regardless of whether they are signed. No warnings or prompts are displayed. |
|
•
|
RemoteSigned—This policy allows any local PowerShell scripts to be run. PowerShell custom actions that are downloaded from the Internet must be digitally signed in order to be run. |
|
•
|
Unrestricted—This policy runs all PowerShell scripts. If your installation runs an unsigned PowerShell script that was downloaded from the Internet, the end user is prompted for permission before the custom action is run. |
The default execution policy is Restricted. Although you can set IS_PS_EXECUTIONPOLICY equal to Restricted, doing so will not allow PowerShell custom actions to be run.
|
3.
|
Add a PowerShell custom action to your project and configure its settings: |
|
a.
|
In the View List under Behavior and Logic, click Custom Actions and Sequences. |
|
b.
|
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.
|
c.
|
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. |
|
d.
|
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. |
|
e.
|
In the Sequence area, schedule the action for the appropriate sequence. In that sequence’s Condition setting, enter the following conditional statement to ensure that the action runs only if the system search detects that PowerShell is installed: |
POWERSHELLVERSION
Tip: If you want to ensure that the action runs only if the system search detects that specific version of PowerShell is installed, use the appropriate operator with the property and the value that you want to check. To learn more about building conditional statements, see Building Conditional Statements.
|
f.
|
Configure the action’s other settings as needed. |
Tip: If PowerShell is not installed on a target system (that is, if the POWERSHELLVERSION property is not set, the installation skips the PowerShell custom action. If you want to prevent the entire installation from running if PowerShell is not installed, you can use the Installation Requirements page of the Project Assistant (instead of the System Search view) to add the PowerShell system search to your project. If you do that, InstallShield uses the POWERSHELLVERSION property in a launch condition for the installation.
See Also
Using the Custom Action Wizard