Compartir a través de

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

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

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 de tiempo de ejecución, que solo están disponibles en el momento del análisis del modelo, las variables de los pipelines de lanzamiento clásicos son accesibles durante todo el proceso de implementación.

Al configurar tareas para implementar su aplicación en cada etapa de la tubería de liberación clásica, las variables le pueden ayudar 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 variables 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. Estas variables 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 proporcionan acceso a 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 esta variable en los scripts o tareas para llamar a las API 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 esta variable en los scripts o tareas para llamar a las API 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 el pipeline descarga artefactos durante la implementación de un release. La canalización borra el directorio antes de cada implementación cuando es necesario descargar artefactos al agente. Igual que Agent.ReleaseDirectory y System.DefaultWorkingDirectory.

Ejemplo: C:\agent\_work\r1\a
System.DefaultWorkingDirectory Directorio al que la canalización descarga artefactos durante la implementación de una versión. La pipeline borra el directorio antes de cada implementación si es necesario descargar artefactos en el agente. Igual que Agent.ReleaseDirectory y System.ArtifactsDirectory.

Ejemplo: C:\agent\_work\r1\a
System.WorkFolder El directorio de trabajo de este agente, donde la canalización crea 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. Establezca esta variable true en 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 especifica 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 al agente.

Ejemplo: FALSE
Release.TriggeringArtifact.Alias Alias del artefacto que desencadenó la versión. Este valor está vacío cuando el lanzamiento se programa o se desencadena 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 este nombre 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 ejecuta, como Release o Build.

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 la implementación de una versión descarga artefactos. El directorio se borra antes de cada implementación si requiere que los artefactos se descarguen en el agente. Es lo mismo 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. Es lo mismo 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. Es lo mismo que Agent.RootDirectory y System.WorkFolder.

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

Ejemplo: 1

Liberar variables de artefactos

Para cada artefacto al que haga referencia en una versión, use 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.

Reemplaza el {alias} marcador de posición por el valor que especificas para el "alias" de fuente del artefacto o por el valor predeterminado que se genera para la canalización de lanzamiento.

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 Tipo de origen de artefacto, como Build. Ejemplos:

Azure Pipelines: Build
Jenkins: Jenkins
Azure DevOps Services: 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 un artefacto como el artefacto principal. Después, Azure Pipelines rellena las siguientes variables para el artefacto principal designado.

Nombre de la variable Igual que
Build.DefinitionId Release.Artifacts. {Alias de artefacto principal}. DefinitionId
Build.DefinitionName Release.Artifacts. {Alias de artefacto principal}. DefinitionName
Build.BuildNumber Release.Artifacts. {Alias de artefacto principal}. BuildNumber
Build.BuildId Release.Artifacts. {Alias de artefacto principal}. BuildId
Build.BuildURI Release.Artifacts. {Alias de artefacto principal}. BuildURI
Build.SourceBranch Release.Artifacts. {Alias de artefacto principal}. SourceBranch
Build.SourceBranchName Release.Artifacts. {Alias de artefacto principal}. SourceBranchName
Build.SourceVersion Release.Artifacts. {Alias de artefacto principal}. SourceVersion
Build.Repository.Provider Release.Artifacts. {Alias de artefacto principal}. Repository.Provider
Build.RequestedForID Release.Artifacts. {Alias de artefacto principal}. RequestedForID
Build.RequestedFor Release.Artifacts. {Alias de artefacto principal}. RequestedFor
Build.Type Release.Artifacts. {Alias de artefacto principal}. Tipo
Build.PullRequest.TargetBranch Release.Artifacts. {Alias de artefacto principal}. PullRequest.TargetBranch
Build.PullRequest.TargetBranchName Release.Artifacts. {Alias de artefacto principal}. 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.

Use una variable predeterminada directamente 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, use $(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, reemplace 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. 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

Puede definir variables personalizadas en distintos ámbitos.

  • Grupos de variables: utilice grupos de variables para compartir valores en todas las definiciones de un proyecto. Este enfoque es ú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. Este enfoque 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. Este enfoque es útil para los valores que difieren de la fase a la 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.

Mediante el uso de variables personalizadas en el proyecto, el flujo de versiones y los niveles de etapas, puede hacer lo siguiente:

  • 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 situado junto a la variable.

    Importante

    Los valores de las variables ocultas (secreto) se almacenan de forma segura en el servidor y los usuarios no pueden verlos después de guardarlos. Durante la implementación, Azure Pipelines descifra estos valores cuando las tareas las hacen referencia y las 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, sobrescribe la variable $env:Path y podría 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, inserte 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, tarea o etapa) pueden entrar en conflicto y provocar resultados impredecibles. Para evitar este problema, 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. Este paso abre los registros. Desplácese hacia abajo para ver los valores que usa 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 mostrando información adicional durante la ejecución de la versión. Puede activar el modo de depuración para toda la versión o solo para las tareas de una fase de versión específica.

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

  • Para activar 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 se produce un error relacionado con las conexiones de servicio de Azure Resource Manager, consulte Solución de problemas de conexiones de servicio de Azure Resource Manager para más información.

Contenido relacionado

  • Last updated on