Expresiones

Azure Pipelines | TFS 2018 | TFS 2017.3

Las expresiones se pueden usar en muchos lugares donde es necesario especificar un valor de cadena, booleano o número al crear una canalización. El uso más común de expresiones es en condiciones para determinar si se debe ejecutar un trabajo o un paso.

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

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

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

Una expresión puede ser un literal, una referencia a una variable, una referencia a una dependencia, una función o una combinación anidada válida de estos.

Literales

Como parte de una expresión, puede usar literales booleanos, null, number, string o version.

# Examples
variables:
  someBoolean: ${{ true }} # case insensitive, so True or TRUE also works
  someNumber: ${{ -1.2 }}
  someString: ${{ 'a b c' }}
  someVersion: ${{ 1.2.3 }}

Boolean

True y False son expresiones literales booleanas.

Null

Null es una expresión literal especial que se devuelve de un error de diccionario, por ejemplo, ( variables['noSuch'] ). Null puede ser la salida de una expresión, pero no se puede llamar directamente dentro de una expresión.

Número

Comienza con "-", "." o "0" a "9".

String

Debe estar entre comillas únicas. Por ejemplo: 'this is a string'.

Para expresar una comilla simple literal, escálela con una comilla simple. Por ejemplo: 'It''s OK if they''re using contractions.'.

Puede usar un carácter de canalización ( | ) para cadenas multilínea.

myKey: |
  one
  two
  three

Version

Número de versión con hasta cuatro segmentos. Debe comenzar con un número y contener dos o tres caracteres de punto ( . ). Por ejemplo: 1.2.3.4.

Variables

Como parte de una expresión, puede acceder a las variables mediante una de estas dos sintaxis:

• Sintaxis de índice: variables['MyVar']
• Sintaxis de desreferencia de propiedad: variables.MyVar

Para usar la sintaxis de desreferencia de propiedad, el nombre de propiedad debe:

• Empezar con a-Z o _
• Estar seguido de a-Z0-9 o_

En función del contexto de ejecución, hay diferentes variables disponibles.

• Si crea canalizaciones mediante YAML, las variables de canalización estarán disponibles.
• Si crea canalizaciones de compilación mediante el editor clásico, las variables de compilación estarán disponibles.
• Si crea canalizaciones de versión mediante el editor clásico, las variables de versión estarán disponibles.

Las variables siempre son cadenas. Si desea usar valores con tipo, debe usar parámetros en su lugar.

Funciones

Las siguientes funciones integradas se pueden usar en expresiones.

y

• Se evalúa como True si todos los parámetros son True
• Parámetros mínimos: 2. Parámetros máximos: N
• Convierte parámetros en booleanos para la evaluación
• Cortocircuitos después de la primera False
• Ejemplo: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

contiene

• Evalúa si True el parámetro izquierdo String contiene el parámetro right
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte parámetros en Cadena para su evaluación
• Realiza la comparación ordinal de casos ordinales
• Ejemplo: contains('ABCDE', 'BCD') (devuelve True)

containsValue

• Evalúa si True el parámetro izquierdo es una matriz y cualquier elemento es igual al parámetro derecho. También evalúa True si el parámetro izquierdo es un objeto y el valor de cualquier propiedad es igual al parámetro derecho.
• Parámetros mínimos: 2. Parámetros máximos: 2
• Si el parámetro izquierdo es una matriz, convierta cada elemento para que coincida con el tipo del parámetro derecho. Si el parámetro izquierdo es un objeto , convierta el valor de cada propiedad para que coincida con el tipo del parámetro derecho. La comparación de igualdad de cada elemento específico se evalúa False si se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Cortocircuitos después de la primera coincidencia

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

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

# Example output
{
  this_is: {
    a_complex: object,
    with: [
      one,
      two
    ]
  }
}

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)

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

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

endsWith

• Evalúa si True el parámetro izquierdo String termina con el parámetro right
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte parámetros en String para su evaluación
• Realiza la comparación ordinal entre mayúsculas y minúsculas
• Ejemplo: endsWith('ABCDE', 'DE') (devuelve True)

eq

