Protokollierungsbefehle

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

Protokollierungsbefehle sind die Kommunikation von tasks und Skripts mit dem Azure Pipelines-Agent. Wenn ein Pipelineschritt eine speziell formatierte Zeichenfolge in die Standardausgabe (stdout) schreibt, fängt der Agent sie ab und führt die angeforderte Aktion aus, z. B. Festlegen einer Variablen, Hochladen eines Artefakts oder Markieren des Schritts als fehlgeschlagen. Protokollierungsbefehle sind hilfreich zum Anpassen des Pipelineverhaltens und zur Problembehandlung.

Funktionsweise von Protokollierungsbefehlen

Der Azure Pipelines-Agent verarbeitet Protokollierungsbefehle, indem standardausgabe (stdout) aus den einzelnen Aufgaben- und Skriptschritten während der Ausführung des Schritts in Echtzeit gescannt wird. Wenn der Agent eine Zeile erkennt, die dem ##vso[...] Oder ##[...] Muster in stdout entspricht, interpretiert er den Befehl und führt die angeforderte Aktion aus (z. B. Festlegen einer Variablen oder Hochladen eines Artefakts).

./my-external-tool 2>&1 | while IFS= read -r line; do echo "$line"; done

Format des Protokollierungsbefehls

Das allgemeine Format eines Protokollierungsbefehls ist wie folgt:

##vso[area.action property1=value;property2=value;...]message

Es gibt auch einige Formatierungsbefehle mit einer etwas anderen Syntax:

##[command]message

Um einen Befehl zur Protokollierung aufzurufen, geben Sie den Befehl über die Standardausgabe aus.

#!/bin/bash
echo "##vso[task.setvariable variable=testvar;]testvalue"

Write-Host "##vso[task.setvariable variable=testvar;]testvalue"

Dateipfade sollten als absolute Pfade angegeben werden: root to a drive on Windows, or beginning with / on Linux and macOS.

Formatierungsbefehle

Bei diesen Befehlen handelt es sich um Nachrichten an den Protokollformatierer in Azure Pipelines. Sie markieren bestimmte Protokollzeilen als Fehler, Warnungen, zuklappbare Abschnitte usw.

Die Formatierungsbefehle sind wie folgt:

##[group]Beginning of a group
##[warning]Warning message
##[error]Error message
##[section]Start of a section
##[debug]Debug text
##[command]Command-line being run
##[endgroup]

Sie können die Formatierungsbefehle in einer Bash- oder PowerShell-Aufgabe verwenden.

steps:
- bash: |
    echo "##[group]Beginning of a group"
    echo "##[warning]Warning message"
    echo "##[error]Error message"
    echo "##[section]Start of a section"
    echo "##[debug]Debug text"
    echo "##[command]Command-line being run"
    echo "##[endgroup]"

steps:
- powershell: |
    Write-Host "##[group]Beginning of a group"
    Write-Host "##[warning]Warning message"
    Write-Host "##[error]Error message"
    Write-Host "##[section]Start of a section"
    Write-Host "##[debug]Debug text"
    Write-Host "##[command]Command-line being run"
    Write-Host "##[endgroup]"

Diese Befehle werden in den Protokollen wie folgt gerendert:

Dieser Befehlsblock kann auch zugeklappt werden und sieht wie folgt aus:

Aufgabenbefehle

LogIssue: Protokollieren eines Fehlers oder einer Warnung

##vso[task.logissue]error/warning message

Verbrauch

Protokollieren Sie eine Fehler- oder Warnmeldung im Zeitachsendatensatz der aktuellen Aufgabe.

Eigenschaften

• type = error oder warning (erforderlich)
• sourcepath = Speicherort der Quelldatei
• linenumber = Zeilennummer
• columnnumber = Spaltennummer
• code = Fehler- oder Warnungscode

Beispiel: Protokollieren eines Fehlers

#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1

Write-Host "##vso[task.logissue type=error]Something went very wrong."
exit 1

Beispiel: Protokollieren einer Warnung zu einer bestimmten Stelle in einer Datei

#!/bin/bash
echo "##vso[task.logissue type=warning;sourcepath=consoleapp/main.cs;linenumber=1;columnnumber=1;code=100;]Found something that could be a problem."

Write-Host "##vso[task.logissue type=warning;sourcepath=consoleapp/main.cs;linenumber=1;columnnumber=1;code=100;]Found something that could be a problem."

SetProgress: Anzeigen von „Prozentsatz abgeschlossen“

##vso[task.setprogress]current operation

