Команды ведения журнала

службы Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Команды ведения журнала — это способ взаимодействия tasks и скриптов с агентом Azure Pipelines. Когда шаг конвейера записывает специально отформатированную строку в стандартные выходные данные (stdout), агент перехватывает его и выполняет запрошенное действие, например задание переменной, отправку артефакта или маркировку шага как неудачного. Команды ведения журнала полезны для настройки поведения конвейера и устранения неполадок.

Внимание

Мы делаем усилия, чтобы маскировать секреты от отображения в Azure Pipelines выходных данных, но вам по-прежнему необходимо принять меры предосторожности. Никогда не повторять секреты в качестве выходных данных. Некоторые аргументы командной строки журнала операционных систем. Никогда не передавать секреты в командной строке. Вместо этого мы рекомендуем сопоставить секреты с переменными среды.

Мы никогда не маскируем подстроки секретов. Если, например, "abc123" задается как секрет, "abc" не маскируется из журналов. Это позволяет избежать маскирования секретов на слишком детальном уровне, что делает журналы нечитаемыми. По этой причине секреты не должны содержать структурированные данные. Если, например, "{ "foo": "bar" }" имеет значение секрета, "панель" не маскируется из журналов.

Как работают команды ведения журнала

Агент Azure Pipelines обрабатывает команды ведения журнала путем сканирования стандартного вывода (stdout) из каждого шага задачи и скрипта в режиме реального времени при выполнении шага. Когда агент обнаруживает строку, соответствующую ##vso[...]##[...] шаблону или шаблону в stdout, он интерпретирует команду и принимает запрошенное действие (например, задание переменной или отправки артефакта).

Внимание

Команды ведения журнала обрабатываются только при записи в stdout задачами и скриптами, выполняемыми непосредственно на агенте. Они не анализируются из:

• Файлы журнала, отправленные с ##vso[build.uploadlog] помощью или ##vso[task.uploadfile]
• Тестовые файлы или вложения
• Выходные данные из внешних средств или платформ тестирования (например, CloudTest), записываемых в файлы, а не stdout
• Журналы контейнеров или выходные данные процесса боковой машины, которые не записываются агентом

Если вам нужны команды ведения журнала из внешнего средства для обработки, передачи или перенаправления выходных данных этого средства через stdout скрипта. Рассмотрим пример.

./my-external-tool 2>&1 | while IFS= read -r line; do echo "$line"; done

Тип	Команды
Команды задач	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Команды артефактов	Связывание, отправка
Команды сборки	AddBuildTag, UpdateBuildNumber, UploadLog
Команды выпуска	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.

Примечание.

Обратите внимание, что вы не можете использовать команду set -x перед командой ведения журнала при использовании Linux или macOS. См . сведения об устранении неполадок, чтобы узнать, как временно отключить set -x Bash.

Команды форматирования

Примечание.

Используйте кодировку 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 будет частично успешной сборки вместо неудачной сборки. Кроме того, можно использовать task.logissue type=errorв качестве альтернативы.

Пример. Ведение журнала предупреждения о конкретном месте в файле

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

Задайте задачу как сбой. Кроме того, можно использовать 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 для отчета о шагах, заданиях и этапах. Хотя клиенты могут добавлять записи на временную шкалу, они обычно не отображаются в пользовательском интерфейсе.

При первом ##vso[task.logdetail] отображении на шаге мы создадим запись "подробной временной шкалы" для шага. Мы можем создавать и обновлять вложенные записи временной шкалы.idparentid

Авторы задач должны помнить, какой 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 синтаксис для ссылки на переменную набора зависит от того, имеет ли вы доступ к этой переменной в том же задании, будущем задании или на следующем этапе. Кроме того, если isOutput задан false синтаксис для использования этой переменной в одном задании, отличается. Ознакомьтесь с уровнями выходных переменных , чтобы определить соответствующий синтаксис для каждого варианта использования.

Дополнительные сведения о выходных переменных см. в задания переменных в скриптах и определения переменных.

Свойства

• variable = имя переменной (обязательно)
• isSecret = логическое значение (необязательно, по умолчанию — false)
• isOutput = логическое значение (необязательно, по умолчанию — 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 "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 "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

Присвойте переменные:

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

PowerShell

Присвойте переменные:

- 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 = идентификатор подключения службы (обязательно)
• 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

Использование

Отправка и присоединение сводки Markdown из MD-файла в репозитории в текущую запись временной шкалы. Эта сводка должна быть добавлена в сводку по сборке или выпуску и недоступна для скачивания с помощью журналов. Сводка должна быть в формате UTF-8 или ASCII. Сводка отображается на вкладке расширений запуска конвейера. Отрисовка Markdown на вкладке "Расширения" отличается от Azure DevOps вики-визуализации. Дополнительные сведения о синтаксисе Markdown см. в руководстве Markdown.

Примеры

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

Команды артефактов

Публикация артефактов не поддерживается в классических конвейерах выпуска.

Связывание: инициализация артефакта

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

Использование

Добавьте тег для текущей сборки. Вы можете развернуть тег с предварительно определенной или пользовательской переменной. Например, здесь новый тег добавляется в задачу Bash со значением last_scanned-$(currentDate). Нельзя использовать двоеточие с 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

Устранение неполадок с командами ведения журнала

Команды ведения журнала не обрабатываются

Команды ведения журнала должны быть записаны в stdout во время выполнения шага агентом. Если команды отображаются в необработанных журналах, но не обрабатываются:

• Внешние средства записи в файлы: если средство записывает ##vso[...] строки в файл журнала, а не stdout, агент не анализирует их. Перенаправьте выходные данные средства на stdout в скрипте.
• Буферированные выходные данные: некоторые программы буфера stdout, если он не подключен к терминалу. Используйте параметры, относящиеся к языку, для очистки выходных данных (например, python -u или задания PYTHONUNBUFFERED=1).
• set -x вмешательство в Linux или macOS: параметр set -x может повредить команды ведения журнала. Сведения об устранении неполадок см. в статье об устранении неполадок .
• Кодировка: команды ведения журнала должны использовать кодировку UTF-8. Другие кодировки могут привести к пропуску команды агентом.
• Новые строки в командах: каждая команда ведения журнала должна находиться в одной строке. Если в строке ##vso[...] отображается новый символ, агент не распознает команду.

Специальные символы в значениях

Некоторые символы должны быть экранироваться при использовании в значениях команд ведения журнала. Эти escape-последовательности определяются в исходном коде агента:

Character	escape-последовательность
Запятой ;	%3B
Newline \n	%0A
Возврат каретки \r	%0D
Закрыть скобку ]	%5D

Чтобы избежать входов в процент значений, используйте %AZP25 вместо %него. Это поведение управляется переменной DECODE_PERCENTS . Дополнительные сведения см. в разделе "Кодирование процентов".