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 suportam .NET 8 e .NET 9. A ferramenta echo-mock requer .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 através do ambiente ou do cofre de segredos. Use o endereço da API, não o URL público do mock. As chaves são emitidas na área de Aplicações do Maestro: emitir uma requer Echo Pro ou Pro AI e a permissão Echo/ManageHosting, atribuída por omissão ao administrador da organização num plano pago. O feed de regras é GET api/echo/mock/rules no endereço base da API configurado. Sem uma chave, o endpoint devolve 401; com uma chave sem ServeMocks ou sem uma subscrição Echo paga em vigor, devolve 403.

Gapfy.Echo.Contracts

Publica uma versão de um contrato que a 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 requer um plano pago. Crie primeiro o contrato e a associação Provides no Maestro, emita uma chave com PublishOwnedContracts e defina GAPFY_ECHO_CONTRACT_ID. Guarde um documento de contrato Echo do editor como orders.echo.json na pasta de trabalho do processo. Tem de ser o documento Echo, não uma resposta de exemplo nem um JSON Schema por converter.

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 disponibiliza o codec, o validador e os motores de inferência e avaliação de contratos. O resultado da publicação inclui Changes, com veredictos para consumidor e fornecedor. Um veredicto incompatível descreve uma publicação já concluída; não a anula. 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 perante uma alteração incompatível, pelo que pode colocá-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. Reveja-os e inclua-os num commit. O CI recusa criar retratos em falta. 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 aos retratos deliberadamente numa 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 associações selecionadas. Uma seleção desconhecida falha em vez de não verificar nada. Depois da revisão numa 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 indique UnmappedMemberHandlingDisallow ou ExhaustiveStatusHandling quando essas condições se aplicarem ao consumidor.

Gapfy.Echo.Mock.Client

Interceta chamadas de saída apenas nos HttpClient criados pela factory que ativar. O exemplo expõe /probe e chama o 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();

As 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 na geração, devolve 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 subscrição paga terminar, a atualização do feed falha e o pacote escreve um aviso no registo, sem parar a sua aplicação. Sem regras em cache, deixa de intercetar e as chamadas seguem para o serviço real; regras já guardadas podem continuar a responder até limpar a cache ou desativar a interceção. Um HttpClient criado manualmente, um canal gRPC ou um SDK com transporte próprio não é intercetado. O pacote não pode ser ativado em Production ou Prod; outros ambientes fora de Development exigem uma 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 a ser um endpoint real. As rotas ainda não implementadas pela API podem responder com regras do Echo. Coloque o middleware depois do encaminhamento 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();

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

Se uma interceção deixar de acontecer e a configuração parecer correta, confirme o plano do Echo e o scope 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 um pedido e examine a resposta dentro da aplicação. Pode escolher respostas reais ou mocks do Echo por controller ou endpoint, incluindo 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 registo completo. Espera que a rota de início de sessão da aplicação, /account/login, emita o cookie Application com os papéis necessários. Ligue o registo à autenticação e às permissões existentes; o pacote não cria contas nem concede acesso. Configure Echo:ApiBaseAddress e Echo:ApiKey no seu fornecedor de configuração protegido, usando uma chave ServeMocks. Depois de entrar, abra /tools/echo no endereço da aplicação. O host decide em que ambientes ativa o painel. Mantenha a autorização de negócio antes de UseEchoDeveloperUI; endpoints Minimal API precisam de WithEchoMocking().

Escolha o âmbito antes de aplicar

  1. Comece por A minha sessão para experimentar pelo executor do seu painel. Outros clientes continuam a usar o perfil da instância.
  2. Escolha um controller ou endpoint, selecione o servidor mock e a rota e escolha um cenário, quando existir. A escolha do endpoint prevalece sobre a do controller; a herança usa a escolha superior.
  3. Aplique o perfil, envie um pedido pelo executor e examine o resultado. Selecionar um servidor ou mudar de separador não aplica o rascunho.
  4. Escolha Toda a instância quando a alteração tiver de afetar todos os clientes dessa instância. É necessária permissão de gestão da instância e confirmação do perfil pendente.

Os perfis pessoais expiram e deixam de ser válidos quando a configuração de referência da instância muda. Recarregue e reveja o novo estado quando solicitado. Se o mock selecionado estiver indisponível, o Echo apresenta um erro, sem executar silenciosamente o código real. A autenticação e os filtros anteriores ao handler continuam em vigor; o código dentro do handler substituído não é executado.

O executor aceita parâmetros, cabeçalhos, corpos e credenciais. Entrar no painel e autenticar o pedido são ações separadas. O host pode ativar início de sessão OpenID Connect pelo navegador ou uma sessão Bearer curta usando a validação de tokens existente; são alternativas. Os tokens de sessão ficam na memória do servidor, expiram e perdem-se ao reiniciar. O início de sessão 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. As descrições da API, os nomes dos campos JSON e os payloads conservam o conteúdo original. O host pode limitar os endpoints apresentados e ativar isolamento por organização; nesse modo, as alterações à instância afetam apenas a organização autenticada. O pacote atual suporta HTTP e não oferece API Explorer para gRPC.

Gapfy.Echo.Offline

Guarda uma configuração de mocks revista num 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 gestão da instância. Depois use echo-mock export, abaixo, para obter as regras selecionadas enquanto estiver ligado. A biblioteca lê e valida o ficheiro 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 verifica o hash do conteúdo, os contratos e a cobertura completa das rotas antes da execução. O SHA-256 deteta alterações no snapshot; não identifica o autor nem concede acesso. Trate os corpos de resposta do ficheiro 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 tem de configurar explicitamente o modo offline e corresponder às identidades de aplicação, workspace, perfil e endpoints. Um snapshot de organização também tem de corresponder a essa organização. Os perfis importados são apenas de 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 através do ambiente ou dos 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 fase 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__*. Os consumidores do API Explorer usam o perfil importado; os consumidores HTTP diretos usam /servers/{serverId} seguido do caminho da regra.

Uma seed fixa estabiliza valores aleatórios. Os geradores que dependem de datas podem continuar a mudar com o tempo; use datas constantes quando precisar de repetição exata. As rotas desconhecidas devolvem 404 em vez de consultar um serviço real. O runner não bloqueia o restante tráfego de rede da aplicação testada.

Use serve --snapshot echo.snapshot.json --port 0 --ready-file ready.json quando outro processo precisar de controlar a execução. O ficheiro de prontidão e /_echo/ready identificam o snapshot validado. O cancelamento ou timeout termina o listener e o processo filho do runner. O relatório JSON regista o hash, as contagens de rotas e o resultado do filho, sem corpos de pedidos 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 o seu próprio código de saída.

Escolha o caminho certo