Verbrauch

Legen Sie den Status und aktuellen Vorgang für die aktuelle Aufgabe fest.

Eigenschaften

• value = Prozentsatz der Fertigstellung

Beispiel

echo "Begin a lengthy process..."
for i in {0..100..10}
do
   sleep 1
   echo "##vso[task.setprogress value=$i;]Sample Progress Indicator"
done
echo "Lengthy process is complete."

Write-Host "Begin a lengthy process..."
$i=0
While ($i -le 100)
{
   Start-Sleep 1
   Write-Host "##vso[task.setprogress value=$i;]Sample Progress Indicator"
   $i += 10
}
Write-Host "Lengthy process is complete."

Um zu prüfen, wie der Build aussieht, speichern Sie ihn, stellen ihn in die Warteschlange und beobachten die Ausführung. Beachten Sie, dass sich eine Statusanzeige ändert, wenn dieses Skript in der Aufgabe ausgeführt wird.

Abgeschlossen: Abschließen der Zeitachse

##vso[task.complete]current operation

Verbrauch

Schließen Sie den Zeitachsendatensatz für die aktuelle Aufgabe ab, und legen Sie das Ergebnis der Aufgabe und den aktuellen Vorgang fest. Wenn kein Ergebnis bereitgestellt wird, legen Sie das Ergebnis auf „erfolgreich“ fest.

Eigenschaften

• result =
  • Succeeded Die Aufgabe wurde erfolgreich abgeschlossen.
  • SucceededWithIssues Bei der Aufgabe sind Probleme aufgetreten. Der Build wird im besten Fall als teilweise erfolgreich abgeschlossen.
  • Failed Der Build wird als fehlgeschlagen abgeschlossen. (Wenn die Option Steuerungsoptionen: Bei Fehler fortsetzen ausgewählt ist, wird der Build im besten Fall als teilweise erfolgreich abgeschlossen.)

Beispiel

Protokollieren Sie eine Aufgabe als erfolgreich.

##vso[task.complete result=Succeeded;]DONE

Legen Sie eine Aufgabe als fehlgeschlagen fest. Alternativ können Sie auch exit 1 verwenden.

- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi

LogDetail: Erstellen oder Aktualisieren eines Zeitachsendatensatzes für eine Aufgabe

##vso[task.logdetail]current operation

Verbrauch

Erstellt und aktualisiert Zeitachsendatensätze. Dies wird in erster Linie intern von Azure Pipelines verwendet, um Schritte, Aufträge und Phasen zu melden. Kunden können zwar Einträge zur Zeitachse hinzufügen, die jedoch in der Regel nicht auf der Benutzeroberfläche angezeigt werden.

Wenn wir während eines Schritts ##vso[task.logdetail] zum ersten Mal sehen, erstellen wir einen Datensatz des Typs „Detaillierte Zeitachse“ für diesen Schritt. Wir können anhand von id und parentid geschachtelte Zeitachsendatensätze erstellen und aktualisieren.

Aufgabenersteller müssen sich merken, welche GUID sie für jeden Zeitachsendatensatz verwendet haben. Das Protokollierungssystem verfolgt die GUID für jeden Zeitachsendatensatz, sodass jede neue GUID einen neuen Zeitachsendatensatz ergibt.

Eigenschaften

• id = GUID für Zeitachsendatensatz (erforderlich)
• parentid= GUID des übergeordneten Zeitachsendatensatzes
• type = Datensatztyp (für erstes Mal erforderlich, kann nicht überschrieben werden)
• name = Datensatzname (für erstes Mal erforderlich, kann nicht überschrieben werden)
• order = Reihenfolge des Zeitachsendatensatzes (für erstes Mal erforderlich, kann nicht überschrieben werden)
• starttime = Datetime
• finishtime = Datetime
• progress = Prozentsatz der Fertigstellung
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Beispiele

Erstellen eines neuen Stamm-Zeitachsendatensatzes:

##vso[task.logdetail id=new guid;name=project1;type=build;order=1]create new timeline record

Erstellen eines neuen geschachtelten Zeitachsendatensatzes:

##vso[task.logdetail id=new guid;parentid=exist timeline record guid;name=project1;type=build;order=1]create new nested timeline record

Aktualisieren eines vorhandenen Zeitachsendatensatzes:

##vso[task.logdetail id=existing timeline record guid;progress=15;state=InProgress;]update timeline record

SetVariable: Initialisieren oder Ändern des Werts einer Variablen

##vso[task.setvariable]value

Verbrauch

