PowerShell-Skripts für Pipelines

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

In diesem Artikel wird erläutert, wie PowerShell-Skripts Azure-Pipelines Geschäftslogik hinzufügen können. Die PowerShell v2-Aufgabe (PowerShell@2) führt PowerShell-Skripts aus, die auf die Azure DevOps-REST-API zugreifen können, mit Azure DevOps-Arbeitsaufgaben arbeiten, Tests verwalten oder andere Dienste aufrufen können.

Sie können vordefinierte Variablen oder benutzerdefinierte Variablen in PowerShell-Skripts verwenden. Sie können auch Ausgabevariablen für mehrere Aufträge festlegen, um Variablen für andere Aufträge verfügbar zu machen. Weitere Informationen finden Sie unter Definieren von Variablen.

Sie können auch benannte Parameter in Ihren PowerShell-Skripts verwenden. Andere Arten von Parametern, z. B. Schalterparameter, werden nicht unterstützt. Weitere Informationen finden Sie unter Deklarieren von Cmdlet-Parametern.

PowerShell-Skriptaufgabe

Um ein PowerShell-Skript zu verwenden, fügen Sie der Pipeline die PowerShell v2-Aufgabe (PowerShell@2) hinzu, und geben Sie dann ein Inline-PowerShell-Skript ein, oder rufen Sie eine PowerShell-Skriptdatei auf.

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

YAML

Im folgenden Beispiel werden targetType: 'inline' verwendet und ein Inline-Skript in der script-Eigenschaft hinzugefügt.

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

Im folgenden Beispiel wird der PowerShell@2 Schritt zu einer YAML-Pipeline hinzugefügt. Der Code ruft eine PowerShell-Skriptdatei mit dem Namen test.ps1 im Stammverzeichnis Ihres Repositorys auf.

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

Hinweis

Standardmäßig verwendet die PowerShell@2 Aufgabe Windows PowerShell 5.1 für Windows-Agents und PowerShell 7.x für Linux/macOS-Agents. Um PowerShell 7.x auf Windows-Agents zu verwenden, müssen Sie PowerShell 7.x installiert haben und den Parametersatz hinzufügen, der pwsh auf true. Microsoft-gehostete Agents haben PowerShell 7.x standardmäßig installiert.

Sie können Ihrer YAML-Pipeline auch einen pwsh-Schritt oder powershell-Schritt als Abkürzung für zum PowerShell@2-Schritt hinzufügen. Die pwsh Tastenkombination führt PowerShell 7.x unter macOS, Linux oder Windows aus. Die powershell Verknüpfung führt Windows PowerShell 5.1 unter Windows oder PowerShell 7.x unter Linux und macOS aus.

steps:
- pwsh: test.ps1

steps:
- pwsh: Write-Host Hello

Klassisch

1. Fügen Sie eine PowerShell-Aufgabe zu einer klassischen Pipeline hinzu.

2. Wählen Sie im PowerShell-Bereich entweder "Dateipfad " oder " Inline " unter "Typ" aus.

   • Wenn Sie den Dateipfad auswählen, die Standardeinstellung, fügen Sie den Pfad Ihrer Skriptdatei relativ zum Arbeitsverzeichnis unter Skriptpfad hinzu.
   • Geben Sie für "Inline" Ihre PowerShell-Befehle in das Feld "Skript " ein.

   

Hinweis

Standardmäßig verwendet die PowerShell v2-Aufgabe Windows PowerShell 5.1 für Windows-Agents und PowerShell 7.x für Linux/macOS-Agents. Um PowerShell 7.x für Windows-Agents zu verwenden, wählen Sie "PowerShell Core verwenden" unter "Erweiterte Optionen " im PowerShell-Bereich aus. Sie müssen PowerShell 7.x installiert haben, die von Microsoft gehostete Agents standardmäßig ausführen.

Beispielskript zum Anwenden der Version auf Assemblys

Das folgende PowerShell-Skript wendet eine Version basierend auf der Buildnummer auf Assemblys an. Wenn ihre Buildnummernformatdefinition $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) beispielsweise die Buildnummer Build HelloWorld_2024.07.19.1 erzeugt, wendet das Skript Version 2024.07.19.1 auf Ihre Assemblys an.

Damit dieses Skript erfolgreich ausgeführt werden kann, muss das Buildnummernformat vier Segmente aufweisen. Weitere Informationen finden Sie unter Ausführen oder Erstellen von Nummern.

Hinweis

Buildnummer wird auch als Ausführungsnummer bezeichnet.

YAML

1. Passen Sie Die Buildnummerndefinition in der YAML-Pipeline mithilfe der name Eigenschaft auf der Stammebene der Pipeline an.

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

2. Speichern Sie das folgende PowerShell-Skript als Datei im Stammverzeichnis Ihres Repositorys.

3. Fügen Sie Ihrer Pipeline einen PowerShell@2 Task-Schritt oder eine pwsh oder powershell Verknüpfung hinzu, und rufen Sie den Dateipfad der PowerShell-Skriptdatei relativ zum Arbeitsverzeichnis auf.

Klassisch

1. Geben Sie in der Klassischen Pipeline das Buildnummernformat auf der Registerkarte Optionen unter Buildnummernformat an. Geben Sie beispielsweise $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) ein.

   

2. Speichern Sie das folgende PowerShell-Skript als Datei im Stammverzeichnis Ihres Repositorys.

3. Fügen Sie Ihrer Pipeline eine PowerShell-Aufgabe hinzu, und rufen Sie den Dateipfad der PowerShell-Skriptdatei relativ zum Arbeitsverzeichnis auf.

PowerShell-Skript zum Anwenden der Version auf Assemblys:

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

Beispielskript für den Zugriff auf die REST-API

Das folgende PowerShell-Skript verwendet Umgebungsvariablen, um auf die REST-API von Azure Pipelines zuzugreifen und die Pipelinedefinition abzurufen.

YAML

In Ihrer YAML-Pipeline können Sie die Umgebungsvariable $env:SYSTEM_ACCESSTOKEN in einer PowerShell@2 Aufgabe definieren und im Inlineskript verwenden, um das OAuth-Token für den Zugriff auf die REST-API abzurufen.

- 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

Um Ihrem Skript die Nutzung des OAuth-Tokens im Buildprozess zu ermöglichen, wählen Sie den Agent-Job für Ihre Pipeline aus, und aktivieren Sie dann das Kontrollkästchen für Skripts den Zugriff auf das OAuth-Token erlauben unter Zusätzliche Optionen.

Ihr Skript kann jetzt die SYSTEM_ACCESSTOKEN Umgebungsvariable verwenden, um auf die REST-API von Azure Pipelines zuzugreifen.

Das folgende Inlineskript in einer PowerShell-Aufgabe verwendet die Rest-API von Azure Pipelines, um die Pipelinedefinition abzurufen.

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

Zugehöriger Inhalt

• Ausführen oder Erstellen von Nummern
• PowerShell-Aufgabe von Azure Pipelines
• REST-API für Azure Pipelines