日志记录命令

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

日志记录命令是 任务 和脚本如何与代理通信。 它们涵盖创建新 变量、将步骤标记为失败以及上传 项目等操作。 排查管道问题时，日志记录命令非常有用。

类型	命令
任务命令	LogIssue、 SetProgress、 LogDetail、 SetVariable、 SetEndpoint、 AddAttachment、 UploadSummary、 UploadFile、 PrependPath
项目命令	关联、 上传
生成命令	UploadLog、 UpdateBuildNumber、 AddBuildTag
发布命令	UpdateReleaseName

日志记录命令格式

日志记录命令的常规格式为：

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

还有一些格式命令，其语法略有不同：

##[command]message

若要调用日志记录命令，请通过标准输出回显该命令。

Bash

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

PowerShell

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

应将文件路径指定为绝对路径：根植于 Windows 上的驱动器，或以 / Linux 和 macOS 开头。

备注

请注意，在 Linux 和 macOS 上的日志记录命令之前，不支持执行“set -x”命令。

格式设置命令

注意

对日志记录命令使用 UTF-8 编码。

这些命令是 Azure Pipelines 中日志格式化程序的消息。 它们将特定日志行标记为错误、警告、可折叠部分等。

格式设置命令包括：

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

可以在 bash 或 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]"

这些命令将在如下所示的日志中呈现：

也可以折叠该命令块，如下所示：

任务命令

LogIssue：记录错误或警告

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

使用情况

在当前任务的日程表记录中记录错误或警告消息。

属性

• type = error 或 warning (必需)
• sourcepath = 源文件位置
• linenumber = 行号
• columnnumber = 列号
• code = 错误或警告代码

示例：记录错误

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

提示

exit 1 是可选的，但通常是在记录错误后不久会发出的命令。 如果选择 “控制选项：继续出错”，则 exit 1 会导致部分成功生成，而不是失败的生成。

示例：记录有关文件中特定位置的警告

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：显示已完成的百分比

##vso[task.setprogress]current operation

使用情况

为当前任务设置进度和当前操作。

属性

• value = 完成百分比

示例

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

若要查看生成的外观，请保存并排队生成，然后监视生成运行。 观察任务运行此脚本时进度指示器发生更改。

完成：完成时间线

##vso[task.complete]current operation

使用情况

完成当前任务的时间线记录、设置任务结果和当前操作。 如果未提供结果，请将结果设置为成功。

属性

• result =
  • Succeeded 任务成功。
  • SucceededWithIssues 任务遇到了问题。 生成将作为部分成功完成。
  • Failed 生成将完成，因为失败。 (如果选中 了“控制选项：继续执行错误 ”选项，则生成将完全成功。)

示例

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

LogDetail：为任务创建或更新时间线记录

##vso[task.logdetail]current operation

使用情况

创建和更新时间线记录。 这主要由 Azure Pipelines 在内部使用，用于报告有关步骤、作业和阶段的信息。 虽然客户可以将条目添加到日程表，但它们通常不会显示在 UI 中。

第一次在 ##vso[task.detail] 步骤中看到时，我们将创建步骤的“详细信息时间线”记录。 我们可以基于 id 和 parentid更新嵌套时间线记录。

任务作者必须记住它们用于每个时间线记录的 GUID。 日志记录系统将跟踪每个时间线记录的 GUID，因此任何新的 GUID 都会导致新的时间线记录。

属性

• id = 时间线记录 GUID (必需)
• parentid = 父时间线记录 GUID
• type = 首次需要记录类型 (无法覆盖)
• name = 记录名称 (首次必需，无法覆盖)
• order = 时间线记录的顺序 (首次必需，无法覆盖)
• starttime = Datetime
• finishtime = Datetime
• progress = 完成百分比
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

示例

创建新的根时间线记录：

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

创建新的嵌套时间线记录：

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

更新存在时间线记录：

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

SetVariable：初始化或修改变量的值

##vso[task.setvariable]value

使用情况

在 taskcontext 的变量服务中设置变量。 第一个任务可以设置变量，并且以下任务可以使用该变量。 该变量作为环境变量公开给以下任务。

true设置为 时issecret，变量的值将保存为机密并从日志中屏蔽。 机密变量不会作为环境变量传递到任务中，而是必须作为输入传递。

