Loggningskommandon

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

Loggningskommandon är hur uppgifter och skript kommunicerar med agenten. De omfattar åtgärder som att skapa nya variabler, markera ett steg som misslyckat och ladda upp artefakter. Loggningskommandon är användbara när du felsöker en pipeline.

Viktigt!

Vi gör ett försök att maskera hemligheter från att visas i Azure Pipelines-utdata, men du måste fortfarande vidta försiktighetsåtgärder. Upprepa aldrig hemligheter som utdata. Vissa operativsystem loggar kommandoradsargument. Skicka aldrig hemligheter på kommandoraden. I stället föreslår vi att du mappar dina hemligheter till miljövariabler.

Vi maskerar aldrig understrängar av hemligheter. Om till exempel "abc123" anges som en hemlighet maskeras inte "abc" från loggarna. Detta är för att undvika maskering av hemligheter på en för detaljerad nivå, vilket gör loggarna olästa. Därför bör hemligheter inte innehålla strukturerade data. Om till exempel "{ "foo": "bar" }" har angetts som en hemlighet maskeras inte "bar" från loggarna.

Typ	Kommandon
Uppgiftskommandon	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Artefaktkommandon	Associera, ladda upp
Skapa kommandon	AddBuildTag, UpdateBuildNumber, UploadLog
Versionskommandon	UpdateReleaseName

Loggningskommandoformat

Det allmänna formatet för ett loggningskommando är:

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

Det finns också några formateringskommandon med en något annorlunda syntax:

##[command]message

Om du vill anropa ett loggningskommando upprepar du kommandot via standardutdata.

Bash

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

PowerShell

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

Filsökvägar bör anges som absoluta sökvägar: rotade på en enhet i Windows eller från och med / i Linux och macOS.

Kommentar

Observera att du inte kan använda set -x kommandot före ett loggningskommando när du använder Linux eller macOS. Se felsökning för att lära dig hur du inaktiverar set -x tillfälligt för Bash.

Formateringskommandon

Kommentar

Använd UTF-8-kodning för loggningskommandon.

Dessa kommandon är meddelanden till loggformaterare i Azure Pipelines. De markerar specifika loggrader som fel, varningar, hopfällbara avsnitt och så vidare.

Formateringskommandona är:

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

Du kan använda formateringskommandona i en bash- eller PowerShell-uppgift.

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

Dessa kommandon återges i loggarna så här:

Det här kommandoblocket kan också komprimeras och ser ut så här:

Uppgiftskommandon

LogIssue: Logga ett fel eller en varning

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

Användning

Logga ett fel eller varningsmeddelande i tidslinjeposten för den aktuella aktiviteten.

Egenskaper

• type = error eller warning (krävs)
• sourcepath = källfilplats
• linenumber = radnummer
• columnnumber = kolumnnummer
• code = fel- eller varningskod

Exempel: Logga ett fel

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

Dricks

exit 1 är valfritt, men är ofta ett kommando som du kommer att utfärda strax efter att ett fel har loggats. Om du väljer Kontrollalternativ: Fortsätt vid felexit 1 resulterar det i en delvis lyckad version i stället för en misslyckad version. Du kan också använda task.logissue type=error.

Exempel: Logga en varning om en specifik plats i en fil

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: Visa att procentandelen har slutförts

##vso[task.setprogress]current operation

Användning

Ange förlopp och aktuell åtgärd för den aktuella aktiviteten.

Egenskaper

• value = procent av slutförande

Exempel

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

Om du vill se hur det ser ut sparar du och köar bygget och tittar sedan på byggkörningen. Observera att en förloppsindikator ändras när aktiviteten kör det här skriptet.

Slutför: Tidslinje för slutförd

##vso[task.complete]current operation

Användning

Slutför tidslinjeposten för den aktuella aktiviteten, ange aktivitetsresultat och aktuell åtgärd. När resultatet inte har angetts anger du resultatet till lyckades.

Egenskaper

• result =
  • Succeeded Uppgiften lyckades.
  • SucceededWithIssues Uppgiften stötte på problem. Bygget slutförs i bästa möjliga mån som delvis slutfört.
  • Failed Bygget slutförs som misslyckat. (Om Kontrollalternativ: Alternativet Fortsätt vid fel har valts. Bygget slutförs i bästa fall som delvis slutfört.)

