Usar um script do PowerShell para personalizar seu pipeline

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

Quando estiver pronto para ir além dos conceitos básicos de compilar e testar seu código, use um script do PowerShell para adicionar a lógica de negócios da sua equipe ao pipeline de build. Você pode executar o Windows PowerShell em um agente de build do Windows. O PowerShell Core é executado em qualquer plataforma.

Adicionar um script do PowerShell

YAML

A sintaxe para incluir o PowerShell Core é ligeiramente diferente da sintaxe para Windows PowerShell.

1. Envie seu script do PowerShell por push para o repositório.

2. Adicione uma etapa pwsh ou powershell. A palavra-chave pwsh é um atalho para a tarefa do PowerShell para o PowerShell Core. A palavra-chave powershell é outro atalho para a tarefa do PowerShell.

# for PowerShell Core
steps:
- pwsh: ./my-script.ps1

# for Windows PowerShell
steps:
- powershell: .\my-script.ps1

Clássico

1. Adicione a tarefa Script do PowerShell ao pipeline. A mesma tarefa do PowerShell funciona para o PowerShell Core e o Windows PowerShell.

   

2. Adicione o seu arquivo ao Caminho do Script.

   

Exemplo de script do PowerShell: assemblies de versão

Aqui está um script de exemplo para a versão de seus assemblies. Para que o script seja executado com êxito, você precisará atualizar o número de build para usar um formato com quatro períodos (exemplo: $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)). O número de build também pode ser chamado de número de execução.

YAML

Você pode personalizar o número de build em um pipeline YAML com a propriedade name.

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

pool:
  vmImage: windows-latest

steps:
- pwsh: echo $(Build.BuildNumber) //output updated build number

Clássico

1. Para personalizar o número de build em um pipeline clássico, primeiro adicione a tarefa de build ao pipeline.

   

2. Em seguida, especifique o número de build.

   

# If found use it to version the assemblies.
#
# For example, if the 'Build number format' build pipeline parameter 
# $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)
# then your build numbers come out like this:
# "Build HelloWorld_2013.07.19.1"
# This script would then apply version 2013.07.19.1 to your assemblies.
	
# Enable -Verbose option
[CmdletBinding()]
	
# Regular expression pattern to find the version in the build number 
# and then apply it to the assemblies
$VersionRegex = "\d+\.\d+\.\d+\.\d+"
	
# If this script is not running on a build server, remind user to 
# set environment variables so that this script can be debugged
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\FabrikamTFVC\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 is 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 "Could not find version number data in BUILD_BUILDNUMBER."
         exit 1
      }
   1 {}
   default 
      { 
         Write-Warning "Found more than instance of version data in BUILD_BUILDNUMBER." 
         Write-Warning "Will assume 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 "Will apply $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 do PowerShell: acessar a API REST

Neste exemplo, você usará a variável SYSTEM_ACCESSTOKEN para acessar a API REST do Azure Pipelines.

YAML

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

- 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 o script use o token OAuth do processo de build, vá para a guia Tarefas da definição de build e, na fase de build, selecione Permitir Scripts para Acessar o Token OAuth, que está localizado na seção Opções adicionais.

Depois de fazer isso, seu script pode ser usado para a variável de ambiente SYSTEM_ACCESSTOKEN para acessar a API REST do Azure Pipelines. Por exemplo:

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

Perguntas frequentes

Quais variáveis estão disponíveis para uso em meus scripts?

Você pode usar variáveis predefinidas em seus scripts. Para obter mais informações sobre variáveis disponíveis e como usá-las, confira Usar variáveis predefinidas.

Como fazer para definir uma variável para que ela possa ser lida por scripts e tarefas subsequentes?

Para saber mais sobre como definir variáveis de build em um script, confira Definir e modificar suas variáveis de build em um script.

Para saber mais sobre como definir variáveis de versão em um script, confira Definir e modificar suas variáveis de versão em um script

Em qual branch do script o build é executado?

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

Que tipos de parâmetros posso usar?

Você pode usar parâmetros nomeados. Não há suporte para outros tipos de parâmetros, como parâmetros de opção. Você verá erros se tentar usar parâmetros de opção.