PowerShell@2 - PowerShell v2 任务

使用此任务在 Linux、macOS 或 Windows 上运行 PowerShell 脚本。

注意

默认情况下,PowerShell v2 对 Linux 代理使用 PowerShell Core,对 Windows 代理使用Windows PowerShell。 若要在 Windows 代理上使用最新版本的 PowerShell,请将 pwsh 参数设置为 true。 然后,将改用 PowerShell Core。

语法

# PowerShell v2
# Run a PowerShell script on Linux, macOS, or Windows.
- task: PowerShell@2
  inputs:
    #targetType: 'filePath' # 'filePath' | 'inline'. Type. Default: filePath.
    filePath: # string. Required when targetType = filePath. Script Path. 
    #arguments: # string. Optional. Use when targetType = filePath. Arguments. 
    #script: # string. Required when targetType = inline. Script. 
  # Preference Variables
    #errorActionPreference: 'stop' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
    #warningPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. WarningPreference. Default: default.
    #informationPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. InformationPreference. Default: default.
    #verbosePreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. VerbosePreference. Default: default.
    #debugPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. DebugPreference. Default: default.
    #progressPreference: 'silentlyContinue' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. ProgressPreference. Default: silentlyContinue.
  # Advanced
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #showWarnings: false # boolean. Show warnings as Azure DevOps warnings. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #workingDirectory: # string. Working Directory. 
    #runScriptInSeparateScope: false # boolean. Run script in the separate scope. Default: false.
# PowerShell v2
# Run a PowerShell script on Linux, macOS, or Windows.
- task: PowerShell@2
  inputs:
    #targetType: 'filePath' # 'filePath' | 'inline'. Type. Default: filePath.
    filePath: # string. Required when targetType = filePath. Script Path. 
    #arguments: # string. Optional. Use when targetType = filePath. Arguments. 
    #script: # string. Required when targetType = inline. Script. 
  # Preference Variables
    #errorActionPreference: 'stop' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
    #warningPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. WarningPreference. Default: default.
    #informationPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. InformationPreference. Default: default.
    #verbosePreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. VerbosePreference. Default: default.
    #debugPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. DebugPreference. Default: default.
  # Advanced
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #showWarnings: false # boolean. Show warnings as Azure DevOps warnings. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #workingDirectory: # string. Working Directory. 
    #runScriptInSeparateScope: false # boolean. Run script in the separate scope. Default: false.
# PowerShell v2
# Run a PowerShell script on Linux, macOS, or Windows.
- task: PowerShell@2
  inputs:
    #targetType: 'filePath' # 'filePath' | 'inline'. Type. Default: filePath.
    filePath: # string. Required when targetType = filePath. Script Path. 
    #arguments: # string. Optional. Use when targetType = filePath. Arguments. 
    #script: # string. Required when targetType = inline. Script. 
    #errorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
  # Advanced
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #showWarnings: false # boolean. Show warnings as Azure DevOps warnings. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #workingDirectory: # string. Working Directory.
# PowerShell v2
# Run a PowerShell script on Linux, macOS, or Windows.
- task: PowerShell@2
  inputs:
    #targetType: 'filePath' # 'filePath' | 'inline'. Type. Default: filePath.
    filePath: # string. Required when targetType = filePath. Script Path. 
    #arguments: # string. Optional. Use when targetType = filePath. Arguments. 
    #script: # string. Required when targetType = inline. Script. 
    #errorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
  # Advanced
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #workingDirectory: # string. Working Directory.
# PowerShell v2
# Run a PowerShell script on Windows, macOS, or Linux.
- task: PowerShell@2
  inputs:
    #targetType: 'filePath' # 'filePath' | 'inline'. Type. Default: filePath.
    filePath: # string. Required when targetType = filePath. Script Path. 
    #arguments: # string. Optional. Use when targetType = filePath. Arguments. 
    #script: # string. Required when targetType = inline. Script. 
    #errorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
  # Advanced
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #workingDirectory: # string. Working Directory.

输入

targetType - 类型
string. 允许的值: filePath (文件路径) 、 inline。 默认值:filePath

指定要运行的任务的脚本类型:内联脚本或文件的路径 .ps1


filePath - 脚本路径
string. 当 targetType = filePath 时,需要此选项。

指定要执行的脚本的路径。 必须是完全限定的路径或相对于 $(System.DefaultWorkingDirectory) 的路径。


arguments - 参数
string. 可选。 在 时 targetType = filePath使用 。

指定传递给 PowerShell 脚本的参数。 参数可以是序号参数或命名参数。 例如 -Name someName -Path -Value "Some long string value"

arguments当 设置为 inlinetargetType,不使用 。


script - 脚本
string. 当 targetType = inline 时,需要此选项。 默认值:# Write your PowerShell commands here.\n\nWrite-Host "Hello World"

指定脚本的内容。 支持的最大内联脚本长度为 20000 个字符。 如果要使用较长的脚本,请使用文件中的脚本。


script - 脚本
string. 当 targetType = inline 时,需要此选项。 默认值:# Write your powershell commands here.\n\nWrite-Host "Hello World"\n\n# Use the environment variables input below to pass secret variables to this script.

