Definieren von Variablen

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 gängigste 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 veränderlich sein. Der Wert einer Variablen kann sich von "Ausführen" in "Ausführen" oder "Auftrag" in Auftrag Ihrer Pipeline ändern.

Wenn Sie dieselbe Variable an mehreren Stellen mit dem gleichen Namen definieren, gewinnt die lokalste Variable. Daher kann eine variable, die auf Auftragsebene definiert ist, eine Variable überschreiben, die auf Stufenebene festgelegt ist. Eine auf Stufenebene definierte Variable überschreibt eine Variable, die auf der Stammebene der Pipeline festgelegt ist. Eine Variable, die auf der Pipelinestammebene festgelegt ist, überschreibt einen Variablensatz auf der Benutzeroberfläche für Pipelineeinstellungen.

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

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

Benutzerdefinierte Variablen

Wenn Sie eine Variable definieren, können Sie verschiedene Syntaxen (Makro, 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 auf der Benutzeroberfläche angeben. Wenn Sie eine Variable auf der Benutzeroberfläche festlegen, kann diese Variable verschlüsselt und als Geheimnis festgelegt werden. Geheimnisvariablen werden in YAML-Pipelines nicht automatisch entschlüsselt und müssen an Ihre YAML-Datei mit oder einer Variablen auf Stammebene übergeben env: werden.

Benutzerdefinierte Variablen können als schreibgeschützt festgelegtwerden. Es gibt Benennungseinschränkungen für Variablen (Beispiel: Sie können secret am Anfang eines Variablennamens nicht verwenden).

Sie können eine Variablengruppe verwenden, um Variablen über mehrere Pipelines hinweg 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 Buildpipelines verwenden, finden Sie unter Vordefinierte Variablen eine umfassende Liste von Systemvariablen. Wenn Sie klassische Releasepipelines verwenden, finden Sie weitere Informationen unter 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 Systemvariablen, bevor die Pipeline ausgeführt wird.

Systemvariablen sind schreibgeschützt.

Umgebungsvariablen

Umgebungsvariablen sind spezifisch für das von Ihnen verwendete Betriebssystem. 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) haben Umgebungsvariablen das Format $NAME . Auf Windows ist das Format %NAME% für Batch und in $env:NAME PowerShell.

System- und benutzerdefinierte Variablen werden auch als Umgebungsvariablen für Ihre Plattform eingefügt. Wenn Variablen in Umgebungsvariablen umgewandelt werden, werden Variablennamen in Großbuchstaben umgewandelt, und Zeiträume werden in Unterstriche umgewandelt. Beispielsweise wird der Variablenname any.variable zum Variablennamen $ANY_VARIABLE .

Einschränkungen bei der Variablenbenennung

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

Grundlegendes zur Variablensyntax

Azure Pipelines unterstützt drei verschiedene Möglichkeiten zum Verweisen auf Variablen: Makro, Vorlagenausdruck und Laufzeitausdruck. Jede Syntax kann für einen anderen Zweck verwendet werden und weist einige Einschränkungen auf.

In einer Pipeline werden Vorlagenausdrucksvariablen ( ${{ variables.var }} ) zur Kompilierzeit verarbeitet, bevor die Laufzeit gestartet wird. Makrosyntaxvariablen $(var) () werden während der Laufzeit verarbeitet, bevor ein Task ausgeführt wird. Laufzeitausdrücke ( $[variables.var] ) werden auch während der Laufzeit verarbeitet, wurden jedoch für die Verwendung mit Bedingungen und Ausdrückenentwickelt. Wenn Sie einen Laufzeitausdruck verwenden, muss er die gesamte rechte Seite einer Definition annehmen.

