Udostępnij przez

Używanie zmiennych w potokach wydania klasycznego

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

Używanie zmiennych w klasycznych potokach wydania to wygodny sposób wymiany i transportu danych w potoku. Każda zmienna jest przechowywana jako ciąg, a jej wartość może ulec zmianie między przebiegami potoku.

W przeciwieństwie do parametrów środowiska uruchomieniowego, które są dostępne tylko w czasie analizowania szablonów, zmienne w potokach wydania klasycznego są dostępne w całym procesie wdrażania.

Podczas konfigurowania zadań wdrażania aplikacji na każdym etapie potoku wydania klasycznego zmienne mogą pomóc:

  • Upraszczanie dostosowywania: zdefiniuj ogólny potok wdrażania raz i łatwo dostosuj go do różnych etapów. Na przykład użyj zmiennej do reprezentowania parametry połączenia wdrożenia internetowego, dostosowując jej wartość zgodnie z potrzebami dla każdego etapu. Te zmienne są nazywane zmiennymi niestandardowymi.

  • Skorzystaj z informacji kontekstowych: uzyskaj dostęp do szczegółów kontekstu wydania, takich jak etap, artefakt lub agent uruchamiającego wdrożenie. Na przykład skrypty mogą wymagać lokalizacji kompilacji do pobrania lub katalogu roboczego agenta w celu utworzenia plików tymczasowych. Te zmienne są określane jako zmienne domyślne.

Uwaga

Aby uzyskać więcej szczegółów, zobacz Temat Potoki YAML, zobacz zmienne zdefiniowane przez użytkownika i wstępnie zdefiniowane zmienne .

Zmienne domyślne

Zmienne domyślne zawierają podstawowe informacje o kontekście wykonywania uruchomionych zadań i skryptów. Te zmienne zapewniają dostęp do szczegółowych informacji o systemie, wydaniu, etapie lub agencie , w którym są uruchomione.

Z wyjątkiem System.Debug, zmienne domyślne są tylko do odczytu, a system automatycznie ustawia ich wartości.

Niektóre z najbardziej znaczących zmiennych opisano w poniższych tabelach. Aby wyświetlić pełną listę, zobacz Wyświetlanie bieżących wartości wszystkich zmiennych.

Zmienne systemowe

Nazwa zmiennej opis
System.TeamFoundationServerUri Adres URL połączenia usługi w usłudze Azure Pipelines. Użyj tej zmiennej w skryptach lub zadaniach, aby wywoływać interfejsy API REST usługi Azure Pipelines.

Przykład: https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri Adres URL kolekcji Team Foundation lub usługi Azure Pipelines. Ta zmienna w skryptach lub zadaniach służy do wywoływania interfejsów API REST w innych usługach, takich jak kontrola kompilacji i wersji.

Przykład: https://dev.azure.com/fabrikam/
System.CollectionId Identyfikator kolekcji, do której należy ta kompilacja lub wydanie.

Przykład: 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId Identyfikator potoku wydania, do którego należy bieżąca wersja.

Przykład: 1
System.TeamProject Nazwa projektu, do którego należy ta kompilacja lub wydanie.

Przykład: Fabrikam
System.TeamProjectId Identyfikator projektu, do którego należy ta kompilacja lub wydanie.

Przykład: 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory Katalog, do którego potok danych pobiera artefakty podczas wdrażania wydania. Potok pipeline czyści folder przed każdym wdrożeniem, jeśli zajdzie potrzeba pobrania artefaktów przez agenta. Takie same jak Agent.ReleaseDirectory i System.DefaultWorkingDirectory.

Przykład: C:\agent\_work\r1\a
System.DefaultWorkingDirectory Katalog, do którego pipeline pobiera artefakty podczas wdrażania wersji. Pipeline czyści katalog przed każdym wdrożeniem, jeśli wymaga pobrania artefaktów przez agenta. Takie same jak Agent.ReleaseDirectory i System.ArtifactsDirectory.

Przykład: C:\agent\_work\r1\a
System.WorkFolder Katalog roboczy dla tego agenta, w którym potok tworzy podfoldery dla każdej kompilacji lub wydania. Takie same jak Agent.RootDirectory i Agent.WorkFolder.

Przykład: C:\agent\_work
System.Debug Jest to jedyna zmienna systemowa, którą użytkownicy mogą ustawić. Ustaw tę zmienną do trueuruchomienia wydania w trybie debugowania, aby ułatwić znajdowanie błędów.

Przykład: true

Zmienne wydania

Nazwa zmiennej opis
Release.AttemptNumber Liczba wdrożeń tej wersji na tym etapie.

