Os quatro pacotes .NET

A fonte NuGet configurada precisa disponibilizar a versão 0.2.2 para estes comandos de instalação funcionarem.

Use a versão 0.2.2 nos exemplos abaixo. Cada exemplo é um Program.cs completo em um projeto .NET 10 separado. Os pacotes também incluem versões para .NET 8 e .NET 9. Instalar um pacote, por si só, não ativa mocks nem valida contratos.

Antes de executar um exemplo com rede, configure GAPFY_ECHO_BASE_ADDRESS com o endereço base da API do Echo, incluindo a barra final, e GAPFY_ECHO_API_KEY pelo ambiente ou pelo cofre de segredos. Use o endereço da API, não a URL pública do mock. A versão correspondente da API precisa estar publicada: o feed de regras é GET api/echo/mock/rules. Um 404 nessa rota não significa que não existam regras.

Gapfy.Echo.Contracts

Publica uma versão de um contrato que sua aplicação fornece. Primeiro crie o contrato e o vínculo Provides no Maestro, emita uma chave com PublishOwnedContracts e defina GAPFY_ECHO_CONTRACT_ID. Salve um documento de contrato Echo do editor como orders.echo.json na pasta de trabalho do processo. Precisa ser o documento Echo, não uma resposta de exemplo nem um JSON Schema sem conversão.

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

O pacote também oferece o codec, o validador e os mecanismos de inferência e avaliação de contratos. O resultado da publicação inclui Changes, com avaliações para consumidor e fornecedor. Uma avaliação incompatível descreve uma publicação já concluída; não a desfaz. Conteúdo idêntico pode devolver Created = false com uma versão existente.

Gapfy.Echo.Testing

Verifica os contratos consumidos pela aplicação com uma chave ReadBoundContracts. A chamada lança uma exceção quando encontra uma alteração incompatível, então você pode usá-la no seu framework de testes. Este exemplo exige resposta do serviço remoto em vez de permitir um resultado positivo offline.

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

Na primeira execução local com sucesso, o pacote cria retratos EchoContracts junto ao projeto. Revise-os e inclua-os em um commit. O CI se recusa a criar retratos ausentes. Sem RequireRemote = true, um serviço inacessível pode produzir um resultado positivo offline com os retratos do repositório; o relatório explica o que não foi verificado. Isso não verifica o contrato remoto de hoje nem a API em execução. Aceite alterações nos retratos deliberadamente em uma máquina de trabalho, nunca automaticamente no CI.

Gapfy.Echo.Mock.Client

Intercepta chamadas de saída apenas nos HttpClient criados pela factory que você ativar. O exemplo expõe /probe e chama a URL real de PARTNER_API_URL pelo cliente ativado. Defina DOTNET_ENVIRONMENT=Development para uso local e forneça uma chave 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();

As regras estáticas podem responder localmente. As regras em modo contrato seguem para o serviço real na versão 0.2.2. O mesmo acontece sem correspondência ou antes de carregar as primeiras regras. Um HttpClient criado manualmente, um canal gRPC ou um SDK com transporte próprio não é interceptado. O pacote não pode ser ativado em Production ou Prod; outros ambientes fora de Development exigem confirmação explícita.

Gapfy.Echo.Mock.Server

Adiciona middleware de mocks à sua API ASP.NET Core com uma chave ServeMocks. Neste exemplo, /health continua sendo um endpoint real. As rotas ainda não implementadas pela API podem responder com regras do Echo. Coloque o middleware depois do roteamento e antes da execução dos endpoints, como neste exemplo com 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();

O middleware deixa passar rotas implementadas e requisições sem correspondência. Serve os corpos de resposta salvos e substituições de parâmetros do caminho; não avalia o documento de geração de contratos na versão 0.2.2. Fica ativo fora de Production por padrão. Production exige a opção explícita EnableInProduction. Sem regras carregadas, deixa passar as requisições; uma atualização que falha mantém as últimas regras em cache.

Escolha o caminho certo