Definieren von Variablen

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

Hinweis

In Microsoft Team Foundation Server (TFS) 2018 und früheren Versionen werden Build- und Release-Pipelines als Definitionen bezeichnet, Ausführungen werden als Builds bezeichnet, Dienstverbindungen werden als Dienstendpunkte bezeichnet, Stages werden als Umgebungen bezeichnet und Aufträge werden als Phasen bezeichnet.

Variablen stellen eine bequeme Möglichkeit dar, wichtige Bits von Daten in verschiedene Teile der Pipeline zu übernehmen. Die häufigste Verwendung von Variablen besteht darin, einen Wert zu definieren, den Sie dann in Ihrer Pipeline verwenden können. Alle Variablen werden als Zeichenfolgen gespeichert und können stummgeschaltet werden. Der Wert einer Variablen kann von Ausführung zu Ausführung oder Auftrag in Auftrag Ihrer Pipeline geändert werden.

Wenn Sie dieselbe Variable an mehreren Stellen mit demselben Namen definieren, gewinnt die lokal definierte Variable. Daher kann eine variable, die auf Auftragsebene definiert ist, eine Variable überschreiben, die auf Stufenebene festgelegt ist. Eine variable, die auf Stufesebene definiert ist, überschreiben eine Variable, die auf der Pipelinestammebene festgelegt ist. Eine Variable, die auf der Pipelinestammebene festgelegt ist, überschreiben eine Variable, die in der Benutzeroberfläche der Pipelineeinstellungen festgelegt ist.

Sie können Variablen mit Ausdrücken verwenden, um Werte bedingt zuzuweisen und Pipelines weiter anzupassen.

Variablen unterscheiden sich von Laufzeitparametern, die während der Vorlagenanalyse eingegeben und verfügbar sind.

Benutzerdefinierte Variablen

Wenn Sie eine Variable definieren, können Sie verschiedene Syntaxen (Makros, Vorlagenausdruck oder Laufzeit) verwenden und welche Syntax Sie verwenden, bestimmt, wo in der Pipeline Ihre Variable gerendert wird.

In YAML-Pipelines können Sie Variablen auf Stamm-, Phasen- und Auftragsebene festlegen. Sie können auch Variablen außerhalb einer YAML-Pipeline in der Benutzeroberfläche angeben. Wenn Sie eine Variable auf der Benutzeroberfläche festlegen, kann diese Variable verschlüsselt und als geheim festgelegt werden.

Benutzerdefinierte Variablen können schreibgeschützt festgelegt werden. Es gibt Benennungseinschränkungen für Variablen (Beispiel: Sie können zu Beginn eines Variablennamens nicht verwenden secret ).

Sie können eine Variablengruppe verwenden , um Variablen in mehreren Pipelines verfügbar zu machen.

Sie können Vorlagen verwenden, um Variablen zu definieren, die in mehreren Pipelines in einer Datei verwendet werden.

Systemvariablen

Zusätzlich zu benutzerdefinierten Variablen verfügt Azure Pipelines über Systemvariablen mit vordefinierten Werten. Wenn Sie YAML- oder klassische Buildpipelinen verwenden, finden Sie vordefinierte Variablen für eine umfassende Liste von Systemvariablen. Wenn Sie klassische Releasepipelinen verwenden, lesen Sie Releasevariablen.

Systemvariablen werden mit ihrem aktuellen Wert festgelegt, wenn Sie die Pipeline ausführen. Einige Variablen werden automatisch festgelegt. Als Pipelineautor oder Endbenutzer ändern Sie den Wert einer Systemvariable, bevor die Pipeline ausgeführt wird.

Systemvariablen sind schreibgeschützt.

Umgebungsvariablen

Umgebungsvariablen sind spezifisch für das betriebssystem, das Sie verwenden. Sie werden auf plattformspezifische Weise in eine Pipeline eingefügt. Das Format entspricht der Formatierung von Umgebungsvariablen für Ihre spezifische Skriptplattform.

Auf UNIX-Systemen (macOS und Linux) weisen Umgebungsvariablen das Format $NAMEauf. Unter Windows gilt %NAME% das Format für Batch und $env:NAME in PowerShell.

System- und benutzerdefinierte Variablen werden auch als Umgebungsvariablen für Ihre Plattform eingefügt. Wenn Variablen in Umgebungsvariablen umgewandelt werden, werden Variablennamen großgeschrieben, und Punkte werden in Unterstriche umgewandelt. Der Variablename any.variable wird beispielsweise zum Variablennamen $ANY_VARIABLE.

Es gibt Variablenbenennungseinschränkungen für Umgebungsvariablen (Beispiel: Sie können zu Beginn eines Variablennamens nicht verwenden secret ).

Einschränkungen bei Variablennamen

Benutzerdefinierte und Umgebungsvariablen können aus Buchstaben, Zahlen .und _ Zeichen bestehen. Verwenden Sie keine Variablenpräfixe, die vom System reserviert sind. Dies sind: endpoint, , inputsecret, path, und securefile. Jede Variable, die mit einer dieser Zeichenfolgen beginnt (unabhängig von der Groß-/Kleinschreibung), ist für Ihre Aufgaben und Skripts nicht verfügbar.

Grundlegendes zur Variablensyntax

Azure Pipelines unterstützt drei verschiedene Methoden, um auf Variablen zu verweisen: Makro, Vorlagenausdruck und Laufzeitausdruck. Jede Syntax kann für einen anderen Zweck verwendet werden und hat gewisse Einschränkungen.

