Die vier .NET-Pakete

Deine konfigurierte NuGet-Quelle muss Version 0.2.2 bereitstellen, damit diese Installationsbefehle funktionieren.

Verwende für diese Beispiele die Version 0.2.2. Jedes Beispiel ist eine vollständige Program.cs in einem eigenen .NET-10-Projekt. Die Pakete enthalten auch Versionen für .NET 8 und .NET 9. Die Installation allein aktiviert keine Mocks und prüft keine Verträge.

Bevor du ein Netzwerkbeispiel ausführst, setze GAPFY_ECHO_BASE_ADDRESS auf die Basisadresse deiner Echo-API einschließlich abschließendem Schrägstrich und GAPFY_ECHO_API_KEY über die Umgebung oder deinen Secret-Speicher. Verwende die API-Adresse, nicht die öffentliche Mock-URL. Die passende API-Version muss bereitgestellt sein. Der Regelfeed lautet GET api/echo/mock/rules. Ein 404 dort bedeutet nicht, dass keine Regeln vorhanden sind.

Gapfy.Echo.Contracts

Veröffentlicht eine Version eines Vertrags, den deine Anwendung anbietet. Erstelle zuerst den Vertrag und seine Provides-Bindung in Maestro, erstelle einen Schlüssel mit PublishOwnedContracts und setze GAPFY_ECHO_CONTRACT_ID. Speichere ein Echo-Vertragsdokument aus dem Editor als orders.echo.json im Arbeitsverzeichnis des Prozesses. Es muss das Echo-Dokument sein, keine Beispielantwort und kein unkonvertiertes JSON Schema.

dotnet new console -n EchoContractsDemo -f net10.0
dotnet add EchoContractsDemo package Gapfy.Echo.Contracts --version 0.2.2

using System.Net.Http.Headers;
using Gapfy.Echo.Contracts;

string Required(string name) =>
    Environment.GetEnvironmentVariable(name)
    ?? throw new InvalidOperationException($"Set {name}.");

using var http = new HttpClient
{
    BaseAddress = new Uri(Required("GAPFY_ECHO_BASE_ADDRESS"))
};
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Required("GAPFY_ECHO_API_KEY"));

var publisher = new EchoContractPublicationClient(http);
var documentJson = await File.ReadAllTextAsync("orders.echo.json");
var publication = await publisher.PublishAsync(
    Guid.Parse(Required("GAPFY_ECHO_CONTRACT_ID")), documentJson);

Console.WriteLine(publication.AssignedVersion.Version);
Console.WriteLine(publication.Created);

Das Paket stellt auch den Codec, den Validator sowie die Inferenz- und Auswertungsmodule für Verträge bereit. Das Veröffentlichungsergebnis enthält Changes mit Bewertungen für Verbraucher und Anbieter. Eine inkompatible Bewertung beschreibt eine bereits abgeschlossene Veröffentlichung und macht sie nicht rückgängig. Identischer Inhalt kann Created = false mit einer vorhandenen Version zurückgeben.

Gapfy.Echo.Testing

Prüft die von der Anwendung konsumierten Verträge mit einem ReadBoundContracts-Schlüssel. Bei einer inkompatiblen Änderung wirft der Aufruf eine Ausnahme. Du kannst ihn daher in deinem bestehenden Testframework verwenden. Dieses Beispiel verlangt eine Antwort des entfernten Dienstes und erlaubt keinen erfolgreichen Offline-Lauf.

dotnet new console -n EchoTestingDemo -f net10.0
dotnet add EchoTestingDemo package Gapfy.Echo.Testing --version 0.2.2

using Gapfy.Echo.Testing;

var echo = GapfyEchoValidation.Create(new GapfyEchoValidationOptions
{
    RequireRemote = true
});

await echo.Contracts.ValidateAsync();

