Using the PowerShell adapter for persistent connections

PowerShell adapter supports session-based command execution or persistent connection based execution using the Enter-PSSession CmdLet. While you can use the Enter-PSSession CmdLet to start an interactive session on a local or remote computer, this command is not useful to identify sessions for monitoring. Starting 20.19.01, the PowerShell adapter now supports the New-PSSession cmedlet, which enables users to create sessions on a local or remote computer and use the Invoke-Command cmdlet to run commands. 

There are no new elements added to the adapter configuration and the configuration remains unchanged. 

The Adapter-request-and-response-for-the-PowerShell-adapter now supports the following capabilities:

• Specify a connection name
• Named connections
• Connection name is used to create session key, which will be used in all Invoke-Command calls for that session

Elements for new persistent connection

The following new elements are added to the PowerShell adapter request to open a remote target session:

• new-ps-session: If true, the New-PSSession cmdlet is used for authentication. If false, the Enter-PSSession cmdlet is used for authentication.

• ps-session-options: 

  Sample ps-sessions-options XML

  <ps-session-options>
     <Authentication>credssp</Authentication>
     <usessl></usessl>
     <SessionOption>(new-pssessionoption -SkipCACheck -SkipRevocationCheck -SkipCNCheck)</SessionOption>
  </ps-session-options>

  If you use the XML, the adapter internally creates the following command to run on the target remote computer: 

  $<connection-name> = New-PSSession -ComputerName clm-abc-123456 -Credential $cred  -Name <connection-name> -Authentication credssp  -usessl  -SessionOption (new-pssessionoption -SkipCACheck -SkipRevocationCheck -SkipCNCheck)
  
  $<connection-name> = Enter-PSSession -ComputerName clm-abc-123456 -Credential $cred  -Authentication credssp  -usessl  -SessionOption (new-pssessionoption -SkipCACheck -SkipRevocationCheck -SkipCNCheck)

However, to use the New-PSSession cmdlet, you must specify the following elements in the adapter request:

• host: Contains the host name or the IP address of the remote or local computer.
• username: Contains the user name to be used for authentication on the remote host computer.
• password: Contains the password corresponding to the specified user name for authentication on the remote host computer.
• enable-psremoting: Specifies whether to enable the remoting feature of PowerShell (Valid value: true).
• enable-psremoting-session: Specifies whether to execute multiple commands in the same session (Valid value: True).
• new-ps-session: Specifies whether to enable the New PSSession command.
• connection-name: Specifies the reference name of the connection to be persisted.

• commands: Contains the PowerShell commands to be executed in the request. 

  How to use connection name in Invoke-Command cmdlet in Commands XML

  Since Invoke-command is used on session created using New-PSSession and session is created with the connection-name (connection name) input, the actual invoke command -Session option value MUST must be the value of connection name.

  If the connection name provided in adapter request is "WO11112345", then the Invoke-Command must be in the following format:

  • For Command execution using script block:
    • Invoke-Command -Session $WO11112345 -ScriptBlock { hostname;ls}
  • For Command execution using File path (local path) that will be executed on remote system :
    • Invoke-Command -Session $WO11112345 -FilePath C:\time.ps1
• (Optional) connection-ttl: Specifies the duration (in seconds) for which a named connection should persist and invalidated or expires when connection is idle for given TTL (time to live) duration.
• (Optional) terminate-connection: Specifies whether the PS Remoting connection should be terminated. 

The following figure shows the sample adapter request XML.