Comandos do registro em log

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

Os comandos de log são como tarefas e scripts se comunicam com o agente. Eles abrangem ações como criar novas variáveis, marcar uma etapa como falha e carregar artefatos. Os comandos de log são úteis quando você está solucionando problemas de um pipeline.

Importante

Fazemos um esforço para mascarar a exibição de segredos na saída do Azure Pipelines, mas ainda é preciso tomar precauções. Nunca ecoe segredos como saída. Alguns sistemas operacionais registram argumentos de linha de comando. Nunca transmita segredos na linha de comando. Em vez disso, a recomendação é mapear os segredos para variáveis de ambiente.

Nunca mascare as subcadeias de caracteres de segredos. Por exemplo, se "abc123" for definido como um segredo, "abc" não será mascarado nos logs. Isso evita mascarar segredos em um nível muito granular, o que torna os logs ilegíveis. Por esse motivo, os segredos não devem conter dados estruturados. Por exemplo, se "{ "foo": "bar" }" for definido como um segredo, "bar" não será mascarado nos logs.

Tipo	Comandos
Comandos de tarefa	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Comandos de artefato	Associate, Upload
Criar comandos	AddBuildTag, UpdateBuildNumber, UploadLog
Comandos de versão	UpdateReleaseName

Formato dos comando de log

O formato geral de um comando de log é:

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

Também há alguns comandos de formatação com uma sintaxe ligeiramente diferente:

##[command]message

Para invocar um comando de log, ecoe o comando por meio da saída padrão.

Bash

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

PowerShell

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

Os caminhos de arquivo devem ser fornecidos como caminhos absolutos: com raiz em uma unidade no Windows ou começando com / no Linux e no macOS.

Observação

Observe que você não pode usar o comando set -x antes de um comando de log, quando estiver usando o Linux ou o macOS. Confira solução de problemas para saber como desabilitar o set -x temporariamente para o Bash.

Comandos de formatação

Observação

Use a codificação UTF-8 para comandos de log.

Esses comandos são mensagens para o formatador de log no Azure Pipelines. Eles marcam linhas de log específicas como erros, avisos, seções recolhidas e assim por diante.

Os comandos de formatação são:

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

Você pode usar os comandos de formatação em uma tarefa do Bash ou do 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]"

Esses comandos serão renderizados nos logs da seguinte maneira:

Esse bloco de comandos também pode ser recolhido e tem esta aparência:

Comandos de tarefa

LogIssue: registrar um erro ou aviso

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

Uso

Registre uma mensagem de erro ou aviso no registro de linha do tempo da tarefa atual.

Propriedades

• type = error ou warning (Obrigatório)
• sourcepath = local do arquivo de origem
• linenumber = número da linha
• columnnumber = número da coluna
• code = código de erro ou aviso

Exemplo: registrar um erro

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

Dica

exit 1 é opcional, mas geralmente é um comando que você emitirá logo após um erro ser registrado. Se você selecionar Opções de Controle: continuar com erro, o exit 1 resultará em um build parcialmente bem-sucedido, em vez de um build com falha. Como alternativa, você também pode usar task.logissue type=error.

Exemplo: registrar um aviso sobre um local específico em um arquivo

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: mostrar porcentagem concluída

##vso[task.setprogress]current operation

Uso

Defina o progresso e a operação atual para a tarefa atual.

Propriedades

• value = porcentagem de conclusão

Exemplo

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

Para ver a aparência, salve e enfileire o build e, em seguida, observe a execução do build. Observe que um indicador de progresso muda quando a tarefa executa esse script.

Complete: concluir linha do tempo

##vso[task.complete]current operation

Uso

Conclua o registro de linha do tempo da tarefa atual, defina o resultado da tarefa e a operação atual. Quando o resultado não for fornecido, defina o resultado como bem-sucedido.

Propriedades

• result =
  • Succeeded A tarefa bem-sucedida.
  • SucceededWithIssues A tarefa teve problemas. O build será concluído como parcialmente bem-sucedido, na melhor das hipóteses.
  • Failed O build será concluído como falha. (Se a opção Opções de Controle: continuar com erro estiver selecionada, o build será concluído como parcialmente bem-sucedido, na melhor das hipóteses.)

