Скрипты PowerShell для конвейеров

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

В этой статье объясняется, как скрипты PowerShell могут добавлять бизнес-логику в Azure Pipelines. Задача PowerShell версии 2 (PowerShell@2) запускает скрипты PowerShell, которые могут получить доступ к REST API Azure DevOps, работать с рабочими элементами Azure DevOps, управлять тестами или вызывать другие службы.

В сценариях PowerShell можно использовать предопределенные переменные или пользовательские переменные . Можно также задать переменные выходных данных с несколькими заданиями , чтобы сделать переменные доступными для других заданий. Дополнительные сведения см. в разделе "Определение переменных".

Вы также можете использовать именованные параметры в скриптах PowerShell. Другие виды параметров, например параметры коммутатора, не поддерживаются. Дополнительные сведения см. в разделе «Как объявить параметры командлета».

Задача скрипта PowerShell

Чтобы использовать скрипт PowerShell, добавьте задачу PowerShell версии 2 (PowerShell@2) в конвейер, а затем введите встроенный скрипт PowerShell или вызовите файл скрипта PowerShell.

В сборке используется активная ветвь вашего кода. Если конвейер использует main ветвь кода, скрипт также использует ветвь main .

YAML

В следующем примере используется targetType: 'inline' и добавляется встроенный скрипт в script свойство.

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: Write-Host "Hello world!"

В следующем примере шаг добавляется в PowerShell@2 конвейер YAML. Код вызывает файл скрипта PowerShell с именемtest.ps1 , расположенный в корне репозитория.

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

Примечание.

По умолчанию PowerShell@2 задача использует Windows PowerShell 5.1 для агентов Windows и PowerShell 7.x для агентов Linux и macOS. Чтобы использовать PowerShell 7.x в агентах Windows, необходимо установить PowerShell 7.x и добавить pwsh в него набор trueпараметров. Агенты, размещенные корпорацией Майкрософт , по умолчанию установлены PowerShell 7.x.

Вы также можете добавить pwsh или powershell шаг в конвейер YAML в качестве ярлыка PowerShell@2 для шага. Ярлык pwsh запускает PowerShell 7.x в macOS, Linux или Windows. Ярлык powershell запускает Windows PowerShell 5.1 в Windows или PowerShell 7.x в Linux и macOS.

steps:
- pwsh: test.ps1

steps:
- pwsh: Write-Host Hello

Классическое

1. В классическом конвейере добавьте задачу PowerShell в конвейер.

2. В области PowerShell выберите "Путь к файлу " или " Встроенный " в разделе "Тип".

   • Если выбрать путь к файлу, по умолчанию добавьте расположение файла скрипта относительно рабочего каталога в разделе "Путь к скрипту".
   • В поле " Встроенный" введите команды PowerShell в поле "Скрипт ".

   

Примечание.

По умолчанию задача PowerShell версии 2 использует Windows PowerShell 5.1 для агентов Windows и PowerShell 7.x для агентов Linux и macOS. Чтобы использовать PowerShell 7.x в агентах Windows, выберите "Использовать PowerShell Core " в разделе "Дополнительные параметры " в области PowerShell. Необходимо установить PowerShell 7.x, который агенты, размещенные корпорацией Майкрософт , выполняются по умолчанию.

Пример скрипта для применения версии к сборкам

Следующий скрипт PowerShell применяет версию на основе номера сборки к сборкам. Например, если определение $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) номера сборки создает номер сборки HelloWorld_2024.07.19.1, скрипт применяет версию 2024.07.19.1 к сборкам.

Для успешного выполнения этого скрипта формат номера сборки должен иметь четыре сегмента. Дополнительные сведения см. в разделе "Номера запуска" или "Сборка".

Примечание.

Номер сборки также называется номером запуска.

YAML

1. Настройте определение номера сборки в конвейере YAML с помощью name свойства на корневом уровне конвейера.

   name: $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)
   

2. Сохраните следующий скрипт PowerShell в качестве файла в корне репозитория.

3. PowerShell@2 Добавьте шаг задачи или pwshpowershell ярлык в конвейер и вызовите путь к файлу скрипта PowerShell относительно рабочего каталога.

Классическое

1. В классическом конвейере укажите формат номера сборки на вкладке "Параметры " в разделе "Номер сборки". Например, введите $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r).

   

2. Сохраните следующий скрипт PowerShell в качестве файла в корне репозитория.

3. Добавьте задачу PowerShell в конвейер и вызовите путь к файлу скрипта PowerShell относительно рабочего каталога.

Скрипт PowerShell для применения версии к сборкам:

