Scripts do PowerShell para personalizar pipelines

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Este artigo explica como você pode ir além da compilação e do teste de código e usar scripts do PowerShell para adicionar lógica de negócios aos pipelines. A tarefa do PowerShell do Azure Pipelines executa scripts do PowerShell em seus pipelines. Você pode usar o PowerShell para acessar a API REST do Azure DevOps, trabalhar com itens de trabalho e gerenciamento de testes do Azure DevOps ou chamar outros serviços conforme necessário.

Você pode usar variáveis em seus scripts do PowerShell, incluindo variáveis definidas pelo usuário que você mesmo definiu. Você também pode usar variáveis predefinidas que estão disponíveis em todos os Azure Pipelines e definir variáveis de saída de vários trabalhos para disponibilizar variáveis para trabalhos futuros. Para obter mais informações, confira Definir variáveis.

Você pode usar parâmetros nomeados em seus scripts do PowerShell. Outros tipos de parâmetros, como parâmetros de opção, não têm suporte e causam erros se você tentar usá-los. Para obter mais informações, consulte Como declarar parâmetros de cmdlet.

Adicionar um script do PowerShell a um pipeline

O build usa o branch ativo do código. Se a execução do pipeline usar o branch main, o script também usa o branch main.

Você pode executar o Windows PowerShell em um agente de build do Windows ou executar o PowerShell Core em qualquer plataforma. A sintaxe para incluir o PowerShell Core é um pouco diferente da do Windows PowerShell.

Depois de enviar o script do PowerShell por push para o repositório, adicione uma pwsh etapa ou powershell ao pipeline. A pwsh palavra-chave e powershell as palavras-chave são atalhos para executar a tarefa do PowerShell.

Exemplo para o PowerShell Core:

steps:
- pwsh: ./my-script.ps1

Exemplo para Windows PowerShell:

steps:
- powershell: .\my-script.ps1

Exemplo de script para aplicar a versão a assemblies

O script de exemplo nesta seção aplica uma versão aos arquivos de propriedade do assembly. Para que o script seja executado com êxito, o formato de número de compilação definido deve ter quatro pontos, por exemplo $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r).

Observação

O número de compilação também é chamado de número de execução.

Personalize o número de build no pipeline YAML usando a name propriedade. A name propriedade deve estar no nível raiz do pipeline. Para obter mais informações, consulte Configurar números de execução ou compilação.

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

O script de exemplo do PowerShell a seguir aplica uma versão a assemblies. Por exemplo, se o formato $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) de número de compilação definido produzir número Build HelloWorld_2024.07.19.1de compilação , o script aplicará a versão 2024.07.19.1 aos assemblies.

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

Exemplo de script para acessar a API REST

Este exemplo usa a SYSTEM_ACCESSTOKEN variável para acessar a API REST do Azure Pipelines.

Você pode usar $env:SYSTEM_ACCESSTOKEN em um script embutido em seu pipeline YAML para acessar o token OAuth.

O script embutido do PowerShell a seguir em um pipeline YAML usa o token OAuth para acessar a API REST do Azure Pipelines que recupera a definição do pipeline.

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