Vouchfx.Sdk 1.0.0-alpha.10

Vouchfx.Sdk

The compile-time provider SDK for authoring vouchfx step providers. This package is the frozen v1 contract (v1.x engine series) — the narrow, strongly-typed surface a provider compiles against.

Install this package if you are writing a new vouchfx step provider. If you only need to author and run .e2e.yaml suites, install the vouchfx CLI tool instead — Vouchfx.Sdk is for provider authors, not test authors.

vouchfx compiles declarative .e2e.yaml integration tests into C#, runs them through Roslyn, and orchestrates the required container topology with .NET Aspire + Testcontainers to test distributed .NET systems end-to-end — one business transaction crossing a REST call, a Kafka event, a DB mutation and an outbound webhook.

What this package gives you

A step provider is a compile-time, source-level plugin — there is no runtime loader, no dynamic assembly loading, and no sandbox. You add a project, reference Vouchfx.Sdk, implement the contract interfaces, and mark your provider class [StepProvider]; the engine's reflective StepKindRegistry (frozen at startup) discovers it.

The contract surface exposed by this package:

Quick start

using Vouchfx.Sdk;

[StepProvider]
public sealed class MyProvider : IStepProvider
{
    public StepKindId Kind => new("db-assert", "postgres");

    public ProviderMetadata Metadata => new(
        Version: "1.0.0",
        MinEngineVersion: "1.0.0",
        License: "Apache-2.0",
        Authors: new[] { "you" });
}

Then implement IStepBinder<TModel>, IStepValidator<TModel>, IStepCompiler<TModel>, and (if the step needs infrastructure) IResourceContributor<TModel> for your model.

Authoring rules that matter

• Step type = <family>.<provider> — family is the intent (db-assert), provider is the technology (postgres).
• Models are strongly-typed records, never Dictionary<string,object>.
• CsxFragment composition: RequiredUsings are bare namespace strings (never inline using lines); RequiredHelpers are nested static classes prefixed with your provider id; the StatementBlock is exactly one brace-enclosed C# block. using var is illegal in a Roslyn script body — use plain var + explicit .Dispose() in a finally. Sanitise step ids with CsxFragment.SanitiseId before splicing.
• Cross-step state passes only through the Vars global.

The v1 interface contract is frozen for the v1.x engine series — evolution is additive only, via new optional interfaces.

Status

Ships as 1.0.0-alpha.x pre-releases ahead of v1.0 GA. When available on NuGet.org, install with dotnet add package Vouchfx.Sdk --prerelease. Pre-release version numbers do not affect the contract guarantee above: the frozen v1 interfaces are stable now, for the whole v1.x series.

Contributing a provider

The authoritative provider-authoring guide is the provider architecture section (§13) of the Technical Architecture and Engineering Blueprint, alongside the CONTRIBUTING guide in the repository:

• Provider architecture (§13): docs/01_Technical_Architecture_and_Engineering_Blueprint.md
• Contributing guide: CONTRIBUTING.md

Licence

Apache-2.0. See LICENSE.