Commandes de journalisation

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

Les commandes de journalisation sont la façon dont les tâches et les scripts communiquent avec l’agent. Elles couvrent des actions comme la création de nouvelles variables, le marquage d’une étape comme ayant échoué et le chargement d’artefacts. Les commandes de journalisation sont utiles lorsque vous résolvez les problèmes d’un pipeline.

Important

Nous nous efforçons de masquer l’affichage des secrets dans la sortie d’Azure Pipelines, mais vous devez tout de même prendre des précautions. N’émettez jamais de secrets comme sortie. Certains systèmes d’exploitation journalisent les arguments de ligne de commande. Ne passez jamais de secrets en ligne de commande. Au lieu de cela, nous vous suggérons de mapper vos secrets dans des variables d’environnement.

Nous ne masquons jamais les sous-chaînes de secrets. Si, par exemple, « abc123 » est défini en tant que secret, « abc » n’est pas masqué dans les journaux. Cela permet d’éviter de masquer les secrets à un niveau trop granulaire, ce qui rendrait les journaux illisibles. Pour cette raison, les secrets ne doivent pas contenir de données structurées. Si, par exemple, « { "foo" : "bar" } » est défini comme secret, « bar » n’est pas masqué dans les journaux.

Type	Commandes
Commandes de tâche	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Commandes d’artefact	Associate, Upload
Commandes de génération	AddBuildTag, UpdateBuildNumber, UploadLog
Commandes de mise en production	UpdateReleaseName

Format de commande de journalisation

Le format général d’une commande de journalisation est le suivant :

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

Il existe également quelques commandes de mise en forme avec une syntaxe légèrement différente :

##[command]message

Pour appeler une commande de journalisation, effectuez un echo de la commande via une sortie standard.

Bash

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

PowerShell

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

Les chemins d’accès aux fichiers doivent être donnés en tant que chemins d’accès absolus : rootés sur un lecteur sous Windows ou commençant par / sur Linux et macOS.

Notes

Notez que vous ne pouvez pas utiliser la commande set -x avant une commande de journalisation lorsque vous utilisez Linux ou macOS. Pour savoir comment désactiver temporairement set -x pour Bash, consultez Résolution des problèmes.

Commandes de mise en forme

Notes

Utilisez l’encodage UTF-8 pour la journalisation des commandes.

Ces commandes sont des messages envoyés au formateur de journaux dans Azure Pipelines. Elles marquent des lignes de journal spécifiques en tant qu’erreurs, avertissements, sections réductibles, etc.

Les commandes de mise en forme sont les suivantes :

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

Vous pouvez utiliser les commandes de mise en forme dans une tâche Bash ou 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]"

Ces commandes sont affichées dans les journaux comme suit :

Ce bloc de commandes peut également être réduit, et ressemble à ceci :

Commandes de tâche

LogIssue : Journaliser une erreur ou un avertissement

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

Utilisation

Consignez un message d’erreur ou d’avertissement dans l’enregistrement de chronologie de la tâche en cours.

Propriétés

• type = error ou warning (Obligatoire)
• sourcepath = emplacement du fichier source :
• linenumber = numéro de ligne
• columnnumber = numéro de colonne
• code = code d’erreur ou d’avertissement

Exemple : Journaliser une erreur

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

Conseil

exit 1 est facultatif, mais il s’agit souvent d’une commande que vous émettrez peu après qu’une erreur a été enregistrée. Si vous sélectionnez Options de contrôle : Continuer en cas d’erreur, exit 1 entraîne une build partiellement réussie au lieu d’une build ayant échoué. En guise d’alternative, vous pouvez également utiliser task.logissue type=error.

Exemple : Journaliser un avertissement concernant un emplacement spécifique dans un fichier

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 : Afficher le pourcentage terminé

##vso[task.setprogress]current operation

Utilisation

Définissez la progression et l’opération actuelle pour la tâche en cours.

Propriétés

• value = pourcentage d’achèvement

Exemple

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

Pour voir à quoi cela ressemble, enregistrez et mettez en file d’attente la build, puis observez l’exécution de la build. Observez qu’un indicateur de progression change lorsque la tâche exécute ce script.

Terminé : Terminer la chronologie

##vso[task.complete]current operation

Utilisation

Terminez l’enregistrement de chronologie pour la tâche active, définissez le résultat de la tâche et l’opération en cours. Lorsque le résultat n’est pas fourni, définissez le résultat sur réussi.

Propriétés