• Evalúa si True los parámetros son iguales
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte el parámetro derecho para que coincida con el tipo de parámetro izquierdo. Devuelve si False se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Ejemplo: eq(variables.letters, 'ABC')

ge

• Evalúa si True el parámetro izquierdo es mayor o igual que el parámetro derecho.
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte el parámetro derecho para que coincida con el tipo de parámetro izquierdo. Errores si se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Ejemplo: ge(5, 5) (devuelve True)

gt

• Evalúa si True el parámetro left es mayor que el parámetro derecho.
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte el parámetro derecho para que coincida con el tipo de parámetro izquierdo. Errores si se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Ejemplo: gt(5, 2) (devuelve True)

in

• Evalúa si True el parámetro left es igual a cualquier parámetro derecho.
• Parámetros mínimos: 1. Parámetros máximos: N
• Convierte los parámetros de la derecha para que coincidan con el tipo de parámetro izquierdo. La comparación de igualdad se evalúa False si se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Cortocircuitos después de la primera coincidencia
• Ejemplo: in('B', 'A', 'B', 'C') (devuelve True)

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

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

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

le

• Evalúa si True el parámetro izquierdo es menor o igual que el parámetro derecho.
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte el parámetro derecho para que coincida con el tipo de parámetro izquierdo. Errores si se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Ejemplo: le(2, 2) (devuelve True)

length

• Devuelve la longitud de una cadena o una matriz, ya sea una que procede del sistema o que procede de un parámetro.
• Parámetros mínimos: 1. Parámetros máximos 1
• Ejemplo: length('fabrikam') devuelve 8

lt

• Evalúa si True el parámetro left es menor que el parámetro derecho.
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte el parámetro derecho para que coincida con el tipo de parámetro izquierdo. Errores si se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Ejemplo: lt(2, 5) (devuelve True)

ne

• Evalúa si True los parámetros no son iguales
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte el parámetro derecho para que coincida con el tipo de parámetro izquierdo. Devuelve si True se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Ejemplo: ne(1, 2) (devuelve True)

not

• Evalúa si True el parámetro es False
• Parámetros mínimos: 1. Parámetros máximos: 1
• Convierte el valor en booleano para la evaluación.
• Ejemplo: not(eq(1, 2)) (devuelve True)

notIn

• Evalúa si True el parámetro left no es igual a ningún parámetro derecho.
• Parámetros mínimos: 1. Parámetros máximos: N
• Convierte los parámetros de la derecha para que coincidan con el tipo de parámetro izquierdo. La comparación de igualdad se evalúa False si se produce un error en la conversión.
• Comparación ordinal entre mayúsculas y minúsculas para cadenas
• Cortocircuitos después de la primera coincidencia
• Ejemplo: notIn('D', 'A', 'B', 'C') (devuelve True)

o bien

• Evalúa si True algún parámetro es True
• Parámetros mínimos: 2. Parámetros máximos: N
• Convierte parámetros a booleanos para la evaluación
• Cortocircuitos después de la primera True
• Ejemplo: or(eq(1, 1), eq(2, 3)) (devuelve True, cortocircuitos)

startsWith

• Evalúa si True la cadena del parámetro izquierdo comienza por el parámetro right.
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte parámetros en String para su evaluación
• Realiza la comparación ordinal entre mayúsculas y minúsculas
• Ejemplo: startsWith('ABCDE', 'AB') (devuelve True)

xor

• Evalúa si True exactamente un parámetro es True
• Parámetros mínimos: 2. Parámetros máximos: 2
• Convierte parámetros a booleanos para la evaluación
• Ejemplo: xor(True, False) (devuelve True)

Funciones de comprobación del estado del trabajo

Puede usar las siguientes funciones de comprobación de estado como expresiones en condiciones, pero no en definiciones de variables.

Siempre

• Siempre se evalúa como True (incluso cuando se cancela). Nota: Un error crítico puede impedir que se ejecute una tarea. Por ejemplo, si se ha podido obtener orígenes.

Cancelado

• Se evalúa como True si se canceló la canalización.

con errores