Exemplo

Registre uma tarefa como bem-sucedida.

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

Defina uma tarefa como falha. Como alternativa, você também pode usar 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: criar ou atualizar um registro de linha do tempo para uma tarefa

##vso[task.logdetail]current operation

Uso

Cria e atualiza os registros de linha do tempo. Isso é usado principalmente internamente pelo Azure Pipelines para relatar etapas, trabalhos e fases. Embora os clientes possam adicionar entradas ao linha do tempo, elas normalmente não serão mostrados na interface do usuário.

Na primeira vez que vemos ##vso[task.detail] durante uma etapa, criamos um registro de "linha do tempo de detalhes" para a etapa. Podemos criar e atualizar registros de linha do tempo aninhados com base em id e parentid.

Os autores de tarefas devem lembrar qual GUID eles usaram para cada registro de linha do tempo. O sistema de log manterá o controle do GUID para cada registro de linha do tempo. Portanto, qualquer novo GUID resultará em um novo registro de linha do tempo.

Propriedades

• id = GUID do registro de linha do tempo (Obrigatório)
• parentid= GUID do registro de linha do tempo pai
• type = Tipo de registro (Obrigatório na primeira vez, não pode ser substituído)
• name = Nome de registro (Obrigatório na primeira vez, não pode ser substituído)
• order= ordem do registro de linha do tempo (Obrigatório na primeira vez, não pode ser substituído)
• starttime = Datetime
• finishtime = Datetime
• progress = porcentagem de conclusão
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Exemplos

Crie um novo registro de linha do tempo raiz:

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

Crie um novo registro de linha do tempo aninhado:

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

A atualização o registro de linha do tempo existente:

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

SetVariable: inicializar ou modificar o valor de uma variável

##vso[task.setvariable]value

Uso

Define uma variável no serviço variável de taskcontext. A primeira tarefa pode definir uma variável e as tarefas a seguir podem usar a variável . A variável é exposta às tarefas a seguir como uma variável de ambiente.

Quando isSecret é definido como true, o valor da variável é salvo como segredo e mascarado do log. As variáveis secretas não são transmitidas para tarefas como variáveis de ambiente e precisam ser transmitidas como entradas.

Quando isOutput é definido como true, a sintaxe para referenciar a variável definida varia com base no fato de você estar acessando essa variável no mesmo trabalho, em um trabalho futuro ou em uma fase futura. Além disso, se isOutput for definido como false, a sintaxe para usar essa variável no mesmo trabalho será diferente. Confira os níveis de variáveis de saída para determinar a sintaxe apropriada para cada caso de uso.

Confira definir variáveis em scripts e definir variáveis para obter mais detalhes.

Propriedades

• variable = nome da variável (Obrigatório)
• isSecret = booliano (opcional, o padrão é false)
• isOutput = booliano (opcional, o padrão é false)
• isReadOnly = booliano (opcional, o padrão é false)

Exemplos

Bash

Defina as variáveis:

- 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

Leia as variáveis:

- 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

Defina as variáveis:

- 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

Leia as variáveis:

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

Saída do console:

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: registra um valor como um segredo

##vso[task.setsecret]value

Uso

O valor é registrado como um segredo durante a duração do trabalho. O valor será mascarado nos logs a partir desse ponto. Esse comando é útil quando um segredo é transformado (por exemplo, codificado em base64) ou derivado.

Observação: as ocorrências anteriores do valor secreto não serão mascaradas.

Exemplos

Bash

Defina as variáveis:

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

Leia as variáveis:

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

PowerShell

Defina as variáveis:

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

Leia as variáveis:

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

Saída do console:

Transformed and derived secrets will be masked: ***

SetEndpoint: modificar um campo de conexão de serviço

##vso[task.setendpoint]value

Uso

Defina um campo de conexão de serviço com determinado valor. O valor atualizado será mantido no ponto de extremidade para as tarefas subsequentes que são executadas no mesmo trabalho.

Propriedades

• id = ID da conexão de serviço (Obrigatório)
• field = tipo de campo, um de authParameter, dataParameter ou url (Obrigatório)
• key = chave (Obrigatório, a menos que field = url)

