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
-
objectDevopsExpressionPrinter
- 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
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
namestringThe 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
namestringThe canonical function name (see FunctionNames).
argumentsIReadOnlyList<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
comparisonComparisonExprThe 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
conditionBoolExprThe 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
logicalLogicalExprThe 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
namestringThe 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
notNotExprThe 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
expressionExprThe 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
referenceReferenceExprThe reference.
Returns
- string
The rendered text.
PrintResult(RunResult)
Renders a run result literal.
protected override string PrintResult(RunResult result)
Parameters
resultRunResultThe 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
templateTemplateThe 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
expressionExprThe 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
printedExpressionstringThe rendered expression.
Returns
- string
The wrapped text.