Przykład: 1
Release.DefinitionEnvironmentId Identyfikator etapu w odpowiednim potoku wydania.

Przykład: 1
Release.DefinitionId Identyfikator potoku wydania, do którego należy bieżąca wersja.

Przykład: 1
Release.DefinitionName Nazwa potoku wydania, do którego należy bieżąca wersja.

Przykład: fabrikam-cd
Release.Deployment.RequestedFor Nazwa wyświetlana tożsamości, która wyzwoliła (uruchomiono) wdrożenie w toku.

Przykład: Mateo Escobedo
Release.Deployment.RequestedForEmail Adres e-mail tożsamości, która wyzwoliła (uruchomiono) wdrożenie w toku.

Przykład: mateo@fabrikam.com
Release.Deployment.RequestedForId Identyfikator tożsamości, która wyzwoliła (uruchomiono) wdrożenie w toku.

Przykład: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID Identyfikator wdrożenia. Unikatowe na zadanie.

Przykład: 254
Release.DeployPhaseID Identyfikator fazy, w której jest uruchomione wdrożenie.

Przykład: 127
Release.EnvironmentId Identyfikator wystąpienia etapu w wydaniu, do którego wdrożenie jest obecnie w toku.

Przykład: 276
Release.EnvironmentName Nazwa etapu, do którego wdrożenie jest obecnie w toku.

Przykład: Dev
Release.EnvironmentUri Identyfikator URI wystąpienia etapu w wydaniu, do którego wdrożenie jest obecnie w toku.

Przykład: vstfs://ReleaseManagement/Environment/276
Release.Environments. {nazwa-etapu}.status Stan wdrożenia etapu.

Przykład: InProgress
Release.PrimaryArtifactSourceAlias Alias podstawowego źródła artefaktu.

Przykład: fabrikam\_web
Release.Reason Przyczyna wdrożenia. Obsługiwane wartości to:
ContinuousIntegration — wydanie zostało uruchomione w ramach ciągłego wdrażania po zakończeniu kompilacji.
Manual — wersja została uruchomiona ręcznie.
None — nie określono przyczyny wdrożenia.
Schedule — wydanie zaczęło się od harmonogramu.
Release.ReleaseDescription Opis tekstu podany w momencie wydania.

Przykład: Critical security patch
Release.ReleaseId Identyfikator bieżącego rekordu wydania.

Przykład: 118
Release.ReleaseName Nazwa bieżącej wersji.

Przykład: Release-47
Release.ReleaseUri Identyfikator URI bieżącej wersji.

Przykład: vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL Adres URL tej wersji.

Przykład: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor Nazwa wyświetlana tożsamości, która wyzwoliła wydanie.

Przykład: Mateo Escobedo
Release.RequestedForEmail Adres e-mail tożsamości, która wyzwoliła wydanie.

Przykład: mateo@fabrikam.com
Release.RequestedForId Identyfikator tożsamości, która wyzwoliła wydanie.

Przykład: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsDownload Wartość logiczna określająca, czy unikać pobierania artefaktów przez agenta.

Przykład: FALSE
Release.TriggeringArtifact.Alias Alias artefaktu, który wyzwolił wydanie. Ta wartość jest pusta, gdy wydanie jest zaplanowane lub wyzwalane ręcznie.

Przykład: fabrikam\_app

Zmienne etapu wydania

Nazwa zmiennej opis
Release.Environments. {nazwa etapu}. Stan Stan wdrożenia tej wersji w określonym etapie.

Przykład: NotStarted

Zmienne agenta

Nazwa zmiennej opis
Agent.Name Nazwa agenta zarejestrowana w puli agentów. Ta nazwa prawdopodobnie różni się od nazwy komputera.

Przykład: fabrikam-agent
Agent.MachineName Nazwa komputera, na którym skonfigurowano agenta.

Przykład: fabrikam-agent
Agent.Version Wersja oprogramowania agenta.

Przykład: 2.109.1
Agent.JobName Nazwa uruchomionego zadania, takiego jak Release lub Build.

Przykład: Release
Agent.HomeDirectory Folder, w którym zainstalowano agenta. Ten folder zawiera kod i zasoby agenta.

Przykład: C:\agent
Agent.ReleaseDirectory Katalog, do którego proces wdrażania wydania pobiera artefakty. Katalog zostanie wyczyszczone przed każdym wdrożeniem, jeśli wymaga pobrania artefaktów do agenta. Jest taka sama jak System.ArtifactsDirectory i System.DefaultWorkingDirectory.