指定脚本的内容。 支持的最大内联脚本长度为 20000 个字符。 如果要使用较长的脚本,请使用文件中的脚本。


errorActionPreference - ErrorActionPreference
string. 允许的值: defaultstopcontinuesilentlyContinue。 默认值:stop

在脚本顶部添加行 $ErrorActionPreference = 'VALUE'


errorActionPreference - ErrorActionPreference
string. 允许的值:stopcontinuesilentlyContinue。 默认值:stop

在脚本顶部添加行 $ErrorActionPreference = 'VALUE'


warningPreference - WarningPreference
string. 允许的值: defaultstopcontinuesilentlyContinue。 默认值:default

如果未设置为 Default,则会在脚本顶部添加行 $WarningPreference = 'VALUE'


informationPreference - InformationPreference
string. 允许的值: defaultstopcontinuesilentlyContinue。 默认值:default

如果未设置为 Default,则会在脚本顶部添加行 $InformationPreference = 'VALUE'


verbosePreference - VerbosePreference
string. 允许的值: defaultstopcontinuesilentlyContinue。 默认值:default

如果未设置为 Default,则会在脚本顶部添加行 $VerbosePreference = 'VALUE'


debugPreference - DebugPreference
string. 允许的值: defaultstopcontinuesilentlyContinue。 默认值:default

如果未设置为 Default,则会在脚本顶部添加行 $DebugPreference = 'VALUE'


progressPreference - ProgressPreference
string. 允许的值: defaultstopcontinuesilentlyContinue。 默认值:silentlyContinue

如果未设置为 Default,则会在脚本顶部添加行 $ProgressPreference = 'VALUE'


failOnStderr - 标准错误失败
boolean. 默认值:false

如果此布尔 true值的值为 ,则如果有任何错误写入错误管道或将任何数据写入标准错误流,则任务将失败。 否则,任务依赖于退出代码来确定失败。


showWarnings - 将警告显示为 Azure DevOps 警告
boolean. 默认值:false

如果该值设置为 true,并且脚本写入警告,则警告将在管道日志中显示为警告。


ignoreLASTEXITCODE - 忽略$LASTEXITCODE
boolean. 默认值:false

如果值设置为 false,则行 if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } 将追加到脚本的末尾。 这将导致外部命令的最后一个退出代码作为 的 powershell退出代码传播。 否则,该行不会追加到脚本的末尾。


pwsh - 使用 PowerShell Core
boolean. 默认值:false

如果为 true,则 Windows 代理上运行的任务将从路径中使用 pwsh.exe 而不是 powershell.exe


workingDirectory - 工作目录
string.

指定运行脚本的工作目录。 如果未指定值,则工作目录为 $(Build.SourcesDirectory)


runScriptInSeparateScope - 在单独的范围内运行脚本
boolean. 默认值:false

此输入允许使用 & 运算符而不是默认 .的 执行 PowerShell 脚本。 如果此输入设置为 true,则脚本将在单独的范围内执行,并且不会更新全局范围的 PowerShell 变量。


任务控制选项

除了任务输入,所有任务都有控制选项。 有关详细信息,请参阅 控制选项和常见任务属性

输出变量

无。

备注

每个 PowerShell 会话的持续时间就是其运行时所在的作业的持续时间。 依赖于被启动项的任务必须与启动位于同一作业中。

任务快捷方式

PowerShell@2 YAML 中具有两个快捷方式: steps.powershellsteps.pwsh

  • powershell在 Windows) 或 pwsh (Linux 和 macOS) 上使用 Windows PowerShell (运行。
  • pwsh 运行 PowerShell Core,这是基于 .NET Core 构建的跨平台 PowerShell 版本。
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.

设置变量,以便后续脚本和任务可以读取它

若要详细了解如何在脚本中定义生成变量,请参阅在脚本中定义和修改生成变量

若要详细了解如何在脚本中定义发布变量,请参阅 在脚本中定义和修改发布变量

在脚本中传递管道机密,但在管道日志中未屏蔽机密

请注意,PowerShell 会切断错误消息,因此,如果在脚本中使用管道机密,则可以剪裁并公开机密。 例如,在下面的内联脚本中:

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

可能存在如下异常: At <path_to_temp_script_file>:4 char:3

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

若要避免此问题,可以在脚本级别处理这些异常,或者避免在错误消息中的源代码行中出现管道机密的情况。

示例

从文件调用脚本

下面是一个名为 test.ps1 的示例 PowerShell 文件,该文件位于存储库的根目录中。

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."

可以在管道中调用此脚本,如下所示。

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

编写警告

- 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

编写错误

- 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

如果希望此错误使生成失败,请将 添加到 exit 1 脚本。

- 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

使用多个参数调用 PowerShell 脚本

创建 PowerShell 脚本 test2.ps1

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

在 YAML 管道中,调用:

- 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'

要求

要求 说明
管道类型 YAML,经典内部版本,经典版本
运行平台 Agent、DeploymentGroup
需求
功能 此任务不满足作业中后续任务的任何要求。
命令限制 任意
可设置的变量 任意
代理版本 2.115.0 或更高版本
任务类别 实用工具

另请参阅