Legt eine Variable im Variablendienst von taskcontext fest. Die erste Aufgabe kann eine Variable festlegen, die folgenden Aufgaben können die Variable verwenden. Die Variable wird den folgenden Aufgaben als Umgebungsvariable verfügbar gemacht.

Wenn isSecret auf true festgelegt ist, wird der Wert der Variable als Geheimnis gespeichert und im Protokoll maskiert. Geheimnisvariablen werden nicht als Umgebungsvariablen an Aufgaben übermittelt und müssen stattdessen als Eingaben übermittelt werden.

Wenn isOutput auf true die Syntax für den Verweis auf die Setvariable festgelegt ist, variiert je nachdem, ob Sie auf diese Variable in demselben Auftrag, einem zukünftigen Auftrag oder einer zukünftigen Phase zugreifen. Wenn außerdem isOutput auf false festgelegt wird, ist die Syntax für die Verwendung dieser Variable innerhalb desselben Auftrags unterschiedlich. Informationen zum Bestimmen der geeigneten Syntax für jeden Anwendungsfall finden Sie unter Ebenen von Ausgabevariablen.

Weitere Informationen zu Ausgabevariablen finden Sie unter Festlegen von Variablen in Skripts und Definieren von Variablen.

Eigenschaften

Beispiele

- bash: |
    echo "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    echo "##vso[task.setvariable variable=secretSauce;isSecret=true]crushed tomatoes with garlic"
    echo "##vso[task.setvariable variable=outputSauce;isOutput=true]canned goods"
  name: SetVars

- bash: |
    echo "Non-secrets automatically mapped in, sauce is $SAUCE"
    echo "Secrets are not automatically mapped in, secretSauce is $SECRETSAUCE"
    echo "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)"

- pwsh: |
    Write-Host "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    Write-Host "##vso[task.setvariable variable=secretSauce;isSecret=true]crushed tomatoes with garlic"
    Write-Host "##vso[task.setvariable variable=outputSauce;isOutput=true]canned goods"
  name: SetVars

- pwsh: |
    Write-Host "Non-secrets automatically mapped in, sauce is $env:SAUCE"
    Write-Host "Secrets are not automatically mapped in, secretSauce is $env:SECRETSAUCE"
    Write-Host "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)"
    Write-Host "Future jobs can also see $env:SETVARS_OUTPUTSAUCE"
    write-Host "Future jobs can also see $(SetVars.outputSauce)"

Konsolenausgabe:

Non-secrets automatically mapped in, sauce is crushed tomatoes
Secrets are not automatically mapped in, secretSauce is 
You can use macro replacement to get secrets, and they'll be masked in the log: ***
Future jobs can also see canned goods
Future jobs can also see canned goods

SetSecret: Registrieren eines Werts als Geheimnis

##vso[task.setsecret]value

Verbrauch

Der Wert wird für die Dauer des Auftrags als Geheimnis registriert. Der Wert wird ab diesem Zeitpunkt aus den Protokollen maskiert. Dieser Befehl ist nützlich, wenn ein geheimer Schlüssel transformiert (z. B. base64-codiert) oder abgeleitet wird.

Hinweis: Vorherige Vorkommen des geheimen Werts werden nicht maskiert.

Beispiele

- bash: |
    NEWSECRET=$(echo $OLDSECRET|base64)
    echo "##vso[task.setsecret]$NEWSECRET"
  name: SetSecret
  env:
    OLDSECRET: "SeCrEtVaLuE"

- bash: |
    echo "Transformed and derived secrets will be masked: $(echo $OLDSECRET|base64)"
  env:
    OLDSECRET: "SeCrEtVaLuE"

- pwsh: |
    $NewSecret = [convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET))
    Write-Host "##vso[task.setsecret]$NewSecret"
  name: SetSecret
  env:
    OLDSECRET: "SeCrEtVaLuE"

- pwsh: |
    Write-Host "Transformed and derived secrets will be masked: $([convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET)))"
  env:
    OLDSECRET: "SeCrEtVaLuE"

Konsolenausgabe:

Transformed and derived secrets will be masked: ***

SetEndpoint: Ändern eines Dienstverbindungsfelds

##vso[task.setendpoint]value

Verbrauch

Legen Sie ein Dienstverbindungsfeld mit dem angegebenen Wert fest. Der aktualisierte Wert wird im Endpunkt für die nachfolgenden Aufgaben beibehalten, die innerhalb desselben Auftrags ausgeführt werden.

Eigenschaften