Exempel

Logga en uppgift som slutförd.

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

Ange en aktivitet som misslyckad. Du kan också använda exit 1.

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

LogDetail: Skapa eller uppdatera en tidslinjepost för en uppgift

##vso[task.logdetail]current operation

Användning

Skapar och uppdaterar tidslinjeposter. Detta används främst internt av Azure Pipelines för att rapportera om steg, jobb och steg. Kunder kan lägga till poster i tidslinjen, men de visas vanligtvis inte i användargränssnittet.

Första gången vi ser ##vso[task.detail] under ett steg skapar vi en "detaljerad tidslinje"-post för steget. Vi kan skapa och uppdatera kapslade tidslinjeposter som bygger på id och parentid.

Uppgiftsförfattare måste komma ihåg vilket GUID de använde för varje tidslinjepost. Loggningssystemet håller reda på GUID för varje tidslinjepost, så alla nya GUID resulterar i en ny tidslinjepost.

Egenskaper

• id = Tidslinjepostens GUID (krävs)
• parentid = GUID för överordnad tidslinjepost
• type = Posttyp (krävs för första gången, kan inte skriva över)
• name = Postnamn (krävs för första gången, kan inte skriva över)
• order = Ordningen på tidslinjeposten (krävs för första gången, kan inte skriva över)
• starttime = Datetime
• finishtime = Datetime
• progress = procent av slutförande
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Exempel

Skapa en ny post för rottidslinjen:

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

Skapa ny kapslad tidslinjepost:

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

Uppdatering finns tidslinjepost:

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

SetVariable: Initiera eller ändra värdet för en variabel

##vso[task.setvariable]value

Användning

Anger en variabel i variabeltjänsten för taskcontext. Den första aktiviteten kan ange en variabel och följande aktiviteter kan använda variabeln. Variabeln exponeras för följande uppgifter som en miljövariabel.

När issecret är inställt på truesparas värdet för variabeln som hemlighet och maskeras från loggen. Hemliga variabler skickas inte till aktiviteter som miljövariabler och måste i stället skickas som indata.

När isoutput är inställt true på syntaxen för att referera till den angivna variabeln varierar beroende på om du kommer åt variabeln i samma jobb, ett framtida jobb eller en framtida fas. Om är inställt false på syntaxen för att använda variabeln inom samma jobb är dessutom isoutput distinkt. Se nivåer av utdatavariabler för att fastställa lämplig syntax för varje användningsfall.

Mer information finns i ange variabler i skript och definiera variabler .

Egenskaper

• variable = variabelnamn (obligatoriskt)
• issecret = booleskt värde (valfritt, standardvärdet falskt)
• isoutput = booleskt värde (valfritt, standardvärdet falskt)
• isreadonly = booleskt värde (valfritt, standardvärdet falskt)

Exempel

Bash

Ange variabler:

- 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

Läs variablerna:

- 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

Ange variabler:

- 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

Läs variablerna:

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

Konsolutdata:

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: Registrera ett värde som en hemlighet

##vso[task.setsecret]value

Användning

Värdet registreras som en hemlighet under hela jobbet. Värdet maskeras från loggarna från och med nu. Det här kommandot är användbart när en hemlighet transformeras (t.ex. base64-kodad) eller härledd.

Obs! Tidigare förekomster av det hemliga värdet maskeras inte.

Exempel

Bash

Ange variabler:

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

Läs variablerna:

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

PowerShell

Ange variabler:

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

Läs variablerna:

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

Konsolutdata:

Transformed and derived secrets will be masked: ***

SetEndpoint: Ändra ett tjänstanslutningsfält

##vso[task.setendpoint]value

Användning

Ange ett tjänstanslutningsfält med angivet värde. Värdet som uppdateras behålls i slutpunkten för efterföljande aktiviteter som körs inom samma jobb.

Egenskaper

• id = tjänstanslutnings-ID (krävs)
• field = fälttyp, en av authParameter, dataParametereller url (krävs)
• key = nyckel (krävs, om inte field = url)

