Die vier .NET-Pakete

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

Verwende für diese Beispiele die Version 0.2.4. 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. Schlüssel werden unter Anwendungen in Maestro ausgestellt. Dazu brauchst du Echo Pro oder Pro AI und die Berechtigung Echo/ManageHosting, die der Organisationsadministrator in einem bezahlten Tarif standardmäßig erhält und einer anderen Rolle geben kann. Der Regelfeed liegt unter GET api/echo/mock/rules auf der konfigurierten API-Basisadresse. Ohne Schlüssel antwortet der Endpunkt mit 401; ohne den erforderlichen Scope ServeMocks oder ohne gültigen bezahlten Echo-Tarif mit 403.

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.4

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.4

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. Das Laden der Mock-Regeln gehört zu Echo Pro und Pro AI. Ohne erfolgreich geladene Regeln fängt der Client nichts ab und ruft den echten Dienst auf; eine verweigerte Aktualisierung beendet deine Anwendung nicht.

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

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 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. Der Regelfeed gehört auch hier zu Echo Pro und Pro AI. 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. Ohne geladene Regeln startet deine API weiterhin und bearbeitet die Routen wie ohne Mock-Middleware.

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

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 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.

Wenn die Interception bei richtiger Konfiguration ausbleibt, prüfe zuerst den Echo-Tarif deiner Organisation und den Scope des Schlüssels. Im Free-Tarif lässt sich kein neuer Anwendungsschlüssel ausstellen, und der Regelfeed verweigert auch einem zuvor ausgestellten Schlüssel den Zugriff. Mock.Client protokolliert den fehlgeschlagenen Abruf als Warnung, Mock.Server als Fehler; beide Anwendungen laufen weiter. Achtung: Bereits geladene oder auf dem Datenträger gespeicherte Regeln können weiterhin Mock-Antworten liefern, bis du den jeweiligen Cache leerst oder die Interception deaktivierst. Mocks auf dem Desktop und die Arbeit mit Verträgen in Maestro bleiben in Free verfügbar.

Wähle den passenden Weg