Invex.StructuredText 2.0.0

Invex.StructuredText

A strongly-typed C# library for generating structured YAML text files, specifically GitHub Actions workflows, Dependabot configurations, and Azure DevOps Pipelines, using a fluent, type-safe API with a powerful expression system.

Packages

Features

• Type-safe workflow authoring. Define CI/CD pipelines as C# objects with full IntelliSense and compile-time validation.
• Unified expression system. Build conditions, string interpolation and function calls once and render them to each platform's syntax.
• GitHub Actions. Generate workflows with triggers, jobs, steps, matrix strategies, permissions, concurrency, containers, and more.
• Dependabot. Generate dependabot.yml configurations with registries, update rules, groups, and schedules.
• Azure DevOps Pipelines. Generate pipelines with stages, jobs, deployment strategies (runOnce, rolling, canary), resources, templates, and parameters.
• Deterministic output. The same model always produces the same text, so generated files diff cleanly.

Installation

dotnet add package Invex.StructuredText.GithubActions
# or
dotnet add package Invex.StructuredText.AzureDevopsPipelines

Both platform packages depend on Invex.StructuredText core, so it will be installed automatically. All three packages target net10.0. The platform packages also depend on the Dunet source generator, which provides their discriminated-union model types.

Quick start

using Invex.StructuredText.Expressions;
using Invex.StructuredText.GithubActions;
using Invex.StructuredText.GithubActions.GithubActionModel;

var workflow = new GithubAction
{
    Name = "CI",
    On =
    [
        new On.Push
        {
            Branches = ["main"],
            BranchesIgnore = null,
            Tags = null,
            TagsIgnore = null,
            Paths = null,
            PathsIgnore = null,
        },
    ],
    Jobs =
    [
        new Job
        {
            Name = new RawExpression("build"),
            RunsOn = new() { Labels = [new RawExpression("ubuntu-latest")] },
            Steps =
            [
                new Step.UsesStep
                {
                    Name = new RawExpression("Checkout"),
                    Uses = new RawExpression("actions/checkout@v4"),
                },
                new Step.RunStep
                {
                    Name = new RawExpression("Build"),
                    Run = ["dotnet build --configuration Release"],
                },
            ],
        },
    ],
};

var writer = new GithubActionWriter();
writer.Write(workflow);

File.WriteAllText(".github/workflows/ci.yml", writer.TextWriter.ToString());

Usage

Azure DevOps Pipelines

var pipeline = new DevopsPipeline.DevopsPipelineWithSteps
{
    Trigger = new Trigger.BranchList { Branches = ["main"] },
    Steps =
    [
        new Step.Script { ScriptContent = new RawExpression("echo Hello, world!") },
    ],
};

var writer = new DevopsPipelineWriter();
writer.Write(pipeline);

var yaml = writer.TextWriter.ToString();

See Azure DevOps Pipelines.

Dependabot

var config = new DependabotConfig
{
    Updates =
    [
        new DependabotUpdate
        {
            PackageEcosystem = PackageEcosystem.Nuget.ToYamlValue(),
            Directory = "/",
            Schedule = new() { Interval = ScheduleInterval.Weekly },
        },
    ],
};

var writer = new DependabotConfigWriter();
writer.WriteConfig(config);

var yaml = writer.TextWriter.ToString();

See Dependabot Configuration.

Expressions

The expression system provides a fluent API for building platform-specific expressions that are formatted differently depending on the target (GitHub Actions uses ${{ }} syntax, Azure DevOps uses its own macro/runtime expression syntax).

// Reference step outputs
var output = new StepOutputExpression
{
    StepName = "build-step",
    OutputName = "artifact-path",
};

// Use conditions
var condition = output.Contains("release").Evaluate();

// String interpolation with format expressions
var formatted = TextExpressions.Format($"Release-{output}");

// Logic operators
var combined = output.Contains("main") & new BooleanExpression(true);

See Expressions.

Generating files as part of your build

A small console project in your repository can regenerate every workflow file; commit the output and the diff shows exactly what changed. Use a fresh writer per file, or call writer.TextWriter.Reset() between documents. See Getting Started.

Documentation

Full documentation: https://invex-games.github.io/structured-text/

Development

The repository requires the .NET 10 SDK selected by global.json:

dotnet build Invex.StructuredText.slnx
dotnet test Invex.StructuredText.slnx

Build and preview the documentation site with the Atom build:

atom BuildDocs
atom ServeDocs

See .github/copilot-instructions.md for repository structure, code conventions, and contributor guidance.

License

This project is licensed under the MIT License.