In diesem Beispiel sehen Sie, dass der Vorlagenausdruck nach dem Aktualisieren der Variablen weiterhin über den Anfangswert der Variablen verfügt. Der Wert der Makrosyntaxvariablen wird aktualisiert. Der Wert des Vorlagenausdrucks ändert sich nicht, da alle Vorlagenausdrucksvariablen zur Kompilierzeit 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 die Makrosyntax ( $(var) ). Die Makrosyntax wurde entwickelt, um Variablenwerte in Aufgabeneingaben und in andere Variablen zu interpolieren.

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 trifft, ersetzt es den Ausdruck durch den Inhalt der Variablen. Wenn es keine Variable mit diesem Namen gibt, bleibt der Makroausdruck unverändert. Wenn z. B. $(var) nicht ersetzt werden kann, wird durch nichts $(var) ersetzt.

Makrosyntaxvariablen bleiben unverändert ohne Wert, da ein leerer Wert wie etwas $() für die ausgeführte Aufgabe bedeuten kann und der Agent nicht davon ausgehen sollte, dass dieser Wert ersetzt werden soll. Wenn Sie z. B. verwenden, $(foo) um in einer Bash-Aufgabe auf eine Variable foo zu verweisen, kann das Ersetzen aller $() Ausdrücke in der Eingabe für den Task ihre Bash-Skripts unterbrechen.

Makrovariablen werden nur erweitert, wenn sie für einen Wert und nicht als Schlüsselwort verwendet werden. Werte werden auf der rechten Seite einer Pipelinedefinition angezeigt. Folgendes ist gültig: key: $(value) . Folgendes ist ungültig: $(key): value . Makrovariablen werden nicht erweitert, wenn sie verwendet werden, um einen Auftragsnamen inline anzuzeigen. Stattdessen müssen Sie die displayName -Eigenschaft verwenden.

Hinweis

Makrosyntaxvariablen werden nur für stages jobs , und steps erweitert. Sie können z. B. keine Makrosyntax innerhalb von resource oder trigger verwenden.

In diesem Beispiel wird die Makrosyntax mit Bash, PowerShell und einem Skripttask 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)

Vorlagenausdruckssyntax

Sie können die Vorlagenausdruckssyntax verwenden, um sowohl Vorlagenparameter als auch Variablen ( ) zu ${{ variables.var }} erweitern. Vorlagenvariablen werden zur Kompilierzeit verarbeitet und vor dem Start der Laufzeit ersetzt. Vorlagenausdrücke sind für die Wiederverwendung von YaML-Teilen als Vorlagen konzipiert.

Vorlagenvariablen werden automatisch zu leeren Zeichenfolgen zusammengeräumt, wenn kein Ersetzungswert gefunden wird. Vorlagenausdrücke können im Gegensatz zu Makro- und Laufzeitausdrücken entweder als Schlüssel (linke Seite) oder als Werte (rechte Seite) angezeigt werden. Folgendes ist gültig: ${{ variables.key }} : ${{ variables.value }} .

Laufzeitausdruckssyntax

Sie können die Laufzeitausdruckssyntax für Variablen verwenden, die zur Laufzeit erweitert werden ( $[variables.var] ). Laufzeitausdrucksvariablen werden automatisch zu leeren Zeichenfolgen zusammengeräumt, wenn kein Ersatzwert gefunden wird. Laufzeitausdrücke sind so konzipiert, dass sie in den Bedingungen von Aufträgen verwendet werden, um die bedingte Ausführung von Aufträgen oder ganze Phasen zu unterstützen.

Laufzeitausdrucksvariablen werden nur erweitert, wenn sie für einen Wert und nicht als Schlüsselwort verwendet werden. Werte werden auf der rechten Seite einer Pipelinedefinition angezeigt. Folgendes ist gültig: key: $[variables.value] . Folgendes ist ungültig: $[variables.key]: value . Der Laufzeitausdruck muss die gesamte rechte Seite eines Schlüssel-Wert-Paars annehmen. Ist z. key: $[variables.value] B. gültig, key: $[variables.value] foo aber nicht .

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

Welche Syntax sollte ich verwenden?