• result =
  • Succeeded La tâche a réussi.
  • SucceededWithIssues La tâche a rencontré des problèmes. La build se termine dans un état partiellement réussi, au mieux.
  • Failed La build se termine en tant qu’échec. (Si l’option Options de contrôle : Continuer en cas d’erreur est sélectionnée, la build se termine dans un état partiellement réussi, au mieux.)

Exemple

Consignez une tâche comme ayant réussi.

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

Définissez une tâche comme ayant échoué. En guise d’alternative, vous pouvez également utiliser 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 : Créer ou mettre à jour un enregistrement de chronologie pour une tâche

##vso[task.logdetail]current operation

Utilisation

Crée et met à jour les enregistrements de chronologie. Il est principalement utilisé en interne par Azure Pipelines pour créer des rapports sur les phases, les travaux et les phases. Bien que les clients puissent ajouter des entrées à la chronologie, elles ne seront généralement pas affichées dans l’interface utilisateur.

La première fois que nous voyons ##vso[task.detail] lors d’une étape, nous créons un enregistrement de « chronologie détaillée » pour l’étape. Nous pouvons créer et mettre à jour la base des enregistrements de chronologie imbriqués sur id et parentid.

Les auteurs de tâches doivent se souvenir du GUID utilisé pour chaque enregistrement de chronologie. Le système de journalisation effectue le suivi du GUID pour chaque enregistrement de chronologie. Par conséquent, tout nouveau GUID entraîne un nouvel enregistrement de chronologie.

Propriétés

• id = GUID d’enregistrement de chronologie (obligatoire)
• parentid = GUID d’enregistrement de chronologie parent
• type = Type d’enregistrement (obligatoire pour la première fois, ne peut pas être remplacé)
• name = Nom de l’enregistrement (obligatoire pour la première fois, ne peut pas être remplacé)
• order = ordre d’enregistrement de chronologie (obligatoire pour la première fois, ne peut pas être remplacé)
• starttime = Datetime
• finishtime = Datetime
• progress = pourcentage d’achèvement
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Exemples

Créez un enregistrement de chronologie racine :

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

Créez un enregistrement de chronologie imbriqué :

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

Mettre à jour un enregistrement de chronologie existant :

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

SetVariable : Initialiser ou modifier la valeur d’une variable

##vso[task.setvariable]value

Utilisation

Définit une variable dans le service de variables de taskcontext. La première tâche peut définir une variable, et les tâches suivantes peuvent l’utiliser. La variable est exposée aux tâches suivantes en tant que variable d’environnement.

Lorsque issecret est défini sur true, la valeur de la variable est enregistrée sous forme de secret et masquée dans le journal. Les variables secrètes ne sont pas transmises aux tâches en tant que variables d’environnement et doivent plutôt être transmises en tant qu’entrées.

Quand isoutput est défini sur true, la syntaxe pour référencer la variable définie varie selon que vous accédez à cette variable dans le même travail, un travail futur ou une phase future. En outre, si isoutput est défini sur false, la syntaxe d’utilisation de cette variable dans le même travail est distincte. Consultez les niveaux de variables de sortie pour déterminer la syntaxe appropriée pour chaque cas d’usage.

Pour plus d’informations, consultez Définir des variables dans des scripts et Définir des variables.

Propriétés

• variable = nom de la variable (Obligatoire)
• issecret = booléen (facultatif, la valeur par défaut est false)
• isoutput = booléen (facultatif, la valeur par défaut est false)
• isreadonly = booléen (Facultatif, la valeur par défaut est false)

Exemples

Bash

Définissez les variables :

- 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

Lisez les variables :

- 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

Définissez les variables :

- 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

Lisez les variables :

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

Sortie de la 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 : enregistrer une valeur comme secret

##vso[task.setsecret]value

Utilisation

La valeur est enregistrée comme secrète pendant toute la durée du travail. La valeur sera masquée des journaux à partir de ce moment. Cette commande est utile lorsqu'un secret est transformé (par exemple codé en base64) ou dérivé.

Remarque : les occurrences précédentes de la valeur secrète ne seront pas masquées.

Exemples

Bash

Définissez les variables :

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

Lisez les variables :

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

PowerShell

Définissez les variables :

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

Lisez les variables :

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

Sortie de la console :

Transformed and derived secrets will be masked: ***

SetEndpoint : Modifier un champ de connexion de service

##vso[task.setendpoint]value

Utilisation

Définissez un champ de connexion de service avec une valeur donnée. La valeur mise à jour est conservée dans le point de terminaison pour les tâches suivantes qui s’exécutent dans le même travail.

Propriétés

