Scripts do PowerShell para pipelines

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Este artigo explica como os scripts do PowerShell podem adicionar lógica de negócios aos Pipelines do Azure. A tarefa PowerShell v2 (PowerShell@2) executa scripts do PowerShell que podem acessar a API REST do Azure DevOps, trabalhar com itens de trabalho do Azure DevOps, gerenciar testes ou chamar outros serviços.

Você pode usar variáveis predefinidas ou variáveis definidas pelo usuário em scripts do PowerShell. Você também pode definir variáveis de saída de vários trabalhos para disponibilizar variáveis para outros trabalhos. Para obter mais informações, consulte Definir variáveis.

Você também pode usar parâmetros nomeados em seus scripts do PowerShell. Outros tipos de parâmetros, como parâmetros de switch, não são suportados. Para obter mais informações, consulte Como declarar parâmetros de cmdlet.

Tarefa de script do PowerShell

Para usar um script do PowerShell, adicione a tarefa PowerShell v2 (PowerShell@2) ao seu pipeline e insira um script do PowerShell embutido ou chame um arquivo de script do PowerShell.

A compilação usa a ramificação ativa do seu código. Se a execução do pipeline usar a main ramificação do código, o script também usará a main ramificação.

YAML

O exemplo a targetType: 'inline' seguir usa script e adiciona um script embutido na propriedade.

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

O exemplo a seguir adiciona a PowerShell@2 etapa a um pipeline YAML. O código invoca um arquivo de script do PowerShell chamado test.ps1 localizado na raiz do repositório.

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

Nota

Por padrão, a tarefa usa agentes do PowerShell@2 Windows PowerShell 5.1 para Windows e PowerShell 7.x para agentes Linux/macOS. Para usar o PowerShell 7.x em agentes do Windows, você deve ter o PowerShell 7.x. instalado e adicionar o pwsh parâmetro definido como true. Os agentes hospedados pela Microsoft têm o PowerShell 7.x instalado por padrão.

Você também pode adicionar uma pwsh ou powershell etapa ao seu pipeline YAML como um atalho para a PowerShell@2 etapa. O atalho executa o pwsh PowerShell 7.x no macOS, Linux ou Windows. O atalho executa o powershell Windows PowerShell 5.1 no Windows ou o PowerShell 7.x no Linux e macOS.

steps:
- pwsh: test.ps1

steps:
- pwsh: Write-Host Hello

Clássico

1. Em um pipeline Clássico, adicione a tarefa PowerShell ao seu pipeline.

2. No painel do PowerShell, selecione Caminho do Arquivo ou Inline em Tipo.

   • Se você escolher Caminho do arquivo, o padrão, adicione o local do arquivo de script relativo ao diretório de trabalho em Caminho do script.
   • Para Inline, insira seus comandos do PowerShell no campo Script .

   

Nota

Por padrão, a tarefa PowerShell v2 usa agentes do Windows PowerShell 5.1 para Windows e PowerShell 7.x para agentes Linux/macOS. Para usar o PowerShell 7.x em agentes do Windows, selecione Usar o PowerShell Core em Opções avançadas no painel do PowerShell. Você deve ter o PowerShell 7.x. instalado, o que os agentes hospedados pela Microsoft fazem por padrão.

Exemplo de script para aplicar a versão a assemblies

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

Para que esse script seja executado com êxito, seu formato de número de compilação deve ter quatro segmentos. Para obter mais informações, consulte Executar ou compilar números.

Nota

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

YAML

1. Personalize sua definição de número de compilação no pipeline YAML usando a name propriedade no nível raiz do pipeline.

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

2. Salve o seguinte script do PowerShell como um arquivo na raiz do repositório.

3. Adicione uma PowerShell@2 etapa de tarefa ou pwshpowershell atalho ao seu pipeline e chame o caminho do arquivo de script do PowerShell, relativo ao diretório de trabalho.

Clássico

1. No pipeline Clássico, especifique o formato do número de compilação na guia Opções em Formato do número de compilação. Por exemplo, digite $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r).

   

2. Salve o seguinte script do PowerShell como um arquivo na raiz do repositório.

3. Adicione uma tarefa do PowerShell ao seu pipeline e chame o caminho do arquivo de script do PowerShell, relativo ao diretório de trabalho.

Script do PowerShell para aplicar a versão 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

O script PowerShell a seguir usa variáveis de ambiente para acessar a API REST do Azure Pipelines e recuperar a definição de pipeline.

YAML

Em seu pipeline YAML, você pode definir a variável $env:SYSTEM_ACCESSTOKEN ambiental em uma PowerShell@2 tarefa e usá-la no script embutido para obter o token OAuth para acessar a API REST.

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

Clássico

Para permitir que seu script use o token OAuth do processo de compilação, selecione o trabalho Agente para seu pipeline e marque a caixa de seleção Permitir que scripts acessem o token OAuth em Opções adicionais.

Seu script agora pode usar a SYSTEM_ACCESSTOKEN variável de ambiente para acessar a API REST do Azure Pipelines.

O script embutido a seguir em uma tarefa do PowerShell usa a API REST do Azure Pipelines para recuperar a definição de pipeline.

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

Conteúdos relacionados

• Executar ou construir números
• Tarefa do Azure Pipelines PowerShell
• Azure Pipelines REST API