PowerShell@2 — задача PowerShell версии 2

Статья
07/02/2024

Используйте эту задачу для запуска скрипта PowerShell в Linux, macOS или Windows.

Примечание

По умолчанию PowerShell версии 2 использует PowerShell Core для агентов Linux и Windows PowerShell для агентов Windows. Чтобы использовать последнюю версию PowerShell в агентах Windows, задайте для 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 не используется, если targetType для задано значение inline.

script - Сценарий
string. Требуется, если targetType = inline. Значение по умолчанию: # Write your PowerShell commands here.\n\nWrite-Host "Hello World".

Указывает содержимое скрипта. Максимальная поддерживаемая длина встроенного скрипта составляет 20 000 символов. Используйте скрипт из файла, если вы хотите использовать более длинный скрипт.

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

errorActionPreference - ErrorActionPreference
string. Допустимые значения: default, stop, continue, silentlyContinue. Значение по умолчанию: stop.

Добавляет в начало строку $ErrorActionPreference = 'VALUE' в верхней части скрипта.

errorActionPreference - ErrorActionPreference
string. Допустимые значения: stop, continue, silentlyContinue. Значение по умолчанию: stop.

Добавляет в начало строку $ErrorActionPreference = 'VALUE' в верхней части скрипта.

warningPreference - WarningPreference
string. Допустимые значения: default, stop, continue, silentlyContinue. Значение по умолчанию: default.

Если не задано значение Default, перед строкой $WarningPreference = 'VALUE' в верхней части скрипта.

informationPreference - InformationPreference
string. Допустимые значения: default, stop, continue, silentlyContinue. Значение по умолчанию: default.

Если не задано значение Default, перед строкой $InformationPreference = 'VALUE' в верхней части скрипта.

verbosePreference - VerbosePreference
string. Допустимые значения: default, stop, continue, silentlyContinue. Значение по умолчанию: default.

Если не задано значение Default, перед строкой $VerbosePreference = 'VALUE' в верхней части скрипта.

debugPreference - DebugPreference
string. Допустимые значения: default, stop, continue, silentlyContinue. Значение по умолчанию: default.

Если не задано значение Default, перед строкой $DebugPreference = 'VALUE' в верхней части скрипта.

progressPreference - ProgressPreference
string. Допустимые значения: default, stop, continue, 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.

Если это так, то задачи, выполняемые в агентах Windows, будут использовать pwsh.exe из пути вместо powershell.exe.

workingDirectory - Рабочий каталог
string.

Указывает рабочий каталог, в котором выполняется скрипт. Если значение не указано, рабочим каталогом будет $(Build.SourcesDirectory).

runScriptInSeparateScope - Выполнение скрипта в отдельной область
boolean. Значение по умолчанию: false.

Эти входные данные позволяют выполнять скрипты PowerShell с помощью & оператора вместо стандартного .. Если для этих входных данных задано значение true, скрипт будет выполняться в отдельном область, а глобальные переменные PowerShell не будут обновляться.

Параметры управления задачами

Помимо входных данных, все задачи имеют параметры управления. Дополнительные сведения см. в разделе Параметры управления и общие свойства задачи.

Выходные переменные

Нет.

Remarks

Каждый сеанс PowerShell длится только в течение задания, в котором он выполняется. Задачи, зависящие от начальной загрузки, должны находиться в том же задании, что и начальная загрузка.

Ярлыки задач

PowerShell@2 имеет два сочетания клавиш в YAML: steps.powershell и steps.pwsh.

powershellвыполняется с помощью Windows PowerShell (в Windows) или pwsh (Linux и macOS).
pwsh запускает PowerShell Core, кроссплатформенный выпуск PowerShell, созданный на основе .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.

Задайте переменную, чтобы ее можно было считывать последующими скриптами и задачами.

Дополнительные сведения об определении переменных сборки в скрипте см. в статье Определение и изменение переменных сборки в скрипте.

Дополнительные сведения об определении переменных выпуска в скрипте см. в статье Определение и изменение переменных выпуска в скрипте.

Передача секретов конвейера в скрипте, но секрет не маскируется в журналах конвейера

Имейте в виду, что 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 с несколькими аргументами

Создайте скрипт test2.ps1PowerShell:

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, классическая сборка, классический выпуск
Выполняется в	Агент, DeploymentGroup
Требования	None
Capabilities	Эта задача не удовлетворяет требованиям для последующих задач в задании.
Ограничения команд	Любой
Устанавливаемые переменные	Любой
Версия агента	2.115.0 или более поздней версии
Категория задач	Служебная программа

См. также раздел

Настройка конвейера с помощью скрипта PowerShell — ApplyVersionToAssemblies.ps1
Дополнительные сведения о скриптах PowerShell

Поделиться через