Protokollierungsbefehle

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

Aufgaben und Skripts kommunizieren mithilfe von Protokollierungsbefehlen mit dem Agent. Dazu zählen Aktionen wie das Erstellen neuer Variablen, Markieren eines Schritts als fehlgeschlagen und Hochladen von Artefakten. Protokollierungsbefehle sind nützlich zur Behandlung von Problemen mit einer Pipeline.

Wichtig

Wir versuchen zwar, die in der Azure Pipelines-Ausgabe angezeigten Geheimnisse zu maskieren, Sie müssen aber trotzdem Vorkehrungen treffen. Geben Sie Geheimnisse niemals als Ausgabe zurück. Einige Betriebssysteme protokollieren Befehlszeilenargumente. Geben Sie niemals Geheimnisse über die Befehlszeile weiter. Stattdessen wird empfohlen, Ihre Geheimnisse Umgebungsvariablen zuzuordnen.

Wir maskieren niemals Teilzeichenfolgen von Geheimnissen. Wenn beispielsweise „abc123“ als Geheimnis festgelegt ist, wird „abc“ in den Protokollen nicht maskiert. Dadurch soll vermieden werden, dass Geheimnisse zu detailliert maskiert werden, sodass die Protokolle nicht mehr lesbar sind. Aus diesem Grund sollten Geheimnisse keine strukturierten Daten enthalten. Wenn beispielsweise „{ "foo": "bar" }“ als Geheimnis festgelegt ist, wird „bar“ nicht in den Protokollen maskiert.

Typ	Befehle
Aufgabenbefehle	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Artefaktbefehle	Associate, Upload
Erstellen von Befehlen	AddBuildTag, UpdateBuildNumber, UploadLog
Releasebefehle	UpdateReleaseName

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.

Bash

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

PowerShell

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

Dateipfade muss als absolute Pfade angegeben werden, und zwar mit Angabe des Stamms auf einem Laufwerk unter Windows oder beginnend mit / unter Linux und macOS.

Hinweis

Beachten Sie, dass Sie unter Linux oder macOS den Befehl set -x nicht vor einem Protokollierungsbefehl verwenden können. Informationen zum vorübergehenden Deaktivieren von set -x für Bash finden Sie unter Problembehandlung.

Formatierungsbefehle

Hinweis

Verwenden Sie für Protokollierungsbefehle die UTF-8-Codierung.

Diese Befehle sind 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.

Bash

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]"

PowerShell

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

Bash

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

PowerShell

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

Tipp

exit 1 ist optional, ist aber häufig ein Befehl, den Sie kurz nach Protokollieren eines Fehlers ausführen. Wenn Sie Steuerungsoptionen: Bei Fehler fortsetzen auswählen, führt exit 1 zu einem teilweise erfolgreichen statt zu einem fehlerhaften Build. Alternativ können Sie auch task.logissue type=error verwenden.

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

Bash

#!/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."

PowerShell

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

Bash

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."

PowerShell

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. Dieser Befehl 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.detail] 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 nach, sodass jede neue GUID zu einem neuen Zeitachsendatensatz führt.

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 festgelegt ist, variiert die Syntax für den Verweis auf die festgelegte Variable je nachdem, ob Sie auf diese Variable im selben Auftrag, in einem künftigen Auftrag oder in einer kü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 finden Sie unter Festlegen von Variablen in Skripts und Definieren von Variablen.

Eigenschaften

• variable = Name der Variablen (erforderlich)
• issecret = boolesch (optional, Standardwert FALSE)
• isoutput = boolesch (optional, Standardwert FALSE)
• isreadonly = boolesch (optional, Standardwert FALSE)

Beispiele

Bash

Legen Sie die Variablen fest:

- 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

Lesen der Variablen:

- 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)"

PowerShell

Legen Sie die Variablen fest:

- 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

Lesen der Variablen:

- 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

Verwendung

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 Geheimnis transformiert (z. B. base64-codiert) oder abgeleitet wird.

Hinweis: Frühere Vorkommen des Geheimniswerts werden nicht maskiert.

Beispiele

Bash

Legen Sie die Variablen fest:

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

Lesen der Variablen:

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

PowerShell

Legen Sie die Variablen fest:

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

Lesen der Variablen:

- 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

Verwendung

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 der Pipelineausführung angezeigt. Das Markdown-Rendering auf der Registerkarte „Erweiterungen“ unterscheidet sich vom Azure DevOps-Wiki-Rendering.

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

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

Hinweis

Der Unterschied zwischen Artifact.associate und Artifact.upload besteht darin, dass mit ersterem ein Link zu einem vorhandenen Artefakt erstellt, während mit letzterem ein neues Artefakt hochgeladen/veröffentlicht werden kann.

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.

Hinweis

Unterstützt in Azure DevOps und Azure DevOps Server ab Version 2020.

Beispiel

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