Edit

Share via

PowerShellOnTargetMachines@3 - PowerShell on target machines v3 task

  • Article

Use this task to execute PowerShell scripts on remote machines using PSSession and Invoke-Command for remoting.

Syntax

# PowerShell on target machines v3
# Execute PowerShell scripts on remote machines using PSSession and Invoke-Command for remoting.
- task: PowerShellOnTargetMachines@3
  inputs:
    Machines: # string. Required. Machines. 
    #UserName: # string. Username. 
    #UserPassword: # string. Password. 
  # Script options
    #ScriptType: 'Inline' # 'FilePath' | 'Inline'. Script Type. Default: Inline.
    #ScriptPath: # string. Required when ScriptType = FilePath. Script File Path. 
    InlineScript: # string. Required when ScriptType = Inline. Script. 
    #ScriptArguments: # string. Optional. Use when ScriptType = FilePath. Script Arguments. 
    #InitializationScript: # string. Optional. Use when ScriptType = FilePath. Initialization script. 
    #SessionVariables: # string. Optional. Use when ScriptType = FilePath. Session Variables. 
  # PSSession options
    #CommunicationProtocol: 'Https' # 'Http' | 'Https'. Protocol. Default: Https.
    #AuthenticationMechanism: 'Default' # 'Default' | 'Credssp'. Authentication. Default: Default.
    #NewPsSessionOptionArguments: '-SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block' # string. Session Option parameters. Default: -SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block.
  # Error handling options
    #ErrorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
  # Advanced
    #WorkingDirectory: # string. Working Directory. 
    #RunPowershellInParallel: true # boolean. Run PowerShell in Parallel. Default: true.

Inputs

Machines - Machines
string. Required.

Specifies a comma-separated list of machine FQDNs or IP addresses, and optionally includes the port number. Can be:

  • The name of an Azure Resource Group.
  • A comma-delimited list of machine names. Example: dbserver.fabrikam.com,dbserver_int.fabrikam.com:5986,192.168.34:5986
  • An output variable from a previous task.

If you do not specify a port, the default WinRM port is used. This depends on the protocol you have configured. For WinRM 2.0, the default HTTP port is 5985 and the default HTTPS port is 5986.


UserName - Username
string.

Specifies the username of a domain or a local administrative account on the target host(s).

  • Formats such as username, domain\username, machine-name\username, and .\username are supported.
  • UPN formats such as username@domain.com and built-in system accounts such as NT Authority\System are not supported.

UserPassword - Password
string.

Specifies the password for the target machines. Variables defined in build/release definitions as $(passwordVariable) are accepted. You may mark the variable type as secret to secure it.


ScriptType - Script Type
string. Allowed values: FilePath (File Path), Inline. Default value: Inline.

Specifies the type of script to execute: Inline or File Path.


ScriptPath - Script File Path
string. Required when ScriptType = FilePath.

Specifies the location of the PowerShell script on the target machines or on a UNC path, like C:\BudgetIT\Web\Deploy\Website.ps1, which should be accessible from the target machine.


InlineScript - Script
string. Required when ScriptType = Inline. Default value: # Write your powershell commands here.\n\nWrite-Output "Hello World".


ScriptArguments - Script Arguments
string. Optional. Use when ScriptType = FilePath.

Specifies the arguments for the PowerShell script. Can be ordinal or named parameters, like -testParam test. For example: -applicationPath $(applicationPath), -username $(vmusername), -password $(vmpassword).


InitializationScript - Initialization script
string. Optional. Use when ScriptType = FilePath.

Specifies the location of the data script for the DSC on the target machines or on a UNC path, like C:\BudgetIT\Web\Deploy\WebsiteConfiguration.ps1. It's recommended to use arguments instead of an initialization script.


SessionVariables - Session Variables
string. Optional. Use when ScriptType = FilePath.

Used to set up the session variables for the PowerShell scripts.
Specifies a comma-separated list, such as $varx=valuex, $vary=valuey. Most commonly used for backward compatibility with earlier versions of the release service. It's recommended to use arguments instead of session variables.


