Azure Template Parameters
A VS Code companion to the official Azure Pipelines extension.
It adds parameter IntelliSense, navigation, and conservative validation for local template calls.
Requirements and installation
- VS Code 1.85 or later.
- The official
ms-azure-devops.azure-pipelines extension is a required dependency.
- Pipeline and template files must be accessible to the extension host.
- Explicit workspace language associations, as described below.
This source package is not a Marketplace release: its publisher is currently local.
Existing VSIX files in the development directory may contain older behavior.
For local use, build/package the current source, then use Extensions: Install from VSIX….
Install the official Azure Pipelines extension as well (VS Code can resolve this dependency when online).
Required workspace settings
Create or update .vscode/settings.json in your workspace. The setting is
files.associations, plural, not file.associations:
{
"files.associations": {
"azure-pipelines.yml": "azure-pipelines",
"azure-pipelines.yaml": "azure-pipelines",
"**/stages/*.{yaml,yml}": "azure-pipelines",
"**/jobs/*.{yaml,yml}": "azure-pipelines",
"**/steps/*.{yaml,yml}": "azure-pipelines",
"**/variables/*.{yaml,yml}": "azure-pipelines",
"**/templates/**/*.{yaml,yml}": "azure-pipelines"
}
}
Adapt these patterns to your pipeline folders. Avoid global *.yaml / *.yml
associations: Kubernetes, Compose, and other YAML should remain in their normal
language modes. Check that the editor status bar shows Azure Pipelines.
This extension does not register a language or associate file extensions.
All providers and diagnostics operate only on azure-pipelines, never on
generic yaml. Diagnostics are cleared when a document leaves that mode.
The official extension owns the language, syntax, and structural schema support.
Features
| Feature |
Use |
| Template argument names |
Press Ctrl+Space on a blank, indented line under a template call's parameters:. Existing arguments are omitted. |
| Argument values |
Request completion for values choices and boolean literals. |
| Current document references |
Complete ${{ parameters.NAME }} and ${{ parameters['NAME'] }}, including partial names. |
| Compact hover |
Hover an argument or a current document parameter reference for a YAML signature, short displayName, type/default, allowed values, and a discreet source link. |
| Definitions |
Use F12 on a template path, argument name, or current document parameter reference. |
| Required arguments |
A quick fix inserts example values for missing required arguments in supported block maps or calls without parameters:. |
| Validation |
See the diagnostics table below. |
Reference completion replaces the name, not the surrounding expression.
For bracket completion, type the opening single quote; complete/close the
bracket expression normally. Both complete bracket expressions and unfinished
names are supported. Bracket access supports names that cannot use dot notation.
References inside compile-time function calls and conditional expressions are
also recognized. Plain text, YAML comments, and expression string literals do
not trigger reference navigation.
Example
# jobs/build.yaml
parameters:
- name: APPLICATION
displayName: Application name
type: string
- name: JAVA_VERSION
displayName: Java version
type: number
default: 17
values: [17, 21]
jobs:
- job: Build
steps:
- bash: echo "Build ${{ parameters.APPLICATION }} with Java ${{ parameters.JAVA_VERSION }}"
# azure-pipelines.yaml
jobs:
- template: jobs/build.yaml
parameters:
APPLICATION: my-application
JAVA_VERSION: 21
Template paths resolve relative to the calling file. Leading / resolves from
the containing workspace folder. Resolution also tries appending .yaml and
.yml. Open, unsaved edits to templates are read.
Diagnostics
All diagnostics use the source Azure Template Parameters.
| Code |
Meaning |
template-not-found |
A local template could not be found. |
remote-template |
A repository-qualified reference cannot be resolved locally (informational). |
unknown-parameter |
An argument is not declared by the called template. |
required-parameter-missing |
An argument with no declared default is absent. |
parameter-type-mismatch |
A literal argument does not match the declared type's basic YAML shape. |
parameter-value-not-allowed |
A literal scalar is outside the declared values. |
unused-parameter |
A declaration has no recognized use in its own document. |
Literal validation and expressions
Primitive validation follows Azure scalar conversion: string parameters accept
string, number, and boolean literals; numeric strings are accepted for number
parameters; boolean spellings such as true, false, yes, and no are
accepted. object accepts any YAML structure, including scalars. step, job,
deployment, and stage require maps; their List variants require lists of
maps. stringList checks scalar string-compatible elements. These are shape
checks, not full Azure schema validation; task fields and job/stage internals
remain the official extension's responsibility.
- Compile-time
${{ ... }}, runtime $[ ... ], and macro $(...) values are
dynamic. Type/allowed-value validation is skipped for an argument containing
any such expression, including nested expressions. No type inference is attempted.
${{ if ... }}, ${{ elseif ... }}, and ${{ else }} argument maps are
traversed for literal argument checks, not treated as unknown parameter names.
- Arguments provided in any conditional branch count as potentially supplied.
Conditions are not evaluated and branch completeness is not enforced.
- Whole-map expressions,
${{ insert }}, ${{ each ... }}, YAML aliases, and
other opaque argument-map constructs suppress missing-required warnings when
the supplied names cannot be determined. Known sibling literals are still checked.
- Invalid YAML suppresses template-call validation rather than guessing.
Unused parameters
Usage analysis scans YAML keys and values outside the root parameters
declaration, including conditions, scripts, and forwarding to another template.
Both dot references and single-quoted bracket references count.
Comments, plain text, declaration metadata/defaults, and macro variables do not
count as parameter usage. Passing a value from a caller does not by itself mean
the template uses its declaration.
Invalid YAML, unfinished expressions, aliases, dynamic parameter indexing, and
use of the whole parameters object suppress unused warnings when analysis
cannot determine the used names safely. No automatic removal is provided.
Limitations
- Repository aliases, including
@self, are not resolved. There is no Azure
DevOps download or network lookup.
- Dynamic template paths are not resolved.
- Parameters must use the root list declaration format with
name, optional
type, displayName, default, and scalar values. Legacy map declarations
are not supported.
- No complete Azure expression evaluation, pipeline expansion, schema validation,
or cross-file unused-parameter inference is performed.
- Current document reference completion/navigation supports dot and single-quoted
bracket access, not dynamically computed property names.
- Missing-required checks are conservative and may omit warnings around dynamic
constructs. Complex
values entries are not validated.
- The required-argument quick fix does not handle explicitly empty
parameters:
or flow maps safely. Use a normal block map or add the arguments manually.
- External filesystem changes are not watched directly; reopening/editing/saving
a document refreshes validation. Other extensions may contribute overlapping UI.
Development and packaging
npm ci
npm run compile
npm test
Tests use Node's test runner with a mocked VS Code API; an Extension Development
Host is still needed for a real editor integration smoke test.
To package locally using a compatible Node.js LTS and the VS Code packaging tool:
npx @vscode/vsce package
.vscodeignore excludes source, tests, development dependencies, source maps,
and old VSIX archives, while retaining runtime code/dependencies, this guide,
and the license. Check the package contents before distribution.
For a future Marketplace release, choose a publisher you control, update the
manifest/version and any repository metadata, verify dependencies and package
contents, and test the VSIX in a clean profile. Do not publish under local or
represent this companion as an official Microsoft extension.
Nothing in this repository automatically installs or publishes the extension.
License
MIT — Copyright (c) 2026 Azure Template Parameters contributors.