Os quatro pacotes .NET

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

Use a versão 0.2.4 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. As chaves são emitidas na área de Aplicações do Maestro: emitir uma exige Echo Pro ou Pro AI e a permissão Echo/ManageHosting, concedida por padrão ao administrador da organização em um plano pago. O feed de regras é GET api/echo/mock/rules no endereço base da API configurado. Sem uma chave, o endpoint retorna 401; com uma chave sem ServeMocks ou sem uma assinatura Echo paga em vigor, retorna 403.

Gapfy.Echo.Contracts

Publica uma versão de um contrato que sua aplicação fornece. Criar e publicar contratos no Maestro está disponível em todos os planos, incluindo o Free; publicar a partir do seu código precisa de uma chave, cuja emissão exige um plano pago. 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.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);

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

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. Este pacote lê o feed de regras, incluído no Echo Pro e Pro AI.

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

As regras estáticas podem responder localmente. As regras em modo contrato seguem para o serviço real. O mesmo acontece sem correspondência ou antes de carregar as primeiras regras. Se a assinatura paga terminar, a atualização do feed falha e o pacote registra um aviso, sem parar sua aplicação. Sem regras em cache, ele deixa de interceptar e as chamadas seguem para o serviço real; regras já salvas podem continuar respondendo até você limpar o cache ou desativar a interceptação. 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. Este pacote lê o mesmo feed pago que o Mock.Client. 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.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();

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. Fica ativo fora de Production por padrão. Production exige a opção explícita EnableInProduction. Se a assinatura paga terminar, o servidor continua iniciando e o pacote registra o aviso de atualização que falhou. Sem regras em cache, deixa passar as requisições para que sua API responda; uma atualização que falha mantém as últimas regras, que podem continuar respondendo até você limpar o cache ou desativar os mocks.

Se uma interceptação deixar de acontecer e a configuração parecer correta, confira o plano do Echo e o escopo ServeMocks da chave antes de procurar o erro no código. O mock no desktop e os contratos no Maestro continuam disponíveis em todos os planos; publicar um mock no serviço público e obter regras para os pacotes .NET fazem parte do Echo Pro e Pro AI.

Escolha o caminho certo