Skip to content

Latest commit

 

History

History
311 lines (241 loc) · 11 KB

steps-powershell.md

File metadata and controls

311 lines (241 loc) · 11 KB
Raw
title description ms.date monikerRange
steps.powershell definition
Runs a script using either Windows PowerShell (on Windows) or pwsh (Linux and macOS).
10/04/2024
>=azure-pipelines-2019

steps.powershell definition

:::moniker range=">=azure-pipelines-2019"

The powershell step runs a script using either Windows PowerShell (on Windows) or pwsh (Linux and macOS).

:::moniker-end

:::moniker range=">=azure-pipelines-2022"

steps:
- powershell: string # Required as first property. Inline PowerShell script.
  errorActionPreference: string # Unless otherwise specified, the error action preference defaults to the value stop. See the following section for more information.
  failOnStderr: string # Fail the task if output is sent to Stderr?
  ignoreLASTEXITCODE: string # Check the final exit code of the script to determine whether the step succeeded?
  workingDirectory: string # Start the script with this working directory.
  condition: string # Evaluate this condition expression to determine whether to run this task.
  continueOnError: boolean # Continue running even on failure?
  displayName: string # Human-readable name for the task.
  target: string | target # Environment in which to run this task.
  enabled: boolean # Run this task when the job runs?
  env: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
  retryCountOnTaskFailure: string # Number of retries if the task fails.

:::moniker-end

:::moniker range=">=azure-pipelines-2020 <=azure-pipelines-2020.1"

steps:
- powershell: string # Required as first property. Inline PowerShell script.
  errorActionPreference: string # Unless otherwise specified, the error action preference defaults to the value stop. See the following section for more information.
  failOnStderr: string # Fail the task if output is sent to Stderr?
  ignoreLASTEXITCODE: string # Check the final exit code of the script to determine whether the step succeeded?
  workingDirectory: string # Start the script with this working directory.
  condition: string # Evaluate this condition expression to determine whether to run this task.
  continueOnError: boolean # Continue running even on failure?
  displayName: string # Human-readable name for the task.
  target: string | target # Environment in which to run this task.
  enabled: boolean # Run this task when the job runs?
  env: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.

:::moniker-end

:::moniker range=">=azure-pipelines-2019 <=azure-pipelines-2019.1"

steps:
- powershell: string # Required as first property. Inline PowerShell script.
  errorActionPreference: string # Unless otherwise specified, the error action preference defaults to the value stop. See the following section for more information.
  failOnStderr: string # Fail the task if output is sent to Stderr?
  ignoreLASTEXITCODE: string # Check the final exit code of the script to determine whether the step succeeded?
  workingDirectory: string # Start the script with this working directory.
  condition: string # Evaluate this condition expression to determine whether to run this task.
  continueOnError: boolean # Continue running even on failure?
  displayName: string # Human-readable name for the task.
  enabled: boolean # Run this task when the job runs?
  env: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

Definitions that reference this definition: steps

:::moniker-end

Properties

:::moniker range=">=azure-pipelines-2019"

powershell string. Required as first property.
Inline PowerShell script.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

errorActionPreference string.
Unless otherwise specified, the error action preference defaults to the value stop. See the following section for more information.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

failOnStderr string.
Fail the task if output is sent to Stderr?

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

ignoreLASTEXITCODE string.
Check the final exit code of the script to determine whether the step succeeded?

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

workingDirectory string.
Start the script with this working directory.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

condition string.
Evaluate this condition expression to determine whether to run this task.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

continueOnError boolean.
Continue running even on failure?

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

displayName string.
Human-readable name for the task.

:::moniker-end

:::moniker range=">=azure-pipelines-2020"

target target.
Environment in which to run this task.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

enabled boolean.
Run this task when the job runs?

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

env string dictionary.
Variables to map into the process's environment.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

name string.
ID of the step. Acceptable values: [-_A-Za-z0-9]*.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

timeoutInMinutes string.
Time to wait for this task to complete before the server kills it.

[!INCLUDE task-timeout]

:::moniker-end

:::moniker range=">=azure-pipelines-2022"

retryCountOnTaskFailure string.
Number of retries if the task fails.

:::moniker-end

Remarks

The powershell keyword is a shortcut for the PowerShell task. The task runs a script using either Windows PowerShell (on Windows) or pwsh (Linux and macOS).

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.

Learn more about conditions and timeouts.

Error action preference

Unless otherwise specified, the error action preference defaults to the value stop, and the line $ErrorActionPreference = 'stop' is prepended to the top of your script.

When the error action preference is set to stop, errors cause PowerShell to terminate the task and return a nonzero exit code. The task is also marked as Failed.

errorActionPreference: stop | continue | silentlyContinue
steps:
- powershell: |
    Write-Error 'Uh oh, an error occurred'
    Write-Host 'Trying again...'
  displayName: Error action preference
  errorActionPreference: continue

Ignore last exit code

The last exit code returned from your script is checked by default. A nonzero code indicates a step failure, in which case the system appends your script with:

if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }

If you don't want this behavior, specify ignoreLASTEXITCODE: true.

ignoreLASTEXITCODE: boolean
steps:
- powershell: git nosuchcommand
  displayName: Ignore last exit code
  ignoreLASTEXITCODE: true

Learn more about conditions and timeouts.

Examples

steps:
- powershell: Write-Host Hello $Env:name
  displayName: Say hello
  name: firstStep
  workingDirectory: $(build.sourcesDirectory)
  failOnStderr: true
  env:
    name: Microsoft

See also