In einer Pipeline werden Vorlagenausdruckvariablen (${{ variables.var }}) zur Kompilierungszeit verarbeitet, bevor die Laufzeit beginnt. Makrosyntaxvariablen ($(var)) werden während der Laufzeit verarbeitet, bevor eine Aufgabe ausgeführt wird. Laufzeitausdrücke ($[variables.var]) werden auch während der Laufzeit verarbeitet, wurden jedoch für die Verwendung mit Bedingungen und Ausdrücken entwickelt. Wenn Sie einen Laufzeitausdruck verwenden, muss er die gesamte rechte Seite einer Definition einnehmen.

In diesem Beispiel können Sie sehen, dass der Vorlagenausdruck weiterhin den Anfangswert der Variablen hat, nachdem die Variable aktualisiert wurde. Der Wert der Makrosyntaxvariable aktualisiert. Der Wert des Vorlagenausdrucks ändert sich nicht, da alle Vorlagenausdrucksvariablen zur Kompilierungszeit verarbeitet werden, bevor Aufgaben ausgeführt werden. Im Gegensatz dazu werden Makrosyntaxvariablen ausgewertet, bevor jede Aufgabe ausgeführt wird.

variables:
- name: one
  value: initialValue 

steps:
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one)
    displayName: First variable pass
  - bash: echo "##vso[task.setvariable variable=one]secondValue"
    displayName: Set new variable value
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one) # outputs secondValue
    displayName: Second variable pass

Makrosyntaxvariablen

Die meisten Dokumentationsbeispiele verwenden Makrosyntax ($(var)). Die Makrosyntax dient zum Interpolieren von Variablenwerten in Aufgabeneingaben und in andere Variablen.

Variablen mit Makrosyntax werden verarbeitet, bevor eine Aufgabe während der Laufzeit ausgeführt wird. Die Laufzeit erfolgt nach der Vorlagenerweiterung. Wenn das System auf einen Makroausdruck stößt, ersetzt es den Ausdruck durch den Inhalt der Variablen. Wenn keine Variable mit diesem Namen vorhanden ist, bleibt der Makroausdruck unverändert. Wenn $(var) sie beispielsweise nicht ersetzt werden können, $(var) werden sie nicht durch etwas ersetzt.

Makrosyntaxvariablen bleiben ohne Wert unverändert, da ein leerer Wert $() wie etwa etwas zu der Aufgabe bedeuten kann, die Sie ausführen, und der Agent sollte nicht davon ausgehen, dass dieser Wert ersetzt werden soll. Wenn Sie beispielsweise auf $(foo) eine Variable foo in einer Bash-Aufgabe verweisen, könnte das Ersetzen aller $() Ausdrücke in der Eingabe in die Aufgabe Ihre Bash-Skripts unterbrechen.

Makrovariablen werden nur erweitert, wenn sie für einen Wert verwendet werden, nicht als Schlüsselwort. Werte werden auf der rechten Seite einer Pipelinedefinition angezeigt. Die folgenden Werte sind gültig: key: $(value). Die folgenden Werte sind ungültig: $(key): value. Makrovariablen werden nicht erweitert, wenn sie zum Anzeigen eines Auftragsnamens inline verwendet werden. Stattdessen müssen Sie die displayName Eigenschaft verwenden.

Hinweis

Makrosyntaxvariablen werden nur für stages, jobsund .steps Sie können z. B. keine Makrosyntax innerhalb einer oder triggereiner resource .

In diesem Beispiel wird die Makrosyntax mit Bash, PowerShell und einer Skriptaufgabe verwendet. Die Syntax zum Aufrufen einer Variablen mit Makrosyntax ist für alle drei identisch.

variables:
 - name: projectName
   value: contoso

steps: 
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)

Vorlagenausdrucksyntax

Mithilfe der Vorlagenausdruckssyntax können Sie sowohl Vorlagenparameter als auch Variablen erweitern (${{ variables.var }}). Vorlagenvariablen werden zur Kompilierungszeit verarbeitet und vor dem Start der Laufzeit ersetzt. Vorlagenausdrücke sind für die Erneutes Verwenden von Teilen von YAML als Vorlagen ausgelegt.

Vorlagenvariablen werden automatisch zusammen mit leeren Zeichenfolgen zusammengeschnürt, wenn ein Ersatzwert nicht gefunden wird. Vorlagenausdrücke können im Gegensatz zu Makro- und Laufzeitausdrücken entweder als Schlüssel (links) oder Werte (rechts) angezeigt werden. Die folgenden Werte sind gültig: ${{ variables.key }} : ${{ variables.value }}.

Syntax des Laufzeitausdrucks

Sie können laufzeitausdruckssyntax für Variablen verwenden, die zur Laufzeit erweitert werden ($[variables.var]). Laufzeitausdruckvariablen werden automatisch zusammen mit leeren Zeichenfolgen geklammert, wenn ein Ersatzwert nicht gefunden wird. Laufzeitausdrücke sollen unter den Bedingungen von Aufträgen verwendet werden, um die bedingte Ausführung von Aufträgen oder ganze Phasen zu unterstützen.

Laufzeitausdruckvariablen werden nur erweitert, wenn sie für einen Wert verwendet werden, nicht als Schlüsselwort. Werte werden auf der rechten Seite einer Pipelinedefinition angezeigt. Die folgenden Werte sind gültig: key: $[variables.value]. Die folgenden Werte sind ungültig: $[variables.key]: value. Der Laufzeitausdruck muss die gesamte rechte Seite eines Schlüsselwertpaars übernehmen. Ist z. B. gültig, key: $[variables.value] ist jedoch key: $[variables.value] foo nicht vorhanden.