• id = Dienstverbindungs-ID (erforderlich)
• field = Feldtyp, entweder authParameter, dataParameter oder url (erforderlich)
• key = Schlüssel (erforderlich, es sei denn field = url)

Beispiele

##vso[task.setendpoint id=000-0000-0000;field=authParameter;key=AccessToken]testvalue
##vso[task.setendpoint id=000-0000-0000;field=dataParameter;key=userVariable]testvalue
##vso[task.setendpoint id=000-0000-0000;field=url]https://example.com/service

AddAttachment: Anfügen einer Datei an den Build

##vso[task.addattachment]value

Verbrauch

Laden Sie die Anlage hoch, und fügen Sie sie an den aktuellen Zeitachsendatensatz an. Diese Dateien können nicht mit Protokollen heruntergeladen werden. Auf sie kann nur über Erweiterungen verwiesen werden, die die Typ- oder Namenswerte verwenden.

Eigenschaften

• type = Typ der Anlage (erforderlich)
• name = Name der Anlage (erforderlich)

Beispiel

##vso[task.addattachment type=myattachmenttype;name=myattachmentname;]c:\myattachment.txt

UploadSummary: Hinzufügen von Markdowninhalten zur Buildzusammenfassung

##vso[task.uploadsummary]local file path

Verbrauch

Laden Sie markdown aus einer MD-Datei im Repository in den aktuellen Zeitachsendatensatz hoch, und fügen Sie sie an. Diese Zusammenfassung wird der Build-/Releasezusammenfassung hinzugefügt und kann nicht mit Protokollen heruntergeladen werden. Die Zusammenfassung muss im UTF-8- oder ASCII-Format vorliegen. Die Zusammenfassung wird auf der Registerkarte Erweiterungen Ihrer Pipelineausführung angezeigt. Das Markdown-Rendering auf der Registerkarte "Erweiterungen" unterscheidet sich von Azure DevOps Wiki-Rendering. Weitere Informationen zur Markdown-Syntax finden Sie im Markdown-Leitfaden.

Beispiele

##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/testsummary.md

Dies ist eine Kurzform des Befehls

##vso[task.addattachment type=Distributedtask.Core.Summary;name=testsummaryname;]c:\testsummary.md

UploadFile: Hochladen einer Datei, die mit Aufgabenprotokollen heruntergeladen werden kann

##vso[task.uploadfile]local file path

Verbrauch

Laden Sie die für den Benutzer interessante Datei als zusätzliche Protokollinformationen zum aktuellen Zeitachsendatensatz auf. Die Datei muss zusammen mit Aufgabenprotokollen zum Herunterladen zur Verfügung stehen.

Beispiel

##vso[task.uploadfile]c:\additionalfile.log

PrependPath: Der Umgebungsvariablen PATH einen Pfad voranstellen

##vso[task.prependpath]local file path

Verbrauch

Aktualisieren Sie die Umgebungsvariable PATH, indem Sie ihre einen Pfad voranstellen. Die aktualisierte Umgebungsvariable wird in nachfolgenden Aufgaben widerspiegelt.

Beispiel

##vso[task.prependpath]c:\my\directory\path

Artefaktbefehle

Die Artefaktveröffentlichung wird in klassischen Release-Pipelines nicht unterstützt.

Associate: Initialisieren eines Artefakts

##vso[artifact.associate]artifact location

Verbrauch

Erstellen Sie einen Link zu einem vorhandenen Artefakt. Der Speicherort des Artefakts muss ein Dateicontainerpfad, VC-Pfad oder UNC-Freigabepfad sein.

Eigenschaften

• artifactname = Name des Artefakts (erforderlich)
• type = Typ des Artefakts (erforderlich) container | filepath | versioncontrol | gitref | tfvclabel

Beispiele

• Container

  ##vso[artifact.associate type=container;artifactname=MyServerDrop]#/1/build
  

• filepath

  ##vso[artifact.associate type=filepath;artifactname=MyFileShareDrop]\\MyShare\MyDropLocation
  

• versioncontrol

  ##vso[artifact.associate type=versioncontrol;artifactname=MyTfvcPath]$/MyTeamProj/MyFolder
  

• gitref

  ##vso[artifact.associate type=gitref;artifactname=MyTag]refs/tags/MyGitTag
  

• tfvclabel

  ##vso[artifact.associate type=tfvclabel;artifactname=MyTag]MyTfvcLabel
  

• Benutzerdefiniertes Artefakt

  ##vso[artifact.associate artifactname=myDrop;artifacttype=myartifacttype]https://downloads.visualstudio.com/foo/bar/package.zip
  

