Table of Contents

Class DevopsExpressionPrinter

Namespace
Invex.StructuredText.AzureDevopsPipelines
Assembly
Invex.StructuredText.AzureDevopsPipelines.dll

Renders typed expressions (Expr) and Templates to Azure DevOps syntax. Operators are functions (and(...), or(...), not(...), eq(...), …) and status checks are succeeded(), failed(), canceled() and always().

public sealed class DevopsExpressionPrinter : ExpressionPrinter
Inheritance
object
DevopsExpressionPrinter
Inherited Members

Remarks

Inside a Template, secrets, variables, matrix values and step outputs are written as macros ($(name)). Expressions that depend on other jobs (job outputs, job results) or contain a DevopsRuntimeExpr are runtime expressions ($[ … ]), and everything else is a template expression (${{ … }}).

Combinations Azure DevOps can't evaluate throw System.NotSupportedException: a runtime expression combined with text or other expressions (Azure DevOps only evaluates one that is the whole value), an input read in a runtime expression or condition (parameters only exist at compile time), and a secret, matrix value or step output inside a compound compile-time expression (they only exist at run time). Bind the value to a variable and reference it with Variable(string) instead.

Inside an expression, secrets, variables and matrix values are variables['name'], inputs are parameters.name, job outputs are dependencies.JOB.outputs['STEP.NAME'] and job results are dependencies.JOB.result.

Constructors

DevopsExpressionPrinter()

public DevopsExpressionPrinter()

Properties

Instance

A shared instance. The printer is stateless.

public static DevopsExpressionPrinter Instance { get; }

Property Value

DevopsExpressionPrinter

Methods

FunctionName(string)

Maps a canonical function name (see FunctionNames) to the platform's name. Returns the name unchanged by default.

protected override string FunctionName(string name)

Parameters

name string

The canonical name.

Returns

string

The platform's name.

PrintCall(string, IReadOnlyList<Expr>)

Renders a function call. Writes FunctionName(string) followed by the arguments in order by default; platforms whose functions take arguments in a different order override this.

protected override string PrintCall(string name, IReadOnlyList<Expr> arguments)

Parameters

name string

The canonical function name (see FunctionNames).

arguments IReadOnlyList<Expr>

The arguments, in canonical order.

Returns

string

The rendered call.

Remarks

Azure DevOps's join takes the separator first and requires it, so the arguments are swapped and a missing separator becomes ','.

PrintComparison(ComparisonExpr)

Renders a comparison. Uses infix operators (==, !=, <, …) by default.

protected override (string Text, int Precedence) PrintComparison(ComparisonExpr comparison)

Parameters

comparison ComparisonExpr

The comparison.

Returns

(string Text, int Precedence)

The rendered text and its precedence.

PrintCondition(BoolExpr)

Renders a condition: value. Azure DevOps evaluates conditions at run time, so they are written without delimiters.

public string PrintCondition(BoolExpr condition)

Parameters

condition BoolExpr

The condition.

Returns

string

The rendered condition.

Exceptions

NotSupportedException

Thrown when the condition reads an input (a parameter).

PrintLogical(LogicalExpr)

Renders an AND or OR. Uses infix && and || by default.

protected override (string Text, int Precedence) PrintLogical(LogicalExpr logical)

Parameters

logical LogicalExpr

The logical expression.

Returns

(string Text, int Precedence)

The rendered text and its precedence.

PrintMember(string)

Renders a property access suffix: .name where valid, otherwise ['name'] with quotes escaped.

protected override string PrintMember(string name)

Parameters

name string

The property name.

Returns

string

The suffix to append to the target.

Remarks

Azure DevOps identifiers can't contain -, so names that aren't letters, digits and _ use ['name'].

PrintNot(NotExpr)

Renders a negation. Uses prefix ! by default.

protected override (string Text, int Precedence) PrintNot(NotExpr not)

Parameters

not NotExpr

The negation.

Returns

(string Text, int Precedence)

The rendered text and its precedence.

PrintOther(Expr)

Renders a node the base class doesn't know, such as a platform-specific node. Throws System.NotSupportedException by default.

protected override (string Text, int Precedence) PrintOther(Expr expression)

Parameters

expression Expr

The node.

Returns

(string Text, int Precedence)

The rendered text and its precedence.

PrintReference(ReferenceExpr)

Renders a portable reference such as a secret or a job output.

protected override string PrintReference(ReferenceExpr reference)

Parameters

reference ReferenceExpr

The reference.

Returns

string

The rendered text.

PrintResult(RunResult)

Renders a run result literal.

protected override string PrintResult(RunResult result)

Parameters

result RunResult

The result.

Returns

string

The rendered text.

Render(Template)

Renders template: literal text as-is, embedded expressions wrapped with WrapEmbedded(string).

public override string Render(Template template)

Parameters

template Template

The template.

Returns

string

The rendered text.

Exceptions

NotSupportedException

Thrown when the template contains an expression, or a combination of expressions and text, the platform can't express.

RenderEmbedded(Expr)

Renders an expression embedded in a Template. By default it is printed and wrapped with WrapEmbedded(string); platforms with several embedding syntaxes override this.

protected override string RenderEmbedded(Expr expression)

Parameters

expression Expr

The embedded expression.

Returns

string

The rendered text.

WrapEmbedded(string)

Wraps a rendered expression that is embedded in literal text, e.g. in expression delimiters.

protected override string WrapEmbedded(string printedExpression)

Parameters

printedExpression string

The rendered expression.

Returns

string

The wrapped text.