Compartir vía

Uso de variables en canalizaciones de versión clásicas

  • Artículo

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

El uso de variables en canalizaciones de versión clásicas son una manera cómoda de intercambiar y transportar datos a lo largo de la canalización. Cada variable se almacena como una cadena y su valor puede cambiar entre ejecuciones de canalización.

A diferencia de los parámetros en tiempo de ejecución, que solo están disponibles en el tiempo de análisis de plantillas, se puede acceder a las variables de las canalizaciones de versión clásicas en todo el proceso de implementación.

Al configurar tareas para implementar la aplicación en cada fase de la canalización de versión clásica, las variables pueden ayudarle a:

  • Simplificar la personalización: defina una canalización de implementación genérica una vez y adáptela fácilmente para diferentes fases. Por ejemplo, use una variable para representar la cadena de conexión de una implementación web, ajustando su valor según sea necesario para cada fase. Estas se conocen como variables personalizadas.

  • Aprovechar información contextual: acceda a los detalles sobre el contexto de versión, como una fase, un artefacto o el agente que ejecuta la implementación. Por ejemplo, los scripts pueden requerir la ubicación de compilación para su descarga o el directorio de trabajo del agente para crear archivos temporales. Estos se conocen como variables predeterminadas.

Nota:

Para las canalizaciones de YAML, consulte variables definidas por el usuario y variables predefinidas para obtener más detalles.

Variables predeterminadas

Las variables predeterminadas proporcionan información esencial sobre el contexto de ejecución para las tareas y scripts en ejecución. Estas variables permiten acceder a los detalles sobre el sistema, la versión, la fase o el agente en los que se ejecutan.

Con la excepción de System.Debug, las variables predeterminadas son de solo lectura y el sistema establece automáticamente sus valores.

Algunas de las variables más significativas se describen en las tablas siguientes. Para ver la lista completa, consulte Ver los valores actuales de todas las variables.

Variables del sistema

Nombre de la variable Descripción
System.TeamFoundationServerUri La URL de la conexión de servicio en Azure Pipelines. Use esto a partir de los scripts o tareas para llamar a las API de REST de Azure Pipelines.

Ejemplo: https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri Dirección URL de la colección de Team Foundation o Azure Pipelines. Use esto a partir de los scripts o tareas para llamar a las API de REST en otros servicios, como Compilación y Control de versiones.

Ejemplo: https://dev.azure.com/fabrikam/
System.CollectionId Identificador de la colección a la que pertenece esta compilación o versión.

Ejemplo: 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId Id. de la canalización de versión a la que pertenece la versión actual.

Ejemplo: 1
System.TeamProject Nombre del proyecto al que pertenece la compilación o versión.

Ejemplo: Fabrikam
System.TeamProjectId Id. del proyecto al que pertenece la compilación o versión.

Ejemplo: 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory Directorio en el que se descargan los artefactos durante la implementación de una versión. El directorio se borra antes de cada implementación si requiere que los artefactos se descarguen en el agente. Igual que Agent.ReleaseDirectory y System.DefaultWorkingDirectory.

Ejemplo: C:\agent\_work\r1\a
System.DefaultWorkingDirectory Directorio en el que se descargan los artefactos durante la implementación de una versión. El directorio se borra antes de cada implementación si requiere que los artefactos se descarguen en el agente. Igual que Agent.ReleaseDirectory y System.ArtifactsDirectory.

Ejemplo: C:\agent\_work\r1\a
System.WorkFolder Directorio de trabajo para este agente, donde se crean subcarpetas para cada compilación o versión. Igual que Agent.RootDirectory y Agent.WorkFolder.

Ejemplo: C:\agent\_work
System.Debug Esta es la única variable del sistema que los usuarios pueden establecer. Establézcalo en true para ejecutar la versión en modo de depuración para ayudar en la búsqueda de errores.

Ejemplo: true

Variables de versión

Nombre de la variable Descripción
Release.AttemptNumber Número de veces que esta versión se implementa en esta fase.