Przykład: C:\agent\_work\r1\a
Agent.RootDirectory Katalog roboczy dla tego agenta, w którym są tworzone podfoldery dla każdej kompilacji lub wydania. Jest taka sama jak Agent.WorkFolder i System.WorkFolder.

Przykład: C:\agent\_work
Agent.WorkFolder Katalog roboczy dla tego agenta, w którym są tworzone podfoldery dla każdej kompilacji lub wydania. Jest taka sama jak Agent.RootDirectory i System.WorkFolder.

Przykład: C:\agent\_work
Agent.DeploymentGroupId ID grupy wdrożeniowej, z którą agent się rejestruje. Ten identyfikator jest dostępny tylko w zadaniach grupy wdrożeniowej.

Przykład: 1

Zmienne artefaktów wydania

Dla każdego artefaktu, do którego odwołujesz się w wydaniu, użyj następujących zmiennych artefaktu. Należy pamiętać, że nie wszystkie zmienne mają zastosowanie do każdego typu artefaktu. W poniższej tabeli wymieniono domyślne zmienne artefaktu i przedstawiono przykłady ich wartości na podstawie typu artefaktu. Jeśli przykład jest pusty, oznacza to, że zmienna nie ma zastosowania do tego typu artefaktu.

Zastąp symbol zastępczy {alias} wartością, którą określisz dla aliasu źródła artefaktu, lub wartością domyślną wygenerowaną dla pipeline'u wydania.

Nazwa zmiennej opis
Release.Artifacts. {alias}. Identyfikator definicji Identyfikator potoku kompilacji lub repozytorium. Przykłady:

Azure Pipelines: 1
Github: fabrikam/asp
Release.Artifacts. {alias}. DefinitionName Nazwa potoku kompilacji lub repozytorium. Przykłady:

Azure Pipelines: fabrikam-ci
TfVC: $/fabrikam
Git: fabrikam
Github: fabrikam/asp (main)
Release.Artifacts. {alias}. Numer kompilacji Numer kompilacji lub identyfikator zatwierdzenia. Przykłady:

Azure Pipelines: 20170112.1
Jenkins: 20170112.1
TfVC: Changeset 3
Git: 38629c964
Github: 38629c964
Release.Artifacts. {alias}. BuildId Identyfikator kompilacji. Przykłady:

Azure Pipelines: 130
Jenkins: 130
Github: 38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts. {alias}. Identyfikator BUILDURI Adres URL kompilacji. Przykłady:

Azure Pipelines: vstfs://build-release/Build/130
Github: https://github.com/fabrikam/asp
Release.Artifacts. {alias}. ŹródłoBranch Pełna ścieżka i nazwa gałęzi, z której utworzono źródło. Przykłady:

Azure Pipelines: refs/heads/main
Release.Artifacts. {alias}. SourceBranchName Nazwa tylko gałęzi, z której utworzono źródło. Przykłady:

Azure Pipelines: main
Release.Artifacts. {alias}. SourceVersion Skompilowane zatwierdzenie. Przykłady:

Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7
Release.Artifacts. {alias}. Repository.Provider Typ repozytorium, z którego utworzono źródło. Przykłady:

Azure Pipelines: Git
Release.Artifacts. {alias}. RequestedForID Identyfikator konta, które wyzwoliło kompilację. Przykłady:

Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.Artifacts. {alias}. RequestedFor Nazwa konta, które zażądało kompilacji. Przykłady:

Azure Pipelines: Mateo Escobedo
Release.Artifacts. {alias}. Typ Typ źródła artefaktu, taki jak Build. Examples:

Azure Pipelines: Build
Jenkins: Jenkins
Azure DevOps Services: TFVC
Git: Git
Github: GitHub
Release.Artifacts. {alias}. PullRequest.TargetBranch Pełna ścieżka i nazwa gałęzi, która jest elementem docelowym żądania ściągnięcia. Ta zmienna jest inicjowana tylko wtedy, gdy wydanie jest wyzwalane przez przepływ żądania ściągnięcia. Przykłady:

Azure Pipelines: refs/heads/main
Release.Artifacts. {alias}. PullRequest.TargetBranchName Nazwa tylko gałęzi, która jest elementem docelowym żądania ściągnięcia. Ta zmienna jest inicjowana tylko wtedy, gdy wydanie jest wyzwalane przez przepływ żądania ściągnięcia. Przykłady:

Azure Pipelines: main

Podstawowe zmienne artefaktu

W przypadku klasycznych potoków wydawniczych, jeśli używasz wielu artefaktów, możesz oznaczyć jeden artefakt jako podstawowy. Następnie usługa Azure Pipelines wypełnia następujące zmienne dla wyznaczonego podstawowego artefaktu.

