Verwenden eines PowerShell-Skripts zum Anpassen Ihrer Pipeline

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

Wenn Sie bereit sind, über die Grundlagen des Kompilierens und Testens Ihres Codes hinauszugehen, verwenden Sie ein PowerShell-Skript, um die Geschäftslogik Ihres Teams zu Ihrer Buildpipeline hinzuzufügen. Sie können Windows PowerShell auf einem Windows-Build-Agent ausführen. PowerShell Core kann auf einer beliebigen Plattform ausgeführt werden.

Hinzufügen eines PowerShell-Skripts

YAML

Die Syntax für das Einschließen von PowerShell Core unterscheidet sich geringfügig von der Syntax für Windows PowerShell.

1. Pushen Sie Ihr PowerShell-Skript an Ihr Repository.

2. Fügen Sie einen pwsh- oder powershell-Schritt hinzu. Das pwsh-Schlüsselwort ist eine Verknüpfung für den PowerShell-Task für PowerShell Core. Das powershell-Schlüsselwort ist eine weitere Verknüpfung für den PowerShell-Task.

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

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

Klassisch

1. Fügen Sie der Pipeline den PowerShell-Skripttask hinzu. Für PowerShell Core und Windows PowerShell kann der gleiche PowerShell-Task genutzt werden.

   

2. Fügen Sie Ihre Datei zum Skriptpfad hinzu.

   

PowerShell-Beispielskript: Versionsassemblys

Hier sehen Sie ein Beispielskript für die Versionsverwaltung Ihrer Assemblys. Damit das Skript erfolgreich ausgeführt werden kann, müssen Sie Ihre Buildnummer aktualisieren, um ein Format mit vier Punkten zu verwenden (Beispiel: $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)). Die Buildnummer wird auch als Ausführungsnummer bezeichnet.

YAML

Sie können Ihre Buildnummer in einer YAML-Pipeline mit der name-Eigenschaft anpassen.

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

pool:
  vmImage: windows-latest

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

Klassisch

1. Um Ihre Buildnummer in einer klassischen Pipeline anzupassen, fügen Sie zuerst den Buildtask zu Ihrer Pipeline hinzu.

   

2. Geben Sie als Nächstes Ihre Buildnummer an.

   

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

PowerShell-Beispielskript: Zugriff auf REST-API

In diesem Beispiel verwenden Sie die Variable SYSTEM_ACCESSTOKEN, um auf die Azure Pipelines-REST-API zuzugreifen.

YAML

Sie können $env:SYSTEM_ACCESSTOKEN in Ihrem Skript in einer YAML-Pipeline verwenden, um auf das OAuth-Token zuzugreifen.

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

Klassisch

Damit Ihr Skript das OAuth-Token des Buildprozesses verwenden kann, wechseln Sie zur Registerkarte Tasks der Builddefinition, und wählen Sie in Ihrer Buildphase die Option Skripts Zugriff auf das OAuth-Token erlauben aus, die sich im Abschnitt Zusätzliche Optionen befindet.

Danach kann Ihr Skript verwenden, um die Umgebungsvariable SYSTEM_ACCESSTOKEN für den Zugriff auf die Azure Pipelines-REST-API zu nutzen. Beispiel:

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

Häufig gestellte Fragen

Welche Variablen stehen mir in meinen Skripts zur Verfügung?

Sie können vordefinierte Variablen in Ihren Skripts verwenden. Weitere Informationen zu verfügbaren Variablen und deren Verwendung finden Sie unter Verwenden vordefinierter Variablen.

Wie lege ich eine Variable so fest, dass sie von nachfolgenden Skripts und Aufgaben gelesen werden kann?

Weitere Informationen zum Definieren von Buildvariablen in einem Skript finden Sie unter Definieren und Ändern Ihrer Buildvariablen in einem Skript.

Weitere Informationen zum Definieren von Releasevariablen in einem Skript finden Sie unter Definieren und Ändern Ihrer Releasevariablen in einem Skript.

Welcher Branch des Skripts wird vom Build ausgeführt?

Der Build verwendet den aktiven Branch Ihres Codes. Wenn die Pipelineausführung den main-Branch verwendet, verwendet auch Ihr Skript den main-Branch.

Welche Arten von Parametern kann ich verwenden?

Sie können benannte Parameter verwenden. Andere Arten von Parametern, z. B. Schalterparameter, werden nicht unterstützt. Wenn Sie versuchen, Schalterparameter zu verwenden, werden Fehler angezeigt.