Syntax Beispiel Wann wird es verarbeitet? Wo wird sie in einer Pipelinedefinition erweitert? Wie wird es gerendert, wenn es nicht gefunden wurde?
Makro $(var) Laufzeit, bevor eine Aufgabe ausgeführt wird Wert (rechts) Druckt $(var)
Vorlagenausdruck ${{ variables.var }} Kompilierzeit Taste oder Wert (links oder rechts) Leere Zeichenfolge
Laufzeitausdruck $[variables.var] Laufzeit Wert (rechts) Leere Zeichenfolge

Welche Syntax sollte ich verwenden?

Verwenden Sie die Makrosyntax, wenn Sie Eingaben für einen Vorgang bereitstellen.

Wählen Sie einen Laufzeitausdruck aus, wenn Sie mit Bedingungen und Ausdrücken arbeiten. Die Ausnahme ist, wenn Sie über eine Pipeline verfügen, bei der ein Problem für die leere Variable auftritt. Wenn Sie beispielsweise über bedingte Logik verfügen, die auf einer Variablen mit einem bestimmten Wert oder keinem Wert basiert. In diesem Fall sollten Sie einen Makroausdruck verwenden.

Wenn Sie eine Variable in einer Vorlage definieren, verwenden Sie einen Vorlagenausdruck.

Festlegen von Variablen in der Pipeline

Im häufigsten Fall legen Sie die Variablen fest und verwenden sie in der YAML-Datei. Auf diese Weise können Sie Änderungen an der Variablen im Versionssteuerungssystem nachverfolgen. Sie können auch Variablen in der Benutzeroberfläche der Pipelineeinstellungen definieren (siehe die Registerkarte "Klassisch") und in Ihrem YAML darauf verweisen.

Im Folgenden finden Sie ein Beispiel, in dem gezeigt wird, wie sie zwei Variablen configuration festlegen und platformdiese später in Schritten verwenden. Um eine Variable in einer YAML-Anweisung zu verwenden, schließen Sie sie in $(). Variablen können nicht verwendet werden, um eine repository YAML-Anweisung zu definieren.

# Set variables once
variables:
  configuration: debug
  platform: x64

steps:

# Use them once
- task: MSBuild@1
  inputs:
    solution: solution1.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

# Use them again
- task: MSBuild@1
  inputs:
    solution: solution2.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

Variable Bereiche

In der YAML-Datei können Sie eine Variable in verschiedenen Bereichen festlegen:

  • Um sie auf der Stammebene für alle Aufträge in der Pipeline verfügbar zu machen.
  • Auf Stufenebene, um sie nur für eine bestimmte Stufe verfügbar zu machen.
  • Auf Jobebene, um sie nur für einen bestimmten Auftrag verfügbar zu machen.

Wenn eine Variable oben in einem YAML definiert ist, steht sie allen Aufträgen und Phasen in der Pipeline zur Verfügung und ist eine globale Variable. Globale Variablen, die in einem YAML definiert sind, sind in der Benutzeroberfläche der Pipelineeinstellungen nicht sichtbar.

Variablen auf Auftragsebene überschreiben Variablen auf Stamm- und Phasenebene. Variablen auf Stufesebene überschreiben Variablen auf der Stammebene.

variables:
  global_variable: value    # this is available to all jobs

jobs:
- job: job1
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable1: value1    # this is only available in job1
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable1)
  - bash: echo $JOB_VARIABLE1 # variables are available in the script environment too

- job: job2
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable2: value2    # this is only available in job2
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable2)
  - bash: echo $GLOBAL_VARIABLE

Die Ausgabe aus beiden Aufträgen sieht wie folgt aus:

# job1
value 
value1
value1

# job2
value
value2
value

Angeben von Variablen

In den vorherigen Beispielen folgt das variables Schlüsselwort einer Liste der Schlüsselwertpaare. Die Schlüssel sind die Variablennamen und die Werte sind die Variablenwerte.

Es gibt eine weitere Syntax, die nützlich ist, wenn Sie Variablenvorlagen oder Variablengruppen verwenden möchten. Diese Syntax sollte auf der Stammebene einer Pipeline verwendet werden.

In dieser alternativen Syntax verwendet das variables Schlüsselwort eine Liste der Variablenbezeichner. Die Variablenbezeichner sind name für eine reguläre Variable, group für eine Variablengruppe und template zum Einschließen einer Variablenvorlage vorgesehen. Im folgenden Beispiel werden alle drei veranschaulicht.

variables:
# a regular variable
- name: myvariable
  value: myvalue
# a variable group
- group: myvariablegroup
# a reference to a variable template
- template: myvariabletemplate.yml

Erfahren Sie mehr über die Wiederverwendung von Variablen mit Vorlagen.

Zugreifen auf Variablen über die Umgebung

Beachten Sie, dass Variablen auch für Skripts über Umgebungsvariablen verfügbar gemacht werden. Die Syntax für die Verwendung dieser Umgebungsvariablen hängt von der Skriptsprache ab.

Der Name ist großgeschrieben, und der . Name wird durch die _. Dies wird automatisch in die Prozessumgebung eingefügt. Hier einige Beispiele:

  • Batchskript: %VARIABLE_NAME%
  • PowerShell-Skript: $env:VARIABLE_NAME
  • Bash-Skript: $VARIABLE_NAME

Wichtig

Vordefinierte Variablen, die Dateipfade enthalten, werden basierend auf dem Agenthosttyp und dem Shelltyp in die entsprechende Formatierung übersetzt (Windows-Format C:\foo\ versus Unix style /foo/). Wenn Sie Bash-Skriptaufgaben unter Windows ausführen, sollten Sie die Umgebungsvariablenmethode für den Zugriff auf diese Variablen anstelle der Pipelinevariablenmethode verwenden, um sicherzustellen, dass Sie über die richtige Dateipfadformatvorlage verfügen.

