PowerShell@2 - PowerShell v2 工作

使用此工作在Linux、macOS或 Windows 上執行 PowerShell 腳本。

注意

根據預設，PowerShell v2 會針對 Linux 代理程式使用 PowerShell Core，並針對 Windows 代理程式使用 Windows PowerShell。 若要在 Windows 代理程式上使用最新版本的 PowerShell，請將 pwsh 參數設定為 true。 接著會改用 PowerShell Core。

Syntax

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

輸入

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當設定為inline時targetType，不會使用 。

script - 腳本
string. 當 targetType = inline 時為必要。 預設值：# Write your PowerShell commands here.\n\nWrite-Host "Hello World"。

指定文稿的內容。 支援的內嵌腳本長度上限為 20000 個字元。 如果您想要使用較長的腳稿，請使用檔案中的腳本。

errorActionPreference - ErrorActionPreference
string. 允許的值：default、、、stopcontinue。silentlyContinue 預設值：stop。

在腳本頂端加上這一行 $ErrorActionPreference = 'VALUE' 。

warningPreference - WarningPreference
string. 允許的值：default、、、stopcontinue。silentlyContinue 預設值：default。

若未設定為 Default，請在腳本頂端加上這一行 $WarningPreference = 'VALUE' 。

informationPreference - InformationPreference
string. 允許的值：default、、、stopcontinue。silentlyContinue 預設值：default。

若未設定為 Default，請在腳本頂端加上這一行 $InformationPreference = 'VALUE' 。

verbosePreference - VerbosePreference
string. 允許的值：default、、、stopcontinue。silentlyContinue 預設值：default。

若未設定為 Default，請在腳本頂端加上這一行 $VerbosePreference = 'VALUE' 。

debugPreference - DebugPreference
string. 允許的值：default、、、stopcontinue。silentlyContinue 預設值：default。

若未設定為 Default，請在腳本頂端加上這一行 $DebugPreference = 'VALUE' 。

progressPreference - ProgressPreference
string. 允許的值：default、、、stopcontinue。silentlyContinue 預設值：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.powershell 和 steps.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>

若要避免此問題，您可以在腳本層級處理這些例外狀況，或避免管線秘密可能會在錯誤訊息內的原始程式碼行中出現的情況。

範例

• 從檔案叫用腳本
• 撰寫警告
• 寫入錯誤
• 使用多個自變數呼叫PowerShell腳本

從檔案叫用腳本

以下是名為 的範例 PowerShell 檔案，位於 test.ps1 存放庫的根目錄中。

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
要求	無
Capabilities	此工作不符合作業中後續工作的任何需求。
命令限制	任何
可設定變數	任何
代理程式版本	2.115.0 或更新版本
工作類別	公用程式

另請參閱

• 使用 PowerShell 腳本自定義管線 - ApplyVersionToAssemblies.ps1
• 深入瞭解 PowerShell 腳本
  • 使用 Windows PowerShell 撰寫指令碼
  • Microsoft 腳本中心 (Scripting Guys)
  • PowerShell.org \(英文\)