Verwenden Sie die Makrosyntax, wenn Sie Eingaben für eine Aufgabe bereitstellen.

Wählen Sie einen Laufzeitausdruck aus, wenn Sie mit Bedingungen und Ausdrücken arbeiten. Eine Ausnahme ist, wenn Sie über eine Pipeline verfügen, bei der die leere Variable ein Problem beim Drucken verursacht. Wenn Sie beispielsweise über eine bedingte Logik verfügen, die davon abhängig ist, dass eine Variable einen bestimmten Wert oder keinen Wert hat. In diesem Fall sollten Sie einen Laufzeitausdruck 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. Dadurch können Sie Änderungen an der Variablen in Ihrem Versionskontrollsystem nachverfolgen. Sie können variablen auch in der Benutzeroberfläche für Pipelineeinstellungen definieren (siehe Registerkarte Klassisch) und in Ihrer YAML-Datei auf sie verweisen.

Hier ist ein Beispiel, das zeigt, wie sie zwei Variablen festlegen, und configuration , und sie später in den Schritten platform verwenden. Um eine Variable in einer YAML-Anweisung zu verwenden, umschließen Sie sie in $() . Variablen können nicht verwendet werden, um einen in einer 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)

Variablenbereich

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

  • Auf Stammebene, um sie für alle Aufträge in der Pipeline verfügbar zu machen.
  • Auf Phasenebene, um sie nur für eine bestimmte Phase verfügbar zu machen.
  • Auf Auftragsebene, um sie nur für einen bestimmten Auftrag verfügbar zu machen.

Wenn eine Variable am Anfang einer YAML-Datei definiert wird, ist sie für alle Aufträge und Phasen in der Pipeline verfügbar und eine globale Variable. Globale Variablen, die in yaml definiert sind, sind auf der Benutzeroberfläche der Pipelineeinstellungen nicht sichtbar.

Variablen auf Auftragsebene überschreiben Variablen auf Stamm- und Phasenebene. Variablen auf Phasenebene überschreiben Variablen auf 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 beider Aufträge sieht wie die folgenden aus:

# job1
value 
value1
value1

# job2
value
value2
value

Angeben von Variablen

In den vorherigen Beispielen folgt variables auf das Schlüsselwort eine Liste von Schlüssel-Wert-Paaren. 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 von Variablenspezifizierern. Die Variablenspezifizierer sind für eine reguläre Variable, für eine Variablengruppe und für das Hinzufügen name group einer template Variablenvorlage. 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 über Umgebungsvariablen für Skripts verfügbar gemacht werden. Die Syntax für die Verwendung dieser Umgebungsvariablen hängt von der Skriptsprache ab.

Der Name ist in Großbuchstaben, und der . wird durch _ ersetzt. Dies wird automatisch in die Prozessumgebung eingefügt. Im Folgenden finden Sie einige Beispiele:

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

Wichtig

Vordefinierte Variablen, die Dateipfade enthalten, werden basierend auf Agenthosttyp und Shelltyp in die entsprechende Formatierung (Windows Format C:\foo\ im Vergleich zum Unix-Stil /foo/) übersetzt. Wenn Sie Bash-Skripttasks auf 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 Dateipfadart verfügen.

YAML wird in TFS nicht unterstützt.

Festlegen von Geheimnisvariablen

Legen Sie keine Geheimnisvariablen in Ihrer YAML-Datei fest. Betriebssysteme protokollieren häufig Befehle für die Prozesse, die sie ausführen, und Sie möchten nicht, dass das Protokoll ein Geheimnis enthält, das Sie als Eingabe übergeben haben. Verwenden Sie die Umgebung des Skripts, oder ordnen Sie die Variable innerhalb des variables Blocks zu, um Geheimnisse an Ihre Pipeline zu übergeben.

Sie müssen geheimnisvariablen 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 Geheimnisvariablen in Variablengruppenfestlegen.