Nazwa zmiennej Tak samo jak
Build.DefinitionId Release.Artifacts. {Podstawowy alias artefaktu}. Identyfikator definicji
Build.DefinitionName Release.Artifacts. {Podstawowy alias artefaktu}. DefinitionName
Build.BuildNumber Release.Artifacts. {Podstawowy alias artefaktu}. Numer kompilacji
Build.BuildId Release.Artifacts. {Podstawowy alias artefaktu}. BuildId
Build.BuildURI Release.Artifacts. {Podstawowy alias artefaktu}. Identyfikator BUILDURI
Build.SourceBranch Release.Artifacts. {Podstawowy alias artefaktu}. ŹródłoBranch
Build.SourceBranchName Release.Artifacts. {Podstawowy alias artefaktu}. SourceBranchName
Build.SourceVersion Release.Artifacts. {Podstawowy alias artefaktu}. SourceVersion
Build.Repository.Provider Release.Artifacts. {Podstawowy alias artefaktu}. Repository.Provider
Build.RequestedForID Release.Artifacts. {Podstawowy alias artefaktu}. RequestedForID
Build.RequestedFor Release.Artifacts. {Podstawowy alias artefaktu}. RequestedFor
Build.Type Release.Artifacts. {Podstawowy alias artefaktu}. Typ
Build.PullRequest.TargetBranch Release.Artifacts. {Podstawowy alias artefaktu}. PullRequest.TargetBranch
Build.PullRequest.TargetBranchName Release.Artifacts. {Podstawowy alias artefaktu}. PullRequest.TargetBranchName

Używanie zmiennych domyślnych

Zmienne domyślne można używać na dwa sposoby: jako parametry do zadań w potoku wydania lub w skryptach.

Użyj zmiennej domyślnej bezpośrednio jako danych wejściowych zadania. Aby, na przykład, przekazać Release.Artifacts.{Artifact alias}.DefinitionName jako argument do zadania PowerShell dla artefaktu o aliasie ASPNET4.CI, użyj $(Release.Artifacts.ASPNET4.CI.DefinitionName).

Zrzut ekranu przedstawiający sposób użycia zmiennej domyślnej jako argumentu.

Aby użyć zmiennej domyślnej w skrypcie, zamień . w nazwach zmiennych domyślnych na _. Aby na przykład wydrukować wartość Release.Artifacts.{Artifact alias}.DefinitionName dla artefaktu z ASPNET4.CI jako aliasem w skry skry skryptzie programu PowerShell, użyj polecenia $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME. Oryginalny alias , ASPNET4.CI, jest zastępowany ASPNET4_CI.

Zrzut ekranu przedstawiający sposób używania zmiennej domyślnej w wbudowanym skryscie programu PowerShell.

Zmienne niestandardowe

Zmienne niestandardowe można definiować w różnych zakresach.

  • Grupy zmiennych: użyj grup zmiennych, aby udostępniać wartości we wszystkich definicjach w projekcie. Takie podejście jest przydatne, gdy chcesz używać tych samych wartości w definicjach, etapach i zadaniach w projekcie oraz zarządzać nimi z jednej lokalizacji. Definiowanie grup zmiennych i zarządzanie nimi w bibliotece potoków>.

  • Zmienne potoku wydania: użyj zmiennych potoku wydania, aby udostępniać wartości we wszystkich etapach w potoku wydania. Takie podejście jest idealne w scenariuszach, w których potrzebna jest spójna wartość między etapami i zadaniami, z możliwością aktualizowania jej z jednej lokalizacji. Zdefiniuj te zmienne i zarządzaj nimi na karcie Zmienne potoku wydania. Na stronie Zmienne potoku ustaw listę rozwijaną Zakres na Release (Wydanie ) podczas dodawania zmiennej.

  • Zmienne etapu: zmienne etapu umożliwiają udostępnianie wartości w określonym etapie potoku wydania. Takie podejście jest przydatne w przypadku wartości, które różnią się od etapu do etapu, ale są spójne we wszystkich zadaniach w ramach etapu. Zdefiniuj te zmienne i zarządzaj nimi na karcie Zmienne potoku wydania. Na stronie Zmienne potoku ustaw listę rozwijaną Zakres na odpowiednie środowisko podczas dodawania zmiennej.

