Příkazy pro protokolování

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

Příkazy protokolování jsou způsob komunikace úloh a skriptů s agentem. Pokrývají akce, jako je vytváření nových proměnných, označení kroku jako selhání a nahrávání artefaktů. Příkazy protokolování jsou užitečné při řešení potíží s kanálem.

Důležité

Snažíme se maskovat tajné kódy, které se zobrazují ve výstupu Služby Azure Pipelines, ale přesto je potřeba provést preventivní opatření. Nikdy neodhalujte tajné kódy jako výstup. Některé argumenty příkazového řádku protokolu operačních systémů. Nikdy nepředávejte tajné kódy na příkazovém řádku. Místo toho doporučujeme namapovat tajné kódy na proměnné prostředí.

Nikdy nezamaskujeme podřetěžky tajných kódů. Pokud je například "abc123" nastaven jako tajný kód, "abc" není maskován z protokolů. Tím se vyhnete maskování tajných kódů na příliš podrobné úrovni, aby protokoly byly nečitelné. Z tohoto důvodu by tajné kódy neměly obsahovat strukturovaná data. Pokud je například "{ "foo": "bar" }" nastaven jako tajný kód, "bar" není maskován z protokolů.

Typ	Příkazy
Příkazy úkolů	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Příkazy artefaktů	Přidružení, nahrání
Příkazy sestavení	AddBuildTag, UpdateBuildNumber, UploadLog
Příkazy vydané verze	UpdateReleaseName

Formát příkazu Protokolování

Obecný formát příkazu protokolování je:

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

Existuje také několik příkazů formátování s mírně odlišnou syntaxí:

##[command]message

Pokud chcete vyvolat příkaz protokolování, ozvěte příkaz prostřednictvím standardního výstupu.

Bash

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

PowerShell

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

Cesty k souborům by měly být uvedeny jako absolutní cesty: rootované na jednotku ve Windows nebo začínající / na Linuxu a macOS.

Poznámka:

Upozorňujeme, že příkaz před příkazem protokolování nemůžete použít set -x , když používáte Linux nebo macOS. Informace o tom, jak dočasně zakázat set -x Bash, najdete v tématu řešení potíží.

Příkazy formátování

Poznámka:

Pro příkazy protokolování použijte kódování UTF-8.

Tyto příkazy jsou zprávy pro formátovací modul protokolu v Azure Pipelines. Označují konkrétní řádky protokolu jako chyby, upozornění, sbalitelné oddíly atd.

Příkazy formátování jsou:

##[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]

Příkazy formátování můžete použít v úloze Bash nebo PowerShellu.

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

Tyto příkazy se v protokolech vykreslí takto:

Tento blok příkazů může být také sbalený a vypadá takto:

Příkazy úkolů

LogIssue: Protokolování chyby nebo upozornění

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

Využití

Zaznamenejte do záznamu časové osy aktuálního úkolu chybovou zprávu nebo upozornění.

Vlastnosti

• type = error nebo warning (povinné)
• sourcepath = umístění zdrojového souboru
• linenumber = číslo řádku
• columnnumber = číslo sloupce
• code = kód chyby nebo upozornění

Příklad: Protokolování chyby

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

Tip

exit 1 je nepovinný, ale často se jedná o příkaz, který vydáte brzy po zaprotokolované chybě. Pokud vyberete možnosti ovládacího prvku: Pokračovat při chybě, výsledkem exit 1 bude částečně úspěšné sestavení místo neúspěšného sestavení. Jako alternativu můžete použít task.logissue type=errortaké .

Příklad: Protokolování upozornění na konkrétní místo v souboru

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: Zobrazit procento dokončeno

##vso[task.setprogress]current operation

Využití

Nastavte průběh a aktuální operaci pro aktuální úkol.

Vlastnosti

• value = procento dokončení

Příklad

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

Pokud chcete zjistit, jak vypadá, uložte a zařaďte sestavení do fronty a sledujte spuštění sestavení. Všimněte si, že indikátor průběhu se při spuštění tohoto skriptu změní.

Dokončeno: Časová osa dokončení

##vso[task.complete]current operation

Využití

Dokončete záznam časové osy pro aktuální úkol, nastavte výsledek úkolu a aktuální operaci. Pokud výsledek není zadaný, nastavte výsledek na úspěch.

Vlastnosti

