Azure Pipelines Tasks 项目中的日志命令详解

Azure Pipelines Tasks 项目中的日志命令详解

azure-pipelines-tasks Tasks for Azure Pipelines 项目地址: https://gitcode.com/gh_mirrors/az/azure-pipelines-tasks

什么是日志命令

日志命令是 Azure Pipelines 中一种特殊的指令格式，允许任务在执行过程中与流水线系统进行交互。通过标准输出发送这些命令，可以实现变量设置、进度更新、错误报告等多种功能。

日志命令基本格式

所有日志命令都遵循以下通用格式：

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

例如，在 PowerShell 任务中设置变量：

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

任务相关日志命令

1. 记录问题（logissue）

用于记录错误或警告信息到当前任务的时间线记录中。

语法：

##vso[task.logissue type=error/warning;sourcepath=...;linenumber=...;columnnumber=...;code=...;]message

示例：

Write-Host "##vso[task.logissue type=error;sourcepath=app/main.cs;linenumber=10;columnnumber=5;code=1001;]编译错误"

2. 设置进度（setprogress）

更新任务的当前进度百分比。

语法：

##vso[task.setprogress value=百分比;]当前操作

示例：

echo "##vso[task.setprogress value=50;]处理数据中"

3. 完成任务（complete）

标记任务完成并设置结果状态。

语法：

##vso[task.complete result=Succeeded/SucceededWithIssues/Failed;]完成消息

示例：

Write-Host "##vso[task.complete result=Succeeded;]任务成功完成"

4. 详细时间线记录（logdetail）

创建和管理详细的时间线记录，支持嵌套结构。

语法：

##vso[task.logdetail id=GUID;parentid=GUID;type=...;name=...;order=...;]消息

示例：

echo "##vso[task.logdetail id=$(uuidgen);name=构建阶段;type=build;order=1]开始构建"

5. 设置变量（setvariable）

设置变量供后续任务使用。

语法：

##vso[task.setvariable variable=变量名;issecret=true/false;]变量值

示例：

Write-Host "##vso[task.setvariable variable=BuildNumber;]2023.10.01"
Write-Host "##vso[task.setvariable variable=ApiKey;issecret=true;]12345-67890"

6. 上传文件（uploadfile）

上传文件作为附加日志信息。

语法：

##vso[task.uploadfile]本地文件路径

示例：

echo "##vso[task.uploadfile]/tmp/build.log"

构建相关日志命令

1. 更新构建号（updatebuildnumber）

动态修改当前构建的编号。

语法：

##vso[build.updatebuildnumber]新构建号

示例：

Write-Host "##vso[build.updatebuildnumber]1.0.$(Build.BuildId)"

2. 添加构建标签（addbuildtag）

为当前构建添加标签。

语法：

##vso[build.addbuildtag]标签名称

示例：

echo "##vso[build.addbuildtag]UnitTestPassed"

发布相关日志命令

更新发布名称（updatereleasename）

修改当前发布的名称。

语法：

##vso[release.updatereleasename]新发布名称

示例：

Write-Host "##vso[release.updatereleasename]Prod-v1.2.3"

最佳实践

1. 错误处理：使用task.logissue记录详细的错误信息，包括源代码位置和错误代码
2. 进度反馈：长时间运行的任务应定期更新进度
3. 变量管理：敏感变量务必设置issecret=true
4. 文件上传：大文件应考虑使用专用上传命令而非日志输出
5. 时间线记录：复杂任务使用logdetail提供更详细的时间线信息

通过合理使用这些日志命令，可以显著提升流水线的可观察性和可维护性，为团队提供更清晰的执行过程和更丰富的诊断信息。

azure-pipelines-tasks Tasks for Azure Pipelines 项目地址: https://gitcode.com/gh_mirrors/az/azure-pipelines-tasks