YAML wird in TFS nicht unterstützt.

Festlegen geheimer Variablen

Legen Sie in Ihrer YAML-Datei keine geheimen Variablen fest. Betriebssysteme protokollieren häufig Befehle für die von ihnen ausgeführten Prozesse, und Sie möchten nicht, dass das Protokoll einen Geheimschlüssel enthält, den Sie als Eingabe übergeben haben. Verwenden Sie die Umgebung des Skripts, oder ordnen Sie die Variable innerhalb des variables Blocks zu, um geheime Schlüssel an Ihre Pipeline zu übergeben.

Sie müssen geheime Variablen in der Benutzeroberfläche der Pipelineeinstellungen für Ihre Pipeline festlegen. Diese Variablen sind auf die Pipeline festgelegt, in der Sie sie festlegen. Sie können auch geheime Variablen in Variablengruppen festlegen.

Führen Sie die folgenden Schritte aus, um geheime Schlüssel in der Webschnittstelle festzulegen:

  1. Wechseln Sie zur Seite Pipelines, wählen Sie die entsprechende Pipeline aus und klicken Sie dann auf Bearbeiten.
  2. Suchen Sie die Variablen für diese Pipeline.
  3. Fügen Sie die Variable hinzu oder aktualisieren Sie sie.
  4. Wählen Sie das Symbol Sperre" aus, um die Variable auf verschlüsselte Weise zu speichern.
  5. Speichern Sie die Pipeline.

Geheime Variablen werden im Ruhezustand mit einem 2048-Bit-RSA-Schlüssel verschlüsselt. Geheime Schlüssel sind im Agent für Aufgaben und Skripts verfügbar, die verwendet werden sollen. Achten Sie darauf, wer Zugriff auf Ihre Pipeline hat.

Wichtig

Wir bemühen uns, geheime Geheimnisse aus der Ausgabe von Azure Pipelines zu maskieren, aber Sie müssen trotzdem Vorsichtsmaßnahmen ergreifen. Niemals als Ausgabe echogeheimnisse. Einige Befehlszeilenargumente für Betriebssysteme protokollieren. Übergeben Sie niemals geheime Schlüssel in der Befehlszeile. Stattdessen schlagen wir vor, dass Sie Ihre Geheimnisse in Umgebungsvariablen zuordnen.

Wir masken niemals Teilzeichenfolgen von Geheimnissen. Wenn z. B. "abc123" als geheimer Schlüssel festgelegt ist, wird "abc" nicht aus den Protokollen maskiert. Dies ist, das Maskieren von Geheimschlüsseln auf zu präziser Ebene zu vermeiden, wodurch die Protokolle nicht lesbar sind. Aus diesem Grund sollten Geheime keine strukturierten Daten enthalten. Wenn beispielsweise "{ "foo": "bar" }" als geheimer Schlüssel festgelegt ist, wird "Balken" nicht aus den Protokollen maskiert.

Im Gegensatz zu einer normalen Variable werden sie nicht automatisch in Umgebungsvariablen für Skripts entschlüsselt. Sie müssen geheime Variablen explizit zuordnen.

Das folgende Beispiel zeigt, wie eine geheime Variable verwendet wird, die in PowerShell- und Bash-Skripts aufgerufen mySecret wird. Im Gegensatz zu einer normalen Pipelinevariable gibt es keine Umgebungsvariable namens MYSECRET.

variables:
 GLOBAL_MYSECRET: $(mySecret) # this will not work because the secret variable needs to be mapped as env
 GLOBAL_MY_MAPPED_ENV_VAR: $(nonSecretVariable) # this works because it's not a secret.

steps:

- powershell: |
    Write-Host "Using an input-macro works: $(mySecret)"
    Write-Host "Using the env var directly does not work: $env:MYSECRET"
    Write-Host "Using a global secret var mapped in the pipeline does not work either: $env:GLOBAL_MYSECRET"
    Write-Host "Using a global non-secret var mapped in the pipeline works: $env:GLOBAL_MY_MAPPED_ENV_VAR" 
    Write-Host "Using the mapped env var for this task works and is recommended: $env:MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable

- bash: |
    echo "Using an input-macro works: $(mySecret)"
    echo "Using the env var directly does not work: $MYSECRET"
    echo "Using a global secret var mapped in the pipeline does not work either: $GLOBAL_MYSECRET"
    echo "Using a global non-secret var mapped in the pipeline works: $GLOBAL_MY_MAPPED_ENV_VAR" 
    echo "Using the mapped env var for this task works and is recommended: $MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable


Die Ausgabe aus beiden Aufgaben im vorherigen Skript würde wie folgt aussehen:

Using an input-macro works: ***
Using the env var directly does not work:
Using a global secret var mapped in the pipeline does not work either:
Using a global non-secret var mapped in the pipeline works: foo
Using the mapped env var for this task works and is recommended: ***

Sie können auch geheime Variablen außerhalb von Skripts verwenden. Sie können beispielsweise geheime Variablen aufgaben mithilfe der variables Definition zuordnen. In diesem Beispiel wird gezeigt, wie geheime Variablen $(vmsUser) und $(vmsAdminPass) in einer Azure-Dateikopieaufgabe verwendet werden.

variables:
  VMS_USER: $(vmsUser)
  VMS_PASS: $(vmsAdminPass)

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: AzureFileCopy@4
  inputs:
    SourcePath: 'my/path'
    azureSubscription: 'my-subscription'
    Destination: 'AzureVMs'
    storage: 'my-storage'
    resourceGroup: 'my-rg'
    vmsAdminUserName: $(VMS_USER)
    vmsAdminPassword: $(VMS_PASS)