• result =
  • Succeeded Úkol byl úspěšný.
  • SucceededWithIssues Úkol narazil na problémy. Sestavení bude dokončeno v nejlepším případě jako částečně úspěšné.
  • Failed Sestavení bude dokončeno, protože selhalo. (Pokud Možnosti ovládacího prvku: Je vybrána možnost Pokračovat při chybě , sestavení bude dokončeno jako částečně úspěšné v nejlepším případě.)

Příklad

Zapíše úkol jako úspěšný.

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

Nastavte úkol jako neúspěšný. Jako alternativu můžete použít exit 1také .

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

LogDetail: Vytvoření nebo aktualizace záznamu časové osy pro úkol

##vso[task.logdetail]current operation

Využití

Vytvoří a aktualizuje záznamy časové osy. Azure Pipelines ho primárně používá interně k hlášení kroků, úloh a fází. I když zákazníci můžou přidávat položky na časovou osu, obvykle se v uživatelském rozhraní nezobrazí.

Při prvním zobrazení ##vso[task.detail] v kroku vytvoříme pro tento krok záznam "časová osa podrobností". Záznamy časové osy můžeme vytvářet a aktualizovat na základě id a parentid.

Autoři úkolů si musí zapamatovat identifikátor GUID, který použili pro každý záznam časové osy. Systém protokolování bude sledovat identifikátor GUID pro každý záznam časové osy, takže každý nový identifikátor GUID bude mít za následek nový záznam časové osy.

Vlastnosti

• id = IDENTIFIKÁTOR GUID záznamu časové osy (povinné)
• parentid = GUID záznamu nadřazené časové osy
• type = Typ záznamu (povinné poprvé, nejde přepsat)
• name = Název záznamu (povinné poprvé, nejde přepsat)
• order = pořadí záznamu časové osy (povinné poprvé, nejde přepsat)
• starttime = Datetime
• finishtime = Datetime
• progress = procento dokončení
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Příklady

Vytvoření nového kořenového záznamu časové osy:

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

Vytvoření nového vnořeného záznamu časové osy:

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

Aktualizace existuje záznam časové osy:

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

SetVariable: Inicializace nebo úprava hodnoty proměnné

##vso[task.setvariable]value

Využití

Nastaví proměnnou ve službě proměnné objektu taskcontext. První úkol může nastavit proměnnou a následující úkoly mohou proměnnou používat. Proměnná se zobrazí pro následující úlohy jako proměnná prostředí.

Pokud issecret je nastavena hodnota trueproměnné, uloží se jako tajný kód a maskuje se z protokolu. Tajné proměnné nejsou předány do úloh jako proměnné prostředí a musí být předány jako vstupy.

Pokud isoutput je nastavena na syntaxi odkazující na true proměnnou sady, liší se podle toho, jestli k této proměnné přistupujete ve stejné úloze, budoucí úloze nebo budoucí fázi. Pokud je navíc nastavená syntaxe false pro použití této proměnné ve stejné úloze, isoutput je odlišná. Prohlédněte si úrovně výstupních proměnných a určete odpovídající syntaxi pro každý případ použití.

Další podrobnosti najdete v tématu Nastavení proměnných ve skriptech a definování proměnných .

Vlastnosti

• variable = název proměnné (povinné)
• issecret = logická hodnota (volitelné, výchozí hodnota je false)
• isoutput = logická hodnota (volitelné, výchozí hodnota je false)
• isreadonly = logická hodnota (volitelné, výchozí hodnota je false)

Příklady

Bash

Nastavte proměnné:

- 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

Přečtěte si proměnné:

- 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

Nastavte proměnné:

- 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

Přečtěte si proměnné:

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

Výstup konzoly:

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: Registrace hodnoty jako tajného kódu

##vso[task.setsecret]value

Využití

Hodnota je registrována jako tajný kód pro dobu trvání úlohy. Hodnota bude maskována z protokolů od tohoto bodu dopředu. Tento příkaz je užitečný při transformaci tajného kódu (např. kódování base64) nebo odvození.

Poznámka: Předchozí výskyty tajné hodnoty nebudou maskovány.

Příklady

Bash

Nastavte proměnné:

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

Přečtěte si proměnné:

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

PowerShell

Nastavte proměnné:

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

Přečtěte si proměnné:

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

Výstup konzoly:

Transformed and derived secrets will be masked: ***

SetEndpoint: Úprava pole připojení služby

##vso[task.setendpoint]value

Využití

Nastavte pole připojení služby s danou hodnotou. Aktualizace hodnoty se zachovají v koncovém bodu pro následné úlohy, které se provádějí ve stejné úloze.

Vlastnosti

