Comandos de registro

servicios Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Los comandos de registro son cómo tasks y los scripts se comunican con el agente de Azure Pipelines. Cuando un paso de canalización escribe una cadena con formato especial en la salida estándar (stdout), el agente la intercepta y realiza la acción solicitada, como establecer una variable, cargar un artefacto o marcar el paso como erróneo. Los comandos de registro son útiles para personalizar el comportamiento de la canalización y la solución de problemas.

Funcionamiento de los comandos de registro

El agente de Azure Pipelines procesa los comandos de registro examinando salida estándar (stdout) desde cada tarea y paso de script en tiempo real a medida que se ejecuta el paso. Cuando el agente detecta una línea que coincide con el patrón o en stdout, interpreta el comando y realiza la acción solicitada (por ejemplo, establecer una variable o cargar un artefacto).

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

Formato de los comandos de registro

El formato general de los comandos de registro es:

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

También hay algunos comandos de formato con una sintaxis ligeramente diferente:

##[command]message

Para invocar un comando de registro, repita el comando mediante la salida estándar.

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

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

Las rutas de acceso de archivo deben proporcionarse como rutas de acceso absolutas: rooteados a una unidad en Windows o a partir de / en Linux y macOS.

Comandos de formato

Estos comandos son mensajes para el formateador de registro en Azure Pipelines. Marcan líneas de registro específicas como errores, advertencias, secciones contraíbles, etc.

Los comandos de formato son:

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

Puede usar los comandos de formato en una tarea de Bash o 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]"

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

Esos comandos se representan en los registros de la siguiente manera:

Captura de pantalla de los registros con opciones de formato personalizadas

Ese bloque de comandos también se puede contraer y tiene el siguiente aspecto:

Captura de pantalla de una sección contraída de registros

Comandos de tarea

LogIssue: registra un error o una advertencia.

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

Uso

Registre un mensaje de error o de advertencia en el registro temporal de la tarea actual.

Propiedades

• o (obligatorio)
• = ubicación del archivo de origen
• = número de línea
• = número de columna
• = cualquier error o advertencia

Ejemplo: registro de un error

#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1

Write-Host "##vso[task.logissue type=error]Something went very wrong."
exit 1

Ejemplo: Registro de una advertencia sobre un lugar específico en un archivo

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

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: muestra el porcentaje completado.

##vso[task.setprogress]current operation

Uso

Establezca el progreso y la operación actual para la tarea actual.

Propiedades

• = porcentaje de finalización

Ejemplo

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

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 cómo parece, guarde y ponga en cola la compilación y observe la ejecución de la compilación. Observe que un indicador de progreso cambia cuando la tarea ejecuta este script.

Complete: fin de la escala de tiempo.

##vso[task.complete]current operation

Uso

Finalice el registro temporal de la tarea actual, establezca el resultado de la tarea y la operación actual. Cuando no se proporciona el resultado, establézcalo en correcto.

Propiedades

• result =
  • Tarea realizada con éxito.
  • La tarea tuvo problemas. La compilación se completará como parcialmente correcta en el mejor de los casos.
  • La compilación se completará como con errores. (Si se selecciona la opción Control Options: Continue on error, la compilación se completará como parcialmente correcta en el mejor de los casos).

Ejemplo

Registre una tarea como que se realizó correctamente.

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

Establezca una tarea como errónea. Como alternativa, también puede usar .

- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi

LogDetail: crea o actualiza un registro temporal para una tarea.

##vso[task.logdetail]current operation

Uso

Crea y actualiza los registros temporales. Esto se usa principalmente internamente por Azure Pipelines para informar sobre los pasos, los trabajos y las fases. Aunque los clientes pueden agregar entradas a la escala de tiempo, normalmente no se mostrarán en la interfaz de usuario.

La primera vez que vemos durante un paso, creamos un registro de "detalle de la escala de tiempo" para el paso. Podemos crear y actualizar registros temporales anidados basados en y .

