Uso de un script de PowerShell para personalizar una canalización

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

Cuando esté listo para ir más allá de los aspectos básicos de la compilación y prueba del código, use un script de PowerShell para agregar la lógica de negocios del equipo a la canalización de compilación. Puede ejecutar Windows PowerShell en un agente de compilación de Windows. PowerShell Core se ejecuta en cualquier plataforma.

Incorporación de un script de PowerShell

YAML

La sintaxis para incluir PowerShell Core es ligeramente distinta de la sintaxis de Windows PowerShell.

1. Inserte el script de PowerShell en el repositorio.

2. Agregue un paso pwsh o powershell. La palabra clave pwsh es un acceso directo para la tarea de PowerShell para PowerShell Core. La palabra clave powershell es otro acceso directo para la tarea de PowerShell.

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

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

Clásico

1. Agregue la tarea Script de PowerShell a la canalización. La misma tarea de PowerShell funciona para PowerShell Core y Windows PowerShell.

   

2. Agregue el archivo a la ruta de acceso del script.

   

Script de PowerShell de ejemplo: ensamblados de versión

Se trata de un script de ejemplo para la versión de los ensamblados. Para que el script se ejecute correctamente, deberá actualizar el número de compilación para que use un formato con cuatro puntos (ejemplo: $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)). El número de compilación también se puede denominar "número de ejecución".

YAML

Puede personalizar el número de compilación dentro de una canalización YAML con la propiedad name.

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

pool:
  vmImage: windows-latest

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

Clásico

1. Para personalizar el número de compilación en una canalización clásica, agregue primero la tarea de compilación a la canalización.

   

2. A continuación, especifique el número de compilación.

   

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

Script de PowerShell de ejemplo: acceso a la API REST

En este ejemplo, usará la variable SYSTEM_ACCESSTOKEN para acceder a la API REST de Azure Pipelines.

YAML

Puede usar $env:SYSTEM_ACCESSTOKEN en el script en una canalización YAML para acceder al token de 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ásico

Para permitir que el script use el token de OAuth del proceso de compilación, vaya a la pestaña Tareas de la definición de compilación y, en la fase de compilación, seleccione la opción Permitir que los scripts accedan al token de OAuth, que se encuentra en la sección Opciones adicionales.

Una vez que lo haga, el script puede usar para la variable de entorno SYSTEM_ACCESSTOKEN a fin de acceder a la API REST de Azure Pipelines. Por ejemplo:

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

Preguntas más frecuentes

¿Qué variables están disponibles para que las use en mis scripts?

Puede usar variables predefinidas en los scripts. Para más información sobre las variables disponibles y cómo usarlas, consulte Uso de variables predefinidas.

¿Cómo puedo establecer una variable para que los scripts y las tareas posteriores puedan leerla?

Para obtener más información sobre cómo definir variables de compilación en un script, consulte Definición y modificación de las variables de compilación en un script.

Para más información sobre cómo definir variables de versión en un script, consulte Definición y modificación de las variables de versión en un script.

¿Qué rama del script ejecuta la compilación?

La compilación usará la rama activa del código. Si la ejecución de la canalización usa la rama main, el script también usará la rama main.

¿Qué tipos de parámetros puedo usar?

Puede usar parámetros con nombre. No se admiten otros tipos de parámetros, como los parámetros de modificador. Si intenta usar este tipo de parámetros, verá errores.