Comandi di registrazione

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

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

Importante

Si fa un tentativo di mascherare i segreti dalla visualizzazione nell'output di Azure Pipelines, ma è comunque necessario adottare precauzioni. Non richiamare mai i segreti come output. Alcuni sistemi operativi registrano gli argomenti della riga di comando. Non passare mai i segreti sulla riga di comando. È invece consigliabile eseguire il mapping dei segreti alle variabili di ambiente.

Non mascheramo mai le sottostringhe dei segreti. Se, ad esempio, "abc123" viene impostato come segreto, "abc" non viene mascherato dai log. Lo scopo è evitare di mascherare i segreti a un livello troppo granulare, rendendo illeggibili i log. Per questo motivo, i segreti non dovrebbero contenere dati strutturati. Se, ad esempio, "{ "foo": "bar" }" è impostato come segreto, "bar" non viene mascherato nei log.

Type	Comandi
Comandi attività	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Comandi dell'artefatto	Associa, Carica
Comandi di compilazione	AddBuildTag, UpdateBuildNumber, UploadLog
Comandi di rilascio	UpdateReleaseName

Formato del comando 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'eco del comando tramite l'output standard.

Bash

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

PowerShell

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

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

Nota

Si noti che non è possibile usare il set -x comando prima di un comando di registrazione quando si usa Linux o macOS. Per informazioni su come disabilitare set -x temporaneamente per Bash, vedere Risoluzione dei problemi.

Comandi di formattazione

Nota

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

Questi comandi sono messaggi 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]

È possibile usare i comandi di formattazione in un'attività bash o PowerShell.

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

Questi comandi verranno visualizzati nei log come segue:

Questo blocco di comandi può anche essere compresso e ha un aspetto simile al seguente:

Comandi attività

LogIssue: Registrare 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

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

Suggerimento

exit 1 è facoltativo, ma è spesso un comando che verrà generato subito dopo la registrazione di un errore. Se si seleziona Opzioni di controllo: Continua in caso di errore, verrà exit 1 restituita una compilazione parzialmente riuscita anziché una compilazione non riuscita. In alternativa, è anche possibile usare task.logissue type=error.

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

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

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

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

Completamento: 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 il risultato non viene specificato, impostare il risultato su succeeded.

Proprietà

• result =
  • Succeeded L'attività ha avuto esito positivo.
  • SucceededWithIssues L'attività ha avuto problemi. La compilazione verrà completata come parzialmente completata.
  • Failed La compilazione verrà completata come non riuscita. (Se il Opzioni di controllo: è selezionata l'opzione Continua in caso di errore , la compilazione verrà completata come parzialmente completata.

Esempio

Registrare un'attività come completata.

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

Impostare un'attività come non riuscita. In alternativa, è anche possibile usare 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: creare o aggiornare un record della sequenza temporale per un'attività

##vso[task.logdetail]current operation

Utilizzo

Crea e aggiorna i record della sequenza temporale. Viene usato internamente da Azure Pipelines per segnalare passaggi, processi e fasi. Anche se i clienti possono aggiungere voci alla sequenza temporale, in genere non verranno visualizzate nell'interfaccia utente.

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

Gli autori di attività devono ricordare il GUID usato per ogni record della sequenza temporale. Il sistema di registrazione continuerà a tenere traccia del GUID per ogni record della sequenza temporale, quindi qualsiasi nuovo GUID genererà 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ò sovrascrivere)
• name = Nome record (obbligatorio per la prima volta, non può sovrascrivere)
• order = ordine del record della sequenza temporale (obbligatorio per la prima volta, non può sovrascrivere)
• starttime = Datetime
• finishtime = Datetime
• progress = percentuale di completamento
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Esempi

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 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 variabile 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 issecret è impostato su true, il valore della variabile verrà salvato come segreto e mascherato dal log. Le variabili segrete non vengono passate alle attività come variabili di ambiente e devono invece essere passate come input.

Quando isoutput è impostata true sulla sintassi per fare riferimento alla variabile set varia a seconda che si acceda a tale variabile nello stesso processo, a un processo futuro o a una fase futura. Inoltre, se isoutput è impostato sulla false sintassi per l'uso di tale variabile all'interno dello stesso processo è distinto. Vedere livelli di variabili di output per determinare la sintassi appropriata per ogni caso d'uso.

Per altri dettagli, vedere Impostare le variabili negli script e definire le variabili .

Proprietà

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

Esempi

Bash

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

PowerShell

Impostare le variabili:

- 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

Leggere le variabili:

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

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

SetSecret: Registrare un valore come segreto

##vso[task.setsecret]value

Utilizzo

Il valore viene registrato come segreto per la durata del processo. Il valore verrà mascherato dai log da questo punto in avanti. Questo comando è utile quando un segreto viene trasformato (ad esempio con codifica Base64) o derivato.

Nota: le occorrenze precedenti del valore del segreto non verranno mascherate.

Esempi

Bash

Impostare le variabili:

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

Leggere le variabili:

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

PowerShell

Impostare le variabili:

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

Leggere le variabili:

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

Output della console:

Transformed and derived secrets will be masked: ***

SetEndpoint: Modificare un campo di connessione al servizio

##vso[task.setendpoint]value

Utilizzo

Impostare un campo di connessione al 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 di authParameter, dataParametero url (obbligatorio)
• key = key (obbligatorio, a meno che field = url)

Esempi

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

Caricare e allegare allegati al record della sequenza temporale corrente. Questi file non sono disponibili per il download con i log. Questi valori possono essere indicati solo dalle estensioni usando i valori di tipo o nome.

Proprietà

• type = tipo di allegato (obbligatorio)
• name = nome 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

Caricare e allegare il riepilogo Markdown da un file md nel repository al record sequenza temporale corrente. Questo riepilogo verrà aggiunto al riepilogo della build/release e non sarà disponibile per il download con i log. Il riepilogo deve essere in formato UTF-8 o ASCII. Il riepilogo verrà visualizzato nella scheda Estensioni dell'esecuzione della pipeline. Il rendering markdown nella scheda Estensioni è diverso dal rendering wiki di Azure DevOps. Per altre informazioni sulla sintassi markdown, vedere la Guida di Markdown.

Esempi

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

Si tratta di una forma breve per il comando

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

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

##vso[task.uploadfile]local file path

Utilizzo

Caricare il file interessato all'utente come informazioni di log aggiuntive nel 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

Associa: 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

Esempi

• container

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

• percorso file

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

• Artefatto personalizzato

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

Caricamento: caricare un artefatto

##vso[artifact.upload]local file path

Utilizzo

Caricare 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, la cartella verrà creata se necessario.
• 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 quest'ultimo può essere usato per caricare/pubblicare un nuovo artefatto.

Comandi di compilazione

UploadLog: caricare un log

##vso[build.uploadlog]local file path

Utilizzo

Caricare il log interessato all'utente nella cartella "logs\tool" del contenitore della compilazione.

Esempio

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

UpdateBuildNumber: eseguire 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. È possibile espandere il tag con una variabile predefinita o definita dall'utente. Ad esempio, qui viene aggiunto un nuovo tag in un'attività Bash con il valore last_scanned-$(currentDate). Non è possibile usare due punti con AddBuildTag.

Esempio

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

Comandi di rilascio

UpdateReleaseName: Rinomina versione corrente

##vso[release.updatereleasename]release name

Utilizzo

Aggiornare il nome della versione per la 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