Opdrachten voor logboekregistratie

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

Logboekregistratieopdrachten zijn de wijze waarop taken en scripts communiceren met de agent. Ze hebben betrekking op acties zoals het maken van nieuwe variabelen, het markeren van een stap als mislukt en het uploaden van artefacten. Logboekregistratieopdrachten zijn handig wanneer u problemen met een pijplijn wilt oplossen.

Belangrijk

We doen er alles aan om geheimen te maskeren van de uitvoer van Azure Pipelines, maar u moet nog steeds voorzorgsmaatregelen nemen. Echo geheimen nooit als uitvoer. Sommige besturingssystemen registreren opdrachtregelargumenten. Geef nooit geheimen door op de opdrachtregel. In plaats daarvan raden we u aan uw geheimen toe te wijzen aan omgevingsvariabelen.

We maskeren nooit subtekenreeksen van geheimen. Als 'abc123' bijvoorbeeld is ingesteld als geheim, wordt 'abc' niet gemaskeerd uit de logboeken. Dit is om te voorkomen dat geheimen te gedetailleerd worden gemaskeerd, waardoor de logboeken onleesbaar worden. Daarom mogen geheimen geen gestructureerde gegevens bevatten. Als bijvoorbeeld '{ 'foo': 'bar' }' is ingesteld als geheim, wordt 'balk' niet gemaskeerd uit de logboeken.

Type	Opdracht
Taakopdrachten	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Artefactopdrachten	Koppelen, uploaden
Build-opdrachten	AddBuildTag, UpdateBuildNumber, UploadLog
Releaseopdrachten	UpdateReleaseName

Indeling van opdracht voor logboekregistratie

De algemene indeling voor een logboekregistratieopdracht is:

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

Er zijn ook enkele opmaakopdrachten met een iets andere syntaxis:

##[command]message

Als u een logboekregistratieopdracht wilt aanroepen, echot u de opdracht via de standaarduitvoer.

Bash

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

Powershell

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

Bestandspaden moeten worden opgegeven als absolute paden: geroot naar een station in Windows of beginnend met / linux en macOS.

Notitie

Houd er rekening mee dat u de set -x opdracht niet kunt gebruiken voordat u een logboekregistratieopdracht gebruikt wanneer u Linux of macOS gebruikt. Zie probleemoplossing voor meer informatie over het tijdelijk uitschakelen set -x van Bash.

Opmaakopdrachten

Notitie

UTF-8-codering gebruiken voor logboekregistratieopdrachten.

Deze opdrachten zijn berichten naar de logboekindeling in Azure Pipelines. Ze markeren specifieke logboeklijnen als fouten, waarschuwingen, samenvouwbare secties, enzovoort.

De opmaakopdrachten zijn:

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

U kunt de opmaakopdrachten in een bash- of PowerShell-taak gebruiken.

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

Deze opdrachten worden als volgt weergegeven in de logboeken:

Dit blok opdrachten kan ook worden samengevouwen en ziet er als volgt uit:

Taakopdrachten

LogIssue: Een fout of waarschuwing vastleggen

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

Gebruik

Een foutbericht of waarschuwingsbericht vastleggen in de tijdlijnrecord van de huidige taak.

Eigenschappen

• type = error of warning (vereist)
• sourcepath = locatie van bronbestand
• linenumber = regelnummer
• columnnumber = kolomnummer
• code = fout- of waarschuwingscode

Voorbeeld: Een fout vastleggen

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 is optioneel, maar is vaak een opdracht die u kort nadat een fout is vastgelegd. Als u Opties voor besturingselementen selecteert : Doorgaan op fout, resulteert dit exit 1 in een gedeeltelijk geslaagde build in plaats van een mislukte build. Als alternatief kunt u ook gebruiken task.logissue type=error.

Voorbeeld: Een waarschuwing vastleggen over een specifieke locatie in een bestand

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: Percentage voltooid weergeven

##vso[task.setprogress]current operation

Gebruik

Voortgang en huidige bewerking voor de huidige taak instellen.

Eigenschappen

• value = percentage voltooiing

Opmerking

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

Als u wilt zien hoe het eruitziet, slaat u de build op en zet u de wachtrij in de wachtrij en bekijkt u de builduitvoering. U ziet dat een voortgangsindicator wordt gewijzigd wanneer dit script wordt uitgevoerd door de taak.

Voltooid: Tijdlijn voltooien

##vso[task.complete]current operation

Gebruik

Voltooi de tijdlijnrecord voor de huidige taak, stel het taakresultaat en de huidige bewerking in. Als het resultaat niet is opgegeven, stelt u het resultaat in op geslaagd.

Eigenschappen