Los autores de las tareas deben recordar qué GUID usaron para cada registro temporal. El sistema de registro realiza un seguimiento del GUID de cada registro de escala de tiempo, por lo que cualquier nuevo GUID da como resultado un nuevo registro de escala de tiempo.

Propiedades

• = GUID de registro temporal (obligatorio)
• = GUID del registro temporal primario
• = tipo de registro (obligatorio la primera vez, no se puede sobrescribir)
• = nombre de registro (obligatorio la primera vez, no se puede sobrescribir)
• = orden del registro temporal (obligatorio la primera vez, no se puede sobrescribir)
• starttime = Datetime
• finishtime = Datetime
• = porcentaje de finalización
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Ejemplos

Cree un registro temporal raíz:

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

Cree un registro temporal anidado:

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

Actualice un registro temporal existente:

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

SetVariable: inicialice o modifique el valor de una variable.

##vso[task.setvariable]value

Uso

Establece una variable en el servicio de variables de taskcontext. La primera tarea puede establecer una variable y las siguientes pueden usarla. La variable se expone a las tareas siguientes como variable de entorno.

Cuando se establece en , el valor de la variable se guarda como secreto y se enmascara en el registro. Las variables secretas no se pasan a las tareas como variables de entorno, sino que se deben pasar como entradas.

Cuando se establece en la sintaxis para hacer referencia a la variable set varía en función de si está accediendo a esa variable en el mismo trabajo, un trabajo futuro o una fase futura. Además, si se establece en , la sintaxis para usar esa variable dentro del mismo trabajo es distinta. Consulte los niveles de las variables de salida para determinar la sintaxis adecuada para cada caso de uso.

Para obtener más información sobre las variables de salida, consulte establecer variables en scripts y definir variables.

Propiedades

Ejemplos

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

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

Salida de la consola:

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 un valor como secreto

##vso[task.setsecret]value

Uso

El valor se registra como secreto durante el trabajo. El valor se enmascarará desde los registros desde este punto hacia delante. Este comando es útil cuando se transforma un secreto (por ejemplo, codificado en base64) o se deriva.

Nota: Las apariciones anteriores del valor secreto no se enmascararán.

Ejemplos

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

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

Salida de la consola:

Transformed and derived secrets will be masked: ***

SetEndpoint: modifica un campo de conexión de servicio.

##vso[task.setendpoint]value

Uso

Establezca un campo de conexión de servicio con un valor especificado. El valor actualizado se conservará en el punto de conexión para las tareas posteriores que se ejecuten en el mismo trabajo.

Propiedades

• = identificador de conexión de servicio (obligatorio)
• = tipo de campo, uno de , o (obligatorio)
• = clave (obligatorio, a menos que )

Ejemplos

##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: adjunta un archivo a la compilación.

##vso[task.addattachment]value

Uso

Cargue y adjunte datos al registro temporal actual. Estos archivos no están disponibles para su descarga con los registros. Solo se puede hacer referencia a ellos mediante extensiones con los valores de tipo o nombre.

Propiedades

• = tipo de los datos adjuntos (obligatorio)
• = nombre de los datos adjuntos (obligatorio)

Ejemplo

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

UploadSummary: agrega contenido de Markdown al resumen de la compilación.

##vso[task.uploadsummary]local file path

Uso

Cargue y adjunte el resumen markdown desde un archivo .md del repositorio al registro de escala de tiempo actual. Este resumen se agregará al resumen de la compilación o versión y no estará disponible para su descarga con los registros. El resumen debe estar en formato UTF-8 o ASCII. El resumen aparece en la pestaña Extensiones de de la ejecución de la canalización. La representación de Markdown en la pestaña Extensiones es diferente de Azure DevOps representación wiki. Para obtener más información sobre la sintaxis de Markdown, consulte la Guía de Markdown.

Ejemplos

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

Es una forma abreviada para el comando.

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

UploadFile: carga un archivo que se puede descargar con los registros de tarea.

##vso[task.uploadfile]local file path