# Enable -Verbose option
[CmdletBinding()]

# Regular expression pattern to find the version in the build number
$VersionRegex = "\d+\.\d+\.\d+\.\d+"

# If not running on a build server, remind user to set environment variables for debugging
if(-not ($Env:BUILD_SOURCESDIRECTORY -and $Env:BUILD_BUILDNUMBER))
{
    Write-Error "You must set the following environment variables"
    Write-Error "to test this script interactively."
    Write-Host '$Env:BUILD_SOURCESDIRECTORY - For example, enter something like:'
    Write-Host '$Env:BUILD_SOURCESDIRECTORY = "C:\code\Fabrikam\HelloWorld"'
    Write-Host '$Env:BUILD_BUILDNUMBER - For example, enter something like:'
    Write-Host '$Env:BUILD_BUILDNUMBER = "Build HelloWorld_0000.00.00.0"'
    exit 1
}

# Make sure path to source code directory is available
if (-not $Env:BUILD_SOURCESDIRECTORY)
{
    Write-Error ("BUILD_SOURCESDIRECTORY environment variable is missing.")
    exit 1
}
elseif (-not (Test-Path $Env:BUILD_SOURCESDIRECTORY))
{
    Write-Error "BUILD_SOURCESDIRECTORY does not exist: $Env:BUILD_SOURCESDIRECTORY"
    exit 1
}
Write-Verbose "BUILD_SOURCESDIRECTORY: $Env:BUILD_SOURCESDIRECTORY"
    
# Make sure there's a build number
if (-not $Env:BUILD_BUILDNUMBER)
{
    Write-Error ("BUILD_BUILDNUMBER environment variable is missing.")
    exit 1
}
Write-Verbose "BUILD_BUILDNUMBER: $Env:BUILD_BUILDNUMBER"
    
# Get and validate the version data
$VersionData = [regex]::matches($Env:BUILD_BUILDNUMBER,$VersionRegex)
switch($VersionData.Count)
{
   0        
      { 
         Write-Error "Couldn't find version number data in BUILD_BUILDNUMBER."
         exit 1
      }
   1 {}
   default 
      { 
         Write-Warning "Found more than one instance of version data in BUILD_BUILDNUMBER." 
         Write-Warning "Assuming first instance is version."
      }
}
$NewVersion = $VersionData[0]
Write-Verbose "Version: $NewVersion"
    
# Apply the version to the assembly property files
$files = gci $Env:BUILD_SOURCESDIRECTORY -recurse -include "*Properties*","My Project" | 
    ?{ $_.PSIsContainer } | 
    foreach { gci -Path $_.FullName -Recurse -include AssemblyInfo.* }
if($files)
{
    Write-Verbose "Applying $NewVersion to $($files.count) files."
    
    foreach ($file in $files) {
        $filecontent = Get-Content($file)
        attrib $file -r
        $filecontent -replace $VersionRegex, $NewVersion | Out-File $file
        Write-Verbose "$file.FullName - version applied"
    }
}
else
{
    Write-Warning "Found no files."
}

Пример скрипта для доступа к REST API

Следующий скрипт PowerShell использует переменные среды для доступа к REST API Azure Pipelines и получения определения конвейера.

YAML

В конвейере YAML можно определить переменную $env:SYSTEM_ACCESSTOKEN среды в задаче и использовать ее в PowerShell@2 встроенном скрипте, чтобы получить маркер OAuth для доступа к REST API.

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      $url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=5.0"
              Write-Host "URL: $url"
              $pipeline = Invoke-RestMethod -Uri $url -Headers @{
                  Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"
              }
              Write-Host "Pipeline = $($pipeline | ConvertTo-Json -Depth 100)"
  env:
     SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Классическое

Чтобы включить скрипт для использования маркера OAuth процесса сборки, выберите задание агента для конвейера, а затем установите флажок разрешить скриптам доступ к маркеру OAuth в разделе "Дополнительные параметры".

Теперь ваш скрипт может использовать переменную среды SYSTEM_ACCESSTOKEN, чтобы получить доступ к REST API Azure Pipelines.

Следующий встроенный скрипт в задаче PowerShell использует REST API Azure Pipelines для получения определения конвейера.

$url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=5.0"
Write-Host "URL: $url"
$pipeline = Invoke-RestMethod -Uri $url -Headers @{
    Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"
}
Write-Host "Pipeline = $($pipeline | ConvertTo-Json -Depth 100)"

Связанный контент

• Номера запуска или сборки
• Задача Azure Pipelines PowerShell
• Azure Pipelines REST API