Exempel

##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: Bifoga en fil till bygget

##vso[task.addattachment]value

Användning

Ladda upp och bifoga den bifogade filen till den aktuella tidslinjeposten. Dessa filer är inte tillgängliga för nedladdning med loggar. Dessa kan endast refereras till av tillägg med hjälp av typ- eller namnvärdena.

Egenskaper

• type = typ av bifogad fil (krävs)
• name = namn på bifogad fil (krävs)

Exempel

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

UploadSummary: Lägg till lite Markdown-innehåll i byggsammanfattningen

##vso[task.uploadsummary]local file path

Användning

Ladda upp och bifoga sammanfattning markdown från en .md-fil på lagringsplatsen till den aktuella tidslinjeposten. Den här sammanfattningen ska läggas till i bygg-/versionssammanfattningen och inte vara tillgänglig för nedladdning med loggar. Sammanfattningen ska vara i UTF-8- eller ASCII-format. Sammanfattningen visas på fliken Tillägg i pipelinekörningen. Markdown-rendering på fliken Tillägg skiljer sig från Azure DevOps wiki-rendering.

Exempel

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

Det är ett kort formulär för kommandot

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

UploadFile: Ladda upp en fil som kan laddas ned med aktivitetsloggar

##vso[task.uploadfile]local file path

Användning

Ladda upp användarintresserad fil som ytterligare logginformation till den aktuella tidslinjeposten. Filen ska vara tillgänglig för nedladdning tillsammans med uppgiftsloggar.

Exempel

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

PrependPath: Förbered en sökväg till PATH-miljövariabeln

##vso[task.prependpath]local file path

Användning

Uppdatera PATH-miljövariabeln genom att vänta till PATH. Den uppdaterade miljövariabeln återspeglas i efterföljande uppgifter.

Exempel

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

Artefaktkommandon

Associera: Initiera en artefakt

##vso[artifact.associate]artifact location

Användning

Skapa en länk till en befintlig artefakt. Artefaktplatsen måste vara en filcontainersökväg, VC-sökväg eller UNC-resurssökväg.

Egenskaper

• artifactname = artefaktnamn (krävs)
• type = artefakttyp (krävs) container | filepath | versioncontrol | gitref | tfvclabel

Exempel

• Behållare

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

• Anpassad artefakt

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

Ladda upp: Ladda upp en artefakt

##vso[artifact.upload]local file path

Användning

Ladda upp en lokal fil till en filcontainermapp och publicera en artefakt som artifactname.

Egenskaper

• containerfolder = mapp som filen laddas upp till, skapas mappen om det behövs.
• artifactname = artefaktnamn. (Krävs)

Exempel

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

Kommentar

Skillnaden mellan Artifact.associate och Artifact.upload är att den första kan användas för att skapa en länk till en befintlig artefakt, medan den senare kan användas för att ladda upp/publicera en ny artefakt.

Skapa kommandon

UploadLog: Ladda upp en logg

##vso[build.uploadlog]local file path

Användning

Ladda upp användarintresserad logg för att skapa containermappen .logs\tool

Exempel

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

UpdateBuildNumber: Åsidosätt det automatiskt genererade versionsnumret

##vso[build.updatebuildnumber]build number

Användning

Du kan automatiskt generera ett versionsnummer från token som du anger i pipelinealternativen. Men om du vill använda din egen logik för att ange versionsnumret kan du använda det här loggningskommandot.

Exempel

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

AddBuildTag: Lägg till en tagg i versionen

##vso[build.addbuildtag]build tag

Användning

Lägg till en tagg för aktuell version. Du kan expandera taggen med en fördefinierad eller användardefinierad variabel. Här läggs till exempel en ny tagg i en Bash-uppgift med värdet last_scanned-$(currentDate). Du kan inte använda ett kolon med AddBuildTag.

Exempel

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

Versionskommandon

UpdateReleaseName: Byt namn på aktuell version

##vso[release.updatereleasename]release name

Användning

Uppdatera versionsnamnet för den version som körs.

Kommentar

Stöds i Azure DevOps och Azure DevOps Server från och med version 2020.

Exempel

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