Referenzschlüsselvariablen in Variablengruppen

In diesem Beispiel wird gezeigt, wie Sie auf eine Variablengruppe in Ihrer YAML-Datei verweisen und auch Variablen innerhalb des YAML hinzufügen. Es gibt zwei Variablen, die aus der Variablengruppe verwendet werden: user und token. Die token Variable ist geheim und der Umgebungsvariable $env:MY_MAPPED_TOKEN zugeordnet, damit sie im YAML referenziert werden kann.

Dieser YAML ruft einen REST-Aufruf ab, um eine Liste der Versionen abzurufen und das Ergebnis auszugeben.

variables: 
- group: 'my-var-group' # variable group
- name: 'devopsAccount' # new variable defined in YAML
  value: 'contoso'
- name: 'projectName' # new variable defined in YAML
  value: 'contosoads'

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
        # Encode the Personal Access Token (PAT)
        # $env:USER is a normal variable in the variable group
        # $env:MY_MAPPED_TOKEN is a mapped secret variable
        $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $env:USER,$env:MY_MAPPED_TOKEN)))

        # Get a list of releases
        $uri = "https://vsrm.dev.azure.com/$(devopsAccount)/$(projectName)/_apis/release/releases?api-version=5.1"

        # Invoke the REST call
        $result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

        # Output releases in JSON
        Write-Host $result.value
  env:
    MY_MAPPED_TOKEN: $(token) # Maps the secret variable $(token) from my-var-group

Wichtig

Standardmäßig werden bei GitHub-Repositorys geheime Variablen, die Ihrer Pipeline zugeordnet sind, nicht zur Verfügung gestellt, um Anforderungsbuilds von Forks abzurufen. Weitere Informationen finden Sie unter "Beiträge von Forks".

YAML wird in TFS nicht unterstützt.

Freigeben von Variablen über Pipelines hinweg

Verwenden Sie die Webschnittstelle, um Variablen in mehreren Pipelines in Ihrem Projekt freizugeben. Verwenden Sie unter "Bibliothek" variablen Gruppen.

Verwenden von Ausgabevariablen aus Tasks

Einige Aufgaben definieren Ausgabevariablen, die Sie in nachgelagerten Schritten, Aufträgen und Phasen nutzen können. In YAML können Sie mithilfe von Abhängigkeiten auf Variablen über Aufträge und Stufen zugreifen.

Einige Aufgaben definieren Ausgabevariablen, die Sie in nachgelagerten Schritten und Aufträgen innerhalb derselben Phase nutzen können. In YAML können Sie mithilfe von Abhängigkeiten auf Variablen in allen Aufträgen zugreifen.

Einige Aufgaben definieren Ausgabevariablen, die Sie in nachgelagerten Schritten innerhalb desselben Auftrags verwenden können.

  • Verwenden Sie die Verwendung TASK.VARIABLE, um auf eine Variable aus einer anderen Aufgabe innerhalb desselben Auftrags zu verweisen.
  • Verwenden Sie zum dependencies.JOB.outputs['TASK.VARIABLE']Verweisen auf eine Variable aus einer Aufgabe aus einem anderen Auftrag.

Hinweis

Standardmäßig hängt jede Phase in einer Pipeline von der ersten in der YAML-Datei ab. Wenn Sie auf eine Phase verweisen müssen, die nicht unmittelbar vor dem aktuellen Element liegt, können Sie diese automatische Standardeinstellung außer Kraft setzen, indem Sie der Phase einen dependsOn Abschnitt hinzufügen.

Hinweis

In den folgenden Beispielen wird die Standardpipelinesyntax verwendet. Wenn Sie Bereitstellungspipelinen verwenden, unterscheiden sich variable und bedingte Variablensyntax. Informationen zur zu verwendenden Syntax finden Sie unter Bereitstellungsaufträge.

In diesen Beispielen wird davon ausgegangen, dass eine Aufgabe aufgerufen MyTaskwird, die eine Ausgabevariable namens " MyVar. Erfahren Sie mehr über die Syntax in Ausdrücken – Abhängigkeiten.

Verwenden von Ausgaben im selben Auftrag

steps:
- task: MyTask@1  # this step generates the output variable
  name: ProduceVar  # because we're going to depend on it, we need to name the step
- script: echo $(ProduceVar.MyVar) # this step uses the output variable

Verwenden von Ausgaben in einem anderen Auftrag

jobs:
- job: A
  steps:
  # assume that MyTask generates an output variable called "MyVar"
  # (you would learn that from the task's documentation)
  - task: MyTask@1
    name: ProduceVar  # because we're going to depend on it, we need to name the step
- job: B
  dependsOn: A
  variables:
    # map the output variable from A into this job
    varFromA: $[ dependencies.A.outputs['ProduceVar.MyVar'] ]
  steps:
  - script: echo $(varFromA) # this step uses the mapped-in variable

Verwenden von Ausgaben in einer anderen Phase

Verwenden Sie die stageDependencies Syntax, um die Ausgabe einer anderen Phase auf Jobebene zu verwenden:

  • Auf Stufenebene ist das Format für das Verweisen auf Variablen aus einer anderen Stufe dependencies.STAGE.outputs['JOB.TASK.VARIABLE']
  • Auf Auftragsebene ist das Format für das Verweisen auf Variablen aus einer anderen Phase stageDependencies.STAGE.JOB.outputs['TASK.VARIABLE']
stages:
- stage: One
  jobs:
  - job: A
    steps:
    - task: MyTask@1  # this step generates the output variable
      name: ProduceVar  # because we're going to depend on it, we need to name the step