Ejemplo: 1
Release.DefinitionEnvironmentId Identificador de la fase en la canalización de versión correspondiente.

Ejemplo: 1
Release.DefinitionId Id. de la canalización de versión a la que pertenece la versión actual.

Ejemplo: 1
Release.DefinitionName Nombre de la canalización de versión a la que pertenece la versión actual.

Ejemplo: fabrikam-cd
Release.Deployment.RequestedFor Nombre para mostrar de la identidad que desencadenó (iniciado) la implementación actualmente en curso.

Ejemplo: Mateo Escobedo
Release.Deployment.RequestedForEmail Dirección de correo electrónico de la identidad que desencadenó (iniciado) la implementación actualmente en curso.

Ejemplo: mateo@fabrikam.com
Release.Deployment.RequestedForId Id. de la identidad que desencadenó (iniciado) la implementación actualmente en curso.

Ejemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID Identificador de la implementación. Único por trabajo.

Ejemplo: 254
Release.DeployPhaseID Identificador de la fase en la que se ejecuta la implementación.

Ejemplo: 127
Release.EnvironmentId Identificador de la instancia de fase en una versión en la que la implementación está actualmente en proceso.

Ejemplo: 276
Release.EnvironmentName Nombre de la fase en la que la implementación está actualmente en curso.

Ejemplo: Dev
Release.EnvironmentUri URI de la instancia de fase en una versión en la que la implementación está actualmente en proceso.

Ejemplo: vstfs://ReleaseManagement/Environment/276
Release.Environments.{stage-name}.status El estado de la implementación de la fase.

Ejemplo: InProgress
Release.PrimaryArtifactSourceAlias Alias del origen del artefacto principal.

Ejemplo: fabrikam\_web
Release.Reason Motivo de la implementación. Los valores admitidos son:
ContinuousIntegration: la versión se inició en la implementación continua después de completar una compilación.
Manual: la versión se inició manualmente.
None: no se ha especificado el motivo de implementación.
Schedule: la versión iniciada a partir de una programación.
Release.ReleaseDescription Descripción del texto proporcionada en el momento de la versión.

Ejemplo: Critical security patch
Release.ReleaseId Identificador del registro de versión actual.

Ejemplo: 118
Release.ReleaseName El nombre de la versión actual.

Ejemplo: Release-47
Release.ReleaseUri URI de la versión actual.

Ejemplo: vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL Dirección URL de esta versión.

Ejemplo: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor Nombre para mostrar de la identidad que desencadenó la versión.

Ejemplo: Mateo Escobedo
Release.RequestedForEmail Dirección de correo electrónico de la identidad que desencadenó la versión.

Ejemplo: mateo@fabrikam.com
Release.RequestedForId ID de la identidad que desencadenó la versión.

Ejemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsDownload Valor booleano que especifica si se va a omitir la descarga de artefactos en el agente.

Ejemplo: FALSE
Release.TriggeringArtifact.Alias Alias del artefacto que desencadenó la versión. Esto estaba vacío cuando la versión se programó o desencadenó manualmente.

Ejemplo: fabrikam\_app

Variables de fase de versión

Nombre de la variable Descripción
Release.Environments.{stage-name}.Status Estado de la implementación de esta versión dentro de una fase especificada.

Ejemplo: NotStarted

Variables de agente

Nombre de la variable Descripción
Agent.Name Nombre del agente registrado con el grupo de agentes. Es probable que esto sea diferente del nombre del equipo.

Ejemplo: fabrikam-agent
Agent.MachineName Nombre del equipo en el que se configura el agente.

Ejemplo: fabrikam-agent
Agent.Version Versión del software del agente.

Ejemplo: 2.109.1
Agent.JobName Nombre del trabajo que se está ejecutando, como Versión o Compilación.

Ejemplo: Release
Agent.HomeDirectory Carpeta donde está instalado el agente. Esta carpeta contiene el código y los recursos del agente.