Führen Sie zum Festlegen von Geheimnissen in der Webschnittstelle die folgenden Schritte aus:

  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. Klicken Sie auf das Symbol Secret Sperrsymbol, um die Variable verschlüsselt zu speichern.
  5. Speichern Sie die Pipeline.

Geheimnisvariablen werden ruhend mit einem 2048-Bit-RSA-Schlüssel verschlüsselt. Geheimnisse sind auf dem Agent für Aufgaben und Skripts verfügbar, die verwendet werden können. Achten Sie darauf, wer Zugriff hat, um Ihre Pipeline zu ändern.

Wichtig

Wir sind darauf achten, Geheimnisse zu maskieren, damit sie nicht in Azure Pipelines werden, aber Sie müssen dennoch Vorsichtsmaßnahmen treffen. Geben Sie Geheimnisse niemals als Ausgabe zurück. Einige Betriebssysteme protokollieren Befehlszeilenargumente. Übergeben Sie geheimnisse niemals über die Befehlszeile. Stattdessen empfehlen wir Ihnen, Ihre Geheimnisse Umgebungsvariablen zu zuordnen.

Teilzeichenfolgen von Geheimnissen werden nie maskiert. Wenn beispielsweise "abc123" als Geheimnis festgelegt ist, wird "abc" nicht aus den Protokollen maskiert. Dadurch wird vermieden, dass Geheimnisse auf einer zu präzisen Ebene maskiert werden, wodurch die Protokolle unlesbar werden. Aus diesem Grund sollten Geheimnisse keine strukturierten Daten enthalten. Wenn beispielsweise "{ "foo": "bar" }" als Geheimnis festgelegt ist, wird "bar" nicht aus den Protokollen maskiert.

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

Das folgende Beispiel zeigt, wie sie eine Geheimnisvariable namens mySecret in PowerShell- und Bash-Skripts verwenden. Im Gegensatz zu einer normalen Pipelinevariablen 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 beider 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 Geheimnisvariablen außerhalb von Skripts verwenden. Beispielsweise können Sie Mithilfe der Definition Geheimnisvariablen Aufgaben variables zuordnen. In diesem Beispiel wird gezeigt, wie Sie Geheimnisvariablen $(vmsUser) und in einem $(vmsAdminPass) Azure-Dateikopiertask verwenden.

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)

Verweisen auf geheimnisverschlüsselte Variablen in Variablengruppen

In diesem Beispiel wird gezeigt, wie Sie in Ihrer YAML-Datei auf eine Variablengruppe verweisen und variablen innerhalb der YAML hinzufügen. Es werden zwei Variablen aus der Variablengruppe verwendet: user und token . Die token Variable ist geheimnisverschlüsselt und wird der Umgebungsvariablen $env:MY_MAPPED_TOKEN zugeordnet, sodass sie in yaml referenziert werden kann.

Diese YAML führt einen REST-Aufruf aus, um eine Liste von Releases abzurufen, und gibt das Ergebnis aus.

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

Bei GitHub Repositorys werden geheime Variablen, die Ihrer Pipeline zugeordnet sind, standardmäßig nicht für Pull Request-Builds von Forks verfügbar gemacht. 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 für mehrere Pipelines in Ihrem Projekt freizugeben. Verwenden Sie unter Bibliothek die Variablengruppen.

Verwenden von Ausgabevariablen aus Tasks

Einige Tasks definieren Ausgabevariablen, die Sie in Downstreamschritten, Aufträgen und Phasen nutzen können. In YAML können Sie über Aufträge und Phasen hinweg mithilfe von Abhängigkeitenauf Variablen zugreifen.

Einige Tasks definieren Ausgabevariablen, die Sie in Downstreamschritten und Aufträgen innerhalb derselben Phase nutzen können. In YAML können Sie mithilfe von Abhängigkeitenaufträgeübergreifend auf Variablen zugreifen.

