Script di PowerShell per le pipeline

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

Questo articolo illustra in che modo gli script di PowerShell possono aggiungere logica di business ad Azure Pipelines. L'attività PowerShell v2 (PowerShell@2) esegue script di PowerShell che possono accedere all'API REST di Azure DevOps, usare gli elementi di lavoro di Azure DevOps, gestire i test o chiamare altri servizi.

È possibile usare variabili predefinite o variabili definite dall'utente negli script di PowerShell. È anche possibile impostare variabili di output multi-processo per rendere le variabili disponibili per altri processi. Per altre informazioni, vedere Definire le variabili.

È anche possibile usare parametri denominati negli script di PowerShell. Altri tipi di parametri, ad esempio parametri switch, non sono supportati. Per altre informazioni, vedere Come dichiarare i parametri dei cmdlet.

Attività script di PowerShell

Per usare uno script di PowerShell, aggiungere l'attività PowerShell v2 (PowerShell@2) alla pipeline e quindi immettere uno script di PowerShell inline o chiamare un file di script di PowerShell.

La build utilizza la branch attiva del tuo codice. Se l'esecuzione della tua pipeline utilizza il ramo main del codice del tuo progetto, anche il tuo script utilizza il ramo main del codice.

YAML

Nell'esempio seguente viene usato targetType: 'inline' e viene aggiunto uno script inline nella proprietà script.

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

Nell'esempio seguente viene aggiunto il PowerShell@2 passaggio a una pipeline YAML. Il codice richiama un file di script di PowerShell denominato test.ps1 che si trova nella radice del repository.

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

Nota

Per impostazione predefinita, l'attività PowerShell@2 usa Windows PowerShell 5.1 per gli agenti Windows e PowerShell 7.x per gli agenti Linux/macOS. Per usare PowerShell 7.x negli agenti Windows, è necessario che PowerShell 7.x sia installato e che il parametro pwsh sia impostato su true. Per impostazione predefinita, gli agenti ospitati da Microsoft hanno Installato PowerShell 7.x.

È anche possibile aggiungere una pwsh fase o una powershell alla pipeline YAML come scorciatoia per la fase PowerShell@2. Il pwsh collegamento esegue PowerShell 7.x in macOS, Linux o Windows. Il powershell collegamento esegue Windows PowerShell 5.1 in Windows o PowerShell 7.x in Linux e macOS.

steps:
- pwsh: test.ps1

steps:
- pwsh: Write-Host Hello

Classico

1. In una pipeline classica, devi aggiungere l'attività PowerShell nella tua pipeline.

2. Nel riquadro di PowerShell selezionare Percorso file o Inline in Tipo.

   • Se si sceglie Percorso file, l'impostazione predefinita, aggiungere il percorso del file di script relativo alla directory di lavoro in Percorso script.
   • Per Inline immettere i comandi di PowerShell nel campo Script .

   

Nota

Per impostazione predefinita, l'attività di PowerShell v2 usa Windows PowerShell 5.1 per gli agenti Windows e PowerShell 7.x per gli agenti Linux/macOS. Per usare PowerShell 7.x negli agenti Windows, selezionare Usa PowerShell Core in Opzioni avanzate nel riquadro PowerShell. È necessario che PowerShell 7.x sia installato, che gli agenti ospitati da Microsoft eseguono per impostazione predefinita.

Script di esempio per applicare la versione agli assembly

Lo script di PowerShell seguente applica una versione basata sul numero di build agli assembly. Ad esempio, se la definizione $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) del formato del numero di build produce il numero di build Build HelloWorld_2024.07.19.1, lo script applica la versione 2024.07.19.1 agli assembly.

Affinché questo script venga eseguito correttamente, il formato del numero di build deve avere quattro segmenti. Per altre informazioni, vedere Eseguire o compilare numeri.

Nota

Il numero di build viene chiamato anche numero di esecuzione.

YAML

1. Personalizza la definizione del numero di build nella pipeline YAML usando la proprietà name al livello principale della pipeline.

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

2. Salvare lo script di PowerShell seguente come file nella radice del repository.

3. Aggiungere un passaggio dell'attività oppure un collegamento PowerShell@2 o pwsh alla pipeline, e chiamare il percorso del file dello script PowerShell rispetto alla directory di lavoro.

Classico

1. Nella pipeline classica specificare il formato del numero di build nella scheda Opzioni in Formato numero di build. Ad esempio, immettere $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r).

   

2. Salvare lo script di PowerShell seguente come file nella radice del repository.

3. Aggiungere un'attività PowerShell alla pipeline e specificare il percorso del file di script PowerShell rispetto alla directory di lavoro.

Script di PowerShell per applicare la versione agli assembly:

# 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 di esempio per accedere all'API REST

Lo script di PowerShell seguente usa le variabili di ambiente per accedere all'API REST di Azure Pipelines e recuperare la definizione della pipeline.

YAML

Nella pipeline YAML è possibile definire la variabile $env:SYSTEM_ACCESSTOKEN di ambiente in un'attività PowerShell@2 e usarla nello script inline per ottenere il token OAuth per accedere all'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)

Classico

Per consentire allo script di utilizzare il token OAuth del processo di compilazione, selezionare il lavoro Agente per la pipeline e poi selezionare la casella di controllo Consenti agli script di accedere al token OAuth sotto Opzioni aggiuntive.

Lo script può ora usare la SYSTEM_ACCESSTOKEN variabile di ambiente per accedere all'API REST di Azure Pipelines.

Lo script inline seguente in un'attività di PowerShell usa l'API REST di Azure Pipelines per recuperare la definizione della 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)"

Contenuto correlato

• Numeri di esecuzione o compilazione
• Attività di PowerShell di Azure Pipelines
• Azure Pipelines REST API