Ejemplo: C:\agent
Agent.ReleaseDirectory Directorio en el que se descargan los artefactos durante la implementación de una versión. El directorio se borra antes de cada implementación si requiere que los artefactos se descarguen en el agente. Igual que System.ArtifactsDirectory y System.DefaultWorkingDirectory.

Ejemplo: C:\agent\_work\r1\a
Agent.RootDirectory Directorio de trabajo para este agente, donde se crean subcarpetas para cada compilación o versión. Igual que Agent.WorkFolder y System.WorkFolder.

Ejemplo: C:\agent\_work
Agent.WorkFolder Directorio de trabajo para este agente, donde se crean subcarpetas para cada compilación o versión. Igual que Agent.RootDirectory y System.WorkFolder.

Ejemplo: C:\agent\_work
Agent.DeploymentGroupId Identificador del grupo de implementación con el que está registrado el agente. Esto solo está disponible en los trabajos del grupo de implementación.

Ejemplo: 1

Variables de artefactos de versión

Para cada artefacto al que se hace referencia en una versión, puede usar las siguientes variables de artefacto. Tenga en cuenta que no todas las variables se aplican a todos los tipos de artefacto. En la tabla siguiente se enumeran las variables de artefacto predeterminadas y se proporcionan ejemplos de sus valores en función del tipo de artefacto. Si un ejemplo está vacío, indica que la variable no es aplicable a ese tipo de artefacto.

Reemplace el marcador de posición {alias} por el valor especificado para el alias de origen de artefacto o por el valor predeterminado generado para la canalización de versión.

Nombre de la variable Descripción
Release.Artifacts.{alias}.DefinitionId Identificador de la canalización de compilación o del repositorio. Ejemplos:

Azure Pipelines: 1
GitHub: fabrikam/asp
Release.Artifacts.{alias}.DefinitionName Nombre de la canalización de compilación o del repositorio. Ejemplos:

Azure Pipelines: fabrikam-ci
TFVC: $/fabrikam
Git: fabrikam
GitHub: fabrikam/asp (main)
Release.Artifacts.{alias}.BuildNumber Número de compilación o identificador de confirmación. Ejemplos:

Azure Pipelines: 20170112.1
Jenkins: 20170112.1
TFVC: Changeset 3
Git: 38629c964
GitHub: 38629c964
Release.Artifacts.{alias}.BuildId Identificador de compilación. Ejemplos:

Azure Pipelines: 130
Jenkins: 130
GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts.{alias}.BuildURI Dirección URL de la compilación. Ejemplos:

Azure Pipelines: vstfs://build-release/Build/130
GitHub: https://github.com/fabrikam/asp
Release.Artifacts.{alias}.SourceBranch Ruta de acceso completa y nombre de la rama desde la que se creó el origen. Ejemplos:

Azure Pipelines: refs/heads/main
Release.Artifacts.{alias}.SourceBranchName El nombre solo de la rama desde la que se creó el origen. Ejemplos:

Azure Pipelines: main
Release.Artifacts.{alias}.SourceVersion Confirmación que se ha compilado. Ejemplos:

Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7
Release.Artifacts.{alias}.Repository.Provider Tipo de repositorio desde el que se creó el origen. Ejemplos:

Azure Pipelines: Git
Release.Artifacts.{alias}.RequestedForID Identificador de la cuenta que desencadenó la compilación. Ejemplos:

Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.Artifacts.{alias}.RequestedFor Nombre de la cuenta que solicitó la compilación. Ejemplos:

Azure Pipelines: Mateo Escobedo
Release.Artifacts.{alias}.Type El tipo de origen del artefacto, como Build. Ejemplos:

Azure Pipelines: Build
Jenkins: Jenkins
TFVC: TFVC
Git: Git
GitHub: GitHub
Release.Artifacts.{alias}.PullRequest.TargetBranch Ruta de acceso completa y nombre de la rama que es el destino de una solicitud de una incorporación de cambios. Esta variable solo se inicializa si un flujo de solicitud de incorporación de cambios desencadena la versión. Ejemplos:

