Les quatre packages .NET

Votre source NuGet configurée doit fournir la version 0.2.2 pour que ces commandes d'installation fonctionnent.

Utilisez la version 0.2.2 pour les exemples ci-dessous. Chacun est un Program.cs complet dans un projet .NET 10 distinct. Les packages incluent aussi des versions pour .NET 8 et .NET 9. Installer un package ne suffit pas à activer les mocks ni à valider les contrats.

Avant d'exécuter un exemple réseau, configurez GAPFY_ECHO_BASE_ADDRESS avec l'adresse de base de votre API Echo, barre finale comprise, et GAPFY_ECHO_API_KEY via l'environnement ou votre coffre de secrets. Utilisez l'adresse de l'API, pas l'URL publique du mock. La version correspondante de l'API doit être déployée : le flux de règles est GET api/echo/mock/rules. Un 404 sur cette route ne signifie pas qu'il n'y a aucune règle.

Gapfy.Echo.Contracts

Publie une version d'un contrat fourni par votre application. Créez d'abord le contrat et sa liaison Provides dans Maestro, créez une clé avec PublishOwnedContracts et définissez GAPFY_ECHO_CONTRACT_ID. Enregistrez un document de contrat Echo de l'éditeur sous orders.echo.json dans le répertoire de travail du processus. Il faut le document Echo, pas une réponse d'exemple ni un JSON Schema non converti.

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);

Le package expose aussi le codec, le validateur et les moteurs d'inférence et d'évaluation des contrats. Le résultat de publication contient Changes avec les verdicts consommateur et fournisseur. Un verdict incompatible décrit une publication déjà terminée ; il ne l'annule pas. Un contenu identique peut renvoyer Created = false avec une version existante.

Gapfy.Echo.Testing

Vérifie les contrats consommés par l'application avec une clé ReadBoundContracts. L'appel lève une exception en cas de changement incompatible ; vous pouvez donc le placer dans votre framework de tests habituel. Cet exemple exige une réponse du service distant au lieu d'autoriser une réussite hors ligne.

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();

Lors de la première exécution locale réussie, le package crée des instantanés EchoContracts à côté du projet. Vérifiez-les et ajoutez-les dans un commit. La CI refuse de créer les instantanés manquants. Sans RequireRemote = true, un service inaccessible peut produire une réussite hors ligne avec les instantanés du dépôt ; le rapport précise ce qui n'a pas été vérifié. Cela ne vérifie ni le contrat distant actuel ni l'API en cours d'exécution. Acceptez les changements d'instantanés volontairement sur un poste de travail, jamais automatiquement en CI.

Gapfy.Echo.Mock.Client

Intercepte les appels sortants uniquement pour les HttpClient créés par la fabrique que vous activez. Cet exemple expose /probe et appelle l'URL réelle de PARTNER_API_URL avec le client activé. Définissez DOTNET_ENVIRONMENT=Development en local et fournissez une clé ServeMocks.

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();

Les règles statiques peuvent répondre localement. Les règles en mode contrat passent au service réel dans la version 0.2.2. Les appels sans correspondance et ceux précédant le premier chargement des règles passent également. Un HttpClient créé manuellement, un canal gRPC ou un SDK avec son propre transport n'est pas intercepté. Le package ne peut pas être activé dans Production ou Prod ; les autres environnements hors Development exigent une confirmation explicite.

Gapfy.Echo.Mock.Server

Ajoute un middleware de mocks à votre API ASP.NET Core avec une clé ServeMocks. Ici, /health reste un endpoint réel. Les routes que votre API n'implémente pas encore peuvent répondre à partir des règles Echo. Placez le middleware après le routage et avant l'exécution des endpoints, comme dans cet exemple avec WebApplication.

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();

Le middleware laisse passer les routes implémentées et les requêtes sans correspondance. Il sert les corps enregistrés et remplace les paramètres de chemin ; il n'évalue pas le document de génération de contrats dans la version 0.2.2. Il s'active hors Production par défaut. Production exige l'option explicite EnableInProduction. Sans règles chargées, il laisse passer les requêtes ; un échec d'actualisation conserve les dernières règles en cache.

Choisir la bonne voie