- stage: Two
  jobs:
  - job: B
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

Sie können variablen auch zwischen Phasen mit einer Dateieingabe übergeben. Dazu müssen Sie Variablen in der zweiten Phase auf Auftragsebene definieren und dann die Variablen als env: Eingaben übergeben.

## script-a.sh
echo "##vso[task.setvariable variable=sauce;isOutput=true]crushed tomatoes"
## script-b.sh
echo 'Hello file version'
echo $skipMe
echo $StageSauce
## azure-pipelines.yml
stages:

- stage: one
  jobs:
  - job: A
    steps:
    - task: Bash@3
      inputs:
          filePath: 'script-a.sh'
      name: setvar
    - bash: |
       echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]true"
      name: skipstep

- stage: two
  jobs:
  - job: B
    variables:
      - name: StageSauce
        value: $[ stageDependencies.one.A.outputs['setvar.sauce'] ]
      - name: skipMe
        value: $[ stageDependencies.one.A.outputs['skipstep.skipsubsequent'] ]
    steps:
    - task: Bash@3
      inputs:
        filePath: 'script-b.sh'
      name: fileversion
      env:
        StageSauce: $(StageSauce) # predefined in variables section
        skipMe: $(skipMe) # predefined in variables section
    - task: Bash@3
      inputs:
        targetType: 'inline'
        script: |
          echo 'Hello inline version'
          echo $(skipMe) 
          echo $(StageSauce) 

Die Ausgabe aus Phasen in der vorherigen Pipeline sieht wie folgt aus:

Hello inline version
true
crushed tomatoes

Listenvariablen

Sie können alle Variablen in Ihrer Pipeline mit dem Befehl "az pipelines variable list " auflisten. Informationen zu den ersten Schritten finden Sie unter Get started with Azure DevOps CLI.

az pipelines variable list [--org]
                           [--pipeline-id]
                           [--pipeline-name]
                           [--project]

Parameter

  • org: Azure DevOps-Organisations-URL. Sie können die Standardorganisation mithilfe az devops configure -d organization=ORG_URLvon . Erforderlich, wenn sie nicht als Standard konfiguriert oder mit git configder Verwendung aufgenommen wurde. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • Pipeline-ID: Erforderlich, wenn der Pipelinename nicht angegeben wird. Die ID der Pipeline.
  • Pipelinename: Erforderlich, wenn die Pipeline-ID nicht angegeben wird, aber ignoriert wird, wenn pipeline-id angegeben wird. Name der Pipeline.
  • Projekt: Name oder ID des Projekts. Sie können das Standardprojekt mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn sie nicht als Standard konfiguriert oder mithilfe von git config" aufgenommen" ausgewählt wurde.

Beispiel

Der folgende Befehl listet alle Variablen in der Pipeline mit ID 12 auf und zeigt das Ergebnis im Tabellenformat an.

az pipelines variable list --pipeline-id 12 --output table

Name           Allow Override    Is Secret    Value
-------------  ----------------  -----------  ------------
MyVariable     False             False        platform
NextVariable   False             True         platform
Configuration  False             False        config.debug

Festlegen von Variablen in Skripts

Ein Skript in Ihrer Pipeline kann eine Variable definieren, damit sie von einem der folgenden Schritte in der Pipeline genutzt werden kann. Alle variablen, die von dieser Methode festgelegt werden, werden als Zeichenfolgen behandelt. Wenn Sie eine Variable aus einem Skript festlegen möchten, verwenden Sie eine Befehlssyntax und drucken sie in Stdout.

Festlegen einer Auftragsbereichsvariable aus einem Skript

Um eine Variable aus einem Skript festzulegen, verwenden Sie den task.setvariableProtokollierungsbefehl. Dadurch werden die Umgebungsvariablen für nachfolgende Aufträge aktualisiert. Nachfolgende Aufträge haben Zugriff auf die neue Variable mit Makrosyntax und in Aufgaben als Umgebungsvariablen.

Wenn issecret der Wert auf "true" festgelegt ist, wird der Wert der Variablen als geheimer Schlüssel gespeichert und aus dem Protokoll maskiert. Weitere Informationen zu geheimen Variablen finden Sie unter Protokollierungsbefehle.

steps:
# Create a variable
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes" # remember to use double quotes

# Use the variable
# "$(sauce)" is replaced by the contents of the `sauce` variable by Azure Pipelines
# before handing the body of the script to the shell.
- bash: |
    echo my pipeline variable is $(sauce)

In den nachfolgenden Schritten wird auch die Pipelinevariable ihrer Umgebung hinzugefügt. Sie können die Variable nicht im definierten Schritt verwenden.

steps:
# Create a variable
# Note that this does not update the environment of the current script.
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes"

# An environment variable called `SAUCE` has been added to all downstream steps
- bash: |
    echo "my environment variable is $SAUCE"
- pwsh: |
    Write-Host "my environment variable is $env:SAUCE"

Die Ausgabe aus der vorherigen Pipeline.

my environment variable is crushed tomatoes
my environment variable is crushed tomatoes

Festlegen einer Ausgabevariable mit mehreren Auftragen

Wenn Sie eine Variable zukünftigen Aufträgen zur Verfügung stellen möchten, müssen Sie sie mithilfe einer Ausgabevariable als isOutput=trueAusgabevariable markieren. Anschließend können Sie sie zukünftigen Aufträgen zuordnen, indem Sie die $[] Syntax verwenden und den Schrittnamen einschließen, der die Variable festgelegt hat. Multiauftragsausgabevariablen funktionieren nur für Aufträge in derselben Phase.