Einige Tasks definieren Ausgabevariablen, die Sie in Downstreamschritten innerhalb desselben Auftrags nutzen können.

Hinweis

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

Hinweis

In den folgenden Beispielen wird die Standardmäßige Pipelinesyntax verwendet. Wenn Sie Bereitstellungspipelines verwenden, unterscheiden sich sowohl die Syntax variabler als auch der bedingten Variablen. Informationen zur spezifischen Syntax finden Sie unter Bereitstellungsaufträge.

In diesen Beispielen wird davon ausgegangen, dass wir über eine Aufgabe namens MyTask verfügen, die eine Ausgabevariable mit dem Namen MyVar festlegt. Weitere Informationen zur Syntax finden Sie unter Ausdrücke – Abhängigkeiten.

Verwenden von Ausgaben im gleichen 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

Um die Ausgabe aus einer anderen Phase auf Auftragsebene zu verwenden, verwenden Sie die stageDependencies -Syntax.

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
  - 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 die Variablen dann 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 der Phasen in der vorherigen Pipeline sieht wie die folgenden aus:

Hello inline version
true
crushed tomatoes

Auflisten von Variablen

Sie können alle Variablen in Ihrer Pipeline mit dem Befehl az pipelines variable list auflisten. Informationen zu den ersten Schritte finden Sie unter Erste Schritte mit Azure DevOps CLI.

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

Parameter

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

Beispiel

Der folgende Befehl listet alle Variablen in der Pipeline mit der 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 nachfolgenden Schritte in der Pipeline verwendet werden kann. Alle von dieser Methode festgelegten Variablen werden als Zeichenfolgen behandelt. Zum Festlegen einer Variablen aus einem Skript verwenden Sie eine Befehlssyntax und geben in stdout aus.

Festlegen einer Auftragsvariablen aus einem Skript

Zum Festlegen einer Variablen aus einem Skript verwenden Sie den task.setvariable Protokollierungsbefehl. 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 auf TRUE festgelegt ist, wird der Wert der Variablen als Geheimnis issecret gespeichert und aus dem Protokoll maskiert. Weitere Informationen zu Geheimnisvariablen 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 in dem Schritt verwenden, in dem sie definiert ist.

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 der vorherigen Pipeline.

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

Festlegen einer Ausgabevariablen mit mehreren Auftrags

Wenn Sie eine Variable für zukünftige Aufträge verfügbar machen möchten, müssen Sie sie mit als Ausgabevariable isOutput=true markieren. Anschließend können Sie sie zukünftigen Aufträgen zuordnen, indem Sie die Syntax verwenden und den Schrittnamen angeben, $[] mit dem die Variable festgelegt wird. Ausgabevariablen mit mehreren Aufträgen funktionieren nur für Aufträge in derselben Phase.

Um Variablen an Aufträge in verschiedenen Phasen zu übergeben, verwenden Sie die Syntax für Phasenabhängigkeiten.

Hinweis

Standardmäßig hängt jede Phase in einer Pipeline von der Phase direkt davor in der YAML-Datei ab. Daher kann jede Phase Ausgabevariablen aus der vorherigen Phase verwenden. Um auf weitere Phasen zu zugreifen, müssen Sie das Abhängigkeitsdiagramm ändern. Wenn z. B. Phase 3 eine Variable aus Phase 1 erfordert, müssen Sie eine explizite Abhängigkeit von Phase 1 deklarieren.

