Table of Contents

Introduction

Invex.StructuredText is a family of strongly-typed C# libraries for generating structured YAML text files — specifically GitHub Actions workflows, Dependabot configurations, and Azure DevOps Pipelines. This page explains why you would generate CI/CD YAML from C#, when the library is (and is not) a good fit, and the concepts the rest of the documentation builds on.

Why generate YAML from C#?

CI/CD configuration files grow quickly. Hand-written YAML suffers from:

  • No compile-time validation — typos in keys, indentation mistakes, and invalid values are only discovered when the pipeline runs (or fails to parse).
  • No refactoring support — renaming a job, output, or variable means find-and-replace across files and hoping you caught every reference.
  • Duplication — YAML has limited reuse mechanisms, so common patterns get copy-pasted between workflows.
  • Stringly-typed expressions — ${{ }} and $( ) expressions are opaque strings to your editor.

Invex.StructuredText solves these problems by letting you define your pipelines as C# object graphs:

  • Full IntelliSense and compile-time validation for every property
  • Models closely follow the official schemas (GitHub workflow schema, Dependabot v2 schema, Azure Pipelines YAML schema)
  • Typed expressions written with C# operators and interpolated strings, printed as GitHub's ${{ }} syntax or Azure DevOps macro, template and runtime syntax
  • Deterministic, cleanly formatted YAML output that is easy to diff and review

When to use it

Invex.StructuredText is a good fit when:

  • You maintain several workflows or pipelines that share jobs, steps, or conventions, and want to reuse them with ordinary C# functions and constants.
  • You maintain many repositories and want their CI configuration generated from one shared definition.
  • You already have a C# build tool (for example an _atom/ or _build/ console project) that can regenerate the files and check them in.
  • Expressions are getting complicated, and you want conditions and output references checked by the compiler instead of discovered at run time.

It is not the right tool when:

  • You need to read or modify existing YAML. The library is write-only; it does not parse workflow files.
  • You have one small workflow. Writing the YAML by hand is simpler than adding a generator project.
  • You target another CI system. Only GitHub Actions, Dependabot, and Azure DevOps Pipelines have models, although the core writer and expression system can be used to build your own (see Architecture).

Key concepts at a glance

Concept What it is
Model An object graph of records rooted at GithubAction, DependabotConfig, or DevopsPipeline.
Union variant Schema "one of" shapes (a step is run: or uses:) are discriminated unions; construct the nested variant you need, such as new Step.RunStep { ... }.
Writer GithubActionWriter, DependabotConfigWriter, or DevopsPipelineWriter walks a model and emits YAML.
StructuredTextWriter The indentation-aware buffer every writer writes into; read the result with writer.TextWriter.ToString(). See StructuredTextWriter.
Tex The single entry point for expressions: Tex holds references (Tex.Secret, Tex.JobOutput, …), status checks, functions, and the platform contexts Tex.GitHub and Tex.DevOps. See Expressions.
Expression A typed tree (BoolExpr, StringExpr, NumberExpr, JsonExpr) that a platform printer writes in that platform's syntax. Conditions are BoolExpr.
Template Text with expressions embedded in it. Every other expression-capable property is a Template, created from a string or an interpolated string.

Design principles

  • Model the schema, not a DSL. Model records mirror the official YAML schemas and their property names map mechanically to YAML keys, so platform documentation applies directly.
  • Invalid shapes do not compile. Discriminated unions rule out combinations the schema forbids, and required properties force a decision on schema-significant values, even when that decision is null.
  • Write once, render per platform. Expressions are platform-agnostic trees; only the printer knows the target syntax.
  • Typed where it matters. Conditions must be BoolExpr, and each expression type offers only the operations that make sense for it, so mistakes show up as compile errors.
  • Deterministic and write-only. The same model always produces the same text, so you can regenerate in CI and fail on git diff --exit-code.
  • Small, composable layers. Platform packages are built on a core writer and expression system that you can reuse for your own generators.

The packages

Package What it provides
Invex.StructuredText The core: StructuredTextWriter (indentation-aware text writer) and the expression API (Tex)
Invex.StructuredText.GithubActions GithubActionWriter, DependabotConfigWriter, GithubExpressionPrinter, Tex.GitHub, and model types
Invex.StructuredText.AzureDevopsPipelines DevopsPipelineWriter, DevopsExpressionPrinter, Tex.DevOps, and model types

Both platform packages depend on the core package, so installing either one gives you everything you need.

Next steps