Verwenden Sie die Syntax der Phasenabhängigkeiten , um Variablen an Aufträge in verschiedenen Phasen zu übergeben.

Hinweis

Standardmäßig hängt jede Phase in einer Pipeline von der ersten in der YAML-Datei ab. Daher kann jede Phase Ausgabevariablen aus der vorherigen Phase verwenden. Um auf weitere Phasen zuzugreifen, müssen Sie beispielsweise das Abhängigkeitsdiagramm ändern, wenn Stufe 3 eine Variable aus Stufe 1 erfordert, müssen Sie eine explizite Abhängigkeit von Stufe 1 deklarieren.

Wenn Sie eine Multiauftragsausgabevariable erstellen, sollten Sie dem Ausdruck eine Variable zuweisen. In diesem YAML $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] wird der Variable $(myVarFromJobA)zugewiesen.

jobs:
# Set an output variable from job A
- job: A
  pool:
    vmImage: 'windows-latest'
  steps:
  - powershell: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable into job B
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromJobA: $[ dependencies.A.outputs['setvarStep.myOutputVar'] ]  # map in the variable
                                                                          # remember, expressions require single quotes
  steps:
  - script: echo $(myVarFromJobA)
    name: echovar

Die Ausgabe aus der vorherigen Pipeline.

this is the value
this is the value

Wenn Sie eine Variable von einer Phase auf eine andere festlegen, verwenden Sie stageDependencies.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=myStageOutputVar;isOutput=true]this is a stage output var"
       name: printvar

- stage: B
  dependsOn: A
  variables:
    myVarfromStageA: $[ stageDependencies.A.A1.outputs['printvar.myStageOutputVar'] ]
  jobs:
  - job: B1
    steps:
    - script: echo $(myVarfromStageA)

Wenn Sie eine Variable aus einer Matrix oder einem Datenschnitt festlegen, müssen Sie folgendes einschließen, um auf die Variable zu verweisen, wenn Sie von einem nachgelagerten Auftrag darauf zugreifen:

  • Der Name des Auftrags.
  • Der Schritt.
jobs:

# Set an output variable from a job with a matrix
- job: A
  pool:
    vmImage: 'ubuntu-18.04'
  strategy:
    maxParallel: 2
    matrix:
      debugJob:
        configuration: debug
        platform: x64
      releaseJob:
        configuration: release
        platform: x64
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the $(configuration) value"
    name: setvarStep
  - bash: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the debug job
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromJobADebug: $[ dependencies.A.outputs['debugJob.setvarStep.myOutputVar'] ]
  steps:
  - script: echo $(myVarFromJobADebug)
    name: echovar
jobs:

# Set an output variable from a job with slicing
- job: A
  pool:
    vmImage: 'ubuntu-18.04'
    parallel: 2 # Two slices
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the slice $(system.jobPositionInPhase) value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ]
  steps:
  - script: "echo $(myVarFromJobsA1)"
    name: echovar

Stellen Sie sicher, dass Sie den Auftragsnamen den Ausgabevariablen eines Bereitstellungsauftrags voranstellen. In diesem Fall lautet Ader Auftragsname :

jobs:

# Set an output variable from a deployment
- deployment: A
  pool:
    vmImage: 'ubuntu-18.04'
  environment: staging
  strategy:
    runOnce:
      deploy:
        steps:
        - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the deployment variable value"
          name: setvarStep
        - bash: echo $(setvarStep.myOutputVar)
          name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromDeploymentJob: $[ dependencies.A.outputs['A.setvarStep.myOutputVar'] ]
  steps:
  - bash: "echo $(myVarFromDeploymentJob)"
    name: echovar

YAML wird in TFS nicht unterstützt.

Festlegen von Variablen mithilfe von Ausdrücken

Sie können eine Variable mithilfe eines Ausdrucks festlegen. Es ist bereits ein Fall aufgetreten, um eine Variable auf die Ausgabe eines anderen von einem vorherigen Auftrag festzulegen.

- job: B
  dependsOn: A
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ] # remember to use single quotes

Sie können einen der unterstützten Ausdrücke verwenden, um eine Variable festzulegen. Hier sehen Sie ein Beispiel zum Festlegen einer Variablen, die als Zähler fungiert, der bei 100 beginnt, für jede Ausführung um 1 erhöht wird und jeden Tag auf 100 zurückgesetzt wird.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Weitere Informationen zu Leistungsindikatoren, Abhängigkeiten und anderen Ausdrücken finden Sie unter Ausdrücke.

YAML wird in TFS nicht unterstützt.

Konfigurieren von settable Variablen für Schritte

Sie können innerhalb eines Schritts definieren settableVariables oder angeben, dass keine Variablen festgelegt werden können.

In diesem Beispiel kann das Skript keine Variable festlegen.

steps:
- script: echo This is a step
  target:
    settableVariables: none

In diesem Beispiel ermöglicht das Skript die Variable sauce , aber nicht die Variable secretSauce. Auf der Pipelineausführungsseite wird eine Warnung angezeigt.

Warnung, dass Sie

steps:
  - bash: |
      echo "##vso[task.setvariable variable=Sauce;]crushed tomatoes"
      echo "##vso[task.setvariable variable=secretSauce;]crushed tomatoes with garlic"
    target:
     settableVariables:
      - sauce
    name: SetVars
  - bash: 
      echo "Sauce is $(sauce)"
      echo "secretSauce is $(secretSauce)"
    name: OutputVars

Erlauben zum Einreihungszeitpunkt

