Comandi di registrazione

I comandi di registrazione sono il modo in cui le attività e gli script comunicano con l'agente. Illustrano azioni come la creazione di nuove variabili,contrassegnando un passaggio come non riuscito e caricando gli artefatti. I comandi di registrazione sono utili per la risoluzione dei problemi relativi a una pipeline.

Tipo Comandi
Comandi delle attività LogIssue, SetProgress, LogDetail, SetVariable, SetEndpoint, AddAttachment, UploadSummary, UploadFile, PrependPath
Comandi dell'artefatto Associare, Upload
Comandi di compilazione UploadLog, UpdateBuildNumber, AddBuildTag
Comandi di rilascio UpdateReleaseName

Formato dei comandi di registrazione

Il formato generale per un comando di registrazione è:

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

Esistono anche alcuni comandi di formattazione con una sintassi leggermente diversa:

##[command]message

Per richiamare un comando di registrazione, eseguire l'echo del comando tramite output standard.

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

I percorsi dei file devono essere specificati come percorsi assoluti: radice di un'unità Windows o a partire / da in Linux e macOS.

Nota

Si noti che non è disponibile il supporto per l'esecuzione del comando 'set -x' prima del comando di registrazione in Linux e macOS.

Comandi di formattazione

Nota

Usare la formattazione UTF-8 per i comandi di registrazione.

Questi comandi sono messaggi inviati al formattatore di log in Azure Pipelines. Contrassegnano righe di log specifiche come errori, avvisi, sezioni comprimibili e così via.

I comandi di formattazione sono:

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

Il rendering di questi comandi nei log sarà simile al seguente:

Screenshot dei log con opzioni di formattazione personalizzate

Questo blocco di comandi può anche essere compresso ed è simile al seguente:

Screenshot della sezione compressa dei log

Comandi delle attività

LogIssue: registra un errore o un avviso

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

Utilizzo

Registrare un messaggio di errore o di avviso nel record della sequenza temporale dell'attività corrente.

Proprietà

  • type = error o warning (obbligatorio)
  • sourcepath = percorso del file di origine
  • linenumber = numero di riga
  • columnnumber = numero di colonna
  • code = codice di errore o avviso

Esempio: Registrare un errore

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

Suggerimento

exit 1 è facoltativo, ma è spesso un comando che verrà eseguito subito dopo la registrazione di un errore. Se si seleziona Opzioni di controllo: Continua in caso di errore, la compilazione verrà completata parzialmente anziché una compilazione non exit 1 riuscita.

Esempio: registrare un avviso relativo a una posizione specifica in un file

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

SetProgress: mostra percentuale completata

##vso[task.setprogress]current operation

Utilizzo

Impostare lo stato di avanzamento e l'operazione corrente per l'attività corrente.

Proprietà

  • value = percentuale di completamento

Esempio

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

Per verificare l'aspetto, salvare e accodare la compilazione e quindi osservare l'esecuzione della compilazione. Si noti che un indicatore di stato cambia quando l'attività esegue questo script.

Completa: Sequenza temporale fine

##vso[task.complete]current operation

Utilizzo

Completare il record della sequenza temporale per l'attività corrente, impostare il risultato dell'attività e l'operazione corrente. Se result non viene specificato, impostare result su succeeded.

Proprietà

  • result =
    • Succeeded L'attività è riuscita.
    • SucceededWithIssues Si sono verificati problemi nell'attività. La compilazione verrà completata nel migliore dei modi.
    • Failed La compilazione verrà completata come non riuscita. Se l'opzione Opzioni di controllo: Continua in caso di errore è selezionata, la compilazione verrà completata nel migliore dei modi.

Esempio

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

LogDetail: crea o aggiorna un record della sequenza temporale per un'attività

##vso[task.logdetail]current operation

Utilizzo

Crea e aggiorna i record della sequenza temporale. Viene usato principalmente internamente dal Azure Pipelines per creare report su passaggi, processi e fasi. Anche se i clienti possono aggiungere voci alla sequenza temporale, in genere non vengono visualizzate nell'interfaccia utente.

La prima volta che viene ##vso[task.detail] visualizzato durante un passaggio, viene creato un record "sequenza temporale dettagliata" per il passaggio. È possibile creare e aggiornare i record annidati della sequenza temporale in base id a e parentid .

Gli autori di attività devono ricordare il GUID usato per ogni record della sequenza temporale. Il sistema di registrazione tiene traccia del GUID per ogni record della sequenza temporale, quindi qualsiasi nuovo GUID avrà come risultato un nuovo record della sequenza temporale.

Proprietà

  • id = GUID record sequenza temporale (obbligatorio)
  • parentid = GUID record sequenza temporale padre
  • type = Tipo di record (obbligatorio per la prima volta, non può essere sovrascritto)
  • name = Nome record (obbligatorio per la prima volta, non può essere sovrascritto)
  • order = ordine dei record della sequenza temporale (obbligatorio per la prima volta, non può essere sovrascritto)
  • starttime = Datetime
  • finishtime = Datetime
  • progress = percentuale di completamento
  • state = Unknown | Initialized | InProgress | Completed
  • result = Succeeded | SucceededWithIssues | Failed

Esempio

Creare un nuovo record della sequenza temporale radice:

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

Creare un nuovo record della sequenza temporale annidata:

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

Aggiornare il record della sequenza temporale esistente:

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

SetVariable: inizializzare o modificare il valore di una variabile