• id = ID de connexion de service (obligatoire)
• field = type de champ, authParameter, dataParameter ou url (obligatoire)
• key = clé (obligatoire, sauf si field = url)

Exemples

##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 : Joindre un fichier à la build

##vso[task.addattachment]value

Utilisation

Chargez et joignez la pièce jointe à l’enregistrement de chronologie actuel. Ces fichiers ne sont pas disponibles en téléchargement avec les journaux. Ils ne peuvent être référencés que par des extensions à l’aide des valeurs de type ou de nom.

Propriétés

• type = type de pièce jointe (obligatoire)
• name = nom de la pièce jointe (obligatoire)

Exemple

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

UploadSummary : Ajouter du contenu Markdown au résumé de build

##vso[task.uploadsummary]local file path

Utilisation

Chargez et joignez le résumé Markdown à partir d’un fichier .md dans le référentiel vers l’enregistrement de chronologie actuel. Ce résumé doit être ajouté au résumé de build/mise en production et n’est pas disponible en téléchargement avec les journaux. Le résumé doit être au format UTF-8 ou ASCII. Le résumé s’affiche sous l’onglet Extensions de votre exécution de pipeline. Le rendu Markdown sous l’onglet Extensions est différent du rendu Wiki Azure DevOps.

Exemples

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

Il s’agit d’une forme abrégée pour la commande

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

UploadFile : Charger un fichier qui peut être téléchargé avec les journaux des tâches

##vso[task.uploadfile]local file path

Utilisation

Chargez le fichier qui intéresse l’utilisateur en tant qu’informations de journal supplémentaires dans l’enregistrement de chronologie actuel. Le fichier doit être disponible au téléchargement avec les journaux des tâches.

Exemple

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

PrependPath : Ajouter un chemin d’accès à la variable d’environnement PATH

##vso[task.prependpath]local file path

Utilisation

Mettez à jour la variable d’environnement PATH en préfixant PATH. La variable d’environnement mise à jour sera reflétée dans les tâches suivantes.

Exemple

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

Commandes d’artefact

Associate : Initialiser un artefact

##vso[artifact.associate]artifact location

Utilisation

Créez un lien vers un artefact existant. L’emplacement de l’artefact doit être un chemin de conteneur de fichiers, un chemin d’accès VC ou un chemin de partage UNC.

Propriétés

• artifactname = nom de l’artefact (obligatoire)
• type = type d’artefact (obligatoire) container | filepath | versioncontrol | gitref | tfvclabel

Exemples

• 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
  

• Artefact personnalisé

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

Upload : Charger un artefact

##vso[artifact.upload]local file path

Utilisation

Chargez un fichier local dans un dossier de conteneur de fichiers et publiez éventuellement un artefact en tant que artifactname.

Propriétés

• containerfolder = dossier dans lequel le fichier sera chargé ; le dossier sera créé si nécessaire.
• artifactname = nom de l’artefact. (Obligatoire)

Exemple

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

Notes

La différence entre Artifact.associate et Artifact.upload est que le premier peut être utilisé pour créer un lien vers un artefact existant, tandis que le second peut être utilisé pour charger/publier un nouvel artefact.

Commandes de génération

UploadLog : Charger un journal

##vso[build.uploadlog]local file path

Utilisation

Chargez le journal qui intéresse l’utilisateur dans le dossier « logs\tool » du conteneur de build.

Exemple

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

UpdateBuildNumber : Remplacer le numéro de build généré automatiquement

##vso[build.updatebuildnumber]build number

Utilisation

Vous pouvez générer automatiquement un numéro de build à partir des jetons que vous spécifiez dans les options de pipeline. Toutefois, si vous souhaitez utiliser votre propre logique pour définir le numéro de build, vous pouvez utiliser cette commande de journalisation.

Exemple

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

AddBuildTag : Ajouter une étiquette à la build

##vso[build.addbuildtag]build tag

Utilisation

Ajoutez une étiquette pour la build actuelle. Vous pouvez développer l’étiquette avec une variable prédéfinie ou définie par l’utilisateur. Par exemple, ici, une nouvelle étiquette est ajoutée dans une tâche Bash avec la valeur last_scanned-$(currentDate). Vous ne pouvez pas utiliser de signe deux-points avec AddBuildTag.

Exemple

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

Commandes de mise en production

UpdateReleaseName : Renommer la version actuelle

##vso[release.updatereleasename]release name

Utilisation

Mettez à jour le nom de la version en cours d’exécution.

Notes

Pris en charge dans Azure DevOps et Azure DevOps Server à compter de la version 2020.

Exemple

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