CommunicationProtocol - Protocol
string. Allowed values: Http, Https. Default value: Https.

Specifies the protocol to use for the WinRM service connection with the machine(s). The default value is HTTPS.


AuthenticationMechanism - Authentication
string. Allowed values: Default, Credssp. Default value: Default.

Specifies the authentication mechanism used for creating the PSSession. For CredSSP authentication, the username and password fields are mandatory.


NewPsSessionOptionArguments - Session Option parameters
string. Default value: -SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block.

Advanced options for a remote session (New-PSSessionOption). For example, -SkipCACheck, -SkipCNCheck, -SkipRevocationCheck, etc. See a complete list of all session options to learn more.


ErrorActionPreference - ErrorActionPreference
string. Allowed values: stop, continue, silentlyContinue. Default value: stop.

Prepends the line $ErrorActionPreference = 'VALUE' at the top of your script.


failOnStderr - Fail on Standard Error
boolean. Default value: false.

If set to true, fails if any errors are written to the error pipeline or if any data is written to the Standard Error stream. Otherwise, the task relies on the exit code to determine failure.


ignoreLASTEXITCODE - Ignore $LASTEXITCODE
boolean. Default value: false.

If set to false, the line if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } is executed at the end of your script. This causes the last exit code from an external command to be propagated as the exit code of PowerShell. Otherwise, the line is not executed to the end of your script.


WorkingDirectory - Working Directory
string.

Specifies the working directory where the script is run.


RunPowershellInParallel - Run PowerShell in Parallel
boolean. Default value: true.

If set to true, runs the PowerShell scripts in parallel on the target machines.


Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

Use this task to execute PowerShell scripts on remote machine(s).

This task can run both PowerShell scripts and PowerShell-DSC scripts:

  • For PowerShell scripts, the computers must have PowerShell 2.0 or higher installed.
  • For PowerShell-DSC scripts, the computers must have the latest version of the Windows Management Framework installed. This is installed by default on Windows 8.1, Windows Server 2012 R2, and subsequent versions.

Prerequisites

This task uses Windows Remote Management (WinRM) to access on-premises physical computers or virtual computers that are domain-joined or workgroup-joined.

To set up WinRM for on-premises physical computers or virtual machines

Follow the steps described in domain-joined

To set up WinRM for Microsoft Azure Virtual Machines

Azure Virtual Machines require WinRM to use the HTTPS protocol. You can use a self-signed Test Certificate. In this case, the automation agent will not validate the authenticity of the certificate as being issued by a trusted certification authority.

  • Azure Classic Virtual Machines. When you create a classic virtual machine from the Azure portal, the virtual machine is already set up for WinRM over HTTPS, with the default port 5986 already opened in the firewall and a self-signed certificate installed on the machine. These virtual machines can be accessed with no further configuration required. Existing Classic virtual machines can be also selected by using the Azure Resource Group Deployment task.

  • Azure Resource Group. If you have an Azure Resource Group already defined in the Azure portal, you must configure it to use the WinRM HTTPS protocol. You need to open port 5986 in the firewall, and install a self-signed certificate.

To dynamically deploy Azure Resource Groups that contain virtual machines, use the Azure Resource Group Deployment task. This task has a checkbox named Enable Deployment Prerequisites. Select this to automatically set up the WinRM HTTPS protocol on the virtual machines, open port 5986 in the firewall, and install a test certificate. The virtual machines are then ready for use in the deployment task.

What's new in this task version

  • Uses PSSession and invoke-command to perform remoting on target machines.
  • Added support for inline script execution.
  • Default and CredSSP authentication are supported.
  • Added options for error handling: ErrorActionPreference, ignoreLASTEXITCODE and Fail on Standard Error.

Requirements

Requirement Description
Pipeline types YAML, Classic build, Classic release
Runs on Agent, DeploymentGroup
Demands None
Capabilities This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions Any
Settable variables Any
Agent version 2.134.0 or greater
Task category Deploy