Azure Pipelines | TFS 2018 | TFS 2017 | TFS 2015
Use this task in a build or release pipeline to run a PowerShell script.
In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, service connections are called service endpoints, stages are called environments, and jobs are called phases.
# PowerShell # Run a PowerShell script on Windows, macOS, or Linux. - task: PowerShell@2 inputs: #targetType: 'filePath' # Optional. Options: filePath, inline #filePath: # Required when targetType == FilePath #arguments: # Optional #script: '# Write your powershell commands here.' # Required when targetType == Inline #errorActionPreference: 'stop' # Optional. Options: stop, continue, silentlyContinue #failOnStderr: false # Optional #ignoreLASTEXITCODE: false # Optional #pwsh: false # Optional #workingDirectory: # Optional
The Powershell task also has a shortcut syntax in YAML:
- powershell: # inline script workingDirectory: # displayName: # failOnStderr: # errorActionPreference: # ignoreLASTEXITCODE: # env: # mapping of environment variables to add
|Type||Sets whether this is an inline script or a path to a |
|File path||Path of the script to execute. Must be a fully qualified path or relative to |
|Arguments||Arguments passed to the Powershell script. Ignored when Type is |
|Script||Contents of the script. Required if Type is |
|Working directory||Specify the working directory in which you want to run the command. If you leave it empty, the working directory is |
|Fail on standard error||If this is
|errorActionPreference||Set PowerShell's error action preference. One of:
|ignoreLASTEXITCODE||By default, the last exit code returned from your script will be checked and, if non-zero, treated as a step failure. If you don't want this behavior, set this to
|Environment variables||A list of additional items to map into the process's environment. For example, secret variables are not automatically mapped. If you have a secret variable called
test.ps1 at the root of your repo:
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."
On the Build tab of a build pipeline, add this task:
Write a warning
Set warning message
"You've been warned by"
Write-Host "$("##vso[task.setvariable variable=WarningMessage]") $($args)"
Write warning using task.LogIssue
# Writes a warning to build summary and to log in yellow text Write-Host "$("##vso[task.LogIssue type=warning;]") $($env:WarningMessage) $("the task.LogIssue Azure Pipelines logging command.")"
Write warning using PowerShell command
# Writes a warning to log preceded by "WARNING: " Write-Warning "$($env:WarningMessage) $("the Write-Warning PowerShell command.")"
Write an error
Set error message
"something went wrong."
Write-Host "$("##vso[task.setvariable variable=ErrorMessage]") $($args)"
Write error using task.LogIssue
# Writes an error to the build summary and to the log in red text Write-Host "$("##vso[task.LogIssue type=error;]") $("the task.LogIssue Azure Pipelines logging command reported that") $($env:ErrorMessage)"
If you want this error to fail the build, then add this line:
Write error using PowerShell command
# Writes an error to the build summary and the log with details about the error Write-Error "$("the Write-Error PowerShell command reported that") $($env:ErrorMessage)"
If you don't want this error to fail the build, then clear the Advanced: Fail on Standard Error check box.
This task is open source on GitHub. Feedback and contributions are welcome.
Q & A
Where can I learn about PowerShell scripts?
How do I set a variable so that it can be read by subsequent scripts and tasks?
Q: I'm having problems. How can I troubleshoot them?
A: Try this:
On the variables tab, add
system.debugand set it to
true. Select to allow at queue time.
In the explorer tab, view your completed build and click the build step to view its output.
The control options arguments described above can also be useful when you're trying to isolate a problem.
Q: How do variables work? What variables are available for me to use in the arguments?
$(Agent.BuildDirectory) are just a few of the variables you can use. See Variables.
Do I need an agent?
You need at least one agent to run your build or release. Get an agent for Linux, macOS, or Windows.
I can't select a default agent pool and I can't queue my build or release. How do I fix this?
See Agent pools.
We'd love to hear your thoughts. Choose the type you'd like to provide:
Our feedback system is built on GitHub Issues. Read more on our blog.