Logging commands
TFS 2017 | TFS 2015 | TFS 2013
Logging commands are how tasks and scripts communicate with the agent. They cover actions like creating new variables, marking a step as failed, and uploading artifacts. Logging commands are useful when you're troubleshooting a pipeline.
Type | Commands |
---|---|
Task commands | LogIssue, SetProgress, LogDetail, SetVariable, SetEndpoint, AddAttachment, UploadSummary, UploadFile, PrependPath |
Artifact commands | Associate, Upload |
Build commands | UploadLog, UpdateBuildNumber, AddBuildTag |
Release commands | UpdateReleaseName |
The general format for a logging command is:
##vso[area.action property1=value;property2=value;...]message
There are also a few formatting commands with a slightly different syntax:
##[command]message
To invoke a logging command, echo the command via standard output.
#!/bin/bash
echo "##vso[task.setvariable variable=testvar;]testvalue"
File paths should be given as absolute paths: rooted to a drive on Windows, or beginning with /
on Linux and macOS.
Nota
Please note that there is no support of 'set -x' command being executed before logging command on Linux and macOS.
Nota
Use UTF-8 formatting for logging commands.
These commands are messages to the log formatter in Azure Pipelines. They mark specific log lines as errors, warnings, collapsible sections, and so on.
The formatting commands are:
##[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]
You can use the formatting commands in a bash or PowerShell task.
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]"
Those commands will render in the logs like this:
That block of commands can also be collapsed, and looks like this:
##vso[task.logissue]error/warning message
Log an error or warning message in the timeline record of the current task.
type
=error
orwarning
(Required)sourcepath
= source file locationlinenumber
= line numbercolumnnumber
= column numbercode
= error or warning code
#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1
Suggerimento
exit 1
is optional, but is often a command you'll issue soon after an error is logged. If you select Control Options: Continue on error, then the exit 1
will result in a partially successful build instead of a failed build.
#!/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."
##vso[task.setprogress]current operation
Set progress and current operation for the current task.
value
= percentage of completion
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."
To see how it looks, save and queue the build, and then watch the build run. Observe that a progress indicator changes when the task runs this script.
##vso[task.complete]current operation
Finish the timeline record for the current task, set task result and current operation. When result not provided, set result to succeeded.
result
=Succeeded
The task succeeded.SucceededWithIssues
The task ran into problems. The build will be completed as partially succeeded at best.Failed
The build will be completed as failed. (If the Control Options: Continue on error option is selected, the build will be completed as partially succeeded at best.)
##vso[task.complete result=Succeeded;]DONE
##vso[task.logdetail]current operation
Creates and updates timeline records. This is primarily used internally by Azure Pipelines to report about steps, jobs, and stages. While customers can add entries to the timeline, they won't typically be shown in the UI.
The first time we see ##vso[task.detail]
during a step, we create a "detail timeline" record for the step. We can create and update nested timeline records base on id
and parentid
.
Task authors must remember which GUID they used for each timeline record. The logging system will keep track of the GUID for each timeline record, so any new GUID will result a new timeline record.
id
= Timeline record GUID (Required)parentid
= Parent timeline record GUIDtype
= Record type (Required for first time, can't overwrite)name
= Record name (Required for first time, can't overwrite)order
= order of timeline record (Required for first time, can't overwrite)starttime
=Datetime
finishtime
=Datetime
progress
= percentage of completionstate
=Unknown
|Initialized
|InProgress
|Completed
result
=Succeeded
|SucceededWithIssues
|Failed
Create new root timeline record:
##vso[task.logdetail id=new guid;name=project1;type=build;order=1]create new timeline record
Create new nested timeline record:
##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
##vso[task.setvariable]value
Sets a variable in the variable service of taskcontext. The first task can set a variable, and following tasks are able to use the variable. The variable is exposed to the following tasks as an environment variable.
When issecret
is set to true
, the value of the variable will be saved as secret and masked out from log. Secret variables aren't passed into tasks as environment variables and must instead be passed as inputs.
See set variables in scripts for more details.
variable
= variable name (Required)issecret
= boolean (Optional, defaults to false)isreadonly
= boolean (Optional, defaults to false)
Set the variables:
- bash: |
echo "##vso[task.setvariable variable=sauce;]crushed tomatoes"
echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
name: SetVars
Read the 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)"
Console output:
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: ***
##vso[task.setendpoint]value
Set a service connection field with given value. Value updated will be retained in the endpoint for the subsequent tasks that execute within the same job.
id
= service connection ID (Required)field
= field type, one ofauthParameter
,dataParameter
, orurl
(Required)key
= key (Required, unlessfield
=url
)
##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
##vso[task.addattachment]value
Upload and attach attachment to current timeline record. These files aren't available for download with logs. These can only be referred to by extensions using the type or name values.
type
= attachment type (Required)name
= attachment name (Required)
##vso[task.addattachment type=myattachmenttype;name=myattachmentname;]c:\myattachment.txt
##vso[task.uploadsummary]local file path
Upload and attach summary Markdown to current timeline record. This summary shall be added to the build/release summary and not available for download with logs. The summary should be in UTF-8 or ASCII format. The summary will appear on an Extensions tab.
##vso[task.uploadsummary]c:\testsummary.md
It's a short hand form for the command
##vso[task.addattachment type=Distributedtask.Core.Summary;name=testsummaryname;]c:\testsummary.md
##vso[task.uploadfile]local file path
Upload user interested file as additional log information to the current timeline record. The file shall be available for download along with task logs.
##vso[task.uploadfile]c:\additionalfile.log
##vso[task.prependpath]local file path
Update the PATH environment variable by prepending to the PATH. The updated environment variable will be reflected in subsequent tasks.
##vso[task.prependpath]c:\my\directory\path
##vso[artifact.associate]artifact location
Create a link to an existing Artifact. Artifact location must be a file container path, VC path or UNC share path.
artifactname
= artifact name (Required)type
= artifact type (Required)container
|filepath
|versioncontrol
|gitref
|tfvclabel
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
Custom Artifact
##vso[artifact.associate artifactname=myDrop;artifacttype=myartifacttype]https://downloads.visualstudio.com/foo/bar/package.zip
##vso[artifact.upload]local file path
Upload a local file into a file container folder, and optionally publish an artifact as artifactname
.
containerfolder
= folder that the file will upload to, folder will be created if needed.artifactname
= artifact name. (Required)
##vso[artifact.upload containerfolder=testresult;artifactname=uploadedresult]c:\testresult.trx
Nota
The difference between Artifact.associate and Artifact.upload is that the first can be used to create a link to an existing artifact, while the latter can be used to upload/publish a new Artifact.
##vso[build.uploadlog]local file path
Upload user interested log to build's container "logs\tool
" folder.
##vso[build.uploadlog]c:\msbuild.log
##vso[build.updatebuildnumber]build number
You can automatically generate a build number from tokens you specify in the pipeline options. However, if you want to use your own logic to set the build number, then you can use this logging command.
##vso[build.updatebuildnumber]my-new-build-number
##vso[build.addbuildtag]build tag
Add a tag for current build.
##vso[build.addbuildtag]Tag_UnitTestPassed
##vso[release.updatereleasename]release name
Update the release name for the running release.
Nota
Supported in Azure DevOps and Azure DevOps Server beginning in version 2020.
##vso[release.updatereleasename]my-new-release-name