• Para un paso, equivalente a eq(variables['Agent.JobStatus'], 'Failed') .
• Para un trabajo:
  • Sin argumentos, se evalúa como True solo si se ha fallado algún trabajo anterior en el gráfico de dependencias.
  • Con los nombres de trabajo como argumentos, solo se evalúa True como si alguno de esos trabajos genera un error.

Correcto

• Para un paso, equivalente a in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
• Para un trabajo:
  • Sin argumentos, se evalúa como solo si todos los trabajos anteriores del gráfico de dependencias se han hecho correctamente o True parcialmente.
  • Si el trabajo anterior se ha hecho correctamente, pero se ha fallado aún más una dependencia ascendente, succeeded('previousJobName') devolverá true. Si solo usa dependsOn: previousJobName , se producirá un error porque todas las dependencias ascendentes no se han realizado correctamente. Para evaluar solo el trabajo anterior, use succeeded('previousJobName') en una condición.
  • Con los nombres de trabajo como argumentos, se evalúa como si todos esos trabajos se han hecho correctamente o True parcialmente.
  • Se evalúa como False si se cancela la canalización.

succeededOrFailed

• Para un paso, equivalente a in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

• Para un trabajo:

  • Sin argumentos, se evalúa como independientemente de si los trabajos del gráfico de dependencias se True han hecho correctamente o no.
  • Con los nombres de trabajo como argumentos, se evalúa si alguno de esos trabajos se True ha hecho correctamente o no.

  Esto es como always() , salvo que se evaluará cuando se False cancele la canalización.

Inserción condicional

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

Los condicionales solo funcionan cuando se usa la sintaxis de plantilla. Obtenga más información sobre la sintaxis de variables.

Para las plantillas, puede usar la inserción condicional al agregar una secuencia o asignación. Obtenga más información sobre la inserción condicional en plantillas.

Asignación condicional de una variable

variables:
  ${{ if eq(variables['Build.SourceBranchName'], 'main') }}: # only works if you have a main branch
    stageName: prod

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo ${{variables.stageName}}

Establecer condicionalmente 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

variables:
  - name: foo
    value: fabrikam # triggers else condition

pool:
  vmImage: 'ubuntu-latest'

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

Each (palabra clave)

Puede usar la palabra each clave para recorrer en bucle 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 }}

Dependencias

Las expresiones pueden usar el contexto de dependencias para hacer referencia a trabajos o fases 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
• Referencia a variables de salida del trabajo anterior en la misma fase
• Referencia a variables de salida de la fase anterior en una fase
• Referencia a variables de salida en un trabajo de una fase anterior de la siguiente fase

Se llama al contexto dependencies para trabajos y fases y funciona de forma muy parecido a las variables. Dentro de un trabajo, si hace referencia a una variable de salida de un trabajo en otra fase, el contexto se denomina stageDependencies .

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

Dependencias de fase a fase

Estructuralmente, el objeto es una asignación de nombres de trabajos dependencies y fases a y resultsoutputs . 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 para dependencies asignar variables o comprobar condiciones en un nivel de fase. En este ejemplo, la fase B se ejecuta si la fase A se ha realizado correctamente o se ha omitido.

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, la fase B depende de una variable de la fase A.

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 dentro de una sola fase, los dependencies datos 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, el trabajo A siempre se omitirá y se ejecutará el trabajo B. Se ejecutará el trabajo C, ya que todas sus dependencias se ejecutan correctamente o se omiten.

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

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

trigger: none

pool:
  vmImage: 'ubuntu-latest'

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, 'Succeeded', 'SucceededWithIssues', '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

stages:
- stage: plan_dev
  jobs:
  - job: terraform_plan_dev
    steps:
    - bash: echo '##vso[task.setvariable variable=terraform_plan_exitcode;isOutput=true]2'
      name: terraform_plan
- stage: apply_dev
  dependsOn: plan_dev
  condition: eq(dependencies.plan_dev.outputs['terraform_plan_dev.terraform_plan.terraform_plan_exitcode'], '2')
  jobs:
  - job: part_b
    steps:
    - bash: echo "BA"

Matrices filtradas