Exemplos

##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: anexar um arquivo ao build

##vso[task.addattachment]value

Uso

Carregue e anexe o anexo ao registro de linha do tempo atual. Esses arquivos não estão disponíveis para download com logs. Eles só podem ser referenciados por extensões usando os valores de tipo ou nome.

Propriedades

• type = tipo de anexo (Obrigatório)
• name = nome do anexo (Obrigatório)

Exemplo

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

UploadSummary: adicionar algum conteúdo de Markdown ao resumo do build

##vso[task.uploadsummary]local file path

Uso

Carregue e anexe o Markdown de resumo de um arquivo .md no repositório ao registro de linha do tempo atual. Este resumo deve ser adicionado ao resumo de build/versão e não está disponível para download com logs. O resumo deve estar no formato UTF-8 ou ASCII. O resumo aparecerá na guia Extensões da execução de pipeline. A renderização de Markdown na guia Extensões é diferente da renderização wiki do Azure DevOps. Para obter mais informações sobre a sintaxe Markdown, consulte o Guia Markdown.

Exemplos

##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/testsummary.md

É uma forma abreviada para o comando

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

UploadFile: carregar um arquivo que pode ser baixado com logs de tarefas

##vso[task.uploadfile]local file path

Uso

Carregue o arquivo de interesse do usuário como informações de log adicionais para o registro de linha do tempo atual. O arquivo deve estar disponível para download junto com os logs de tarefas.

Exemplo

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

PrependPath: preceder um caminho para a variável de ambiente PATH

##vso[task.prependpath]local file path

Uso

Atualize a variável de ambiente PATH anexando ao PATH. A variável de ambiente atualizada será refletida nas tarefas subsequentes.

Exemplo

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

Comandos de artefato

Associar: inicializar um artefato

##vso[artifact.associate]artifact location

Uso

Crie um link para um Artefato existente. O local do artefato deve ser um caminho de contêiner de arquivo, caminho de VC ou caminho de compartilhamento de UNC.

Propriedades

• artifactname = nome do artefato (Obrigatório)
• type = tipo de artefato (Obrigatório) container | filepath | versioncontrol | gitref | tfvclabel

Exemplos

• contêiner

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

• Artefato Personalizado

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

Upload: carregar um artefato

##vso[artifact.upload]local file path

Uso

Carregue um arquivo local em uma pasta de contêiner de arquivos e, opcionalmente, publique um artefato como artifactname.

Propriedades

• containerfolder = pasta na qual o arquivo será carregado. A pasta será criada, se necessário.
• artifactname = nome do artefato. (Obrigatória)

Exemplo

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

Observação

A diferença entre Artifact.associate e Artifact.upload é que o primeiro pode ser usado para criar um link para um artefato existente, enquanto o último pode ser usado para carregar/publicar um novo Artefato.

Criar comandos

UploadLog: carregar um log

##vso[build.uploadlog]local file path

Uso

Carregue o log de interesse do usuário na pasta "logs\tool" do contêiner do build.

Exemplo

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

UpdateBuildNumber: substituir o número de build gerado automaticamente

##vso[build.updatebuildnumber]build number

Uso

Você pode gerar automaticamente um número de build nos tokens especificados nas opções de pipeline. No entanto, se você quiser usar sua própria lógica para definir o número de build, poderá usar esse comando de log.

Exemplo

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

AddBuildTag: adicionar uma marca ao build

##vso[build.addbuildtag]build tag

Uso

Adicione uma marca para o build atual. Você pode expandir a marca com uma variável predefinida ou definida pelo usuário. Por exemplo, aqui uma nova marca é adicionada em uma tarefa Bash com o valor last_scanned-$(currentDate). Não é possível usar dois-pontos com AddBuildTag.

Exemplo

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

Comandos de versão

UpdateReleaseName: renomear a versão atual

##vso[release.updatereleasename]release name

Uso

Atualize o nome da versão para a versão em execução.

Observação

Com suporte no Azure DevOps e Azure DevOps Server a partir da versão 2020.

Exemplo

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