BinaryWrapper v2: Versioned CLI Contracts and Typed Output📋

BinaryWrapper connects versioned command-line interfaces to generated C# commands, typed environments and observable process execution. This series follows the implementation from help acquisition and build-time source generation to stdout/stderr parsing, versioned output contracts and consumer libraries.

This series documents the locally inspected implementation on 2 October 2026. “v2” names this architectural iteration; it does not assert a NuGet release numbered 2.0. Vagrant provides the main walkthrough; ten executable wrappers and a separate GitLab CI YAML schema consumer illustrate the shared mechanisms and their limits.

Start with a concrete execution📋

A generated command is a value you can inspect before running anything. Its environment is another typed value. The runner then turns process lines into observations with a producing channel, parser profile and version.

The following complete offline example references Vagrant, BinaryWrapper and BinaryWrapper.Testing. It feeds synthetic, source-shaped output to the real executor and Vagrant parser. It starts no VM.

using FrenchExDev.Net.BinaryWrapper;
using FrenchExDev.Net.BinaryWrapper.Lib;
using FrenchExDev.Net.BinaryWrapper.Testing;
using FrenchExDev.Net.Vagrant;

var version = SemanticVersion.Parse("2.4.9");
var binding = new BinaryBinding
{
    Identifier = new BinaryIdentifier("vagrant"),
    ExecutablePath = "vagrant",
    DetectedVersion = version,
};
var command = new VagrantUpCommand(version)
{
    MachineReadable = true,
    Environment = new VagrantEnvironment { Home = "example/.vagrant.d" },
};
var transport = new FakeProcessRunner([
    new OutputLine(
        "1700000000,web,ui,output,Machine booted and ready!",
        OutputSource.StdOut),
    new OutputLine("provider diagnostic", OutputSource.StdErr),
]);
IVagrantRunner runner = new VagrantRunner(
    new CommandExecutor(new DictionaryBinaryResolver(binding), transport),
    binding.Identifier);

Console.WriteLine(string.Join(" | ", command.ToArguments()));
await foreach (var observation in runner.StreamAsync(command))
{
    if (observation is VagrantMachineBooted ready)
        Console.WriteLine($"Communicator ready: {ready.MachineName}");
    if (observation.OutputLine is { } line)
        Console.WriteLine($"{line.Source}: {line.Text}");
    if (observation is VagrantCommandExited exited)
        Console.WriteLine($"Process exit: {exited.ExitCode}");
}
var result = await runner.ExecuteAsync(command, new VagrantUpCollector());
Console.WriteLine(result.Match(
    onSuccess: value => $"Ready machines: {value.MachinesReady.Count}",
    onFailure: error => error.ToString()));

The command emits --machine-readable and serializes Home as VAGRANT_HOME. A boot observation means that Vagrant's communicator readiness step reported completion. The zero process exit is a separate fact. The collector receives the same kinds of events in a second simulated execution, using a fresh parser.

Replace the transport with a real process runner only when you intend to execute an installed tool. Supplying DetectedVersion is metadata; it does not install that version or switch executables.

The system map📋

The architecture has three different times, each with its own inputs and failures.

The architecture chapter explains package ownership. Build-time generation distinguishes Roslyn-generated code from the maintenance-generated Vagrant message catalogue. Typed output follows both stdout and stderr through decoding.

Five reading paths📋

Choose a path according to the decision you need to make. These are ordered routes through shared chapters, with no separate versions of the technical explanation.

Chapters and concepts📋

Each chapter starts with its practical question, then develops the implementation and its limits.

The implementation subtree contains one detailed study for each of the ten executable wrappers and a separate GitLab CI YAML schema-collection study.

Keep four compatibility questions separate📋

A wrapper can know how to construct a command while having no reviewed semantic parser for its output. Its environment can introduce another compatibility boundary.

The examples preserve raw evidence and explicitly separate observations from success. The resulting consumer API keeps invocation values, protocol assumptions and execution evidence inspectable.

Source snapshot📋

Source inspection: 2 October 2026. These implementation paths are relative to Net/FrenchExDev in the local ecosystem checkout. The v2 changes are largely uncommitted; these paths identify inspected code, without claiming that public branch links contain it.

• BinaryWrapper/doc/ARCHITECTURE.md
• BinaryWrapper/doc/CONSUMER-MIGRATION.md

Start with the scope · Explore implementations · Read the v1 article