Prerequisite

The Integration Pack for Windows PowerShell 2 (PowerShell IP) is developed using Opalis Quick Integration Kit (QIK).  The prerequisite for using this IP includes:

  • .NET Framework 3.5.
  • Windows PowerShell 2.

    Installation

  • Download the latest version of the IP from http://orchestrator.codeplex.com/releases/view/72744
  • Register the IP using the Deployment Manager.
  • Deploy the IP on to the Runbook Server and the Designer Client.

    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.

    Name Mandatory Description
    64-bit Runspace (local) Yes Whether 32bit or 64-bit of the runspace will be opened.
    Runspace Name Yes The name of the runspace.  Note that the name needs to be unique and it is case sensitive, but there is no restriction on what char can be used or the length of the name.
    User name No User name when connecting to a remote machine via WinRM.
    Password No Password for above user.
    Domain No Domain of the user when connecting to remote machine.
    Host Name No Host name of the remote machine.
    Port Number No Port number for the WinRM connection
    Connection Use SSL No  
    Authentication No Mechanism that is used to authenticate the user’s credential.

    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.

    Name Mandatory? Description
    Runspace Name Yes Which runspace needs to be closed.

    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:

    Name Mandatory Description
    Runspace Name Yes  
    Script Yes PowerShell script.  It can be one line or multiple lines.

    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:

    Name Mandatory Description
    Runspace Name Yes  
    User name Yes  
    Password Yes  
    Variable (e.g. $var) Yes Name of variable with $ prefix
  • Last edited Sep 3, 2011 at 1:24 AM by Yao, version 4

    Comments

    No comments yet.