日志记录命令

项目
04/05/2024

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

日志记录命令是任务和脚本与代理通信的方式。它们涵盖新建变量、将步骤标记为失败以及上传项目等操作。对管道进行故障排除时，日志记录命令非常有用。

重要

我们要尽量屏蔽机密，使其不出现在 Azure Pipelines 输出中，但你仍然需要采取预防措施。切勿将机密作为输出进行回显。某些操作系统记录命令行参数。切勿在命令行上传递机密。相反，我们建议将机密映射到环境变量中。

我们从不屏蔽机密的子字符串。例如，如果将“abc123”设置为机密，则不会从日志中屏蔽“abc”。这是为了避免在过于精细的级别屏蔽机密，从而使日志不可读。因此，机密不应包含结构化数据。例如，如果“{ "foo": "bar" }”设置为机密，则不会从日志中屏蔽“bar”。

类型	命令
任务命令	AddAttachment、Complete、LogDetail、LogIssue、PrependPath、SetEndpoint、SetProgress、SetVariable、SetSecret、UploadFile、UploadSummary
项目命令	Associate、Upload
生成命令	AddBuildTag、UpdateBuildNumber、UploadLog
发布命令	UpdateReleaseName

日志记录命令的格式

日志记录命令的一般格式为：

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

还有一些格式设置命令的语法略有不同：

##[command]message

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

Bash
PowerShell

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

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

文件路径应以绝对路径的形式提供：在 Windows 上根化为驱动器，或在 Linux 和 macOS 上以 / 开头。

注意

请注意，在使用 Linux 或 macOS 时，不能先使用 set -x 命令，再使用日志记录命令。请参阅故障排除，了解如何暂时为 Bash 禁用 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
PowerShell

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

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 = 错误或警告代码

#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1

Write-Host "##vso[task.logissue type=error]Something went very wrong."
exit 1

提示

exit 1 是可选的，但此命令通常在记录错误后不久发出。如果选择“控制选项: 出错时继续”，exit 1 将导致生成部分成功，而不是生成失败。作为替代方法，也可以使用 task.logissue type=error。

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

Bash
PowerShell

#!/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."

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
PowerShell

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

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

如果想看看它是什么样子的，请保存生成并排队，然后观察生成运行。观察任务运行此脚本时进度指示器是否更改。

Complete：完成时间线

##vso[task.complete]current operation

使用情况

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

属性

result =
- Succeeded 任务成功。
- SucceededWithIssues 任务遇到问题。生成完成，但是最多只能部分成功。
- Failed 生成完成，但是失败。（如果选择了“控制选项: 出错时继续”选项，则生成最多只能部分成功完成。）

示例

将任务记录为成功。

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

将任务设置为失败。作为替代方法，也可以使用 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：为任务创建或更新时间线记录

##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 的变量服务中设置变量。第一个任务可以设置变量，后续任务可以使用变量。该变量作为环境变量公开给以下任务。

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

当 isoutput 设置为 true 时，引用 set 变量的语法有所不同，具体取决于你是在同一作业、未来作业还是未来阶段中访问该变量。此外，如果 isoutput 设置为 false，同一作业中使用该变量的语法将是不同的。请参阅输出变量的级别，以确定适合每个用例的语法。

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

属性

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

示例

Bash
PowerShell

设置变量：

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

设置变量：

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

控制台输出：

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：将值注册为机密

##vso[task.setsecret]value

使用情况

值在作业期间注册为机密。值将从此时起在日志中被屏蔽。当机密被转换（例如进行了 base64 编码）或派生时，此命令非常有用。

注意：不会屏蔽之前出现的机密值。

示例

Bash
PowerShell

设置变量：

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

读取变量：

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

设置变量：

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

读取变量：

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

控制台输出：

Transformed and derived secrets will be masked: ***

SetEndpoint：修改服务连接字段

##vso[task.setendpoint]value

使用情况

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

属性

id = 服务连接 ID（必需）
field= 字段类型，authParameter、dataParameter 或 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

使用情况

将存储库的 .md 文件中的摘要 Markdown 上传并附加到当前时间线记录。此摘要应添加到生成/发布摘要中，不能随日志一起下载。摘要应采用 UTF-8 或 ASCII 格式。摘要会显示在管道运行的“扩展”选项卡上。 “扩展”选项卡上的 Markdown 呈现与 Azure DevOps wiki 呈现不同。

示例

##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/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

项目命令

Associate：初始化项目

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

Upload：上传项目

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

使用情况

为当前生成添加标记。可以使用预定义变量或用户定义的变量展开标记。例如，此处会将新标记添加到值为 last_scanned-$(currentDate) 的 Bash 任务中。不能将冒号与 AddBuildTag 一起使用。

示例

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

发布命令

UpdateReleaseName：重命名当前版本

##vso[release.updatereleasename]release name

使用情况

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

注意

在 Azure DevOps 和 Azure DevOps Server（版本 2020 以上）中受支持。

示例

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

通过

日志记录命令

日志记录命令的格式

格式设置命令

任务命令

LogIssue：记录错误或警告

使用情况

属性

示例：记录错误

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

SetProgress：显示已完成百分比

使用情况

属性

示例

Complete：完成时间线

使用情况

属性

示例

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

使用情况

属性

示例

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

使用情况

属性

示例

SetSecret：将值注册为机密

使用情况

示例

SetEndpoint：修改服务连接字段

使用情况

属性

示例

AddAttachment：将文件附加到生成

使用情况

属性

示例

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

使用情况

示例

UploadFile：上传可随任务日志一起下载的文件

使用情况

示例

PrependPath：在 PATH 环境变量的前面追加路径

使用情况

示例

项目命令

Associate：初始化项目

使用情况

属性

示例

Upload：上传项目

使用情况

属性

示例

生成命令

UploadLog：上传日志

使用情况

示例

UpdateBuildNumber：替代自动生成的生成号

使用情况

示例

AddBuildTag：向生成添加标记

使用情况

示例

发布命令

UpdateReleaseName：重命名当前版本

使用情况

示例

反馈

其他资源