Al funcionar en una colección de elementos, puede usar la * sintaxis para aplicar una matriz filtrada. Una matriz filtrada devuelve todos los objetos o elementos independientemente de sus nombres.

Por ejemplo, considere una matriz de objetos denominada foo . Queremos obtener una matriz de los valores de la id propiedad en cada objeto de la matriz.

[
    { "id": 1, "a": "avalue1"},
    { "id": 2, "a": "avalue2"},
    { "id": 3, "a": "avalue3"}
]

Podríamos hacer lo siguiente:

foo.*.id

Esto indica al sistema que funcione como foo una matriz filtrada y, a continuación, seleccione la id propiedad .

Esto devolvería:

[ 1, 2, 3 ]

Conversión de tipos

Los valores de una expresión se pueden convertir de un tipo a otro a medida que se evalúa la expresión. Cuando se evalúa una expresión, los parámetros se convierten en el tipo de datos pertinente y, a continuación, se convierten en cadenas.

Por ejemplo, en este YAML, los valores y TrueFalse se convierten en y cuando 1 se evalúa la 0 expresión. La función lt() devuelve cuando el parámetro izquierdo es menor que el parámetro True derecho.

variables:
  firstEval: $[lt(False, True)] # 0 vs. 1, True
  secondEval: $[lt(True, False)] # 1 vs. 0, False

steps:
- script: echo $(firstEval)
- script: echo $(secondEval)

En este ejemplo, los valores y variables.emptyString la cadena vacía se evalúan como cadenas vacías. La función evalúa los parámetros en orden y devuelve el primer valor que coalesce() no es igual a null o empty-string.

variables:
  coalesceLiteral: $[coalesce(variables.emptyString, '', 'literal value')]

steps:
- script: echo $(coalesceLiteral) # outputs literal value

A continuación se enumeran las reglas de conversión detalladas.

Boolean

Para numerar:

• False → 0
• True → 1

Para la cadena:

• False → 'False'
• True → 'True'

Null

• A booleano: False
• Para numerar: 0
• To string: '' (la cadena vacía)

Número

• Para booleano: 0 → , cualquier otro número False → True
• Para la versión: debe ser mayor que cero y debe contener un decimal distinto de cero. Debe ser menor que Int32.MaxValue (componente decimal también).
• En cadena: convierte el número en una cadena sin separador de miles ni separador decimal.

String

• Para booleano: '' (la cadena vacía) → False , cualquier otra cadena → True
• Para null: '' (la cadena vacía) → Null , cualquier otra cadena no convertible
• Para numerar: (la cadena vacía) → 0; de lo contrario, ejecuta C# mediante InvariantCulture y las reglas ''Int32.TryParse siguientes: AllowDecimalPoint | '' AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Si TryParse se produce un error, no se puede convertir.
• Para la versión: ejecuta el de Version.TryParse C#. Debe contener como mínimo los componentes Principal y Menor. Si TryParse se produce un error, no se puede convertir.

Version

• A booleano: True
• Para la cadena: Major.Minor, Major.Minor.Build o Major.Minor.Build.Revision.

Preguntas más frecuentes

Quiero hacer algo que no sea compatible con las expresiones. ¿Qué opciones tengo para ampliar Pipelines funcionalidad?

Puede personalizar la canalización con un script que incluya una expresión. Por ejemplo, este fragmento de código BUILD_BUILDNUMBER toma la variable y la divide con Bash. Este script genera dos nuevas variables, $MAJOR_RUN y , para los números de ejecución principales y $MINOR_RUN menores. A continuación, las dos variables se usan para crear dos variables de canalización y $major$minor con $major. Estas variables están disponibles para los pasos de nivel inferior. Para compartir variables entre canalizaciones, vea Grupos de variables.

steps:
- bash: |
    MAJOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f1)
    echo "This is the major run number: $MAJOR_RUN"
    echo "##vso[task.setvariable variable=major]$MAJOR_RUN"

    MINOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f2)
    echo "This is the minor run number: $MINOR_RUN"
    echo "##vso[task.setvariable variable=minor]$MINOR_RUN"

- bash: echo "My pipeline variable for major run is $(major)"
- bash: echo "My pipeline variable for minor run is $(minor)"