Comandos de registro

  • Artículo

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

Los comandos de registro son cómo se comunican las tareas y los scripts con el agente. Tratan acciones como crear nuevas variables, marcar un paso como erróneo y cargar artefactos. Los comandos de registro son útiles al solucionar problemas con las canalizaciones.

Importante

Hacemos un esfuerzo por enmascarar los secretos para que no aparezcan en la salida de Azure Pipelines, pero debe tomar precauciones. Nunca haga eco de secretos como salida. Algunos sistemas operativos registran los argumentos de la línea de comandos. Nunca pase secretos en la línea de comandos. En su lugar, se recomienda asignar los secretos a variables de entorno.

Nunca enmascaramos las subcadenas de los secretos. Si, por ejemplo, se establece "abc123" como secreto, "abc" no se enmascara en los registros. El objetivo de esto es no enmascarar los secretos de un modo demasiado pormenorizado, que haría los registros ilegibles. Por este motivo, los secretos no deben contener datos estructurados. Si, por ejemplo, se establece "{ "foo": "bar" }" como secreto, "bar" no se enmascara en los registros.

Tipo Comandos
Comandos de tarea AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Comandos de artefacto Associate, Upload
Comandos de compilación AddBuildTag, UpdateBuildNumber, UploadLog
Comandos de versión UpdateReleaseName

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"

Las rutas de acceso de archivo deben proporcionarse como absolutas: con la raíz en una unidad en Windows o con / al principio en Linux y macOS.

Nota:

Tenga en cuenta que no puede usar el comando set -x antes de un comando de registro con Linux o macOS. Consulte la solución de problemas para más información sobre cómo deshabilitar temporalmente set -x para Bash.

Comandos de formato

Nota:

Use la codificación UTF-8 para los comandos de registro.

Estos comandos son mensajes para el formateador del 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]"

Estos comandos se representarán 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

  • type = error o warning (obligatorio)
  • sourcepath = ubicación del archivo de origen
  • linenumber = número de línea
  • columnnumber = número de columna
  • code = cualquier error o advertencia

Ejemplo: registro de un error

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

Sugerencia

exit 1 es opcional, pero suele ser un comando que se emitirá poco después del registro de un error. Si selecciona Control Options: Continue on error, exit 1 dará como resultado una compilación parcialmente correcta en lugar de una compilación con errores. Como alternativa, también puede usar task.logissue type=error.

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

SetProgress: muestra el porcentaje completado.

##vso[task.setprogress]current operation

Uso

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

Propiedades

  • value = 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."

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 =
    • Succeeded Tarea realizada con éxito.
    • SucceededWithIssues La tarea tuvo problemas. La compilación se completará como parcialmente correcta en el mejor de los casos.
    • Failed 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 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: crea o actualiza un registro temporal para una tarea.

##vso[task.logdetail]current operation

Uso

Crea y actualiza los registros temporales. Azure Pipelines usa internamente esto 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 ##vso[task.detail] 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 id y parentid.

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

Propiedades

  • id = GUID de registro temporal (obligatorio)
  • parentid = GUID del registro temporal primario
  • type = tipo de registro (obligatorio la primera vez, no se puede sobrescribir)
  • name = nombre de registro (obligatorio la primera vez, no se puede sobrescribir)
  • order = orden del registro temporal (obligatorio la primera vez, no se puede sobrescribir)
  • starttime = Datetime
  • finishtime = Datetime
  • progress = 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 issecret se establece en true, 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 isoutput se establece en true, la sintaxis que hace referencia a la variable establecida varía en función de si se accede a esa variable en el mismo trabajo, un trabajo futuro o una fase futura. Además, si isoutput se establece en false, 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.

Consulte Establecimiento de variables en scripts y Definición de variables para más detalles.

Propiedades

  • variable = nombre de la variable (obligatorio)
  • issecret = booleano (opcional, el valor predeterminado es false)
  • isoutput = booleano (opcional, el valor predeterminado es false)
  • isreadonly = booleano (opcional, el valor predeterminado es false)

Ejemplos

Establezca las variables:

- 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

Lea las variables:

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

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

Establezca las variables:

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

Lea las variables:

- bash: |
    echo "Transformed and derived secrets will be masked: $(echo $OLDSECRET|base64)"
  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

  • id = identificador de conexión de servicio (obligatorio)
  • field = tipo de campo, uno de authParameter, dataParametero url (obligatorio)
  • key = clave (obligatorio, a menos que field = url)

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

  • type = tipo de los datos adjuntos (obligatorio)
  • name = 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 de 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 aparecerá en la pestaña Extensiones de la ejecución de la canalización. La representación de Markdown en la pestaña Extensiones es diferente de la representación de la wiki de Azure DevOps.

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

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

  • artifactname = nombre del artefacto (obligatorio)
  • type = tipo de artefacto (obligatorio) container | filepath | versioncontrol | gitref | tfvclabel

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

Propiedades

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

Ejemplo

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

Nota

La diferencia entre Artifact.associate y Artifact.upload es que la primera se puede usar para crear un vínculo a un artefacto existente, mientras que la última se puede usar para cargar o publicar un artefacto nuevo.

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 "logs\tool" 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 last_scanned-$(currentDate). 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.

Nota:

Se admite en Azure DevOps y Azure DevOps Server a partir de la versión 2020.

Ejemplo

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