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

  • Статья

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Команды ведения журнала — это способ взаимодействия задач и скриптов с агентом. Они охватывают такие действия, как создание переменных, маркировка шага как неудачная и отправка артефактов. Команды ведения журнала полезны при устранении неполадок конвейера.

Внимание

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

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

Тип Команды
Команды задач 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

Чтобы вызвать команду ведения журнала, выполните команду через стандартные выходные данные.

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

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

Эти команды будут отображаться в таких журналах:

Снимок экрана: журналы с настраиваемыми параметрами форматирования

Этот блок команд также можно свернуть и выглядеть следующим образом:

Снимок экрана: свернутый раздел журналов

Команды задач

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

Совет

exit 1 является необязательным, но часто возникает команда, которую вы будете выдавать вскоре после записи ошибки. Если выбрать параметры управления: продолжить ошибку, результатом exit 1 будет частично успешной сборки вместо неудачной сборки. Кроме того, можно использовать task.logissue type=errorв качестве альтернативы.

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

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

SetProgress: отображение процента завершено

##vso[task.setprogress]current operation

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

Задайте ход выполнения и текущую операцию для текущей задачи.

Свойства

  • value = процент завершения

Пример

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

Чтобы узнать, как он выглядит, сохраните и в очереди сборку, а затем просмотрите выполнение сборки. Обратите внимание, что индикатор хода выполнения изменяется при выполнении этого скрипта.

Завершение: завершение временная шкала

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

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

Свойства

  • variable = имя переменной (обязательно)
  • issecret = логическое значение (необязательно, по умолчанию — false)
  • isoutput = логическое значение (необязательно, по умолчанию — false)
  • isreadonly = логическое значение (необязательно, по умолчанию — false)

Примеры

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

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

Выходные данные консоли:

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

Выходные данные консоли:

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.

Примеры

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

Примеры

  • 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

  • Настраиваемый артефакт

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