Upload: Hochladen eines Artefakts

##vso[artifact.upload]local file path

Verbrauch

Laden Sie eine lokale Datei in einen Dateicontainerordner hoch, und veröffentlichen Sie optional ein Artefakt als artifactname.

Eigenschaften

• containerfolder = Ordner, in den die Datei hochgeladen wird; Ordner wird bei Bedarf erstellt.
• artifactname = Name des Artefakts. (Erforderlich)

Beispiel

##vso[artifact.upload containerfolder=testresult;artifactname=uploadedresult]c:\testresult.trx

Erstellen von Befehlen

UploadLog: Hochladen eines Protokolls

##vso[build.uploadlog]local file path

Verbrauch

Laden Sie das für den Benutzer interessante Protokoll in den Containerordner logs\tool des Builds hoch.

Beispiel

##vso[build.uploadlog]c:\msbuild.log

UpdateBuildNumber: Überschreiben der automatisch generierten Buildnummer

##vso[build.updatebuildnumber]build number

Verbrauch

Sie können automatisch eine Buildnummer anhand von Token generieren, die Sie in den Pipelineoptionen angeben. Wenn Sie jedoch die Buildnummer mit Ihrer eigenen Logik festlegen möchten, können Sie diesen Protokollierungsbefehl verwenden.

Beispiel

##vso[build.updatebuildnumber]my-new-build-number

AddBuildTag: Hinzufügen eines Tags zum Build

##vso[build.addbuildtag]build tag

Verbrauch

Fügen Sie dem aktuellen Build ein Tag hinzu. Sie können das Tag mit einer vordefinierten oder benutzerdefinierten Variablen erweitern. Hier wird beispielsweise ein neues Tag in einer Bash-Aufgabe mit dem Wert last_scanned-$(currentDate)hinzugefügt. Sie können mit AddBuildTag keinen Doppelpunkt verwenden.

Beispiel

- task: Bash@3
  inputs:
    targetType: 'inline'
    script: |
      last_scanned="last_scanned-$(currentDate)"
      echo "##vso[build.addbuildtag]$last_scanned"
  displayName: 'Apply last scanned tag'

Releasebefehle

UpdateReleaseName: Umbenennen des aktuellen Releases

##vso[release.updatereleasename]release name

Verbrauch

Aktualisieren Sie den Releasenamen des ausgeführte Releases.

Beispiel

##vso[release.updatereleasename]my-new-release-name

Problembehandlung bei Protokollierungsbefehlen

Protokollierungsbefehle werden nicht verarbeitet

Protokollierungsbefehle müssen während der Schrittweisen Ausführung durch den Agent in stdout geschrieben werden. Wenn Ihre Befehle in den rohen Protokollen angezeigt werden, aber nicht verarbeitet werden:

• Externe Tools, die in Dateien geschrieben werden: Wenn ein Tool Zeichenfolgen in eine Protokolldatei und nicht in stdout schreibt ##vso[...] , analysiert der Agent sie nicht. Leiten Sie die Ausgabe des Tools in Ihr Skript an stdout um.
• Gepufferte Ausgabe: Einige Programme puffern Stdout, wenn sie nicht mit einem Terminal verbunden ist. Verwenden Sie sprachspezifische Optionen, um die Ausgabe zu leeren (z python -u . B. oder festlegen PYTHONUNBUFFERED=1).
• set -x Interferenzen auf Linux/macOS: Die set -x Option kann Protokollierungsbefehle beschädigen. Eine Problemumgehung finden Sie unter "Problembehandlung ".
• Codierung: Protokollierungsbefehle müssen UTF-8-Codierung verwenden. Andere Codierungen können dazu führen, dass der Agent den Befehl überspringt.
• Newlines innerhalb von Befehlen: Jeder Protokollierungsbefehl muss sich in einer einzigen Zeile enthalten. Wenn innerhalb der ##vso[...] Zeichenfolge ein Neuzeilenzeichen angezeigt wird, erkennt der Agent den Befehl nicht.

Sonderzeichen in Werten

Einige Zeichen müssen bei Verwendung in Protokollierungsbefehlswerten escapet werden. Diese Escapesequenzen werden im Agent-Quellcode definiert:

Um Prozentzeichen in Werten zu escapen, verwenden Sie %AZP25 anstelle von %. Dieses Verhalten wird durch die DECODE_PERCENTS Variable gesteuert. Weitere Informationen finden Sie unter "Prozentcodierung".