Installation

Configuration

The configuration for the IP can be access from PowerShell in the Options menu of the Designer Client.  The Type of the configuration is “PowerShell Settings” which defines the parameters used to host the runspace and run the script.  For instance, if the service account for the Runbook Server is REDMOND\scxsvc but we want to use REDMOND\zhyao to run the script, we will enter “REDMOND”, “zhyao” and “(password here)” in the settings.  Note that the code uses Win32 API LogonUser to log the user on to the local computer and the type of logon operation is LOGON32_LOGON_INTERACTIVE.  Therefore, the user right assignment needs to be done properly and this does not work for users not in untrusted domains.

Activities

Open Runspace

Prior to running a PowerShell script, a runspace must be created.  In this IP, the PowerShell runspace is hosted in an independent process named PowerShellInvoke-x86.exe (for 32-bit) or PowerShellInvoke-x64.exe.  The type of the runspace can be local 32-bit, or local 64-bit (for 64-bit OS), or remote via WinRM.  The IP and the runspace host process are communicated using WCF service through secure named pipe.

The following table lists all input parameters.

The runspace can be closed after finishing executing the PowerShell scripts.  If it is not closed, the runspace will be preserved and can be opened again even in a new Runbook instance.  When an existing runspace is openned, only mandatory parameters will be checked.

Close Runspace

If the runspace is not in use, it can be closed to claim the system resource.  If the host process has no runspace, it is considered as idle.  After being idle for 60 seconds, the host process will be automatically terminated.  Next time when a new runspace is created, the host process will be started again.

There is only one parameter.

Run Script

This activity is to execute the script in the specified runspace, and publish the properties and string representation of the last PSObject after the execution.

Example 1: we have a

script to list all VM’s on a VMM server:

Add-PSSnapin Microsoft.SystemCenter.VirtualMachineManager
Get-VMMServer zyv
Get-VM

Only the value of the last statement (list of VM as well as their properties) will be returned.

Example 2: a simple script to calculate the sum of integer:

1+2

The result will be returned as a string representation with the name of “.ToString”.

Many scripts and Cmdlets have huge amount of properties. Sometimes a large list of PSObject is generated during the execution. In this case, put them in a variable and use “Select-Object” to choose a subset of data to be returned. The data being transferred back will be serialized to XML blob, if the size is greater than 128 MB (can be adjusted in the source code), an exception will be thrown and the activity will fail.

If some data are stored in variables, they can be returned simply by using their names. For instance:

# some heavy computing
$vms = Get-VM
# more things
...
$vms

Because the runspace is persisted across activity and runbook instance, one can define some variables in one “Run Script” activity and use them in another “Run Script” activity.

Here is the list of parameters:

Set Credential

This activity takes a user name / password pair and creates a variable with the specified name, the created PsCredential object can be referenced by other “Run Script” object.  It is possible to use “Run Script” to create such object, in fact the underlying code is almost the same, but this activity will hide the password instead of exposing it as clear text.

Here is the list of parameters: