Expresiones

# Expressions are used to define conditions for a step, job, or stage
steps:
- task: ...
  condition: <expression>

Otro uso común de expresiones consiste en definir variables. Las expresiones se pueden evaluar en tiempo de compilación o en tiempo de ejecución. Las expresiones de tiempo de compilación se pueden utilizar en cualquier lugar; las expresiones en tiempo de ejecución se pueden usar en variables y condiciones. Las expresiones en tiempo de ejecución están diseñadas como una manera de calcular el contenido de las variables y el estado (ejemplo: condition).

# Two examples of expressions used to define variables
# The first one, a, is evaluated when the YAML file is compiled into a plan.
# The second one, b, is evaluated at runtime.
# Note the syntax ${{}} for compile time and $[] for runtime expressions.
variables:
  a: ${{ <expression> }}
  b: $[ <expression> ]

La diferencia entre las sintaxis de expresiones en tiempo de ejecución y en tiempo de compilación es principalmente qué contexto está disponible. En una expresión en tiempo de compilación (${{ <expression> }}), tiene acceso a parameters y variables se define estáticamente. En una expresión en tiempo de ejecución ($[ <expression> ]), tiene acceso a más variables, pero no a los parámetros.

En este ejemplo, una expresión en tiempo de ejecución establece el valor de $(isMain). Una variable estática en una expresión de compilación establece el valor de $(compileVar).

variables:
  staticVar: 'my value' # static variable
  compileVar: ${{ variables.staticVar }} # compile time expression
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')] # runtime expression

steps:
  - script: |
      echo ${{variables.staticVar}} # outputs my value
      echo $(compileVar) # outputs my value
      echo $(isMain) # outputs True

coalesce

• Evalúa los parámetros por orden (de izquierda a derecha) y devuelve el primer valor que no es igual a null o cadena vacía.
• No se devuelve ningún valor si los valores de parámetro todos son cadenas nulas o vacías.
• Parámetros mínimos: 2. Parámetros máximos: N
• Ejemplo: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Tome un objeto complejo y genere una salida como JSON.
• Parámetros mínimos: 1. Parámetros máximos: 1.

parameters:
  - name: listOfValues
    type: object
    default:
      this_is:
        a_complex: object
        with:
          - one
          - two

steps:
- script: |
    echo "${MY_JSON}"
  env:
    MY_JSON: ${{ convertToJson(parameters.listOfValues) }}

Salida del script:

{
  "this_is": {
    "a_complex": "object",
    "with": [
      "one",
      "two"
    ]
  }
}

counter

• Esta función solo se puede usar en una expresión que define una variable. No se puede usar como parte de una condición para un paso, trabajo o etapa.
• Evalúa un número que se incrementa con cada ejecución de una canalización.
• Parámetros: 2. prefix y seed.
• El prefijo es una expresión de cadena. Se realiza un seguimiento de un valor independiente del contador para cada valor único del prefijo. prefix debe usar caracteres UTF-16.
• El valor de inicialización es el valor de inicio del contador.

Puede crear un contador que se incremente automáticamente en uno en cada ejecución de la canalización. Al definir un contador, proporciona prefix y seed. Este es un ejemplo de código que muestra justo esto.

variables:
  major: 1
  # define minor as a counter with the prefix as variable major, and seed as 100.
  minor: $[counter(variables['major'], 100)]

steps:
- bash: echo $(minor)

El valor de minor en el ejemplo anterior en la primera ejecución de la canalización es 100. En la segunda ejecución es 101, siempre que el valor de major siga siendo 1.

Si edita el archivo de YAML y actualiza el valor de la variable major para que sea 2, entonces en la siguiente ejecución de la canalización, el valor de minor será de 100. Las ejecuciones posteriores incrementan el contador a 101, 102, 103,...

Más adelante, si edita el archivo de YAML y establece el valor de major de nuevo en 1, el valor del contador se reanuda donde se dejó para ese prefijo. En este ejemplo, se reanuda en 102.

Este es otro ejemplo de cómo establecer una variable para que actúe como un contador que comienza en 100, se incrementa en 1 para cada ejecución y se restablece a 100 todos los días.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Este es un ejemplo de tener un contador que mantiene un valor independiente para las solicitudes de incorporación de cambios y las ejecuciones de CI.

variables:
  patch: $[counter(variables['build.reason'], 0)]

Los contadores se limitan a una canalización. En otras palabras, su valor se incrementa para cada ejecución de esa canalización. No hay contadores limitados a proyectos.

format

• Evalúa los parámetros finales y los inserta en la cadena de parámetro inicial.
• Parámetros mínimos: 1. Parámetros máximos: N
• Ejemplo: format('Hello {0} {1}', 'John', 'Doe')
• Usa especificadores de formato de fecha y hora personalizados de .NET para el formato de fecha (yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K).
• Ejemplo: format('{0:yyyyMMdd}', pipeline.startTime). En este caso, pipeline.startTime es una variable de objeto de fecha y hora especial.
• Añada un carácter de escape duplicando las llaves. Por ejemplo: format('literal left brace {{ and literal right brace }}')

join

• Concatena todos los elementos de la matriz del parámetro derecho, separados por la cadena del parámetro izquierdo.
• Parámetros mínimos: 2. Parámetros máximos: 2
• Cada elemento de la matriz se convierte en una cadena. Los objetos complejos se convierten en una cadena vacía.
• Si el parámetro derecho no es una matriz, el resultado es el parámetro derecho convertido en una cadena.

En este ejemplo, se agrega un punto y coma entre cada elemento de la matriz. El tipo del parámetro es un objeto.

parameters:
- name: myArray
  type: object
  default:
    - FOO
    - BAR
    - ZOO

variables:
   A: ${{ join(';',parameters.myArray) }}

steps:
  - script: echo $A # outputs FOO;BAR;ZOO

lower

• Convierte un valor de cadena o variable a caracteres todos en minúsculas.
• Parámetros mínimos: 1. Parámetros máximos: 1
• Devuelve el equivalente en minúsculas de una cadena.
• Ejemplo: lower('FOO') devuelve foo

replace

• Devuelve una nueva cadena en la que todas las instancias de una cadena en la instancia actual se reemplazan por otra cadena.
• Parámetros mínimos: 3. Parámetros máximos: 3
• replace(a, b, c): devuelve a, con todas las instancias de b reemplazadas por c.
• Ejemplo: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (devuelve http://server/saml/consume)

split

• Divide una cadena en subcadenas en función de los caracteres de delimitación especificados.
• Parámetros mínimos: 2. Parámetros máximos: 2
• El primer parámetro es la cadena que se va a dividir.
• El segundo parámetro son los caracteres delimitadores.
• Devuelve una matriz de subcadenas. La matriz incluye cadenas vacías cuando los caracteres delimitadores aparecen consecutivamente o al final de la cadena.
• Ejemplo:

  variables:
  - name: environments
    value: prod1,prod2 
  steps:  
    - ${{ each env in split(variables.environments, ',')}}:
      - script: ./deploy.sh --environment ${{ env }}
  

• Ejemplo de uso de split() con replace():

  parameters:
  - name: resourceIds
    type: object
    default:
    - /subscriptions/mysubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/loadBalancers/kubernetes-internal
    - /subscriptions/mysubscription02/resourceGroups/myResourceGroup02/providers/Microsoft.Network/loadBalancers/kubernetes
  - name: environments
    type: object
    default: 
    - prod1
    - prod2
  
  trigger:
  - main
  
  steps:
  - ${{ each env in parameters.environments }}:
    - ${{ each resourceId in parameters.resourceIds }}:
        - script: echo ${{ replace(split(resourceId, '/')[8], '-', '_') }}_${{ env }}
  

upper

• Convierte un valor de cadena o variable a caracteres todos en mayúsculas.
• Parámetros mínimos: 1. Parámetros máximos: 1
• Devuelve el equivalente en mayúsculas de una cadena.
• Ejemplo: upper('bah') devuelve BAH

Puede usar las cláusulas if, elseify else para asignar condicionalmente valores de variable o establecer entradas para las tareas. También puede ejecutar de forma condicional un paso cuando se cumple una condición.

Puede usar if para asignar condicionalmente valores de variable o establecer entradas para tareas. También puede ejecutar de forma condicional un paso cuando se cumple una condición.

Las cláusulas elseif y else están disponibles a partir de Azure DevOps 2022 y no están disponibles para Azure DevOps Server 2020 y versiones anteriores de Azure DevOps.

Establecimiento condicional de una entrada de tarea

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)'
    ${{ if eq(variables['Build.SourceBranchName'], 'main') }}:
      artifact: 'prod'
    ${{ else }}:
      artifact: 'dev'
    publishLocation: 'pipeline'

Ejecución condicional de un paso

Si no hay ninguna variable establecida o si el valor de foo no coincide con las condiciones if, se ejecuta la instrucción else. Aquí el valor de foo devuelve true en la condición elseif.

variables:
  - name: foo
    value: contoso # triggers elseif condition

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start"
- ${{ if eq(variables.foo, 'adaptum') }}:
  - script: echo "this is adaptum"
- ${{ elseif eq(variables.foo, 'contoso') }}: # true
  - script: echo "this is contoso" 
- ${{ else }}:
  - script: echo "the value is not adaptum or contoso"

Each (palabra clave)

Puede usar la palabra clave each para recorrer los parámetros con el tipo de objeto.

parameters:
- name: listOfStrings
  type: object
  default:
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}:
  - script: echo ${{ value }}

Además, puede recorrer en iteración los elementos anidados dentro de un objeto.

parameters:
- name: listOfFruits
  type: object
  default:
  - fruitName: 'apple'
    colors: ['red','green']
  - fruitName: 'lemon'
    colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
  - ${{ each fruitColor in fruit.colors}} :
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }}

Dependencias

Las expresiones pueden usar el contexto de dependencias para hacer referencia a fases o trabajos anteriores. Puede usar dependencias para:

• Hacer referencia al estado del trabajo de un trabajo anterior.
• Hacer referencia al estado de la fase de una fase anterior.
• Hacer referencia a variables de salida del trabajo anterior en la misma fase.
• Hacer referencia a variables de salida de la fase anterior en una fase.
• Hacer referencia a variables de salida en un trabajo de una fase anterior en la siguiente fase.

El contexto se llama dependencies para los trabajos y fases y funciona de forma muy similar a las variables. Si hace referencia a una variable de salida de un trabajo en otra fase, el contexto se llama stageDependencies.

Si tiene problemas con las variables de salida que tienen caracteres de comillas (' o ") en ellas, consulte esta guía de solución de problemas.

Introducción a la sintaxis de dependencia

La sintaxis de hacer referencia a variables de salida con dependencias varía en función de las circunstancias. Esta es una introducción a los escenarios más comunes. Puede haber ocasiones en las que la sintaxis alternativa también funcione.

También hay diferentes sintaxis para las variables de salida en los trabajos de implementación en función de la estrategia de implementación. Para obtener más información, consulte Trabajos de implementación.

Dependencias de fase a fase

Estructuralmente, el objeto dependencies es una asignación de nombres de trabajos y fases a results y outputs. Expresado como JSON, tendría el siguiente aspecto:

"dependencies": {
  "<STAGE_NAME>" : {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
        "jobName.stepName.variableName": "value"
    }
  },
  "...": {
    // another stage
  }
}

Use esta forma de dependencies para asignarlo en variables o comprobar condiciones en un nivel de fase.

En este ejemplo, hay dos fases, A y B. La fase A tiene la condición false y no se ejecutará nunca como resultado. La fase B se ejecuta si el resultado de la fase A es Succeeded, SucceededWithIssueso Skipped. La etapa B se ejecuta porque se omitió la etapa A.

stages:
- stage: A
  condition: false
  jobs:
  - job: A1
    steps:
    - script: echo Job A1
- stage: B
  condition: in(dependencies.A.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
  jobs:
  - job: B1
    steps:
    - script: echo Job B1

Las fases también pueden usar variables de salida de otra fase. En este ejemplo, también hay dos fases. La fase A incluye un trabajo, A1, que establece una variable de salida en shouldrun a true. La fase B se ejecuta cuando shouldrun es true. Dado que shouldrun es true, se ejecuta la fase B.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  condition: and(succeeded(), eq(dependencies.A.outputs['A1.printvar.shouldrun'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

Dependencias de trabajo a trabajo dentro de una fase

En el nivel de trabajo de una sola fase, los datos dependencies no contienen información de nivel de fase.

"dependencies": {
  "<JOB_NAME>": {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
      "stepName.variableName": "value1"
    }
  },
  "...": {
    // another job
  }
}

En este ejemplo, hay tres trabajos (a, b y c). El trabajo a siempre se omitirá debido a condition: false. El trabajo b se ejecuta porque no hay condiciones asociadas. El trabajo c se ejecuta porque todas sus dependencias son correctas (trabajo b) o se omiten (trabajo a).

jobs:
- job: a
  condition: false
  steps:
  - script: echo Job a
- job: b
  steps:
  - script: echo Job b
- job: c
  dependsOn:
  - a
  - b
  condition: |
    and
    (
      in(dependencies.a.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'),
      in(dependencies.b.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
    )
  steps:
  - script: echo Job c

En este ejemplo, el trabajo B depende de una variable de salida del trabajo A.

jobs:
- job: A
  steps:
  - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
  # or on Windows:
  # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
    name: printvar

- job: B
  condition: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Dependencias de trabajo a trabajo entre fases

En el nivel de trabajo, también puede hacer referencia a salidas de un trabajo en una fase anterior. Esto requiere el uso del contexto stageDependencies.

"stageDependencies": {
  "<STAGE_NAME>" : {
    "<JOB_NAME>": {
      "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
      "outputs": {
          "stepName.variableName": "value"
      }
    },
    "...": {
      // another job
    }
  },
  "...": {
    // another stage
  }
}

En este ejemplo, el trabajo B1 se ejecuta si se omite el trabajo A1. El trabajo B2 comprueba el valor de la variable de salida del trabajo A1 para determinar si debe ejecutarse.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  dependsOn: A
  jobs:
  - job: B1
    condition: in(stageDependencies.A.A1.result, 'Skipped') # change condition to `Succeeded and stage will be skipped`
    steps:
    - script: echo hello from Job B1
  - job: B2
    condition: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')
    steps:
     - script: echo hello from Job B2

Si un trabajo depende de una variable definida por un trabajo de implementación en una fase diferente, la sintaxis será diferente. En el ejemplo siguiente, el trabajo run_tests se ejecuta si el trabajo de implementación build_job establece runTests en true. Observe que la clave usada para el diccionario outputs es build_job.setRunTests.runTests.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  jobs:  
    - job: run_tests
      condition: eq(stageDependencies.build.build_job.outputs['build_job.setRunTests.runTests'], 'true')
      steps:
        ...

Variables de salida del trabajo de implementación

Si una fase depende de una variable definida por un trabajo de implementación en una fase distinta, la sintaxis es diferente. En el ejemplo siguiente, la fase test depende de la implementación build_job que establece shouldTest en true. Observe que en condition de la fase test, build_job aparece dos veces.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')
  jobs:
    - job: A
      steps:
        - script: echo Hello from job A

En el ejemplo anterior, la condición hace referencia a un entorno y no a un recurso de entorno. Para hacer referencia a un recurso de entorno, deberá agregar el nombre del recurso de entorno a la condición de dependencias. En el ejemplo siguiente, la condición hace referencia a un recurso de máquina virtual de entorno denominado vmtest.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: vmtest
      resourceName: winVM2
      resourceType: VirtualMachine
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.Deploy_winVM2.setRunTests.runTests'], 'true')
  jobs:
  - job: A
    steps:
     - script: echo Hello from job A