Os sete pacotes .NET

Os sete pacotes abaixo estão disponíveis no NuGet.org na versão 0.2.10. Mantenha as versões alinhadas em cada aplicação.

Os exemplos das bibliotecas usam 0.2.10 em projetos .NET 10 e também atendem .NET 8 e .NET 9. A ferramenta echo-mock exige .NET 10. 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.10

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

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.

Use CheckAsync() quando precisar do relatório sem uma exceção, ou Only("partner-orders") para verificar vínculos selecionados. Uma seleção desconhecida falha em vez de verificar nada. Depois da revisão em uma estação de trabalho, AcceptAsync("partner-orders") atualiza uma referência e AcceptAllAsync() atualiza todas; o CI recusa essa aceitação. Ative TreatWarningsAsErrors para tratar avisos como falhas e informe UnmappedMemberHandlingDisallow ou ExhaustiveStatusHandling quando essas condições se aplicarem ao consumidor.

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

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

Regras estáticas e de contrato podem responder dentro da sua aplicação. As respostas de contrato são geradas pelo Gapfy.Echo.Contracts e aceitam X-Echo-Scenario e X-Echo-Seed. Um contrato ausente ou inválido, ou uma falha de geração, retorna 502 application/problem+json sem chamar o serviço real. Chamadas sem correspondência ou feitas antes do primeiro carregamento das regras seguem para o serviço real. 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.10

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

Rotas implementadas e requisições sem correspondência seguem para sua API. Regras estáticas devolvem corpos salvos; regras de contrato geram respostas a partir do documento. Use X-Echo-Scenario para escolher um cenário salvo e X-Echo-Seed para repetir os valores gerados. Um contrato inválido ou uma falha de geração retorna 502 em vez de chamar o código real. Mock.Server fica ativo fora de Production por padrão; Production exige a opção explícita EnableInProduction. Sem regras carregadas, as requisições seguem normalmente. Uma atualização que falha mantém as últimas regras em cache.

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.

Gapfy.Echo.ApiExplorer

Adiciona o Echo API Explorer à sua aplicação ASP.NET Core. Consulte endpoints HTTP e descrições OpenAPI, prepare uma requisição e examine a resposta dentro da própria aplicação. Você pode escolher respostas reais ou mocks do Echo por controller ou endpoint, inclusive para operações já implementadas.

dotnet new web -n EchoExplorerDemo -f net10.0
dotnet add EchoExplorerDemo package Gapfy.Echo.ApiExplorer --version 0.2.10

using Gapfy.Echo.ApiExplorer;
using Microsoft.AspNetCore.Authentication.Cookies;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication("Application")
    .AddCookie("Application", x => x.LoginPath = "/account/login");
builder.Services.AddAuthorization(x =>
{
    x.AddPolicy("Echo.View", x => x.RequireAuthenticatedUser()
        .RequireRole("EchoViewer", "EchoDeveloper", "EchoAdministrator"));
    x.AddPolicy("Echo.Execute", x => x.RequireAuthenticatedUser()
        .RequireRole("EchoDeveloper", "EchoAdministrator"));
    x.AddPolicy("Echo.Session", x => x.RequireAuthenticatedUser()
        .RequireRole("EchoDeveloper", "EchoAdministrator"));
    x.AddPolicy("Echo.Instance", x => x.RequireAuthenticatedUser()
        .RequireRole("EchoAdministrator"));
});
builder.Services.AddEchoDeveloperUI(builder.Configuration.GetSection("Echo"), x =>
{
    x.ApplicationName = "Orders.API";
    x.UI.RoutePrefix = "/tools/echo";
    x.UI.ManageSessionPolicy = "Echo.Session";
    x.UI.ManageInstancePolicy = "Echo.Instance";
});

var app = builder.Build();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEchoDeveloperUI();
app.MapEchoDeveloperUI();
app.MapGet("/api/orders", () => Results.Ok(new[] { new { id = 1 } }))
    .RequireAuthorization()
    .WithEchoMocking();
app.Run();

Este exemplo contém o registro completo. Ele espera que a rota de login da sua aplicação, /account/login, emita o cookie Application com os papéis necessários. Conecte o registro à autenticação e às permissões existentes; o pacote não cria contas nem concede acesso. Configure Echo:ApiBaseAddress e Echo:ApiKey no seu provedor de configuração protegido, usando uma chave ServeMocks. Depois de entrar, abra /tools/echo no endereço da aplicação. O host decide em quais ambientes habilitar o painel. Mantenha a autorização de negócio antes de UseEchoDeveloperUI; endpoints Minimal API precisam de WithEchoMocking().

Escolha o alcance antes de aplicar

  1. Comece por Minha sessão para experimentar pelo seu executor do painel. Outros clientes continuam usando o perfil da instância.
  2. Escolha um controller ou endpoint, selecione o servidor mock e a rota e escolha um cenário, quando houver. A escolha do endpoint prevalece sobre a do controller; a herança usa a escolha superior.
  3. Aplique o perfil, envie uma requisição pelo executor e examine o resultado. Selecionar um servidor ou trocar de aba não aplica o rascunho.
  4. Escolha Toda a instância quando a mudança precisar afetar todos os clientes daquela instância. Isso exige permissão de gerenciamento da instância e confirmação do perfil pendente.

