PowerShell@2 - PowerShell v2 task

Artikel
02/27/2024

Use this task to run a PowerShell script on Linux, macOS, or Windows.

Note

By default, PowerShell v2 uses PowerShell Core for Linux agents and Windows PowerShell for Windows agents. To use the latest version of PowerShell on Windows agents, set the pwsh parameter to true. PowerShell Core will then be used instead.

Inputs

targetType - Type
string. Allowed values: filePath (File Path), inline. Default value: filePath.

Specifies the type of script for the task to run: an inline script or a path to a .ps1 file.

filePath - Script Path
string. Required when targetType = filePath.

Specifies the path of the script to execute. Must be a fully qualified path or relative to $(System.DefaultWorkingDirectory).

arguments - Arguments
string. Optional. Use when targetType = filePath.

Specifies the arguments passed to the PowerShell script. Arguments can be ordinal parameters or named parameters. For example, -Name someName -Path -Value "Some long string value".

arguments is not used when targetType is set to inline.

script - Script
string. Required when targetType = inline. Default value: # Write your powershell commands here.\n\nWrite-Host "Hello World".

Specifies the contents of the script. The maximum supported inline script length is 20000 characters. Use a script from a file if you want to use a longer script.

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 the value of this boolean is true, the task 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 the value is set to false, the line if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } is appended to the end of your script. This will cause the last exit code from an external command to be propagated as the exit code of powershell. Otherwise, the line is not appended to the end of your script.

workingDirectory - Working Directory
string.

Specifies the working directory where the script is run. If a value is not specified, the working directory is $(Build.SourcesDirectory).

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

Each PowerShell session lasts only for the duration of the job in which it runs. Tasks that depend on what has been bootstrapped must be in the same job as the bootstrap.

Task shortcuts

PowerShell@2 has two shortcuts in YAML: steps.powershell and steps.pwsh.

powershell runs using either Windows PowerShell (on Windows) or pwsh (Linux and macOS).
pwsh runs PowerShell Core, the cross-platform edition of PowerShell built on .NET Core.

steps:
- powershell: # Run a script in Windows PowerShell on Windows, and pwsh on Linux and macOS.
- pwsh: # Run a script in PowerShell Core on Windows, macOS, and Linux.

Set a variable so it can be read by subsequent scripts and tasks

To learn more about defining build variables in a script, see Define and modify your build variables in a script.

To learn more about defining release variables in a script, see Define and modify your release variables in a script.

Passing pipeline secrets in script, but secret is not masked in pipeline logs

Be aware that PowerShell cuts off error messages, so if you use pipeline secrets in a script, the secrets could be trimmed and exposed. For example, in the inline script below:

./script.ps1 --arg1 value1 --arg2 <some_secret_which_will_be_masked_here>

There could be an exception like: At <path_to_temp_script_file>:4 char:3:

+   ./script.ps1 --arg1 value1 --arg2 <unmasked_part_of_original_secret> ...
+   ~~~~~~~~~~
    + <Additional exception details>

To avoid this issue, you can handle these exceptions on a script level, or avoid cases when pipeline secrets could appear in source code lines within error messages.

Examples

Invoke a script from a file
Write a warning
Write an error
Call PowerShell script with multiple arguments

Invoke a script from a file

The following is a sample PowerShell file named test.ps1 located in the root of your repository.

Write-Host "Hello World from $Env:AGENT_NAME."
Write-Host "My ID is $Env:AGENT_ID."
Write-Host "AGENT_WORKFOLDER contents:"
gci $Env:AGENT_WORKFOLDER
Write-Host "AGENT_BUILDDIRECTORY contents:"
gci $Env:AGENT_BUILDDIRECTORY
Write-Host "BUILD_SOURCESDIRECTORY contents:"
gci $Env:BUILD_SOURCESDIRECTORY
Write-Host "Over and out."

You can invoke this script in your pipeline like this.

steps:
- task: PowerShell@2
  inputs:
    targetType: 'filePath'
    filePath: 'test.ps1'

Write a warning

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: Write-Host "##vso[task.LogIssue type=warning;]This is the warning"
    # Writes a warning to build summary and to log in yellow text

Write an error

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: Write-Host "##vso[task.LogIssue type=error;]This is the error"
    # Writes an error to build summary and to log in red text

If you want this error to fail the build, add exit 1 to the script.

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host "##vso[task.LogIssue type=error;]This is the error"
      exit 1
    # Writes an error to build summary and to log in red text

Call PowerShell script with multiple arguments

Create PowerShell script test2.ps1:

param ($input1, $input2)
Write-Host "$input1 $input2"

In your YAML pipeline, call:

- task: PowerShell@2
  inputs:
    targetType: 'filePath'
    filePath: $(System.DefaultWorkingDirectory)\test2.ps1
    arguments: > # Use this to avoid newline characters in multiline string
      -input1 "Hello"
      -input2 "World"
  displayName: 'Print Hello World'

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.115.0 or greater
Task category	Utility

Dela via