Scripts de PowerShell para canalizaciones

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

En este artículo se explica cómo los scripts de PowerShell pueden agregar lógica de negocios a Azure Pipelines. La tarea de PowerShell v2 (PowerShell@2) ejecuta scripts de PowerShell que pueden acceder a la API rest de Azure DevOps, trabajar con elementos de trabajo de Azure DevOps, administrar pruebas o llamar a otros servicios.

Puede usar variables predefinidas o variables definidas por el usuario en scripts de PowerShell. También puede establecer variables de salida de varios trabajos para que las variables estén disponibles para otros trabajos. Para obtener más información, consulte Definición de variables.

También puede usar parámetros con nombre en los scripts de PowerShell. No se admiten otros tipos de parámetros, como los parámetros de modificador. Para obtener más información, consulte Cómo declarar parámetros de cmdlet.

Tarea de script de PowerShell

Para usar un script de PowerShell, agregue la tarea PowerShell v2 (PowerShell@2) a la canalización y, a continuación, escriba un script de PowerShell en línea o llame a un archivo de script de PowerShell.

La compilación usa la rama activa del código. Si tu ejecución de pipeline usa la rama main de tu código, tu script también utilizará la rama main.

YAML

En el siguiente ejemplo se usa targetType: 'inline' y se agrega un script en línea en la propiedad script.

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

En el ejemplo siguiente se agrega el paso PowerShell@2 a una canalización YAML. El código invoca un archivo de script de PowerShell denominado test.ps1 ubicado en la raíz del repositorio.

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

Nota:

De forma predeterminada, la PowerShell@2 tarea usa Windows PowerShell 5.1 para agentes de Windows y PowerShell 7.x para agentes de Linux/macOS. Para usar PowerShell 7.x en los agentes de Windows, debe tener PowerShell 7.x instalado y agregar el pwsh parámetro establecido en true. Los agentes hospedados por Microsoft tienen PowerShell 7.x instalado de forma predeterminada.

También puede agregar un pwsh paso o un powershell paso a la canalización de YAML como acceso directo para el PowerShell@2 paso. El pwsh acceso directo ejecuta PowerShell 7.x en macOS, Linux o Windows. El powershell acceso directo ejecuta Windows PowerShell 5.1 en el sistema operativo Windows o PowerShell 7.x en los sistemas operativos Linux y macOS.

steps:
- pwsh: test.ps1

steps:
- pwsh: Write-Host Hello

Clásico

1. En una canalización clásica, agregue la tarea PowerShell a tu canalización.

2. En el panel de PowerShell, seleccione Ruta de acceso de archivo o Insertada en Tipo.

   • Si elige Ruta de archivo, el valor predeterminado, agregue la ubicación de su archivo de script en relación con el directorio de trabajo en Ruta de acceso del script.
   • Para Inline, escriba los comandos de PowerShell en el campo Script.

   

Nota:

De forma predeterminada, la tarea de PowerShell v2 usa Windows PowerShell 5.1 para agentes de Windows y PowerShell 7.x para agentes de Linux/macOS. Para usar PowerShell 7.x en agentes de Windows, seleccione Usar PowerShell Core en Opciones avanzadas en el panel de PowerShell. Debe tener Instalado PowerShell 7.x, que los agentes hospedados por Microsoft hacen de forma predeterminada.

Script de ejemplo para aplicar la versión a los ensamblados

El siguiente script de PowerShell aplica una versión basada en el número de compilación a los ensamblados. Por ejemplo, si la definición $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) del formato de número de compilación genera el número de compilación Build HelloWorld_2024.07.19.1, el script aplica la versión 2024.07.19.1 a los ensamblados.

Para que este script se ejecute correctamente, el formato de número de compilación debe tener cuatro segmentos. Para obtener más información, vea Ejecutar o compilar números.

Nota:

El número de compilación también se denomina número de ejecución.

YAML

1. Personalice la definición del número de compilación en la canalización YAML utilizando la propiedad name en el nivel raíz de la canalización.

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

2. Guarde el siguiente script de PowerShell como un archivo en la raíz del repositorio.

3. Agregue un paso de tarea PowerShell@2, pwsh o un acceso directo powershell a la canalización, y especifique la ruta del archivo del script de PowerShell, en relación con el directorio de trabajo.

Clásico

1. En la canalización clásica, especifique el formato del número de compilación en la pestaña Opciones en Formato de número de compilación. Por ejemplo, escriba $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r).

   

2. Guarde el siguiente script de PowerShell como un archivo en la raíz del repositorio.

3. Agregue una tarea de PowerShell a la canalización, y utilice la ruta de acceso del archivo de script de PowerShell, relativa al directorio de trabajo.

Script de PowerShell para aplicar la versión a los ensamblajes:

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

Script de ejemplo para acceder a la API REST

El siguiente script de PowerShell usa variables de entorno para acceder a la API REST de Azure Pipelines y recuperar la definición de canalización.

YAML

En la canalización de YAML, puede definir la variable $env:SYSTEM_ACCESSTOKEN de entorno en una PowerShell@2 tarea y usarla en el script en línea para obtener el token de OAuth para acceder a la 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ásico

Para permitir que el script use el token de OAuth del proceso de compilación, seleccione el trabajo del Agente para la canalización y, a continuación, active la casilla Permitir que los scripts accedan al token de OAuth en Opciones adicionales.

El script ahora puede usar la SYSTEM_ACCESSTOKEN variable de entorno para acceder a la API REST de Azure Pipelines.

El siguiente script insertado en una tarea de PowerShell usa la API REST de Azure Pipelines para recuperar la definición de la canalización.

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

Contenido relacionado

• Ejecutar o compilar números
• Tarea de PowerShell de Azure Pipelines
• Azure Pipelines REST API