Utiliser un script PowerShell pour personnaliser votre pipeline

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

Lorsque vous êtes prêt à aller au-delà des principes de base de la compilation et du test de votre code, utilisez un script PowerShell pour ajouter la logique métier de votre équipe à votre pipeline de build. Vous pouvez exécuter Windows PowerShell sur un agent de build Windows. PowerShell Core s’exécute sur toutes les plateformes.

Ajouter un script PowerShell

YAML

La syntaxe pour inclure PowerShell Core est légèrement différente de celle pour Windows PowerShell.

1. Envoyez votre script PowerShell à votre référentiel.

2. Ajoutez une étape pwsh ou powershell. Le mot clé pwsh est un raccourci de la tâche PowerShell pour PowerShell Core. Le mot clé powershell est un autre raccourci pour la tâche PowerShell.

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

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

Classique

1. Ajoutez la tâche Script PowerShell à votre pipeline. La même tâche PowerShell fonctionne pour PowerShell Core et Windows PowerShell.

   

2. Ajoutez votre fichier au chemin d’accès du script.

   

Exemple de script PowerShell : assemblys de version

Voici un exemple de script pour la version de vos assemblys. Pour que le script s’exécute correctement, vous devez mettre à jour votre numéro de build afin d’utiliser un format avec quatre périodes (exemple : $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)). Le numéro de build peut également être appelé numéro d’exécution.

YAML

Vous pouvez personnaliser votre numéro de build dans un pipeline YAML avec la propriété name.

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

pool:
  vmImage: windows-latest

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

Classique

1. Pour personnaliser votre numéro de build dans un pipeline classique, ajoutez d’abord la tâche de build à votre pipeline.

   

2. Ensuite, spécifiez votre numéro 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."
}

Exemple de script PowerShell : accéder à l’API REST

Dans cet exemple, vous allez utiliser la variable SYSTEM_ACCESSTOKEN pour accéder à l’API REST Azure Pipelines.

YAML

Vous pouvez utiliser $env:SYSTEM_ACCESSTOKEN dans votre script au sein d’un pipeline YAML pour accéder au jeton 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)

Classique

Pour permettre à votre script d’utiliser le jeton OAuth du processus de build, accédez à l’onglet Tâches de la définition de build puis, dans votre phase de build, sélectionnez Autoriser les scripts à accéder au jeton OAuth, qui se trouve dans la section Options supplémentaires.

Après cela, votre script peut utiliser SYSTEM_ACCESSTOKEN comme variable d’environnement pour accéder à l’API REST Azure Pipelines. Par exemple :

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

Questions fréquentes (FAQ)

Quelles variables peuvent être utilisées dans mes scripts ?

Vous pouvez utiliser des variables prédéfinies dans vos scripts. Pour plus d’informations sur les variables disponibles et leur utilisation, consultez Utiliser des variables prédéfinies.

Comment définir une variable de manière à ce qu’elle soit lue par les scripts et les tâches suivants ?

Pour en savoir plus sur la définition de variables de build dans un script, consultez Définir et modifier vos variables de build dans un script.

Pour en savoir plus sur la définition de variables de mise en production dans un script, consultez Définir et modifier vos variables de mise en production dans un script.

Quelle branche du script la build exécute-t-elle ?

La build utilise la branche active de votre code. Si votre exécution de pipeline utilise la branche main, votre script utilisera également la branche main.

Quels types de paramètres puis-je utiliser ?

Vous pouvez utiliser des paramètres nommés. D’autres types de paramètres, tels que les paramètres de commutateur, ne sont pas pris en charge. Vous verrez des erreurs si vous essayez d’utiliser des paramètres de commutateur.