##vso[task.setvariable]value

Utilizzo

Imposta una variabile nel servizio variabili di taskcontext. La prima attività può impostare una variabile e le attività seguenti possono usare la variabile. La variabile viene esposta alle attività seguenti come variabile di ambiente.

Quando è impostato su , il valore della variabile verrà salvato issecret true come segreto e mascherato dal log. Le variabili segrete non vengono passate nelle attività come variabili di ambiente e devono invece essere passate come input.

Per altri dettagli, vedere Impostare le variabili negli script.

Proprietà

  • variable = nome variabile (obbligatorio)
  • issecret = boolean (facoltativo, il valore predefinito è false)
  • isoutput = boolean (facoltativo, il valore predefinito è false)
  • isreadonly = boolean (facoltativo, il valore predefinito è false)

Esempio

Impostare le variabili:

- 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

Leggere le variabili:

- 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)"
    echo "Future jobs can also see $SETVARS_OUTPUTSAUCE"
    echo "Future jobs can also see $(SetVars.outputSauce)"

Output della console:

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

SetEndpoint: modificare un campo di connessione del servizio

##vso[task.setendpoint]value

Utilizzo

Impostare un campo di connessione del servizio con il valore specificato. Il valore aggiornato verrà mantenuto nell'endpoint per le attività successive eseguite all'interno dello stesso processo.

Proprietà

  • id = ID connessione al servizio (obbligatorio)
  • field = tipo di campo, uno authParameter tra dataParameter , o url (obbligatorio)
  • key= chiave (obbligatorio, a meno che field = url non )

Esempio

##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: allegare un file alla compilazione

##vso[task.addattachment]value

Utilizzo

Upload e allegare un allegato al record della sequenza temporale corrente. Questi file non sono disponibili per il download con i log. Queste estensioni possono fare riferimento solo a queste estensioni usando i valori di tipo o nome.

Proprietà

  • type = tipo di allegato (obbligatorio)
  • name = nome dell'allegato (obbligatorio)

Esempio

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

UploadSummary: aggiungere contenuto Markdown al riepilogo della compilazione

##vso[task.uploadsummary]local file path

Utilizzo

Upload e allegare il markdown di riepilogo al record della sequenza temporale corrente. Questo riepilogo verrà aggiunto al riepilogo di compilazione/versione e non sarà disponibile per il download con i log. Il riepilogo deve essere in formato UTF-8 o ASCII. Il riepilogo verrà visualizzato in una scheda Estensioni.

Esempio

##vso[task.uploadsummary]c:\testsummary.md

Si tratta di una forma abbreviata per il comando

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

UploadFile: Upload un file che può essere scaricato con i log attività

##vso[task.uploadfile]local file path

Utilizzo

Upload utente interessato come informazioni di log aggiuntive per il record della sequenza temporale corrente. Il file sarà disponibile per il download insieme ai log attività.

Esempio

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

PrependPath: anteporre un percorso alla variabile di ambiente PATH

##vso[task.prependpath]local file path

Utilizzo

Aggiornare la variabile di ambiente PATH anteponendo a PATH. La variabile di ambiente aggiornata verrà riflessa nelle attività successive.

Esempio

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

Comandi dell'artefatto

Associare: inizializzare un artefatto

##vso[artifact.associate]artifact location

Utilizzo

Creare un collegamento a un elemento esistente. Il percorso dell'artefatto deve essere un percorso del contenitore di file, un percorso VC o un percorso di condivisione UNC.

Proprietà

  • artifactname = nome artefatto (obbligatorio)
  • type = tipo di artefatto (obbligatorio) container | filepath | versioncontrol | gitref | tfvclabel

Esempio

  • 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
    
  • Elemento personalizzato

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

Upload: Upload un artefatto

##vso[artifact.upload]local file path

Utilizzo

Upload un file locale in una cartella del contenitore di file e, facoltativamente, pubblicare un artefatto come artifactname .

Proprietà

  • containerfolder = cartella in cui verrà caricato il file. Se necessario, verrà creata la cartella .
  • artifactname = nome dell'artefatto. (Obbligatorio)

Esempio

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

Nota

La differenza tra Artifact.associate e Artifact.upload è che il primo può essere usato per creare un collegamento a un artefatto esistente, mentre il secondo può essere usato per caricare/pubblicare un nuovo artefatto.

Comandi di compilazione

UploadLog: Upload un log

##vso[build.uploadlog]local file path

Utilizzo

Upload'utente interessato alla cartella " " del logs\tool contenitore di compilazione.

Esempio

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

UpdateBuildNumber: esegue l'override del numero di build generato automaticamente

##vso[build.updatebuildnumber]build number

Utilizzo

È possibile generare automaticamente un numero di build dai token specificati nelle opzioni della pipeline. Tuttavia, se si vuole usare la propria logica per impostare il numero di build, è possibile usare questo comando di registrazione.

Esempio

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

AddBuildTag: aggiungere un tag alla compilazione

##vso[build.addbuildtag]build tag

Utilizzo

Aggiungere un tag per la compilazione corrente.

Esempio

##vso[build.addbuildtag]Tag_UnitTestPassed

Comandi di rilascio

UpdateReleaseName: rinomina la versione corrente

##vso[release.updatereleasename]release name

Utilizzo

Aggiornare il nome della versione in esecuzione.

Nota

Supportato in Azure DevOps e Azure DevOps Server a partire dalla versione 2020.

Esempio

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