Beim ersten erfolgreichen lokalen Lauf erstellt das Paket EchoContracts-Momentaufnahmen neben dem Projekt. Prüfe sie und nimm sie in einen Commit auf. Die CI erstellt keine fehlenden Momentaufnahmen. Ohne RequireRemote = true kann ein unerreichbarer Dienst zu einem erfolgreichen Offline-Lauf mit den gespeicherten Momentaufnahmen führen. Der Bericht erklärt, was nicht geprüft wurde. Das prüft weder den heutigen entfernten Vertrag noch die laufende API. Akzeptiere Änderungen bewusst auf einem Arbeitsplatzrechner, nie automatisch in der CI.

Gapfy.Echo.Mock.Client

Fängt ausgehende Aufrufe nur für ausdrücklich aktivierte HttpClient-Instanzen aus der Factory ab. Dieses Beispiel stellt /probe bereit und ruft die echte URL aus PARTNER_API_URL über den aktivierten Client auf. Setze für lokale Nutzung DOTNET_ENVIRONMENT=Development und hinterlege einen ServeMocks-Schlüssel.

dotnet new web -n EchoMockClientDemo -f net10.0
dotnet add EchoMockClientDemo package Gapfy.Echo.Mock.Client --version 0.2.2

using Gapfy.Echo.Mock.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEchoMock(x =>
{
    x.ApiKey = builder.Configuration["GAPFY_ECHO_API_KEY"];
    x.RuleServiceUri = new Uri(
        builder.Configuration["GAPFY_ECHO_BASE_ADDRESS"]
        ?? throw new InvalidOperationException("Set GAPFY_ECHO_BASE_ADDRESS."));
});
builder.Services.AddHttpClient("partner").AddEchoMockInterception();

var app = builder.Build();

app.MapGet("/probe", async (IHttpClientFactory factory) =>
{
    var target = app.Configuration["PARTNER_API_URL"]
        ?? throw new InvalidOperationException("Set PARTNER_API_URL.");
    return await factory.CreateClient("partner").GetStringAsync(target);
});

app.Run();

Statische Regeln können lokal antworten. Regeln im Vertragsmodus gehen in Version 0.2.2 an den echten Dienst weiter. Das gilt auch bei fehlenden Treffern und vor dem ersten Laden der Regeln. Manuell erstellte HttpClient-Instanzen, gRPC-Kanäle und SDKs mit eigenem Transport werden nicht abgefangen. In Production und Prod lässt sich das Paket nicht aktivieren. Andere Umgebungen außerhalb von Development verlangen eine ausdrückliche Bestätigung.

Gapfy.Echo.Mock.Server

Ergänzt deine ASP.NET-Core-API um Mock-Middleware mit einem ServeMocks-Schlüssel. Im Beispiel bleibt /health ein echter Endpunkt. Noch nicht implementierte Routen können anhand passender Echo-Regeln antworten. Platziere die Middleware nach dem Routing und vor der Endpunktausführung, wie hier mit WebApplication gezeigt.

dotnet new web -n EchoMockServerDemo -f net10.0
dotnet add EchoMockServerDemo package Gapfy.Echo.Mock.Server --version 0.2.2

using Gapfy.Echo.Mock.Server;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEchoMock(x =>
{
    x.ApiKey = builder.Configuration["GAPFY_ECHO_API_KEY"];
    x.BaseAddress = new Uri(
        builder.Configuration["GAPFY_ECHO_BASE_ADDRESS"]
        ?? throw new InvalidOperationException("Set GAPFY_ECHO_BASE_ADDRESS."));
});

var app = builder.Build();

app.MapEchoMock();
app.MapGet("/health", () => Results.Ok(new { status = "ok" }));

app.Run();

Die Middleware lässt implementierte Routen und Anfragen ohne Treffer weiterlaufen. Sie liefert gespeicherte Antworttexte mit Pfadparameter-Ersetzungen. Das Dokument zur Vertragsgenerierung wertet sie in Version 0.2.2 nicht aus. Außerhalb von Production ist sie standardmäßig aktiv. Production verlangt die ausdrückliche Option EnableInProduction. Ohne geladene Regeln lässt sie Anfragen durch. Fehlgeschlagene Aktualisierungen behalten die zuletzt gespeicherten Regeln.

Wähle den passenden Weg