Używając zmiennych niestandardowych na poziomie projektu, potoku wydania i etapu, można wykonywać następujące czynności:

  • Unikaj duplikowania wartości, co ułatwia aktualizowanie wszystkich wystąpień za pomocą jednej zmiany.

  • Zabezpieczanie poufnych wartości, uniemożliwiając ich wyświetlanie lub modyfikowanie przez użytkowników. Aby oznaczyć zmienną jako bezpieczną (wpis tajny), wybierz ikonę obok zmiennej.

    Ważne

    Wartości ukrytych zmiennych (tajnych) są bezpiecznie przechowywane na serwerze i użytkownicy nie mogą ich wyświetlać po zapisaniu. Podczas wdrażania usługa Azure Pipelines odszyfrowuje te wartości podczas odwoływania się do nich zadań i przekazuje je do agenta za pośrednictwem bezpiecznego kanału HTTPS.

Uwaga

Tworzenie zmiennych niestandardowych może zastąpić standardowe zmienne. Jeśli na przykład zdefiniujesz niestandardową zmienną Path na agencie systemu Windows, zastępuje zmienną $env:Path i może uniemożliwić prawidłowe działanie programu PowerShell.

Używanie zmiennych niestandardowych

Aby użyć zmiennych niestandardowych w zadaniach, należy ująć nazwę zmiennej w nawiasy i poprzedzić ją znakiem $ . Jeśli na przykład masz zmienną o nazwie adminUserName, wstaw bieżącą wartość do zadania jako $(adminUserName).

Uwaga

Zmienne z różnych grup powiązanych z pipeline w tym samym zakresie (na przykład zadanie lub faza) mogą powodować konflikt i skutkować nieprzewidywalnymi wynikami. Aby uniknąć tego problemu, upewnij się, że zmienne we wszystkich grupach zmiennych mają unikatowe nazwy.

Definiowanie i modyfikowanie zmiennych w skryfcie

Aby zdefiniować lub zmodyfikować zmienną ze skryptu, użyj polecenia rejestrowania task.setvariable . Zaktualizowana wartość zmiennej jest ograniczona do wykonywanego zadania i nie jest utrwalana w ramach zadań ani etapów. Należy pamiętać, że nazwy zmiennych są przekształcane na wielkie litery z literami "." i "" zastąpione ciągiem "_".

Na przykład, Agent.WorkFolder staje się AGENT_WORKFOLDER.

  • W systemie Windows uzyskaj dostęp do tej zmiennej jako %AGENT_WORKFOLDER% lub $env:AGENT_WORKFOLDER.
  • W systemach Linux i macOS użyj polecenia $AGENT_WORKFOLDER.

Napiwek

Skrypt można uruchomić na:

Skrypt usługi Batch

sauce Ustawianie zmiennych i secret.Sauce

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic

Odczytywanie zmiennych

Argumenty

"$(sauce)" "$(secret.Sauce)"

Skrypt

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret)

Dane wyjściowe konsoli z odczytywania zmiennych:

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)

Wyświetlanie bieżących wartości wszystkich zmiennych

  1. Wybierz pozycję Wydania potoków>, a następnie wybierz potok wydania.

  2. Otwórz widok podsumowania wersji i wybierz interesujący Cię etap. Na liście kroków wybierz pozycję Inicjowanie zadania.

    Zrzut ekranu przedstawiający krok inicjowania zadania.

  3. Ten krok otwiera dzienniki. Przewiń w dół, aby wyświetlić wartości używane przez agenta dla tego zadania.

    Zrzut ekranu przedstawiający zmienne używane przez agenta.

Uruchamianie wydania w trybie debugowania

Uruchomienie wydania w trybie debugowania może pomóc zdiagnozować i rozwiązać problemy, wyświetlając dodatkowe informacje podczas wykonywania wydania. Możesz włączyć tryb debugowania dla całej wersji lub tylko dla zadań w określonym etapie wydania.

  • Aby włączyć tryb debugowania dla całej wersji, dodaj zmienną o nazwie System.Debug z wartością true na karcie Zmienne pipeline'u wydania.

  • Aby włączyć tryb debugowania dla określonego etapu, otwórz okno dialogowe Konfigurowanie etapu z menu skrótów etapu i dodaj zmienną o nazwie System.Debug z wartością true na karcie Zmienne .

  • Alternatywnie utwórz grupę zmiennych zawierającą zmienną o nazwie System.Debug z wartością truei połącz tę grupę zmiennych z potokiem wydania.

Napiwek

Jeśli wystąpi błąd związany z połączeniami usługi Azure Resource Manager, zobacz Instrukcje: rozwiązywanie problemów z połączeniami usługi Azure Resource Manager , aby uzyskać więcej informacji.

Powiązana zawartość

  • Last updated on