Los cuatro paquetes .NET

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

Usa la versión 0.2.4 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. Las claves nuevas se emiten en Aplicaciones de Maestro, una función de Echo Pro y Pro AI que requiere Echo/ManageHosting; el administrador de la organización recibe este permiso por defecto con un plan de pago y puede concedérselo a otro rol. El feed de reglas es GET api/echo/mock/rules en la dirección base configurada. Sin una clave, el endpoint devuelve 401. Devuelve 403 si la clave no tiene ServeMocks o si la organización no tiene una suscripción Echo de pago en vigor.

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

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

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. Obtener las reglas forma parte de Echo Pro y Pro AI; un mock del escritorio en Free no necesita este paquete.

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

Las reglas estáticas pueden responder localmente. Las reglas en modo contrato pasan al servicio real. También pasan las llamadas sin coincidencia y las anteriores a la primera carga de reglas. Si se pierde el plan de pago, la actualización de reglas devuelve 403 y escribe un aviso, pero la aplicación sigue funcionando. Las reglas ya cargadas, incluso desde una copia local, pueden seguir interceptando; sin reglas, las llamadas pasan al servicio real. 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. Obtener las reglas forma parte de Echo Pro y Pro AI. 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.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();

El middleware deja pasar las rutas implementadas y las peticiones sin coincidencia. Sirve los cuerpos guardados y sustituye parámetros de ruta; no evalúa el documento de generación de contratos. Se activa fuera de Production por defecto. Production exige la opción explícita EnableInProduction. Si se pierde el plan de pago, la actualización de reglas devuelve 403 y escribe un aviso sin impedir que arranque la API. Sin reglas cargadas, las rutas siguen su comportamiento normal; si ya hay reglas cargadas o guardadas en caché, pueden seguir respondiendo por mock.

Si la interceptación deja de funcionar y la configuración parece correcta, comprueba la suscripción Echo de tu organización y el scope ServeMocks antes de buscar un fallo en tu código. Crear y probar mocks en el escritorio y trabajar con contratos en Maestro sigue incluido en Free; publicar en el servicio público y cargar reglas para estos dos paquetes requiere Echo Pro o Pro AI.

Elige la vía adecuada