如果 isoutput 设置为 true 引用集变量的语法，则根据你是否在同一作业、将来的作业或将来阶段访问该变量而有所不同。 此外，如果 isoutput 设置为 false 在同一作业中使用该变量的语法是不同的。 请参阅 输出变量级别 ，以确定每个用例的相应语法。

有关更多详细信息，请参阅 脚本中的设置变量 并 定义变量 。

属性

• variable = 变量名称 (必需)
• issecret = 布尔 (可选，默认值为 false)
• isoutput = 布尔 (可选，默认值为 false)
• isreadonly = 布尔 (可选，默认值为 false)

• variable = 变量名称 (必需)
• issecret = 布尔 (可选，默认值为 false)
• isreadonly = 布尔 (可选，默认值为 false)

示例

Bash

设置变量：

- 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

- bash: |
    echo "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
  name: SetVars

读取变量：

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

- 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

设置变量：

- 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

- pwsh: |
    Write-Host "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    Write-Host "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
  name: SetVars

读取变量：

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

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

控制台输出：

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

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

SetEndpoint：修改服务连接字段

##vso[task.setendpoint]value

使用情况

使用给定值设置服务连接字段。 更新的值将保留在终结点中，以便执行在同一作业中执行的后续任务。

属性

• id = 服务连接 ID (必需)
• field= 字段类型、一种authParameterdataParameter或url (必需)
• key = 键 (必需，除非 field = 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

AddAttachment：将文件附加到生成

##vso[task.addattachment]value

使用情况

上传附件并将其附加到当前时间线记录。 这些文件不能随日志一起下载。 这些只能由使用类型或名称值的扩展引用。

属性

• type = 附件类型 (必需)
• name = 附件名称 (必需)

示例

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

UploadSummary：将一些 Markdown 内容添加到生成摘要

##vso[task.uploadsummary]local file path

使用情况

上传摘要 Markdown 并将其附加到当前时间线记录。 此摘要应添加到生成/发布摘要中，不能随日志一起下载。 摘要应采用 UTF-8 或 ASCII 格式。 摘要将显示在“扩展”选项卡上。

示例

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

它是命令的短手窗体

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

UploadFile：上传可使用任务日志下载的文件

##vso[task.uploadfile]local file path

使用情况

将用户感兴趣的文件作为其他日志信息上传到当前时间线记录。 该文件应随任务日志一起下载。

示例

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

PrependPath：将路径追加到 PATH 环境变量

##vso[task.prependpath]local file path

使用情况

通过追加到 PATH 来更新 PATH 环境变量。 更新的环境变量将反映在后续任务中。

示例

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

项目命令

关联：初始化项目

##vso[artifact.associate]artifact location

使用情况

创建指向现有项目的链接。 项目位置必须是文件容器路径、VC 路径或 UNC 共享路径。

属性

• artifactname = 项目名称 (必需)
• type = 项目类型 (必需) container | filepath | versioncontrol | gitref | tfvclabel

示例

• 容器

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

• 自定义项目

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

上传：上传项目

##vso[artifact.upload]local file path

使用情况

将本地文件上传到文件容器文件夹中，并选择性地将项目发布为 artifactname。

属性

• containerfolder = 文件将上传到的文件夹，如果需要，将创建文件夹。
• artifactname = 项目名称。 （必需）

示例

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

注意

Artifact.associate 和 Artifact.upload 之间的区别在于，第一个可用于创建现有项目的链接，而后者可用于上传/发布新项目。

生成命令

UploadLog：上传日志

##vso[build.uploadlog]local file path

使用情况

上传用户感兴趣的日志以生成容器“logs\tool”文件夹。

示例

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

UpdateBuildNumber：重写自动生成的生成号

##vso[build.updatebuildnumber]build number

使用情况

可以从 管道选项中指定的令牌自动生成生成号。 但是，如果要使用自己的逻辑来设置内部版本号，则可以使用此日志记录命令。

示例

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

AddBuildTag：将标记添加到生成

##vso[build.addbuildtag]build tag

使用情况

为当前生成添加标记。

示例

##vso[build.addbuildtag]Tag_UnitTestPassed

发布命令

UpdateReleaseName：重命名当前版本

##vso[release.updatereleasename]release name

使用情况

更新正在运行的版本的版本名称。

备注

Azure DevOps 和从版本 2020 开始Azure DevOps Server支持。

示例

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