Uso

Cargue el archivo que le interesa al usuario como información de registro adicional en el registro temporal actual. El archivo estará disponible para su descarga junto con los registros de tarea.

Ejemplo

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

PrependPath: antepone una ruta de acceso a la variable de entorno PATH.

##vso[task.prependpath]local file path

Uso

Actualice la variable de entorno PATH anteponiéndola a PATH. La variable de entorno actualizada se reflejará en las tareas posteriores.

Ejemplo

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

Comandos de artefacto

La publicación de artefactos no se admite en canalizaciones de versión clásicas.

Associate: inicia un artefacto.

##vso[artifact.associate]artifact location

Uso

Cree un vínculo a un artefacto existente. La ubicación del artefacto debe ser una ruta de acceso del contenedor de archivos, una ruta de acceso verificable o una ruta de acceso de recurso compartido UNC.

Propiedades

• = nombre del artefacto (obligatorio)
• = tipo de artefacto (obligatorio)

Ejemplos

• 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
  

• Artefacto personalizado

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

Upload: carga un artefacto.

##vso[artifact.upload]local file path

Uso

Cargue un archivo local en una carpeta de contenedor de archivos y, opcionalmente, publique un artefacto como .

Propiedades

• = carpeta en la que se cargará el archivo, si es necesario, se crea.
• = nombre del artefacto. (Requerido)

Ejemplo

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

Comandos de compilación

UploadLog: carga un registro.

##vso[build.uploadlog]local file path

Uso

Cargue el registro que le interesa al usuario en la carpeta "" del contenedor de la compilación.

Ejemplo

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

UpdateBuildNumber: invalida el número de compilación generado automáticamente.

##vso[build.updatebuildnumber]build number

Uso

Puede generar automáticamente un número de compilación a partir de los tokens que especifique en las opciones de canalización. Sin embargo, si desea usar su propia lógica para establecer el número de compilación, puede usar este comando de registro.

Ejemplo

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

AddBuildTag: agrega una etiqueta a la compilación.

##vso[build.addbuildtag]build tag

Uso

Agregue una etiqueta para la compilación actual. Puede expandir la etiqueta con una variable predefinida o definida por el usuario. Por ejemplo, aquí se agrega una nueva etiqueta en una tarea de Bash con el valor . No puede usar dos puntos con AddBuildTag.

Ejemplo

- 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 versión

UpdateReleaseName: cambia el nombre de la versión actual.

##vso[release.updatereleasename]release name

Uso

Actualice el nombre de la versión en ejecución.

Ejemplo

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

Solución de problemas de comandos de registro

Los comandos de registro no se procesan

Los comandos de registro deben escribirse en stdout durante la ejecución del paso por parte del agente. Si los comandos aparecen en los registros sin procesar, pero no se procesan:

• Herramientas externas que escriben en archivos: si una herramienta escribe cadenas en un archivo de registro en lugar de stdout, el agente no los analiza. Redirigir la salida de la herramienta a stdout en el script.
• Salida almacenada en búfer: algunos programas búfer stdout cuando no están conectados a un terminal. Use opciones específicas del idioma para vaciar la salida (por ejemplo, o establecer ).
• interferencias en Linux/macOS: la opción puede dañar los comandos de registro. Consulte solución de problemas para obtener una solución alternativa.
• Codificación: los comandos de registro deben usar la codificación UTF-8. Otras codificaciones pueden hacer que el agente omita el comando.
• Líneas nuevas dentro de los comandos: cada comando de registro debe estar en una sola línea. Si aparece un carácter de nueva línea dentro de la cadena, el agente no reconoce el comando.

Caracteres especiales en valores

Algunos caracteres deben tener caracteres de escape cuando se usan en los valores de comando de registro. Estas secuencias de escape se definen en el código fuente del agente:

Para escapar porcentaje de inicio de sesión de valores, use en lugar de . Este comportamiento se controla mediante la variable . Para obtener más información, consulte Codificación por porcentaje.