• result =
  • Succeeded De taak is voltooid.
  • SucceededWithIssues Er zijn problemen opgetreden bij de taak. De build wordt voltooid als gedeeltelijk geslaagd.
  • Failed De build wordt voltooid als mislukt. (Als de Besturingselementopties: Doorgaan op foutoptie is geselecteerd, de build wordt voltooid als gedeeltelijk geslaagd in het beste.)

Opmerking

Registreer een taak als voltooid.

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

Een taak instellen als mislukt. Als alternatief kunt u ook gebruiken 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: een tijdlijnrecord voor een taak maken of bijwerken

##vso[task.logdetail]current operation

Gebruik

Hiermee worden tijdlijnrecords gemaakt en bijgewerkt. Dit wordt voornamelijk intern gebruikt door Azure Pipelines om te rapporteren over stappen, taken en fasen. Hoewel klanten vermeldingen aan de tijdlijn kunnen toevoegen, worden ze meestal niet weergegeven in de gebruikersinterface.

De eerste keer dat we tijdens een stap zien ##vso[task.detail] , maken we een record voor de detailtijdlijn voor de stap. We kunnen geneste tijdlijnrecords maken en bijwerken op id en parentid.

Taakauteurs moeten onthouden welke GUID ze voor elke tijdlijnrecord hebben gebruikt. Het logboekregistratiesysteem houdt de GUID voor elke tijdlijnrecord bij, zodat elke nieuwe GUID een nieuwe tijdlijnrecord oplevert.

Eigenschappen

• id = GUID van tijdlijnrecord (vereist)
• parentid = GUID van bovenliggende tijdlijnrecord
• type = Recordtype (vereist voor de eerste keer, kan niet worden overschreven)
• name = Recordnaam (vereist voor de eerste keer, kan niet worden overschreven)
• order = volgorde van tijdlijnrecord (vereist voor de eerste keer, kan niet worden overschreven)
• starttime = Datetime
• finishtime = Datetime
• progress = percentage voltooiing
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Voorbeelden

Nieuwe hoofdtijdlijnrecord maken:

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

Nieuwe geneste tijdlijnrecord maken:

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

Update exist timeline record:

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

SetVariable: De waarde van een variabele initialiseren of wijzigen

##vso[task.setvariable]value

Gebruik

Hiermee stelt u een variabele in de variabeleservice van taskcontext in. De eerste taak kan een variabele instellen en de volgende taken kunnen de variabele gebruiken. De variabele wordt als een omgevingsvariabele blootgesteld aan de volgende taken.

Wanneer issecret deze waarde is ingesteld true, wordt de waarde van de variabele opgeslagen als geheim en gemaskeerd uit het logboek. Geheime variabelen worden niet doorgegeven aan taken als omgevingsvariabelen en moeten in plaats daarvan worden doorgegeven als invoer.

Wanneer isoutput deze is ingesteld op true de syntaxis om te verwijzen naar de setvariabele, is afhankelijk van of u die variabele opent in dezelfde taak, een toekomstige taak of een toekomstige fase. isoutput Als deze is ingesteld op false de syntaxis voor het gebruik van die variabele binnen dezelfde taak, is bovendien uniek. Zie de uitvoervariabelen om de juiste syntaxis voor elke use-case te bepalen.

Zie set variables in scripts en definieer variabelen voor meer informatie.

Eigenschappen

• variable = variabelenaam (vereist)
• issecret = Booleaanse waarde (optioneel, standaard ingesteld op onwaar)
• isoutput = Booleaanse waarde (optioneel, standaard ingesteld op onwaar)
• isreadonly = Booleaanse waarde (optioneel, standaard ingesteld op onwaar)

Voorbeelden

Bash

Stel de variabelen in:

- 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

Lees de variabelen:

- 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

Stel de variabelen in:

- 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

Lees de variabelen:

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

Console-uitvoer:

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: Een waarde registreren als geheim

##vso[task.setsecret]value

Gebruik

De waarde wordt geregistreerd als geheim voor de duur van de taak. De waarde wordt vanaf dit moment uit de logboeken gemaskeerd. Deze opdracht is handig wanneer een geheim wordt getransformeerd (bijvoorbeeld met base64 gecodeerd) of afgeleid.

Opmerking: eerdere exemplaren van de geheime waarde worden niet gemaskeerd.

Voorbeelden

Bash

Stel de variabelen in:

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

Lees de variabelen:

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

Powershell

Stel de variabelen in:

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

Lees de variabelen:

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

Console-uitvoer:

Transformed and derived secrets will be masked: ***

SetEndpoint: Een serviceverbindingsveld wijzigen

##vso[task.setendpoint]value

Gebruik

Stel een serviceverbindingsveld in met de opgegeven waarde. De bijgewerkte waarde wordt bewaard in het eindpunt voor de volgende taken die binnen dezelfde taak worden uitgevoerd.