• id = ID připojení služby (povinné)
• field = typ pole, jeden z authParameter, dataParameternebo url (povinný)
• key = klíč (povinné, pokud field = url)

Příklady

##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: Připojení souboru k sestavení

##vso[task.addattachment]value

Využití

Nahrajte a připojte přílohu k aktuálnímu záznamu časové osy. Tyto soubory nejsou k dispozici ke stažení s protokoly. Na tyto hodnoty lze odkazovat pouze rozšířeními používajícími hodnoty typu nebo názvu.

Vlastnosti

• type = typ přílohy (povinné)
• name = název přílohy (povinné)

Příklad

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

UploadSummary: Přidání obsahu Markdownu do souhrnu buildu

##vso[task.uploadsummary]local file path

Využití

Nahrajte a připojte souhrnný Markdown ze souboru .md v úložišti k aktuálnímu záznamu časové osy. Tento souhrn se přidá do souhrnu sestavení/verze a není k dispozici ke stažení s protokoly. Souhrn by měl být ve formátu UTF-8 nebo ASCII. Souhrn se zobrazí na kartě Rozšíření spuštění kanálu. Vykreslování Markdownu na kartě Rozšíření se liší od vykreslování wikiwebu Azure DevOps.

Příklady

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

Jedná se o krátký formulář pro příkaz.

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

UploadFile: Nahrání souboru, který lze stáhnout pomocí protokolů úloh

##vso[task.uploadfile]local file path

Využití

Nahrajte soubor se zájmem o uživatele jako další informace protokolu do aktuálního záznamu časové osy. Soubor bude k dispozici ke stažení spolu s protokoly úkolů.

Příklad

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

PředpendPath: Předpendá cesta k proměnné prostředí PATH

##vso[task.prependpath]local file path

Využití

Aktualizujte proměnnou prostředí PATH tak, že předzálohujte cestu. Aktualizovaná proměnná prostředí se projeví v dalších úlohách.

Příklad

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

Příkazy artefaktů

Přidružení: Inicializace artefaktu

##vso[artifact.associate]artifact location

Využití

Vytvořte odkaz na existující artefakt. Umístění artefaktu musí být cesta ke kontejneru souborů, cesta VC nebo cesta ke sdílené složce UNC.

Vlastnosti

• artifactname = název artefaktu (povinné)
• type = typ artefaktu (povinné) container | filepath | versioncontrol | gitref | tfvclabel

Příklady

• Kontejner

  ##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
  

• Vlastní artefakt

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

Nahrání: Nahrání artefaktu

##vso[artifact.upload]local file path

Využití

Nahrajte místní soubor do složky kontejneru souborů a volitelně publikujte artefakt jako artifactname.

Vlastnosti

• containerfolder = složka, do které se soubor nahraje, bude v případě potřeby vytvořena složka.
• artifactname = název artefaktu. (Povinné)

Příklad

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

Poznámka:

Rozdíl mezi Artifact.associate a Artifact.upload spočívá v tom, že první je možné použít k vytvoření odkazu na existující artefakt, zatímco druhý se dá použít k nahrání nebo publikování nového artefaktu.

Příkazy sestavení

UploadLog: Nahrání protokolu

##vso[build.uploadlog]local file path

Využití

Nahrajte protokol, který zajímá uživatele, do složky "" kontejnerulogs\tool sestavení.

Příklad

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

UpdateBuildNumber: Přepsání automaticky generovaného čísla sestavení

##vso[build.updatebuildnumber]build number

Využití

V možnostech kanálu můžete automaticky vygenerovat číslo buildu z tokenů, které zadáte. Pokud ale chcete k nastavení čísla sestavení použít vlastní logiku, můžete použít tento příkaz protokolování.

Příklad

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

AddBuildTag: Přidání značky do sestavení

##vso[build.addbuildtag]build tag

Využití

Přidejte značku pro aktuální sestavení. Značku můžete rozšířit pomocí předdefinované nebo uživatelem definované proměnné. Zde se například přidá nová značka do úkolu Bash s hodnotou last_scanned-$(currentDate). Nelze použít dvojtečku se značkou AddBuildTag.

Příklad

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

Příkazy vydané verze

UpdateReleaseName: Přejmenování aktuální verze

##vso[release.updatereleasename]release name

Využití

Aktualizujte název vydané verze pro spuštěnou verzi.

Poznámka:

Podporováno v Azure DevOps a Azure DevOps Serveru počínaje verzí 2020.

Příklad

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