Wenn eine Variable im variables Block einer YAML-Datei angezeigt wird, ist der Wert behoben und kann nicht zur Warteschlangenzeit überschrieben werden. Bewährte Methode besteht darin, Ihre Variablen in einer YAML-Datei zu definieren, aber es gibt Zeiten, in denen dies nicht sinnvoll ist. Sie können beispielsweise eine geheime Variable definieren und nicht über die Variable verfügen, die in Ihrem YAML verfügbar gemacht wird. Möglicherweise müssen Sie auch während der Pipelineausführung manuell einen Variablenwert festlegen.

Sie haben zwei Optionen zum Definieren von Warteschlangenzeitwerten. Sie können eine Variable in der Benutzeroberfläche definieren und die Option auswählen, mit der Benutzer diesen Wert beim Ausführen dieser Pipeline außer Kraft setzen können, oder Sie können stattdessen Laufzeitparameter verwenden. Wenn Ihre Variable kein geheimer Schlüssel ist, empfiehlt es sich, Laufzeitparameter zu verwenden.

Wenn Sie eine Variable zur Warteschlangenzeit festlegen möchten, fügen Sie eine neue Variable in Ihrer Pipeline hinzu, und wählen Sie die Option "Außerkraftsetzung" aus.

Legen Sie eine Variable zur Warteschlangenzeit fest.

Damit eine Variable zur Warteschlangenzeit festgelegt werden kann, stellen Sie sicher, dass die Variable nicht auch im variables Block einer Pipeline oder eines Auftrags angezeigt wird. Wenn Sie eine Variable sowohl im Variablenblock eines YAML als auch in der Benutzeroberfläche definieren, hat der Wert in YAML Priorität.

YAML wird in TFS nicht unterstützt.

Erweiterung von Variablen

Wenn Sie in mehreren Bereichen eine Variable mit dem gleichen Namen festlegen, gilt die folgende Rangfolge (höchster Rang zuerst):

  1. In der YAML-Datei festgelegte Variable auf Auftragsebene
  2. In der YAML-Datei festgelegte Variable auf Phasenebene
  3. In der YAML-Datei festgelegte Variable auf Pipelineebene
  4. Zum Einreihungszeitpunkt festgelegte Variable
  5. Über die Benutzeroberfläche für die Pipelineeinstellungen festgelegte Variable

Im folgenden Beispiel wird dieselbe Variable a auf Pipelineebene und Auftragsebene in der YAML-Datei festgelegt. Sie wird auch in einer Variablengruppe Gund als Variable auf der Benutzeroberfläche der Pipelineeinstellungen festgelegt.

variables:
  a: 'pipeline yaml'

stages:
- stage: one
  displayName: one
  variables:
  - name: a
    value: 'stage yaml'

  jobs:
  - job: A
    variables:
    - name: a
      value: 'job yaml'
    steps:
    - bash: echo $(a)        # This will be 'job yaml'

Wenn Sie eine Variable mit demselben Namen im gleichen Bereich festlegen, hat der letzte Satzwert Vorrang.

stages:
- stage: one
  displayName: Stage One
  variables: 
    - name: a
      value: alpha
    - name: a
      value: beta
  jobs: 
  - job: I
    displayName: Job I
    variables:
      - name: b
        value: uno
      - name: b
        value: dos
    steps: 
    - script: echo $(a) #outputs beta
    - script: echo $(b) #outputs dos

Hinweis

Wenn Sie eine Variable in der YAML-Datei festlegen, definieren Sie sie nicht im Web-Editor als settable zur Warteschlangenzeit. Sie können derzeit keine Variablen ändern, die in der YAML-Datei zur Warteschlangenzeit festgelegt sind. Wenn Sie zur Warteschlangenzeit eine Variable festlegen müssen, legen Sie sie nicht in der YAML-Datei fest.

Variablen werden einmal erweitert, wenn die Ausführung gestartet wird, und erneut am Anfang jedes Schritts. Zum Beispiel:

jobs:
- job: A
  variables:
    a: 10
  steps:
  - bash: |
      echo $(a)            # This will be 10
      echo '##vso[task.setvariable variable=a]20'
      echo $(a)            # This will also be 10, since the expansion of $(a) happens before the step
  - bash: echo $(a)        # This will be 20, since the variables are expanded just before the step

Es gibt zwei Schritte im vorherigen Beispiel. Die Erweiterung erfolgt $(a) einmal am Anfang des Auftrags und einmal am Anfang jeder der beiden Schritte.

Da Variablen am Anfang eines Auftrags erweitert werden, können Sie sie nicht in einer Strategie verwenden. Im folgenden Beispiel können Sie die Variable nicht verwenden, um die Auftragsmatrix zu erweitern, da die Variable a nur am Anfang jeder erweiterten Aufgabe verfügbar ist.

jobs:
- job: A
  variables:
    a: 10
  strategy:
    matrix:
      x:
        some_variable: $(a)    # This does not work

Wenn die Variable a eine Ausgabevariable aus einem vorherigen Auftrag ist, können Sie sie in einem zukünftigen Auftrag verwenden.

- job: A
  steps:
  - powershell: echo "##vso[task.setvariable variable=a;isOutput=true]10"
    name: a_step

# Map the variable into job B
- job: B
  dependsOn: A
  variables:
    some_variable: $[ dependencies.A.outputs['a_step.a'] ]

Rekursive Erweiterung

Auf dem Agent werden Variablen, auf die mithilfe der $( ) Syntax verwiesen wird, rekursiv erweitert. Zum Beispiel:

variables:
  myInner: someValue
  myOuter: $(myInner)

steps:
- script: echo $(myOuter)  # prints "someValue"
  displayName: Variable is $(myOuter)  # display name is "Variable is someValue"

YAML wird in TFS nicht unterstützt.