Azure Pipelines: refs/heads/main
Release.Artifacts.{alias}.PullRequest.TargetBranchName Solo el nombre de la rama que es el destino de una solicitud de incorporación de cambios. Esta variable solo se inicializa si un flujo de solicitud de incorporación de cambios desencadena la versión. Ejemplos:

Azure Pipelines: main

Variables de artefacto principal

En canalizaciones de versión clásicas, si usa varios artefactos, puede designar uno como artefacto principal. Azure Pipelines rellenará las siguientes variables para el artefacto principal designado.

Nombre de la variable Igual que
Build.DefinitionId Release.Artifacts.{Primary artifact alias}.DefinitionId
Build.DefinitionName Release.Artifacts.{Primary artifact alias}.DefinitionName
Build.BuildNumber Release.Artifacts.{Primary artifact alias}.BuildNumber
Build.BuildId Release.Artifacts.{Primary artifact alias}.BuildId
Build.BuildURI Release.Artifacts.{Primary artifact alias}.BuildURI
Build.SourceBranch Release.Artifacts.{Primary artifact alias}.SourceBranch
Build.SourceBranchName Release.Artifacts.{Primary artifact alias}.SourceBranchName
Build.SourceVersion Release.Artifacts.{Primary artifact alias}.SourceVersion
Build.Repository.Provider Release.Artifacts.{Primary artifact alias}.Repository.Provider
Build.RequestedForID Release.Artifacts.{Primary artifact alias}.RequestedForID
Build.RequestedFor Release.Artifacts.{Primary artifact alias}.RequestedFor
Build.Type Release.Artifacts.{Primary artifact alias}.Type
Build.PullRequest.TargetBranch Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranch
Build.PullRequest.TargetBranchName Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranchName

Usar variables predeterminadas

Puede usar las variables predeterminadas de dos maneras: como parámetros para las tareas de una canalización de versión o dentro de los scripts.

Puede usar directamente una variable predeterminada como entrada para una tarea. Por ejemplo, para pasar Release.Artifacts.{Artifact alias}.DefinitionName como argumento a una tarea de PowerShell para un artefacto con ASPNET4.CI como alias, usaría $(Release.Artifacts.ASPNET4.CI.DefinitionName).

Captura de pantalla que muestra cómo usar una variable predeterminada como argumento.

Para usar una variable predeterminada en el script, primero debe reemplazar . en los nombres de variable predeterminados por _. Por ejemplo, para imprimir el valor de Release.Artifacts.{Artifact alias}.DefinitionName para un artefacto con ASPNET4.CI como alias en un script de PowerShell, use $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME. Tenga en cuenta que el alias original, ASPNET4.CI, se reemplaza por ASPNET4_CI.

Captura de pantalla que muestra cómo usar una variable predeterminada en un script de PowerShell insertado.

Variables personalizadas

Las variables personalizadas se pueden definir en varios ámbitos.

  • Grupos de variables: utilice grupos de variables para compartir valores en todas las definiciones de un proyecto. Esto resulta útil cuando desea usar los mismos valores en las definiciones, las fases y las tareas de un proyecto y administrarlos desde una sola ubicación. Defina y administre grupos de variables en Canalizaciones>Biblitoeca.

  • Variables de canalización de versión: use variables de canalización de versión para compartir valores en todas las fases de una canalización de versión. Esto es ideal para escenarios en los que se necesita un valor coherente entre fases y tareas, con la capacidad de actualizarlo desde una sola ubicación. Defina y administre estas variables en la pestaña Variables de la canalización de versión. En la página Variables de canalización, establezca la lista desplegable Ámbito en Versión al agregar una variable.

  • Variables de fase: use variables de fase para compartir valores dentro de una fase específica de una canalización de versión. Esto es útil para los valores que difieren de fase a fase, pero son coherentes en todas las tareas de una fase. Defina y administre estas variables en la pestaña Variables de la canalización de versión. En la página Variables de canalización, establezca la lista desplegable Ámbito en el entorno adecuado al agregar una variable.

