Azure DevOps Pipelines
The Invex.StructuredText.AzureDevopsPipelines package generates Azure Pipelines YAML from a strongly-typed model
rooted at DevopsPipeline (namespace Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.*). Read this
page when you generate Azure Pipelines: pipeline shapes, triggers, steps, pools, variables, deployment jobs, and
Azure DevOps expression syntax.
var writer = new DevopsPipelineWriter();
writer.Write(pipeline);
var yaml = writer.TextWriter.ToString();
The four pipeline shapes
Azure Pipelines YAML allows four top-level shapes, and DevopsPipeline is a union over exactly those four:
| Variant | YAML shape |
|---|---|
DevopsPipelineWithSteps |
steps: at the root (implicit single job) |
DevopsPipelineWithJobs |
jobs: at the root (implicit single stage) |
DevopsPipelineWithStages |
stages: — the full multi-stage syntax |
DevopsPipelineWithExtends |
extends: — extend a pipeline template |
All four share the common pipeline-level properties: Name (run number format), Trigger, Pr, Schedules,
Parameters, Pool, Variables, resources, LockBehavior, and AppendCommitMessageToRunName.
Steps pipeline
var pipeline = new DevopsPipeline.DevopsPipelineWithSteps
{
Pool = new Pool.PoolSpec { VmImage = "ubuntu-latest" },
Trigger = new Trigger.BranchList { Branches = ["main"] },
Steps =
[
new Step.Script { ScriptContent = "echo hello" },
],
};
trigger:
branches:
include: [ main ]
pool:
vmImage: ubuntu-latest
steps:
- script: echo hello
Jobs pipeline
var pipeline = new DevopsPipeline.DevopsPipelineWithJobs
{
Jobs =
[
new Job.RegularJob
{
JobId = "build",
DisplayName = "Build",
Pool = new Pool.PoolSpec { VmImage = "ubuntu-latest" },
Steps =
[
new Step.Script { ScriptContent = "dotnet build" },
],
},
new Job.RegularJob
{
JobId = "test",
DependsOn = ["build"],
Condition = Tex.Success(),
Steps =
[
new Step.Script { ScriptContent = "dotnet test" },
],
},
],
};
Stages pipeline
var pipeline = new DevopsPipeline.DevopsPipelineWithStages
{
Stages =
[
new Stage.StageDefinition
{
StageId = "Build",
Jobs = [ /* Job.RegularJob ... */ ],
},
new Stage.StageDefinition
{
StageId = "Deploy",
DependsOn = ["Build"],
Condition = Tex.Success(),
Jobs = [ /* deployment jobs ... */ ],
},
],
};
Extends pipeline
var pipeline = new DevopsPipeline.DevopsPipelineWithExtends
{
Extends = new Extends
{
Template = "pipeline-template.yml@templates",
Parameters = new Dictionary<string, Template>
{
["configuration"] = "Release",
},
},
};
Triggers
// CI trigger: branch list
Trigger = new Trigger.BranchList { Branches = ["main", "release/*"] },
// CI trigger: full control
Trigger = new Trigger.Full
{
Batch = true,
Branches = new IncludeExcludeFilters
{
Include = ["main"],
Exclude = ["experimental/*"],
},
Paths = new IncludeExcludeFilters { Include = ["src/*"] },
},
// Disable CI triggers entirely
Trigger = new Trigger.None(),
Pr (pull-request triggers) and Schedules (cron triggers) follow the same pattern with their own union/record
types.
Steps
Step is a union over the twelve Azure Pipelines step kinds:
| Variant | YAML key | Required property |
|---|---|---|
Task |
task: |
TaskName (+ Inputs) |
Script |
script: |
ScriptContent |
Bash |
bash: |
ScriptContent |
PowerShell |
powershell: |
ScriptContent |
Pwsh |
pwsh: |
ScriptContent |
Checkout |
checkout: |
Repository |
Download |
download: |
Pipeline |
DownloadBuild |
downloadBuild: |
Build |
GetPackage |
getPackage: |
Package |
Publish |
publish: |
PublishPath |
Template |
template: |
TemplatePath |
ReviewApp |
reviewApp: |
ReviewAppType |
All script/task-like steps share the common properties DisplayName, Name, Condition, ContinueOnError,
Enabled, Env, Target, TimeoutInMinutes, and RetryCountOnTaskFailure.
Steps =
[
new Step.Checkout
{
Repository = "self",
FetchDepth = 0,
Lfs = true,
},
new Step.Task
{
TaskName = "UseDotNet@2",
DisplayName = "Install .NET SDK",
Inputs = new Dictionary<string, Template>
{
["packageType"] = "sdk",
["version"] = "10.0.x",
},
},
new Step.Script
{
ScriptContent = "dotnet build -c Release",
DisplayName = "Build",
Env = new Dictionary<string, Template>
{
["DOTNET_NOLOGO"] = "true",
},
},
new Step.Publish
{
PublishPath = Tex.DevOps.Build.ArtifactStagingDirectory,
Artifact = "drop",
Condition = Tex.Always(),
},
],
Pools
// Microsoft-hosted image
Pool = new Pool.PoolSpec { VmImage = "ubuntu-latest" },
// Named (self-hosted) pool
Pool = new Pool.PoolName { Name = "Default" },
Variables
Variables is a union supporting both YAML syntaxes:
// Mapping syntax: name/value pairs
Variables = new Variables.Dictionary
{
Values = new Dictionary<string, Template>
{
["buildConfiguration"] = "Release",
},
},
// List syntax: named variables, groups, and templates
Variables = new Variables.VariableList
{
Values =
[
new Variable.Name
{
VariableName = "buildConfiguration",
Value = "Release",
ReadOnly = true,
},
new Variable.Group { GroupName = "shared-secrets" },
new Variable.Template { TemplatePath = "variables/common.yml" },
],
},
Reference variables in steps with Tex.Variable, which is written in macro syntax:
new Step.Script
{
ScriptContent = $"dotnet build -c {Tex.Variable("buildConfiguration")}", // dotnet build -c $(buildConfiguration)
}
Deployment jobs and strategies
Deployment jobs (Job.Deployment) target an environment and require a DeploymentStrategy — a union over RunOnce,
Rolling, and Canary, each with lifecycle hooks (PreDeploy, Deploy, RouteTraffic, PostRouteTraffic,
OnSuccess, OnFailure):
new Job.Deployment
{
DeploymentId = "deploy_prod",
DisplayName = "Deploy to production",
Environment = new DeploymentEnvironment.EnvironmentName
{
Name = "production",
},
Strategy = new DeploymentStrategy.RunOnce
{
Deploy = new DeploymentHook
{
Steps =
[
new Step.Script { ScriptContent = "./deploy.sh" },
],
},
OnFailure = new DeploymentHook
{
Steps =
[
new Step.Script { ScriptContent = "./rollback.sh" },
],
},
},
}
Rolling deployments add MaxParallel; canary deployments require Increments (e.g. [10, 20, 70]).
Resources
PipelineResources / Resources lets you declare repositories, pipelines, builds, containers, packages, and
webhooks used by the pipeline — each modeled with its own strongly-typed record under
DevopsPipelineModel.Resources.
Templates and parameters
- Job, stage, step, and variable lists each have a
Templatevariant for referencing template files withParameters. - Pipeline-level
Parametersdefine runtime parameters for the pipeline (or template parameters when authoring templates).
Expressions in Azure DevOps
Azure DevOps uses the same expression API as GitHub Actions (see Expressions), printed with
DevopsExpressionPrinter. Conditions use the function-style syntax:
| C# | Output |
|---|---|
a && b |
and(a, b) |
a \|\| b |
or(a, b) |
!a |
not(a) |
a.Eq("x"), a.Ne("x") |
eq(a, 'x'), ne(a, 'x') |
n.Lt(1), n.Le(1), n.Gt(1), n.Ge(1) |
lt(n, 1), le(n, 1), gt(n, 1), ge(n, 1) |
a.Contains("x") |
contains(a, 'x') |
Tex.Success(), Tex.Failure(), Tex.Cancelled(), Tex.Always() |
succeeded(), failed(), canceled(), always() |
Tex.JobResult("build").Eq(Tex.Result(RunResult.Success)) |
eq(dependencies.build.result, 'Succeeded') |
Condition = Tex.DevOps.Build.SourceBranch.Eq("refs/heads/main") && !Tex.DevOps.Build.Reason.Eq("PullRequest"),
// condition: and(eq(variables['Build.SourceBranch'], 'refs/heads/main'), not(eq(variables['Build.Reason'], 'PullRequest')))
Inside a template, each kind of value is embedded with the syntax Azure DevOps expects for it:
| C# | Embedded as |
|---|---|
Tex.Variable("x"), Tex.Secret("x"), Tex.Matrix("x") |
$(x) (macro) |
Tex.StepOutput("step", "out") |
$(step.out) (macro) |
Tex.Input("x") |
${{ parameters.x }} (template expression) |
Tex.JobOutput("job", "out", "step") |
$[ dependencies.job.outputs['step.out'] ] (runtime expression) |
Tex.DevOps.Runtime(expression) |
$[ expression ] (runtime expression) |
| Any expression that reads a job output or job result | $[ expression ] (runtime expression) |
| Any other expression | ${{ expression }} (template expression) |
Important
The printer throws NotSupportedException for combinations Azure DevOps can't evaluate, rather than writing YAML
that silently misbehaves:
- A runtime expression combined with text, such as
$"v{Tex.JobOutput("Setup", "version", "Info")}". Azure DevOps only evaluates$[ … ]when it is the whole value. - An input (
Tex.Input) in a condition or a runtime expression. Parameters only exist at compile time. - A secret, matrix value or step output inside a compound expression such as
Tex.Format(...), which would be a compile-time${{ … }}. Interpolate them directly as macros, or wrap the expression inTex.DevOps.Runtime.
In each case, bind the value to a variable and use Tex.Variable("name").
Tex.DevOps lists the common predefined variables, such as Tex.DevOps.Build.SourceBranch,
Tex.DevOps.Build.BuildId, Tex.DevOps.System.AccessToken, Tex.DevOps.Agent.Os and
Tex.DevOps.PipelineWorkspace. Use Tex.Variable("Name") for any other variable.
Variables = new Variables.Dictionary
{
Values = new Dictionary<string, Template>
{
// isMain: $[ eq(variables['Build.SourceBranch'], 'refs/heads/main') ]
["isMain"] = Tex.DevOps.Runtime(Tex.DevOps.Build.SourceBranch.Eq("refs/heads/main")),
},
},
Note
Azure DevOps has no fromJSON, so Tex.FromJson throws NotSupportedException here. ToJson() prints
convertToJson(...), Join puts the separator first (join(',', items)), and array membership (value.In(items),
items.Contains(value)) prints containsValue(items, value).
See also
- Getting Started: your first pipeline
- Expressions: the expression API shared with GitHub Actions
- The model closely follows the Azure Pipelines YAML schema — property names and XML docs mirror the official documentation.
- DevopsPipeline, DevopsPipelineWriter, DevopsExpressionPrinter