Eigenschappen

• id = serviceverbindings-id (vereist)
• field = veldtype, een van authParameter, dataParameterof url (vereist)
• key = sleutel (vereist, tenzij field = url)

Voorbeelden

##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: Voeg een bestand toe aan de build

##vso[task.addattachment]value

Gebruik

Upload en voeg bijlage toe aan de huidige tijdlijnrecord. Deze bestanden zijn niet beschikbaar voor downloaden met logboeken. Deze kunnen alleen worden verwezen door extensies met behulp van het type of de naamwaarden.

Eigenschappen

• type = bijlagetype (vereist)
• name = bijlagenaam (vereist)

Opmerking

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

UploadSummary: Enkele Markdown-inhoud toevoegen aan de samenvatting van de build

##vso[task.uploadsummary]local file path

Gebruik

Upload en voeg samenvatting markdown toe vanuit een MD-bestand in de opslagplaats naar de huidige tijdlijnrecord. Deze samenvatting wordt toegevoegd aan het build-/releaseoverzicht en kan niet worden gedownload met logboeken. De samenvatting moet de indeling UTF-8 of ASCII hebben. De samenvatting wordt weergegeven op het tabblad Extensies van de pijplijnuitvoering. Markdown-rendering op het tabblad Extensies verschilt van Azure DevOps-wikirendering.

Voorbeelden

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

Het is een korte vorm voor de opdracht

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

UploadFile: Upload een bestand dat kan worden gedownload met taaklogboeken

##vso[task.uploadfile]local file path

Gebruik

Upload het bestand met geïnteresseerde gebruikers als aanvullende logboekinformatie naar de huidige tijdlijnrecord. Het bestand moet samen met taaklogboeken kunnen worden gedownload.

Opmerking

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

PrependPath: Een pad naar de omgevingsvariabele PATH prepend

##vso[task.prependpath]local file path

Gebruik

Werk de omgevingsvariabele PATH bij door vooraf te gaan aan path. De bijgewerkte omgevingsvariabele wordt weergegeven in de volgende taken.

Opmerking

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

Artefactopdrachten

Koppelen: Een artefact initialiseren

##vso[artifact.associate]artifact location

Gebruik

Maak een koppeling naar een bestaand artefact. Artefactlocatie moet een bestandscontainerpad, VC-pad of UNC-sharepad zijn.

Eigenschappen

• artifactname = artefactnaam (vereist)
• type = artefacttype (vereist) container | filepath | versioncontrol | gitref | tfvclabel

Voorbeelden

• 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
  

• Aangepast artefact

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

Uploaden: een artefact uploaden

##vso[artifact.upload]local file path

Gebruik

Upload een lokaal bestand naar een bestandscontainermap en publiceer eventueel een artefact als artifactname.

Eigenschappen

• containerfolder = map waarnaar het bestand wordt geüpload, wordt indien nodig de map gemaakt.
• artifactname = artefactnaam. (Verplicht)

Opmerking

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

Notitie

Het verschil tussen Artifact.associate en Artifact.upload is dat de eerste kan worden gebruikt om een koppeling naar een bestaand artefact te maken, terwijl de laatste kan worden gebruikt om een nieuw artefact te uploaden/publiceren.

Build-opdrachten

UploadLog: Een logboek uploaden

##vso[build.uploadlog]local file path

Gebruik

Upload de gebruiker die geïnteresseerd is in het logboek naar de map container 'logs\tool' van de build.

Opmerking

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

UpdateBuildNumber: Overschrijf het automatisch gegenereerde buildnummer

##vso[build.updatebuildnumber]build number

Gebruik

U kunt automatisch een buildnummer genereren op basis van tokens die u opgeeft in de pijplijnopties. Als u echter uw eigen logica wilt gebruiken om het buildnummer in te stellen, kunt u deze opdracht voor logboekregistratie gebruiken.

Opmerking

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

AddBuildTag: Een tag toevoegen aan de build

##vso[build.addbuildtag]build tag

Gebruik

Voeg een tag toe voor de huidige build. U kunt de tag uitbreiden met een vooraf gedefinieerde of door de gebruiker gedefinieerde variabele. Hier wordt bijvoorbeeld een nieuwe tag toegevoegd aan een Bash-taak met de waarde last_scanned-$(currentDate). U kunt geen dubbele punt gebruiken met AddBuildTag.

Opmerking

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

Releaseopdrachten

UpdateReleaseName: naam van huidige release wijzigen

##vso[release.updatereleasename]release name

Gebruik

Werk de releasenaam voor de actieve release bij.

Notitie

Ondersteund in Azure DevOps en Azure DevOps Server vanaf versie 2020.

Opmerking

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