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: 1GitHub: fabrikam/asp |
| Release.Artifacts. {alias}. DefinitionName | Nazwa potoku kompilacji lub repozytorium. Przykłady: Azure Pipelines: fabrikam-ciTfVC: $/fabrikamGit: fabrikamGitHub: fabrikam/asp (main) |
| Release.Artifacts. {alias}. Numer kompilacji | Numer kompilacji lub identyfikator zatwierdzenia. Przykłady: Azure Pipelines: 20170112.1Jenkins: 20170112.1TfVC: Changeset 3Git: 38629c964GitHub: 38629c964 |
| Release.Artifacts. {alias}. BuildId | Identyfikator kompilacji. Przykłady: Azure Pipelines: 130Jenkins: 130GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
| Release.Artifacts. {alias}. Identyfikator BUILDURI | Adres URL kompilacji. Przykłady: Azure Pipelines: vstfs://build-release/Build/130GitHub: 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: BuildJenkins: JenkinsTfVC: TFVCGit: GitGitHub: 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).
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.
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ę
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:
- Agent systemu Windows używający zadania skryptu usługi Batch lub zadania programu PowerShell.
- Agent systemu macOS lub Linux przy użyciu zadania skryptu powłoki.
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
Wybierz pozycję Wydania potoków>, a następnie wybierz potok wydania.
Otwórz widok podsumowania wersji i wybierz interesujący Cię etap. Na liście kroków wybierz pozycję Inicjowanie zadania.
Spowoduje to otwarcie dzienników dla tego kroku. Przewiń w dół, aby wyświetlić wartości używane przez agenta dla tego zadania.
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.Debugz wartościątruena 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.Debugz wartościątruena karcie Zmienne .Alternatywnie utwórz grupę zmiennych zawierającą zmienną o nazwie
System.Debugz 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.