Azure Pipelines YAML has three expression syntaxes — ${{ }}, $[ ] and $( ). When is each evaluated, and what breaks if you pick the wrong one?

## Three clocks, not three styles The reason Azure Pipelines has three token forms is that a pipeline is processed in three distinct phases, and each syntax belongs to one of them. | Syntax | Name | Evaluated | Can it change the YAML shape? | |---|---|---|---| | `${{ }}` | template expression | at compile time, before scheduling | yes | | `$[ ]` | runtime expression | at stage/job start | no | | `$( )` | macro syntax | just before the task runs | no | ## `${{ }}` — compile time When a run is queued, Azure first *expands* the YAML: it pulls in templates, substitutes parameters and evaluates every `${{ }}`. The result is a fully-materialised pipeline document; only then is anything scheduled onto an agent. Because this happens before execution, `${{ }}` is the only syntax that can decide whether a block of YAML exists at all: ```yaml parameters: - name: runIntegration type: boolean default: false steps: - script: npm test - ${{ if eq(parameters.runIntegration, true) }}: - script: npm run test:integration ``` With `${{ if }}`, the skipped step is not *skipped* — it is **absent** from the expanded pipeline, so it never appears in the run at all. The same applies to `${{ each }}`, which generates repeated blocks from an `object` parameter, and `${{ insert }}`, which merges a mapping in. What `${{ }}` cannot see is anything that does not exist yet: a variable a script set during the run, a job's output, or a secret from a Key Vault-linked group. Reading those with `${{ }}` does not error loudly — it resolves to the compile-time value, or to an empty string, and the pipeline carries on with the wrong data. That silence is what makes this the platform's most common trap. ## `$[ ]` — runtime A runtime expression is evaluated when the run actually reaches the stage or job that owns it, so it can read state produced earlier in the same run. It has a strict placement rule: **it must be the entire right-hand side of the value**, not embedded in a larger string. ```yaml variables: buildNumber: $[ counter('release', 1) ] gitSha: $[ dependencies.Build.outputs['setVars.sha'] ] ``` `$[ 'v' ]-suffix` is invalid; wrap concatenation in `format()` instead. One place you never type the brackets is `condition:` — that field is already a runtime-expression context, so you write `condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')` bare. ## `$( )` — macro substitution Macro syntax is not really an expression language; it is the agent doing find-and-replace on task inputs and script bodies immediately before the task executes. It is what you use for ordinary variable interpolation: ```yaml steps: - script: echo "building $(Build.BuildId) on $(Agent.OS)" - task: PublishPipelineArtifact@1 inputs: artifact: app-$(Build.BuildId) ``` Two behaviours matter. First, macros resolve *late*, so `$(myVar)` correctly picks up a value a previous step set with `echo "##vso[task.setvariable variable=myVar]abc"`. Second, an **undefined** macro is not an error: the literal text `$(notSet)` is passed through to the task unchanged, which surfaces as a bizarre filename or a URL with a dollar sign in it rather than a clean failure. ## The failure this actually causes ```yaml steps: - script: echo "##vso[task.setvariable variable=tag]$(git rev-parse --short HEAD)" - script: echo "deploying ${{ variables.tag }}" # empty — compile time - script: echo "deploying $(tag)" # correct — runtime ``` The second step prints nothing useful. `${{ variables.tag }}` was resolved during expansion, minutes before the first step ran, so there was no such variable to read. The same shape of bug appears when someone tries to pass a runtime value into a template parameter: template parameters are consumed at compile time, so a runtime value can never reach one. If a decision genuinely depends on runtime state, it has to be expressed as a `condition:` on a step, job or stage — not as a `${{ if }}`. ## Secrets and precedence Secret variables are deliberately unavailable to `${{ }}`; they exist only at runtime, and only as `$(name)` in task inputs or as values you map explicitly into a script's environment. Any design that needs a secret to *shape* the pipeline is a design that needs rethinking, because the shape is fixed before the secret is fetched. A practical rule of thumb: use `${{ }}` for anything derived from `parameters`, `$[ ]` when you need a value computed earlier in the same run, and `$( )` everywhere else inside steps.