El uso de variables personalizadas en el ámbito de proyecto, canalización de versión y fase le ayuda a:

  • Evitar duplicar los valores, lo que facilita la actualización de todas las repeticiones con un único cambio.

  • Proteger los valores confidenciales evitando que los usuarios los vean o modifiquen. Para marcar una variable como segura (secreto), seleccione el icono icono de candado situado junto a la variable.

    Importante

    Los valores de las variables ocultas (secretas) se almacenan de forma segura en el servidor y los usuarios no pueden verlos después de guardarlas. Durante la implementación, Azure Pipelines descifra estos valores cuando las tareas hacen referencia a ellos y los pasa al agente a través de un canal HTTPS seguro.

Nota:

La creación de variables personalizadas puede sobrescribir variables estándar. Por ejemplo, si define una variable Path personalizada en un agente de Windows, sobrescribirá la variable $env:Path, lo que puede impedir que PowerShell se ejecute correctamente.

Uso de variables personalizadas

Para usar variables personalizadas en las tareas, incluya el nombre de la variable entre paréntesis y precédalo con un carácter $. Por ejemplo, si tiene una variable denominada adminUserName, puede insertar su valor actual en una tarea como $(adminUserName).

Nota:

Las variables de diferentes grupos vinculados a una canalización en el mismo ámbito (por ejemplo, trabajo o fase) pueden entrar en conflicto, lo que provoca resultados impredecibles. Para evitarlo, asegúrese de que las variables de todos los grupos de variables tengan nombres únicos.

Definición y modificación de las variables en un script

Para definir o modificar una variable a partir de un script, use el comando de registro task.setvariable. El valor de variable actualizado tiene como ámbito el trabajo que se ejecuta y no se mantiene entre trabajos o fases. Tenga en cuenta que los nombres de variable se transforman en mayúsculas, con "." y " " reemplazados por "_".

Por ejemplo, Agent.WorkFolder se convierte en AGENT_WORKFOLDER.

  • En Windows, puede acceder a esta variable como %AGENT_WORKFOLDER% o $env:AGENT_WORKFOLDER.
  • En Linux y macOS, use $AGENT_WORKFOLDER.

Sugerencia

Puede ejecutar un script en:

Script de Batch

Establecer las variables sauce y secret.Sauce

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic

Leer las variables

Argumentos

"$(sauce)" "$(secret.Sauce)"

Script

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret)

Salida de la consola de la lectura de las variables:

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)

Ver los valores actuales de todas las variables

  1. Seleccione Versiones de >canalización y, a continuación, seleccione la canalización de versión.

  2. Abra la vista de resumen de su versión y seleccione la etapa que le interese. En la lista de pasos, elija Inicializar trabajo.

    Captura de pantalla que muestra el paso inicializar trabajo.

  3. Se abrirán los registros de este paso. Desplácese hacia abajo para ver los valores usados por el agente para este trabajo.

    Captura de pantalla que muestra las variables usadas por el agente.

Ejecución de una versión en modo de depuración

La ejecución de una versión en modo de depuración puede ayudarle a diagnosticar y resolver problemas o errores mostrando información adicional durante la ejecución de la versión. Puede habilitar el modo de depuración para toda la versión o solo para las tareas dentro de una fase de versión específica.

  • Para habilitar el modo de depuración para una versión completa, agregue una variable denominada System.Debug con el valor true a la pestaña Variables de la canalización de versión.

  • Para habilitar el modo de depuración para una fase específica, abra el cuadro de diálogo Configurar fase desde el menú contextual de la fase y agregue una variable denominada System.Debug con el valor true a la pestaña Variables.

  • Como alternativa, cree un grupo de variables que contenga una variable denominada System.Debug con el valor true y vincule este grupo de variables a la canalización de versión.

Sugerencia

Si encuentra un error relacionado con conexiones de servicio de Azure RM, consulte Tutorial: Solución de problemas de conexiones de servicio de Azure Resource Manager para obtener más información.

Contenido relacionado