Los cuatro paquetes .NET

La fuente NuGet configurada debe ofrecer la versión 0.2.2 para que funcionen estos comandos de instalación.

Usa la versión 0.2.2 en los siguientes ejemplos. Cada uno es un Program.cs completo en un proyecto .NET 10 independiente. Los paquetes también incluyen versiones para .NET 8 y .NET 9. Instalar un paquete por sí solo no activa mocks ni valida contratos.

Antes de ejecutar un ejemplo con red, configura GAPFY_ECHO_BASE_ADDRESS con la dirección base de tu API Echo, incluida la barra final, y GAPFY_ECHO_API_KEY mediante el entorno o tu almacén de secretos. Usa la dirección de la API, no la URL pública del mock. Debe estar desplegada la versión correspondiente de la API: el feed de reglas es GET api/echo/mock/rules. Un 404 en esa ruta no significa que no haya reglas.

Gapfy.Echo.Contracts

Publica una versión de un contrato que ofrece tu aplicación. Primero crea el contrato y su vínculo Provides en Maestro, emite una clave con PublishOwnedContracts y define GAPFY_ECHO_CONTRACT_ID. Guarda un documento de contrato Echo del editor como orders.echo.json en el directorio de trabajo del proceso. Debe ser el documento Echo, no una respuesta de ejemplo ni un JSON Schema sin convertir.

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

El paquete también ofrece el códec, el validador y los motores de inferencia y evaluación de contratos. El resultado de publicación incluye Changes con evaluaciones de consumidor y proveedor. Una evaluación incompatible describe una publicación ya completada; no la deshace. Un contenido idéntico puede devolver Created = false con una versión existente.

Gapfy.Echo.Testing

Comprueba los contratos consumidos por la aplicación con una clave ReadBoundContracts. La llamada lanza una excepción si encuentra un cambio incompatible, por lo que puedes usarla en tu framework de pruebas. Este ejemplo exige que responda el servicio remoto en vez de permitir un resultado positivo sin conexión.

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

En la primera ejecución local correcta, el paquete crea instantáneas EchoContracts junto al proyecto. Revísalas e inclúyelas en un commit. El CI se niega a crear instantáneas que falten. Sin RequireRemote = true, un servicio inaccesible puede producir un resultado positivo sin conexión usando las instantáneas del repositorio; el informe explica qué no se comprobó. Esto no verifica el contrato remoto actual ni la API en ejecución. Acepta cambios en las instantáneas de forma deliberada en una estación de trabajo, nunca automáticamente en CI.

Gapfy.Echo.Mock.Client

Intercepta llamadas salientes solo en los HttpClient creados por la factoría que actives. Este ejemplo expone /probe y llama a la URL real de PARTNER_API_URL mediante el cliente activado. Define DOTNET_ENVIRONMENT=Development para uso local y proporciona una clave 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();

Las reglas estáticas pueden responder localmente. Las reglas en modo contrato pasan al servicio real en 0.2.2. También pasan las llamadas sin coincidencia y las anteriores a la primera carga de reglas. No intercepta un HttpClient creado manualmente, un canal gRPC ni un SDK con transporte propio. El paquete no puede activarse en Production ni Prod; otros entornos fuera de Development requieren una aceptación explícita.

Gapfy.Echo.Mock.Server

Añade middleware de mocks a tu API ASP.NET Core con una clave ServeMocks. En este ejemplo, /health sigue siendo un endpoint real. Las rutas que la API todavía no implementa pueden responder mediante reglas de Echo. Coloca el middleware después del enrutamiento y antes de ejecutar los endpoints, como en este ejemplo con 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();

El middleware deja pasar las rutas implementadas y las solicitudes sin coincidencia. Sirve los cuerpos guardados y sustituye parámetros de ruta; no evalúa el documento de generación de contratos en 0.2.2. Se activa fuera de Production por defecto. Production exige la opción explícita EnableInProduction. Sin reglas cargadas, deja pasar las solicitudes; si una actualización falla, conserva las últimas reglas en caché.

Elige la vía adecuada