Comandos de registo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

Os comandos de registro em log são como as tarefas e os 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 registro em log são úteis quando você está solucionando problemas de um pipeline.

Importante

Fazemos um esforço para impedir que segredos apareçam na saída do Azure Pipelines, mas você ainda precisa tomar precauções. Nunca ecoe segredos como saída. Alguns sistemas operacionais registram argumentos de linha de comando. Nunca passe segredos na linha de comando. Em vez disso, sugerimos que você mapeie seus segredos em variáveis de ambiente.

Nunca mascaramos subcadeias de segredos. Se, por exemplo, "abc123" for definido como um segredo, "abc" não será mascarado dos logs. Isso é para evitar mascarar segredos em um nível muito granular, tornando os logs ilegíveis. Por esta razão, os segredos não devem conter dados estruturados. Se, por exemplo, "{ "foo": "bar" }" for definido como um segredo, "bar" não será mascarado dos logs.

Type	Comandos
Comandos de tarefas	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Comandos de artefato	Associar, Carregar
Comandos de compilação	AddBuildTag, UpdateBuildNumber, UploadLog
Comandos de lançamento	UpdateReleaseName

Formato do comando de registo

O formato geral de um comando de registo é:

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

Há também 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 dados como caminhos absolutos: enraizados em uma unidade no Windows, ou começando com / no Linux e macOS.

Nota

Observe que você não pode usar o set -x comando antes de um comando de registro quando estiver usando Linux ou macOS. Consulte a resolução de problemas para saber como desativar set -x temporariamente o Bash.

Comandos de formatação

Nota

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

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 recolhíveis 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 bash ou 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 forma:

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

Comandos de tarefas

LogIssue: Registrar um erro ou aviso

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

Utilização

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

Propriedades

• type = error ou warning (Obrigatório)
• sourcepath = localização do ficheiro 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

Gorjeta

exit 1 é opcional, mas geralmente é um comando que você emitirá logo após o registro de um erro. Se você selecionar Opções de controle: continuar no erro, o exit 1 resultará em uma compilação parcialmente bem-sucedida em vez de uma compilação com falha. Como alternativa, você também pode usar task.logissue type=erroro .

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

Utilização

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

Propriedades

• value = percentagem 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 a compilação e, em seguida, observe a execução da compilação. Observe que um indicador de progresso muda quando a tarefa executa esse script.

Completo: Cronograma de término

##vso[task.complete]current operation

Utilização

Conclua o registro da 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 foi bem sucedida.
  • SucceededWithIssues A tarefa esbarrou em problemas. A construção será concluída como parcialmente bem-sucedida, na melhor das hipóteses.
  • Failed A compilação será concluída como falha. (Se a seringa Opções de controle: A opção Continuar no erro está selecionada, a compilação será concluída como parcialmente bem-sucedida, 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 1o .

- 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

Utilização

Cria e atualiza registros de linha do tempo. Isso é usado principalmente internamente pelo Azure Pipelines para gerar relatórios sobre etapas, trabalhos e estágios. Embora os clientes possam adicionar entradas à linha do tempo, elas normalmente não serão mostradas na interface do usuário.

A primeira vez que vemos ##vso[task.detail] durante uma etapa, criamos um registro de "linha do tempo detalhada" 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 registro 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 de registro da linha do tempo (Obrigatório)
• parentid = GUID do registro da linha do tempo pai
• type = Tipo de registo (Necessário pela primeira vez, não é possível substituir)
• name = Nome do registro (Necessário pela primeira vez, não pode substituir)
• order = ordem do registro da linha do tempo (Necessário para a primeira vez, não pode substituir)
• starttime = Datetime
• finishtime = Datetime
• progress = percentagem 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

Atualização existe registro de linha do tempo:

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

Utilização

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

Quando issecret estiver definido como true, o valor da variável será salvo como secreto e mascarado do log. As variáveis secretas não são passadas para tarefas como variáveis de ambiente e, em vez disso, devem ser passadas como entradas.

Quando isoutput é definido como true a sintaxe para fazer referência, a variável set varia com base no fato de você estar acessando essa variável no mesmo trabalho, em um trabalho futuro ou em um estágio futuro. Além disso, se isoutput estiver definido como false a sintaxe para usar essa variável dentro do mesmo trabalho é distinta. Consulte os níveis de variáveis de saída para determinar a sintaxe apropriada para cada caso de uso.

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

Propriedades

• variable = nome da variável (Obrigatório)
• issecret = booleano (Opcional, padrão para false)
• isoutput = booleano (Opcional, padrão para false)
• isreadonly = booleano (Opcional, padrão para 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: Registrar um valor como um segredo

##vso[task.setsecret]value

Utilização

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

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

Utilização

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

Propriedades

• id = ID de conexão de serviço (Obrigatório)
• field = tipo de campo, um dos authParameter, dataParameterou 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 à compilação

##vso[task.addattachment]value

Utilização

Carregue e anexe anexo ao registro da linha do tempo atual. Esses arquivos não estão disponíveis para download com logs. Eles só podem ser referidos 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: Adicione algum conteúdo de Markdown ao resumo da compilação

##vso[task.uploadsummary]local file path

Utilização

Carregue e anexe Markdown de resumo de um arquivo .md no repositório ao registro da linha do tempo atual. Este resumo deve ser adicionado ao resumo de compilação/lançamento e não está disponível para download com logs. O resumo deve estar em formato UTF-8 ou ASCII. O resumo aparecerá na guia Extensões da execução do pipeline. A renderização de Markdown na guia Extensões é diferente da renderização wiki do Azure DevOps.

Exemplos

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

É uma forma de mão curta para o comando

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

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

##vso[task.uploadfile]local file path

Utilização

Carregue o arquivo interessado do usuário como informações de log adicionais para o registro de linha do tempo atual. O ficheiro deve estar disponível para descarregamento juntamente com os registos 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

Utilização

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

Exemplo

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

Comandos de artefato

Associado: inicializar um artefato

##vso[artifact.associate]artifact location

Utilização

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

Propriedades

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

Exemplos

• contentor

  ##vso[artifact.associate type=container;artifactname=MyServerDrop]#/1/build
  

• caminho do arquivo

  ##vso[artifact.associate type=filepath;artifactname=MyFileShareDrop]\\MyShare\MyDropLocation
  

• controle de versão

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

Carregar: Carregar um artefacto

##vso[artifact.upload]local file path

Utilização

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

Propriedades

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

Exemplo

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

Nota

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.

Comandos de compilação

UploadLog: Carregar um registo

##vso[build.uploadlog]local file path

Utilização

Carregue o log do usuário interessado na pasta "" do contêiner dalogs\tool compilação.

Exemplo

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

UpdateBuildNumber: Substitua o número de compilação gerado automaticamente

##vso[build.updatebuildnumber]build number

Utilização

Você pode gerar automaticamente um número de compilação a partir de tokens especificados nas opções de pipeline. No entanto, se você quiser usar sua própria lógica para definir o número de compilação, então você pode usar este comando de log.

Exemplo

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

AddBuildTag: Adicionar uma tag à compilação

##vso[build.addbuildtag]build tag

Utilização

Adicione uma tag para a compilação atual. Você pode expandir a tag com uma variável predefinida ou definida pelo usuário. Por exemplo, aqui uma nova tag é 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 lançamento

UpdateReleaseName: Renomear versão atual

##vso[release.updatereleasename]release name

Utilização

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

Nota

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

Exemplo

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