Udostępnij za pośrednictwem


Używanie zmiennych w potokach wydania klasycznego

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

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 jego 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 klasycznych potokach wydania są dostępne w całym procesie wdrażania

Podczas konfigurowania zadań wdrażania aplikacji na każdym etapie potoku klasycznego wydania 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. Są one 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. Są one 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 umożliwiają dostęp do szczegółów dotyczących systemu, wydania, etapu lub agenta , w którym są uruchomione.

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

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 tego z poziomu skryptów lub zadań, aby wywołać 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. Użyj tego z poziomu skryptów lub zadań, aby wywołać interfejsy 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 artefakty są pobierane podczas wdrażania wydania. Katalog zostanie wyczyszczone przed każdym wdrożeniem, jeśli wymaga pobrania artefaktów do agenta. Takie same jak Agent.ReleaseDirectory i System.DefaultWorkingDirectory.

Przykład: C:\agent\_work\r1\a
System.DefaultWorkingDirectory Katalog, do którego artefakty są pobierane podczas wdrażania wydania. Katalog zostanie wyczyszczone przed każdym wdrożeniem, jeśli wymaga pobrania artefaktów do agenta. Tak samo jak Agent.ReleaseDirectory i System.ArtifactsDirectory.

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

Przykład: C:\agent\_work
System.Debug Jest to jedyna zmienna systemowa, która może być ustawiana przez użytkowników. Ustaw wartość true, aby uruchomić wydanie 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 pominąć pobieranie artefaktów do agenta.

Przykład: FALSE
Release.TriggeringArtifact.Alias Alias artefaktu, który wyzwolił wydanie. Jest to puste, gdy wydanie zostało zaplanowane lub wyzwolone 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. Prawdopodobnie różni się to 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 wydanie lub kompilacja.

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 artefakty są pobierane podczas wdrażania wydania. Katalog zostanie wyczyszczone przed każdym wdrożeniem, jeśli wymaga pobrania artefaktów do agenta. Tak samo 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. Tak samo 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. Tak samo jak Agent.RootDirectory i System.WorkFolder.

Przykład: C:\agent\_work
Agent.DeploymentGroupId Identyfikator grupy wdrożenia, w ramach których agent jest zarejestrowany. Jest to dostępne tylko w zadaniach grupy wdrożeń.

Przykład: 1

Zmienne Release Artifacts

Dla każdego artefaktu, do którego odwołuje się wydanie, można użyć 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 dla tego typu artefaktu.

{alias} Zastąp symbol zastępczy wartością określoną dla aliasu źródła artefaktu lub wartością domyślną wygenerowaną dla potoku 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
TfVC: 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 potoków wydania klasycznego, jeśli używasz wielu artefaktów, możesz wyznaczyć jeden jako podstawowy artefakt. Usługa Azure Pipelines wypełni 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.

Możesz użyć zmiennej domyślnej bezpośrednio jako danych wejściowych zadania. Aby na przykład przekazać Release.Artifacts.{Artifact alias}.DefinitionName jako argument do zadania programu PowerShell dla artefaktu z ASPNET4.CI jako alias, należy użyć polecenia $(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, należy najpierw zastąpić wartością . w domyślnych nazwach _zmiennych . 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. Należy pamiętać, że 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. Jest to 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. Jest to idealne rozwiązanie 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. Jest to 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żywanie zmiennych niestandardowych w projekcie, potoku wydania i poziomach etapów ułatwia:

  • 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ę kłódka obok zmiennej.

    Ważne

    Wartości ukrytych zmiennych (secret) są bezpiecznie przechowywane na serwerze i nie mogą być wyświetlane przez użytkowników po ich zapisaniu. Podczas wdrażania usługa Azure Pipelines odszyfrowuje te wartości podczas odwoływania się do 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ąpi zmienną $env:Path , która 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, możesz wstawić jej bieżącą wartość do zadania jako $(adminUserName).

Uwaga

Zmienne z różnych grup połączonych z potokiem w tym samym zakresie (np. zadanie lub etap) mogą powodować konflikt, co prowadzi do nieprzewidywalnych wyników. Aby tego uniknąć, 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. Spowoduje to otwarcie dzienników dla tego kroku. 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 lub błędy, wyświetlając dodatkowe informacje podczas wykonywania wydania. Tryb debugowania można włączyć 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 potoku 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 ARM, zobacz Instrukcje: rozwiązywanie problemów z połączeniami usługi Azure Resource Manager, aby uzyskać więcej informacji.