Perfis pessoais expiram e ficam inválidos quando a configuração de referência da instância muda. Recarregue e revise o novo estado quando solicitado. Se o mock selecionado estiver indisponível, o Echo mostra um erro, sem executar o código real silenciosamente. A autenticação e os filtros anteriores ao handler continuam valendo; o código dentro do handler substituído não é executado.

O executor aceita parâmetros, headers, corpos e credenciais. Entrar no painel e autenticar a requisição são ações separadas. O host pode habilitar login OpenID Connect pelo navegador ou uma sessão Bearer curta usando sua validação de tokens existente; são alternativas. Tokens de sessão ficam na memória do servidor, expiram e são perdidos ao reiniciar. O login pelo navegador exige HTTPS. O cookie do painel não autentica chamadas comuns da aplicação.

A interface oferece sete idiomas e mantém a escolha do navegador. Descrições da API, nomes de campos JSON e payloads conservam o conteúdo original. O host pode limitar os endpoints exibidos e habilitar isolamento por organização; nesse modo, mudanças na instância afetam apenas a organização autenticada. O pacote atual atende HTTP e não oferece API Explorer para gRPC.

Gapfy.Echo.Offline

Guarda uma configuração de mocks revisada em um snapshot portátil para executar testes sem consultar o Echo. O snapshot contém a revisão do perfil, endpoints HTTP selecionados, regras e contratos completos, cenários e seed. Não contém a chave da aplicação Echo nem as credenciais do executor.

Exporte o perfil da instância pelo API Explorer com permissão de gerenciamento da instância. Depois use echo-mock export, abaixo, para obter as regras selecionadas enquanto estiver conectado. A biblioteca lê e valida o arquivo resultante:

dotnet new console -n EchoOfflineDemo -f net10.0
dotnet add EchoOfflineDemo package Gapfy.Echo.Offline --version 0.2.10

using Gapfy.Echo.Offline;

var snapshot = await EchoOfflineSnapshotCodec.ReadAsync("echo.snapshot.json");
EchoOfflineSnapshotCodec.Validate(snapshot);
Console.WriteLine(snapshot.ContentHash);

A validação confere o hash do conteúdo, os contratos e a cobertura completa das rotas antes da execução. O SHA-256 detecta alterações no snapshot; não identifica seu autor nem concede acesso. Trate os corpos de resposta do arquivo como dados de teste que podem exigir acesso restrito. Um snapshot com regras incompletas ou sem seleção de mock não pode ser executado.

A aplicação que importa o snapshot pelo API Explorer precisa configurar explicitamente o modo offline e corresponder às identidades de aplicação, workspace, perfil e endpoints. Um snapshot de organização também precisa corresponder àquela organização. Perfis importados são somente leitura e não atualizam um catálogo remoto.

Gapfy.Echo.Mock.Runner

Instala o comando echo-mock para executar snapshots HTTP preparados. É separado do gapfy-echo, que executa coleções e cadeias.

dotnet tool install --global Gapfy.Echo.Mock.Runner --version 0.2.10
echo-mock export --profile echo.mock.json --server https://api.example.test/ --key-env ECHO_API_KEY --output echo.snapshot.json --seed 17
echo-mock validate --snapshot echo.snapshot.json --report validation.json
echo-mock run --snapshot echo.snapshot.json --report execution.json --timeout 300 -- dotnet Tests.dll --minimum-expected-tests 1

Substitua o endereço ilustrativo pelo endereço configurado da API do Echo. Defina ECHO_API_KEY pelo ambiente ou pelos segredos do CI; o comando de exportação recebe o nome da variável, sem passar o segredo como argumento. A chave precisa de ServeMocks e acesso ao feed pago de regras. Prepare a ferramenta, o runtime .NET e os testes compilados antes da etapa offline.

run valida o snapshot, abre um listener privado em loopback e inicia o comando depois de --. Use o comando real de testes do projeto; o exemplo espera uma aplicação de testes Microsoft.Testing.Platform já compilada e exige pelo menos um teste. O processo filho recebe ECHO_MOCK_BASE_ADDRESS e as configurações Echo__Offline__*. Consumidores do API Explorer usam o perfil importado; consumidores HTTP diretos usam /servers/{serverId} seguido do caminho da regra.

Uma seed fixa estabiliza valores aleatórios. Geradores que dependem de datas ainda podem mudar com o tempo; use datas constantes quando precisar repetir exatamente. Rotas desconhecidas retornam 404 em vez de consultar um serviço real. O runner não bloqueia o restante do tráfego de rede da aplicação testada.

Use serve --snapshot echo.snapshot.json --port 0 --ready-file ready.json quando outro processo precisar controlar a execução. O arquivo de prontidão e /_echo/ready identificam o snapshot validado. Cancelamento ou timeout encerra o listener e o processo filho do runner. O relatório JSON registra o hash, as contagens de rotas e o resultado do filho, sem corpos de requisições ou credenciais. Os códigos de saída são 0 para sucesso, 2 para entrada inválida, 3 para falha de execução ou rota sem correspondência e 130 para cancelamento; um filho que falha conserva seu próprio código de saída.

Escolha o caminho certo