Scripts PowerShell pour les pipelines

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

Cet article explique comment les scripts PowerShell peuvent ajouter une logique métier à Azure Pipelines. La tâche PowerShell v2 (PowerShell@2) exécute des scripts PowerShell qui peuvent accéder à l’API REST Azure DevOps, utiliser des éléments de travail Azure DevOps, gérer des tests ou appeler d’autres services.

Vous pouvez utiliser des variables prédéfinies ou des variables définies par l’utilisateur dans des scripts PowerShell. Vous pouvez également définir des variables de sortie pour plusieurs travaux pour rendre les variables disponibles pour d'autres travaux. Pour plus d’informations, consultez Définir des variables.

Vous pouvez également utiliser des paramètres nommés dans vos scripts PowerShell. D’autres types de paramètres, tels que les paramètres de commutateur, ne sont pas pris en charge. Pour plus d’informations, consultez Comment déclarer des paramètres d’applet de commande.

Tâche de script PowerShell

Pour utiliser un script PowerShell, vous ajoutez la tâche PowerShell v2 (PowerShell@2) à votre pipeline, puis entrez un script PowerShell inline ou appelez un fichier de script PowerShell.

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

YAML

L’exemple suivant utilise targetType: 'inline' et ajoute un script inline dans la script propriété.

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

L’exemple suivant ajoute l’étape PowerShell@2 à un pipeline YAML. Le code appelle un fichier de script PowerShell nommé test.ps1 situé à la racine de votre référentiel.

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

Remarque

Par défaut, la PowerShell@2 tâche utilise Windows PowerShell 5.1 pour les agents Windows et PowerShell 7.x pour les agents Linux/macOS. Pour utiliser PowerShell 7.x sur les agents Windows, vous devez avoir installé PowerShell 7.x. et ajouter le pwsh paramètre défini sur true. Les agents hébergés par Microsoft ont installé PowerShell 7.x par défaut.

Vous pouvez également ajouter une étape pwsh ou powershell à votre pipeline YAML en tant que raccourci pour l’étape PowerShell@2. Le pwsh raccourci exécute PowerShell 7.x sur macOS, Linux ou Windows. Le powershell raccourci exécute Windows PowerShell 5.1 sur Windows ou PowerShell 7.x sur Linux et macOS.

steps:
- pwsh: test.ps1

steps:
- pwsh: Write-Host Hello

Classique

1. Dans un pipeline Classique, ajoutez la tâche PowerShell à votre pipeline.

2. Dans le volet PowerShell , sélectionnez Chemin d’accès au fichier ou inline sous Type.

   • Si vous choisissez Chemin du fichier, la valeur par défaut, ajoutez l’emplacement de votre fichier de script par rapport au répertoire de travail sous Chemin de script.
   • Pour Inline, entrez vos commandes PowerShell dans le champ Script .

   

Remarque

Par défaut, la tâche PowerShell v2 utilise Windows PowerShell 5.1 pour les agents Windows et PowerShell 7.x pour les agents Linux/macOS. Pour utiliser PowerShell 7.x sur les agents Windows, sélectionnez Utiliser PowerShell Core sous Options avancées dans le volet PowerShell. PowerShell 7.x doit être installé, que les agents hébergés par Microsoft effectuent par défaut.

Exemple de script pour appliquer la version aux assemblys

Le script PowerShell suivant applique une version basée sur le numéro de build aux assemblys. Par exemple, si votre définition $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) de format de numéro de build produit le numéro de build build HelloWorld_2024.07.19.1, le script applique la version 2024.07.19.1 à vos assemblys.

Pour que ce script s’exécute correctement, votre format de numéro de build doit avoir quatre segments. Pour plus d’informations, consultez Exécuter ou générer des numéros.

Remarque

Le numéro de build est également appelé numéro d’exécution.

YAML

1. Personnalisez votre définition de numéro de build dans le pipeline YAML à l’aide de la name propriété au niveau racine du pipeline.

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

2. Enregistrez le script PowerShell suivant en tant que fichier à la racine de votre dépôt.

3. Ajoutez une PowerShell@2 étape de tâche, ou un raccourci pwsh ou powershell à votre pipeline, et appelez le chemin d’accès du fichier de script PowerShell, par rapport au répertoire de travail.

Classique

1. Dans votre pipeline Classique, spécifiez votre format de numéro de build sous l’onglet Options sous format Numéro de build. Par exemple, saisissez $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r).

   

2. Enregistrez le script PowerShell suivant en tant que fichier à la racine de votre dépôt.

3. Ajoutez une tâche PowerShell à votre pipeline et appelez le chemin du fichier de script PowerShell, par rapport au répertoire de travail.

Script PowerShell pour appliquer la version aux assemblies :

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

Exemple de script pour accéder à l’API REST

Le script PowerShell suivant utilise des variables d’environnement pour accéder à l’API REST Azure Pipelines et récupérer la définition du pipeline.

YAML

Dans votre pipeline YAML, vous pouvez définir la variable $env:SYSTEM_ACCESSTOKEN environnementale dans une PowerShell@2 tâche et l’utiliser dans le script inline pour obtenir le jeton OAuth pour accéder à l’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)

Classique

Pour permettre à votre script d’utiliser le jeton OAuth du processus de génération, sélectionnez le travail Agent pour votre pipeline, puis cochez la case Autoriser les scripts à accéder au jeton OAuth sous Options supplémentaires.

Votre script peut désormais utiliser la SYSTEM_ACCESSTOKEN variable d’environnement pour accéder à l’API REST Azure Pipelines.

Le script inline suivant dans une tâche PowerShell utilise l’API REST Azure Pipelines pour récupérer la définition du 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)"

Contenu connexe

• Numéros de version ou de build
• Tâche PowerShell Azure Pipelines
• Azure Pipelines REST API