Skrypty programu PowerShell dla potoków

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

W tym artykule wyjaśniono, jak skrypty programu PowerShell mogą dodawać logikę biznesową do usługi Azure Pipelines. Zadanie programu PowerShell w wersji 2 (PowerShell@2) uruchamia skrypty programu PowerShell, które mogą uzyskiwać dostęp do interfejsu API REST usługi Azure DevOps, pracować z elementami roboczymi usługi Azure DevOps, zarządzać testami lub wywoływać inne usługi.

W skryptach programu PowerShell można użyć wstępnie zdefiniowanych zmiennych lub zmiennych zdefiniowanych przez użytkownika . Można również ustawić zmienne wyjściowe wielozadaniowe, aby udostępnić zmienne innym zadaniom. Aby uzyskać więcej informacji, zobacz Definiowanie zmiennych.

Możesz również użyć nazwanych parametrów w skryptach programu PowerShell. Inne rodzaje parametrów, takich jak parametry przełącznika, nie są obsługiwane. Aby uzyskać więcej informacji, zobacz Jak zadeklarować parametry polecenia cmdlet.

Zadanie skryptu programu PowerShell

Aby użyć skryptu PowerShell, należy dodać zadanie PowerShell v2 (PowerShell@2) do potoku, a następnie wprowadzić wewnętrzny skrypt PowerShell lub wywołać plik skryptu PowerShell.

Kompilacja używa aktywnej gałęzi kodu. Jeśli uruchomienie potoku używa gałęzi main kodu, to skrypt również używa gałęzi main.

YAML

W poniższym przykładzie użyto targetType: 'inline' i dodano skrypt wbudowany we właściwości script.

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

Poniższy przykład dodaje PowerShell@2 krok do potoku YAML. Kod wywołuje plik skryptu programu PowerShell o nazwie test.ps1 znajdujący się w katalogu głównym repozytorium.

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

Uwaga

Domyślnie PowerShell@2 zadanie używa programu Windows PowerShell 5.1 dla agentów systemu Windows i programu PowerShell 7.x dla agentów systemu Linux/macOS. Aby używać programu PowerShell 7.x na agentach systemu Windows, musisz mieć zainstalowany program PowerShell 7.x. i dodać pwsh parametr ustawiony na true. Agenci hostowani przez firmę Microsoft domyślnie mają zainstalowany program PowerShell 7.x.

Możesz również dodać krok pwsh lub powershell do potoku YAML jako skrót do kroku PowerShell@2. Skrót pwsh uruchamia program PowerShell 7.x w systemach macOS, Linux lub Windows. Skrót powershell uruchamia program Windows PowerShell 5.1 w systemie Windows lub PowerShell 7.x w systemach Linux i macOS.

steps:
- pwsh: test.ps1

steps:
- pwsh: Write-Host Hello

Klasyczny

1. W potoku klasycznym dodaj zadanie programu PowerShell do potoku.

2. W okienku programu PowerShell wybierz ścieżkę pliku lub śródliniowy w obszarze Typ.

   • Jeśli wybierzesz opcję Ścieżka pliku, domyślnie dodaj lokalizację pliku skryptu względem katalogu roboczego w obszarze Ścieżka skryptu.
   • Dla Inline wprowadź polecenia programu PowerShell w polu Skrypt.

   

Uwaga

Domyślnie zadanie programu PowerShell w wersji 2 używa programu Windows PowerShell 5.1 dla agentów systemu Windows i programu PowerShell 7.x dla agentów systemu Linux/macOS. Aby użyć programu PowerShell 7.x w agentach systemu Windows, wybierz pozycję Użyj programu PowerShell Core w obszarze Opcje zaawansowane w okienku programu PowerShell. Musisz mieć zainstalowany program PowerShell 7.x. , który domyślnie robią agenci hostowani przez firmę Microsoft .

Przykładowy skrypt do nadawania wersji zestawom

Poniższy skrypt programu PowerShell stosuje wersję opartą na numerze kompilacji do zestawów. Jeśli na przykład definicja $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r) formatu numeru kompilacji generuje numer kompilacji Build HelloWorld_2024.07.19.1, skrypt stosuje wersję 2024.07.19.1 do zestawów.

Aby ten skrypt działał pomyślnie, format numeru kompilacji musi zawierać cztery segmenty. Aby uzyskać więcej informacji, zobacz Numery wersji lub kompilacji.

Uwaga

Numer kompilacji jest również nazywany numerem uruchomienia.

YAML

1. Dostosuj definiowanie numeru kompilacji w potoku YAML, używając właściwości name na poziomie głównym potoku.

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

2. Zapisz następujący skrypt programu PowerShell jako plik w katalogu głównym repozytorium.

3. Dodaj krok zadania PowerShell@2 lub skrót pwsh albo powershell do potoku i wywołaj ścieżkę do pliku skryptu PowerShell względnie do katalogu roboczego.

Klasyczny

1. W potoku klasycznym określ format numeru kompilacji na karcie Opcje w obszarze Format numeru kompilacji. Na przykład wpisz $(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r).

   

2. Zapisz następujący skrypt programu PowerShell jako plik w katalogu głównym repozytorium.

3. Dodaj zadanie PowerShell do potoku i wywołaj ścieżkę pliku skryptu PowerShell względem katalogu roboczego.

Skrypt programu PowerShell do nadawania wersji zestawom:

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

Przykładowy skrypt umożliwiający uzyskanie dostępu do interfejsu API REST

Poniższy skrypt programu PowerShell używa zmiennych środowiskowych do uzyskiwania dostępu do interfejsu API REST usługi Azure Pipelines i pobierania definicji potoków.

YAML

W potoku YAML możesz zdefiniować zmienną środowiskową w zadaniu `$env:SYSTEM_ACCESSTOKEN`, a następnie użyć jej w skrypcie w linii `PowerShell@2`, aby uzyskać token OAuth do dostępu do interfejsu 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)

Klasyczny

Aby umożliwić skryptowi korzystanie z tokenu OAuth procesu kompilacji, wybierz Agent job dla swojego potoku, a następnie zaznacz pole wyboru Zezwol na dostęp skryptów do tokenu OAuth w sekcji Opcje dodatkowe.

Skrypt może teraz używać zmiennej środowiskowej SYSTEM_ACCESSTOKEN do uzyskiwania dostępu do interfejsu API REST usługi Azure Pipelines.

Następujący wbudowany skrypt w zadaniu PowerShell używa Azure Pipelines REST API do pobrania definicji potoku.

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

Powiązana zawartość

• Numery uruchomień lub kompilacji
• Zadanie programu PowerShell w usłudze Azure Pipelines
• Azure Pipelines REST API