Architecture
This page explains how the three packages fit together and the design decisions behind them. Useful if you want to extend the library, contribute, or build your own generator on top of the core.
Package layering
┌─────────────────────────────────┐ ┌──────────────────────────────────────┐
│ Invex.StructuredText │ │ Invex.StructuredText │
│ .GithubActions │ │ .AzureDevopsPipelines │
│ │ │ │
│ • GithubActionWriter │ │ • DevopsPipelineWriter │
│ • DependabotConfigWriter │ │ • DevopsExpressionPrinter │
│ • GithubExpressionPrinter │ │ • Tex.DevOps (DevopsContexts) │
│ • Tex.GitHub (GitHubContexts) │ │ • DevopsRuntimeExpr │
│ • GithubActionModel/* │ │ • DevopsPipelineModel/* │
│ • DependabotConfigModel/* │ │ │
└───────────────┬─────────────────┘ └──────────────────┬───────────────────┘
│ │
└───────────────────┬───────────────────┘
▼
┌─────────────────────────────────────┐
│ Invex.StructuredText (core) │
│ │
│ • StructuredTextWriter │
│ • Tex (the expression entry point) │
│ • Expr, BoolExpr, StringExpr, … │
│ • Template │
│ • ExpressionPrinter (base) │
└─────────────────────────────────────┘
Core (Invex.StructuredText)
StructuredTextWriter
A minimal, indentation-aware text writer. WriteSection returns an IDisposable scope that decrements the indent on
dispose, so the structure of the generating C# code mirrors the structure of the generated YAML. A version counter
makes stale scopes harmless after Reset(). See StructuredTextWriter.
The expression tree
Expr is an abstract record with four typed roots: BoolExpr, StringExpr, NumberExpr and JsonExpr. The result
type decides which operations the compiler offers, so If = Tex.GitHub.Ref (a string) does not compile. The concrete
nodes are grouped by concern:
- Literals:
StringLiteral,NumberLiteral,BoolLiteral,NullLiteral, created implicitly from C# literals - Context paths:
StringContext,BoolContext,NumberContext,JsonContext, used by the generated catalogues such asTex.GitHub - Access and casts:
MemberAccessExpr,IndexAccessExpr,StringCast,BoolCast,NumberCast - Logic:
ComparisonExpr,LogicalExpr(flattened, soa && b && cis one node),NotExpr - Functions:
BoolFunction,StringFunction,JsonFunction, named with the constants inFunctionNames - References:
SecretRef,VariableRef,InputRef,MatrixRef,StepOutputRef,JobOutputRef,JobResultRefandResultLiteral, which each platform spells its own way - Raw text:
RawExprand its typed siblings, for theTex.Rawescape hatch
Because they are records, expressions compare structurally, and DescendantsAndSelf() walks the tree. Atom uses that
to find the jobs a condition depends on.
Tex is the single entry point that creates them. Platform packages and libraries add members to it with C# 14
extension(Tex) blocks, which is how Tex.GitHub, Tex.DevOps and Atom's Tex.ParamOutput appear on the same type.
Template
Template is a sequence of literal text and embedded expressions. It is an interpolated string handler, so
$"v{Tex.GitHub.RunNumber}" builds one directly, and it converts implicitly from string, Expr, bool and numbers.
Every model property that can hold an expression, other than conditions, is a Template.
ExpressionPrinter
The abstract printer renders an Expr (Print) or a Template (Render). The base class handles operator
precedence (adding parentheses only where needed), literal quoting and escaping, member and index access, casts and
raw text. A platform printer supplies what differs:
WrapEmbedded: the delimiters around an expression inside a template, such as${{ … }}.PrintReferenceandPrintResult: how references and job results are spelled.- Optional overrides:
FunctionName,PrintComparison,PrintLogical,PrintNot,RenderEmbeddedand others. Azure DevOps overrides the logic members to printand(…),eq(…), andRenderEmbeddedto choose between$(…),${{ … }}and$[ … ].
A node a printer can't express throws NotSupportedException rather than producing invalid YAML.
Platform packages
Each platform package contains:
- Model types — records that mirror the official YAML schema for the platform. Conditions are
BoolExpr, and almost every other scalar property is aTemplate, so any value can contain expressions. - A writer — walks the model and emits YAML through a
StructuredTextWriter, calling the platform expression printer for every expression-valued property. - An expression printer —
GithubExpressionPrinterorDevopsExpressionPrinter, anExpressionPrinterfor the platform's syntax. - A context catalogue —
Tex.GitHuborTex.DevOps. The GitHub catalogue is generated at build time fromContexts/github.contextsbyInvex.StructuredText.Generators.
GitHub Actions (Invex.StructuredText.GithubActions)
GithubActionWriter— serializes aGithubActionmodel to workflow YAML.DependabotConfigWriter— serializes aDependabotConfigmodel todependabot.yml.GithubExpressionPrinter— prints expressions using GitHub's syntax, and${{ }}inside templates.- Model types — strongly-typed records for all GitHub Actions concepts (triggers, jobs, steps, matrix, permissions,
etc.) in
GithubActionModel, and for Dependabot inDependabotConfigModel.Model.
Azure DevOps Pipelines (Invex.StructuredText.AzureDevopsPipelines)
DevopsPipelineWriter— serializes aDevopsPipelinemodel to pipeline YAML.DevopsExpressionPrinter— prints expressions using Azure DevOps syntax.DevopsRuntimeExpr— created byTex.DevOps.Runtime(…), embeds an expression as a$[ … ]runtime expression.- Model types — strongly-typed records and unions for pipelines, stages, jobs, steps, resources, triggers,
variables, deployment strategies, and more, under
DevopsPipelineModel.*.
Discriminated unions
YAML schemas are full of "one of" shapes (a step is run: or uses:; a pool is a name or a spec). These are
modeled as discriminated unions using the Dunet source generator: an abstract
base record with nested variant records. You construct the variant you need (new Step.RunStep { ... }), and the
writers pattern-match on the variant to emit the right YAML shape. This rules out invalid combinations at compile
time.
Schema fidelity
The GitHub workflow JSON schema and Dependabot v2 JSON schema are checked into the source tree alongside the models, and the Azure DevOps models carry XML docs lifted from the official YAML schema reference. Property names map mechanically to YAML keys (PascalCase → kebab-case / camelCase as appropriate per platform).
Public API discipline
The libraries use:
[PublicAPI]annotations (JetBrains.Annotations) on all public surface- Public API surface snapshot tests (
PublicApiSurfaceTestswith verified.txtbaselines in each test project), so any accidental API change shows up as a test diff - Targets .NET 10 and .NET 11
Extending the library
| Goal | How |
|---|---|
| New target platform | Reference the core, define model records, write an ExpressionPrinter subclass and a writer over StructuredTextWriter |
New Tex member |
Add an extension(Tex) block in your package, returning existing node types where you can |
| New context in the GitHub catalogue | Add a line to Contexts/github.contexts; the generator adds the member and its XML docs |
| Platform-specific expression syntax | Follow the pattern of DevopsRuntimeExpr: define the record in the platform package and print it in that platform's printer (PrintOther or RenderEmbedded) |
See also
- StructuredTextWriter: the writer every generator is built on
- Expressions: writing your own printer
- FAQ: common questions about the model design
- StructuredTextWriter, Tex, Expr, ExpressionPrinter