Wenn Sie eine Ausgabevariable mit mehreren Auftrag erstellen, sollten Sie den Ausdruck einer Variablen zuweisen. In diesem YAML wird $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] der Variablen $(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 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 Slice festlegen, müssen Sie Folgendes hinzufügen, um auf die Variable zu verweisen, wenn Sie von einem Downstreamauftrag 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 vorangestellt haben. In diesem Fall ist der Auftragsname A :

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. Wir haben bereits einen Fall von diesem gefunden, um eine Variable auf die Ausgabe eines anderen aus einem vorherigen Auftrag zu setzen.

- 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 zum Festlegen einer Variablen verwenden. Hier ist ein Beispiel für das Festlegen einer Variablen als Indikator, der bei 100 beginnt, für jede Ausführung um 1 erhöht und täglich 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 festlegbaren Variablen für Schritte

Sie können innerhalb settableVariables eines Schritts definieren 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 lässt das Skript die Variable sauce zu, aber nicht die Variable secretSauce . Auf der Seite "Pipeline run" (Pipelinelauf) wird eine Warnung angezeigt.

Warnung, dass Sie secretSauce nicht festlegen können.

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

Zur Warteschlangenzeit zulassen

Wenn eine Variable im Block einer YAML-Datei angezeigt wird, wird ihr Wert festgelegt und kann variables zur Warteschlangenzeit nicht überschrieben werden. Die bewährte Methode besteht in der Definition Ihrer Variablen in einer YAML-Datei, aber es gibt Zeiten, in denen dies nicht sinnvoll ist. Sie können z. B. eine Geheimnisvariable definieren und die Variable nicht in Ihrer YAML verfügbar machen. Oder Sie müssen während der Pipelinelauf manuell einen Variablenwert festlegen.

Sie haben zwei Optionen zum Definieren von Warteschlangenzeitwerten. Sie können eine Variable auf der Benutzeroberfläche definieren und die Option Benutzern das Überschreiben dieses Werts beim Ausführen dieser Pipeline erlauben oder stattdessen Laufzeitparameter verwenden. Wenn Ihre Variable kein Geheimnis ist, besteht die bewährte Methode darin, Laufzeitparameterzu verwenden.

Um eine Variable zur Warteschlangenzeit festzulegen, fügen Sie in Ihrer Pipeline eine neue Variable hinzu, und wählen Sie die Außerkraftsetzungsoption 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 Block einer Pipeline oder eines Auftrags angezeigt variables wird. Wenn Sie eine Variable sowohl im Variablenblock einer YAML-Datei als auch in der Benutzeroberfläche definieren, hat der Wert in der YAML Priorität.

YAML wird in TFS nicht unterstützt.

Erweiterung von Variablen

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

  1. In der YAML-Datei festgelegte Variable auf Auftragsebene
  2. In der YAML-Datei festgelegte Variable auf Stufenebene
  3. In der YAML-Datei festgelegte Variable auf Pipelineebene
  4. Zur Warteschlangenzeit festgelegte Variable
  5. Auf der Benutzeroberfläche für Pipelineeinstellungen festgelegte Pipelinevariablen

Im folgenden Beispiel wird dieselbe Variable a auf Pipeline- und Auftragsebene in der YAML-Datei festgelegt. Sie wird auch in einer Variablengruppe G und als Variable in der Benutzeroberfläche für 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 dem gleichen Namen im gleichen Bereich festlegen, hat der zuletzt festgelegte Wert 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 zur Warteschlangenzeit als settable. Sie können derzeit keine Variablen ändern, die zur Warteschlangenzeit in der YAML-Datei festgelegt sind. Wenn Sie eine Variable zur Warteschlangenzeit festlegen müssen, legen Sie sie nicht in der YAML-Datei fest.

Variablen werden einmal erweitert, wenn die Ausführung gestartet wird, und wieder am Anfang jedes Schritts. 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

Im vorherigen Beispiel gibt es zwei Schritte. Die Erweiterung von $(a) erfolgt einmal am Anfang des Auftrags und einmal am Anfang jedes der beiden Schritte.

Da Variablen zu Beginn eines Auftrags erweitert werden, können Sie sie nicht in einer Strategie verwenden. Im folgenden Beispiel können Sie die Variable nicht verwenden, a um die Auftragsmatrix zu erweitern, da die Variable nur am Anfang jedes erweiterten Auftrags 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. 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.