Les quatre packages .NET

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

Utilisez la version 0.2.4 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. Les nouvelles clés se créent dans Applications de Maestro, fonction d'Echo Pro et Pro AI qui nécessite Echo/ManageHosting ; l'administrateur de l'organisation reçoit cette autorisation par défaut avec un forfait payant et peut l'attribuer à un autre rôle. Le flux de règles est GET api/echo/mock/rules sur l'adresse de base configurée. Sans clé, l'endpoint renvoie 401. Il renvoie 403 si la clé n'a pas le scope ServeMocks ou si l'organisation n'a pas d'abonnement Echo payant en vigueur.

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

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

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. Récupérer les règles fait partie d'Echo Pro et Pro AI ; un mock sur le bureau dans Free n'a pas besoin de ce package.

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

Les règles statiques peuvent répondre localement. Les règles en mode contrat passent au service réel. Les appels sans correspondance et ceux précédant le premier chargement des règles passent également. Si l'organisation perd le forfait payant, l'actualisation des règles renvoie 403 et écrit un avertissement, mais l'application continue à fonctionner. Les règles déjà chargées, y compris depuis une copie locale, peuvent continuer à intercepter ; sans règles, les appels passent au service réel. 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. Récupérer les règles fait partie d'Echo Pro et Pro AI. 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.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();

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. Il s'active hors Production par défaut. Production exige l'option explicite EnableInProduction. Si l'organisation perd le forfait payant, l'actualisation des règles renvoie 403 et écrit un avertissement sans empêcher le démarrage de l'API. Sans règles chargées, les routes suivent leur comportement habituel ; des règles déjà chargées ou conservées en cache peuvent continuer à fournir des réponses simulées.

Si l'interception cesse de fonctionner alors que la configuration semble correcte, vérifiez l'abonnement Echo de votre organisation et le scope ServeMocks avant de chercher une erreur dans votre code. Créer et essayer des mocks sur le bureau et travailler avec des contrats dans Maestro reste compris dans Free ; publier sur le service public et charger les règles pour ces deux packages nécessite Echo Pro ou Pro AI.

Choisir la bonne voie