Forem: Danilo O. Pinheiro, dopme.io

🚀 C# 14 já estava bom… agora ficou ainda melhor

Danilo O. Pinheiro, dopme.io — Mon, 23 Mar 2026 01:31:39 +0000

🚀 C# 14 já estava bom… agora ficou ainda melhor

Comparando C# 14 vs C# 15 e o que muda na prática para desenvolvedores .NET

A evolução do C# segue um padrão cada vez mais claro:

✅ reduzir complexidade

✅ aumentar expressividade

✅ melhorar performance

✅ elevar a produtividade do desenvolvedor

Se o C# 14 já consolidou uma linguagem mais limpa, moderna e consistente, o C# 15 (ainda em evolução) dá mais um passo importante rumo a um ecossistema mais fluido, seguro e alinhado às demandas do desenvolvimento moderno em .NET.

Neste artigo, exploramos as principais diferenças entre C# 14 e C# 15, com foco no impacto real no dia a dia de quem desenvolve aplicações .NET.

⚠️ Observação importante

O C# 15 encontra-se em fase de preview/evolução. Os exemplos apresentados refletem direções e conceitos esperados, podendo sofrer ajustes até a versão final.

🧠 Visão Geral

Aspecto	C# 14	C# 15
Foco	Simplificação e consistência	Produtividade e redução de boilerplate
Sintaxe	Mais limpa	Ainda mais concisa
Pattern Matching	Avançado	Mais poderoso e flexível
Coleções	Simplificadas	Expandidas
Interoperabilidade	Melhorias incrementais	Mais abstração e segurança
Experiência do Dev	Boa	Ainda melhor

🧩 O que o C# 14 trouxe

O C# 14 consolidou melhorias importantes que vinham sendo introduzidas ao longo das versões anteriores.

1️⃣ Inicialização simplificada de coleções

List<int> numbers = [];

✅ Menos código

✅ Mais legibilidade

✅ Sintaxe mais direta

2️⃣ Pattern Matching mais expressivo

if (user is { Age: > 18, Active: true })
{
    Console.WriteLine("Usuário válido");
}

✅ Código mais declarativo

✅ Redução de if/else encadeados

✅ Melhor leitura da intenção

3️⃣ Melhor suporte a cenários de performance

Span<int> data = stackalloc int[10];

✅ Menos alocações no heap

✅ Melhor uso de memória

✅ Ideal para sistemas de alta performance

🚀 O que o C# 15 melhora

O C# 15 não é uma revolução, mas sim uma evolução refinada do que já vinha sendo construído.

1️⃣ Ainda menos boilerplate

A proposta é reduzir ainda mais código repetitivo.

C# 14:

var user = new User { Name = "Danilo", Age = 30 };

C# 15 (conceito esperado):

User user = { Name: "Danilo", Age: 30 };

📌 Inicialização mais direta, fluida e expressiva.

2️⃣ Pattern Matching ainda mais poderoso

Expansão dos padrões compostos:

if (order is { Items.Count: > 0 } and { Status: "Paid" })
{
    Console.WriteLine("Pedido válido");
}

✅ Menos código imperativo

✅ Mais clareza semântica

✅ Melhor leitura da regra de negócio

3️⃣ Evolução no suporte a coleções

Ampliação das collection expressions:

var values = [1, 2, 3, ..otherValues];

📌 Composição de dados mais simples e natural.

4️⃣ Funções e expressões mais diretas

int Sum(int a, int b) => a + b;

➡️ Mais coerência com estilos funcionais

➡️ Código mais enxuto e previsível

5️⃣ Interoperabilidade ainda mais forte

O C# 15 continua evoluindo cenários críticos como:

Span<T>
Memory<T>
Interop com código nativo
APIs de alto desempenho

📌 Ideal para sistemas críticos, de alta escala e baixa latência.

🏗️ Impacto Arquitetural

🔹 Aplicações corporativas

Código mais limpo
Menos repetição
Melhor manutenção e evolução

🔹 Sistemas distribuídos

Modelagem de dados mais clara
Menor acoplamento
APIs mais expressivas

🔹 Times de desenvolvimento

Padronização mais simples
Onboarding mais rápido
Revisões de código mais eficientes

📊 Comparação prática

C# 14

var users = new List<string> { "Ana", "Carlos" };

C# 15

var users = ["Ana", "Carlos"];

C# 14

if (user != null && user.IsActive)
{
    Console.WriteLine(user.Name);
}

C# 15

if (user is { IsActive: true } u)
{
    Console.WriteLine(u.Name);
}

🧩 Quando atualizar?

✅ Atualize para C# 15 se:

Já utiliza versões recentes do .NET
Busca reduzir boilerplate
Quer código mais expressivo
Está iniciando novos projetos

⚠️ Avalie com cautela se:

O projeto é legado e crítico
Ferramentas e bibliotecas ainda não suportam totalmente

🔮 Direção do C\

O caminho do C# está cada vez mais claro:

Menos código repetitivo
Mais expressividade
Mais segurança
Melhor performance
Integração cada vez maior com cloud e microserviços

✅ Conclusão

Se o C# 14 já entregou uma experiência moderna e produtiva, o C# 15 dá continuidade a essa evolução com foco em simplicidade, fluidez e consistência.

Não se trata de mudanças radicais, mas de refinamentos que fazem grande diferença no dia a dia, especialmente em projetos grandes e times distribuídos.

O resultado é uma linguagem cada vez mais preparada para os desafios do desenvolvimento moderno.

🤝 Conecte-se comigo

Se você trabalha com .NET moderno e quer evoluir em temas como arquitetura, C#, DevOps e interoperabilidade, vamos conversar:

💼 Linkedin
💻 Devto
✍️ Medium
📰 Substack

Não vos escrevi porque não soubésseis a verdade, mas porque a sabeis, e porque nenhuma mentira é da verdade. 1 João 2:21

Dez tecnologias essenciais em .NET

Danilo O. Pinheiro, dopme.io — Sat, 21 Mar 2026 20:35:53 +0000

Este material está alinhado à conversa em vídeo “10 coisas que você deve fazer na sua aplicação .NET”, publicada no YouTube pelo canal Eximiaco — Excelência Tecnológica.

Gabriel Kohlrausch conduz a conversa com Bruno Joaquim (desenvolvimento .NET/Node.js e Kafka) e Francisco Schneider (especialista em .NET em aplicações corporativas complexas). Página oficial da live e resumo do tema: EximiaCo — 10 coisas que você deve fazer na sua aplicação .NET. Perfil do mediador na consultoria: Gabriel Kohlrausch — EximiaCo.

O repositório dopTenEssentialTechNet não substitui a palestra: ele oferece laboratórios em console para experimentar, no código, temas que dialogam com essa linha de boas práticas em aplicações .NET.

Introdução

Dominar o ecossistema .NET moderno vai além da linguagem C#: envolve configuração, hospedagem, HTTP resiliente, dados, testes e observabilidade. O repositório dopTenEssentialTechNet reúne aplicativos de console independentes, todos com .NET 10 (net10.0), cada um focado em um tema recorrente em projetos reais — em sintonia com a conversa citada acima.

Este texto descreve o propósito do repositório, o que cada projeto representa e como utilizá-lo como material de estudo ou referência.

Objetivo do repositório

Centralizar exemplos mínimos executáveis (console), fáceis de abrir e rodar.
Separar um tema por pasta, sem misturar dependências desnecessárias entre exemplos.
Servir de base para artigos, treinamentos ou experimentos isolados.

A solução está em dopTenEssentialTechNet.sln na raiz; cada subpasta é um projeto .csproj próprio.

Projetos e temas

Projeto	O que se pretende explorar
SubStringSpan	Manipulação eficiente de texto com `Span<T>`, `ReadOnlySpan<char>` e `Memory<T>`, reduzindo alocações.
OptionsConfig	Padrão Options (`IOptions`, `IOptionsSnapshot`) e ligação com `IConfiguration`.
BackgroundServer	Hospedagem com `Host` / `IHostedService` e execução contínua em segundo plano.
WorkflowCore	Definição e execução de fluxos com a biblioteca WorkflowCore.
VerticalSliceFastEndpoints	Estrutura em fatias verticais usando FastEndpoints (API enxuta sobre ASP.NET Core).
HTTPolly	Chamadas HTTP com Polly (retentativas, circuit breaker, timeouts).
Flurl	Cliente HTTP declarativo com Flurl.Http.
TddContainers	Testes de integração com Testcontainers (dependências reais em containers).
DynamicDapper	Consultas e cenários dinâmicos com Dapper.
ContextPool	Uso de pooling de contexto (por exemplo, `DbContext` com pool de conexões).
SourceGeneratedLogging	Logging com source generators (APIs geradas em tempo de compilação).

Os códigos evoluem com o tempo; a tabela acima define a intenção pedagógica de cada pasta.

Pré-requisitos

SDK .NET 10 instalado.

Verificação rápida:

dotnet --version

Como obter e compilar

git clone https://github.com/daniloopinheiro/dopTenEssentialTechNet.git
cd dopTenEssentialTechNet
dotnet restore
dotnet build dopTenEssentialTechNet.sln

Como executar um exemplo

Substitua NomeDoProjeto pelo nome da pasta (por exemplo, SubStringSpan):

dotnet run --project NomeDoProjeto/NomeDoProjeto.csproj

Sugestão de ordem de estudo

Não há ordem obrigatória. Uma sequência possível para quem está estruturando conhecimento:

SubStringSpan e OptionsConfig — fundamentos de performance e configuração.
BackgroundServer — modelo mental de serviços longos.
HTTPolly e Flurl — consumo de HTTP no mundo real.
DynamicDapper e ContextPool — persistência e recursos.
TddContainers — confiança em integração.
VerticalSliceFastEndpoints, WorkflowCore e SourceGeneratedLogging — organização de API, orquestração e ferramentas modernas de logging.

CI/CD e qualidade

O repositório inclui pipelines em .github/workflows/ (build, dependências, monitoramento, deploy e versionamento). Detalhes operacionais estão no README principal e em .github/README_WORKFLOWS.md.

Conclusão

O dopTenEssentialTechNet é um mapa de estudo: cada console é um “capítulo” sobre um pedaço comum do .NET corporativo, em eco à discussão de Gabriel Kohlrausch com Bruno Joaquim e Francisco Schneider sobre o que priorizar em aplicações .NET. Use o repositório para comparar abordagens, extrair trechos para seus próprios sistemas ou acompanhar evoluções de versão do SDK e das bibliotecas.

Conecte-se

Se você trabalha com .NET moderno e quer evoluir em arquitetura, C#, DevOps, APIs e interoperabilidade:

Quando, pois, tiveres comido, e fores farto, louvarás ao Senhor teu Deus pela boa terra que te deu. Deuteronômio 8:10

Construindo API Gateway Tyk utilizando .NET 10

Danilo O. Pinheiro, dopme.io — Mon, 09 Mar 2026 15:22:40 +0000

Construindo API Gateway Tyk utilizando .NET 10

No desenvolvimento de arquiteturas modernas baseadas em microserviços e APIs, o uso de um API Gateway tornou-se praticamente essencial. Ele atua como uma camada intermediária entre clientes e serviços, centralizando segurança, autenticação, monitoramento, versionamento e controle de tráfego.

Uma das soluções que vem ganhando destaque nesse cenário é o https://tyk.io/, uma plataforma open source e cloud-ready para gerenciamento de APIs.

Neste artigo vamos explorar como implementar um API Gateway utilizando Tyk com uma API construída em .NET 10, entendendo os conceitos arquiteturais, configuração do gateway e integração prática.

🧠 O que é um API Gateway?

Um API Gateway é um componente responsável por atuar como ponto único de entrada para múltiplos serviços.

Ele pode oferecer funcionalidades como:

🔐 Autenticação e autorização
📊 Monitoramento e métricas
⚡ Rate limiting
🔁 Balanceamento de carga
🔄 Versionamento de APIs
🧩 Transformação de requests/responses

Em vez de o cliente chamar diretamente vários serviços, ele interage com o gateway, que encaminha as requisições para os serviços corretos.

🏗️ Arquitetura da Solução

Uma arquitetura simples com .NET 10 + Tyk pode ser representada assim:

Cliente
   │
   ▼
API Gateway (Tyk)
   │
   ├── API .NET 10 - Usuários
   ├── API .NET 10 - Produtos
   └── API .NET 10 - Pedidos

Benefícios da abordagem:

Centralização de segurança
Governança de APIs
Observabilidade unificada
Escalabilidade independente

⚙️ Criando a API com .NET 10

Primeiro, vamos criar uma API simples utilizando o CLI do .NET.

📌 Documentação oficial:

https://learn.microsoft.com/dotnet/core/tools/

dotnet new webapi -n ProductApi
cd ProductApi

Execute a aplicação:

dotnet run

Endpoint de exemplo:

app.MapGet("/products", () =>
{
    var products = new[]
    {
        new { Id = 1, Name = "Notebook", Price = 3500 },
        new { Id = 2, Name = "Mouse", Price = 120 }
    };

    return products;
});

A API estará disponível em:

👉 http://localhost:5000/products

🧩 Instalando o Tyk API Gateway

A maneira mais simples de executar o gateway é utilizando Docker.

📌 Documentação oficial do Tyk Gateway:

https://tyk.io/docs/tyk-gateway/

docker run -d \
  -p 8080:8080 \
  tykio/tyk-gateway

Após subir o container, o gateway já estará pronto para configuração.

📦 Criando uma Definição de API no Tyk

O Tyk utiliza arquivos JSON para definir APIs.

Exemplo de configuração:

{
  "name": "Product API",
  "api_id": "product-api",
  "org_id": "default",
  "use_keyless": true,
  "proxy": {
    "listen_path": "/products/",
    "target_url": "http://host.docker.internal:5000/",
    "strip_listen_path": true
  }
}

Explicando os principais campos:

Campo	Descrição
`name`	Nome da API
`api_id`	Identificador único
`use_keyless`	Permite acesso sem chave
`listen_path`	Endpoint exposto no gateway
`target_url`	URL da API real

🔄 Fluxo da Requisição

Cliente
   │
   ▼
http://localhost:8080/products
   │
   ▼
Tyk API Gateway
   │
   ▼
API .NET 10

Ou seja: o cliente não acessa diretamente a API.

🔐 Adicionando Segurança com API Key

Para proteger sua API:

"use_keyless": false

Agora cada requisição deve enviar:

Authorization: Bearer API_KEY

Isso permite:

Controle de acesso
Limite de requisições
Monitoramento por cliente

📌 Documentação:

Authentication

📊 Observabilidade e Monitoramento

O Tyk oferece:

Logs centralizados
Métricas de consumo
Rate limiting
Analytics de API

Esses dados são essenciais em ambientes com:

múltiplos microserviços
alto volume de requisições
integrações com terceiros

🧪 Testando a Integração

Após configurar o gateway, basta chamar:

GET http://localhost:8080/products

Resposta esperada:

[
  { "id": 1, "name": "Notebook", "price": 3500 },
  { "id": 2, "name": "Mouse", "price": 120 }
]

Mesmo resultado da API original — porém agora gerenciado pelo gateway.

⚡ Benefícios de Usar Tyk com .NET

🔹 Escalabilidade
🔹 Segurança centralizada
🔹 Observabilidade robusta
🔹 Governança e versionamento de APIs

🧩 Quando Utilizar um API Gateway

Use um gateway quando:

há múltiplos microserviços
há integração com sistemas externos
é necessário controle de segurança centralizado
existe alto volume de chamadas de API

Em aplicações pequenas, pode ser exagero.

🔮 O Futuro das APIs no .NET

Com a evolução do .NET e da arquitetura baseada em APIs, ferramentas como API Gateways tendem a se tornar cada vez mais comuns.

Plataformas modernas buscam:

Padronização de integração
Segurança centralizada
Observabilidade completa
Redução da complexidade do cliente

O Tyk é uma das opções mais poderosas nesse ecossistema.

✅ Conclusão

A integração entre .NET 10 e o Tyk API Gateway demonstra como arquiteturas modernas podem ser construídas de forma escalável e organizada.

Centralizando segurança, monitoramento e controle de tráfego, o gateway simplifica o desenvolvimento e melhora a governança em ambientes de APIs.

Para equipes que trabalham com microserviços ou integrações complexas, essa abordagem oferece ganhos expressivos de produtividade e confiabilidade.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer evoluir em temas como arquitetura, C#, DevOps, APIs e interoperabilidade, vamos conversar:

💼 LinkedIn
💻 DEV Community
✍️ Medium
📰 Substack
📧 Email

O norte e o sul tu os criaste; Tabor e Hermom jubilam em teu nome.Tu tens um braço poderoso; forte é a tua mão, e alta está a tua destra.
Salmos 89:12,13

🚀 Que bom que chegou C# 13, Porém o mais novo também C# 14

Danilo O. Pinheiro, dopme.io — Thu, 19 Feb 2026 12:51:28 +0000

O que mudou e como isso impacta seu código no .NET moderno

O C# continua evoluindo de forma incremental, priorizando clareza, segurança, performance e expressividade.
Com a chegada do C# 13 e a evolução para o C# 14, vemos melhorias voltadas principalmente para:

Melhor controle de memória
Redução de boilerplate
Padrões mais expressivos
Maior previsibilidade em código de alto desempenho

Neste artigo, vamos comparar as principais diferenças entre C# 13 e C# 14, com exemplos práticos.

🧠 Visão Geral

Aspecto	C# 13	C# 14
Foco principal	Performance e refinamentos de linguagem	Simplificação e expressividade
Params collections	Melhor suporte	Expandido
Pattern Matching	Melhorias incrementais	Mais expressivo
Ref structs	Mais flexibilidade	Evolução em segurança
Inicialização	Mais controle	Sintaxe ainda mais limpa
Interoperabilidade	Melhorias nativas	Refinamento de cenários low-level

🧩 Principais Novidades do C# 13

1️⃣ Params Collections

Antes do C# 13, params aceitava apenas arrays:

void Print(params string[] values)
{
    foreach (var v in values)
        Console.WriteLine(v);
}

No C# 13, você pode usar outros tipos de coleção como Span<T>:

void Print(params ReadOnlySpan<string> values)
{
    foreach (var v in values)
        Console.WriteLine(v);
}

📌 Benefício:
Melhor performance e menos alocação desnecessária.

2️⃣ Melhorias em `ref struct`

O C# 13 flexibilizou restrições de ref struct, permitindo uso mais amplo em cenários de alta performance.

ref struct BufferProcessor
{
    public void Process() { }
}

📌 Impacto:
Mais controle em cenários de baixo nível e manipulação de memória.

3️⃣ Melhorias em Pattern Matching

C# 13 trouxe pequenos refinamentos em expressões de padrão:

var result = number switch
{
    > 0 and < 10 => "Pequeno",
    >= 10 and < 100 => "Médio",
    _ => "Grande"
};

📌 Código mais legível e expressivo.

🚀 Principais Evoluções do C# 14

O C# 14 continua a linha de simplificação iniciada nas versões anteriores.

1️⃣ Inicialização Mais Simples

Redução adicional de boilerplate em construções comuns.

Antes:

List<int> numbers = new List<int>();

Agora (refinamento):

List<int> numbers = [];

📌 Mais conciso e moderno.

2️⃣ Pattern Matching Mais Poderoso

Expressões ainda mais declarativas:

if (obj is Person { Age: > 18 } person)
{
    Console.WriteLine(person.Name);
}

📌 Melhor leitura sem necessidade de múltiplas verificações.

3️⃣ Melhor Interoperabilidade com Código Nativo

C# 14 aprimora cenários envolvendo:

Span
Memory
Interop com código não gerenciado
Otimizações JIT

Exemplo conceitual:

Span<int> data = stackalloc int[5];

📌 Menos alocação no heap → mais performance.

4️⃣ Melhorias Incrementais em Expressões

Expansão da consistência sintática para manter a linguagem previsível.

🏗️ Impacto Arquitetural

🔹 Para aplicações corporativas

Código mais legível
Menos verbosidade
Menos risco de erro humano

🔹 Para sistemas de alta performance

Melhor controle de memória
Menos alocação desnecessária
Maior previsibilidade

🔹 Para times grandes

Código mais consistente
Melhor padronização
Facilita revisão de código

📊 Comparação Prática

C# 13

void Log(params ReadOnlySpan<string> messages)
{
    foreach (var message in messages)
        Console.WriteLine(message);
}

C# 14

List<string> messages = ["C#", "14", "Evolução"];
Console.WriteLine(string.Join(" ", messages));

Diferença principal:

C# 13 → foco técnico e performance
C# 14 → foco em simplificação e fluidez

🧩 Quando Atualizar?

Vale migrar quando:

✅ O projeto já utiliza .NET 9 ou 10
✅ Há necessidade de melhorias em performance
✅ O time busca código mais moderno e limpo
✅ O projeto é novo

Evite migrar imediatamente se:
⚠️ O projeto é legado e estável
⚠️ Há dependência de ferramentas antigas

🔮 O Caminho do C

A tendência do C# é clara:

Mais expressivo
Menos boilerplate
Mais seguro
Melhor para cloud-native
Melhor para alto desempenho

O foco deixou de ser apenas orientação a objetos e passou a abranger:

Programação funcional
Padrões declarativos
Performance de baixo nível

✅ Conclusão

O C# 13 trouxe melhorias importantes focadas em performance e refinamentos estruturais.
O C# 14 avança na direção de simplificação e consistência sintática, tornando o código ainda mais limpo e intuitivo.

Ambas as versões demonstram maturidade da linguagem e compromisso com produtividade e eficiência.

Para quem trabalha com .NET moderno, acompanhar essas mudanças é essencial para escrever código sustentável e preparado para o futuro.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer evoluir em temas como arquitetura, C#, DevOps e interoperabilidade, vamos conversar:

💼 LinkedIn
💻 DEV Community
✍️ Medium
📰 Substack
📧 Email

Bendizei, povos, ao nosso Deus, e fazei ouvir a voz do seu louvor. Ao que sustenta com vida a nossa alma, e não consente que sejam abalados os nossos pés. Salmos 66:8,9

Integrando Sentry com .NET

Danilo O. Pinheiro, dopme.io — Wed, 28 Jan 2026 14:20:38 +0000

📖 Introdução

O desenvolvimento de aplicações .NET modernas exige não apenas código funcional, mas também visibilidade completa sobre o comportamento do sistema em produção. Monitoramento, rastreamento de erros e observabilidade tornaram-se componentes essenciais para garantir a confiabilidade e a capacidade de resposta de aplicações críticas.

Este artigo apresenta uma abordagem prática para integrar o Sentry em uma aplicação .NET 8, utilizando Vertical Slice Architecture e padrões modernos como CQRS e MediatR. Demonstraremos como implementar monitoramento robusto, captura automática de exceções e rastreamento contextualizado de eventos.

O projeto dopNetSentry serve como exemplo prático, mostrando como combinar arquitetura limpa, padrões de design e ferramentas de observabilidade para criar soluções profissionais e sustentáveis.

🧱 Visão Geral do Projeto

O dopNetSentry é uma aplicação .NET 8 que demonstra a integração completa do SDK do Sentry para monitoramento e rastreamento automático de erros e exceções. O projeto utiliza uma arquitetura em camadas bem definida:

Api: Camada de apresentação com Minimal APIs
Application: Lógica de aplicação com CQRS (Commands e Queries)
Domain: Entidades de domínio puras
Infrastructure: Persistência e integrações externas

Essa organização permite separação clara de responsabilidades, facilitando testes, manutenção e evolução do sistema.

Características Principais

.NET 8: Utilizando a versão mais recente do framework
Sentry SDK 6.0.0: Monitoramento em tempo real de erros e exceções
Vertical Slice Architecture: Organização por funcionalidade
CQRS com MediatR: Separação entre leitura e escrita
Entity Framework Core: ORM para persistência de dados
FluentValidation: Validação robusta de entrada
Swagger/OpenAPI: Documentação automática da API

🛠️ Componentes Fundamentais

🔹 Arquitetura em Camadas

A aplicação segue o princípio de dependência unidirecional:

Api → Application + Infrastructure
Application → Domain
Infrastructure → Domain + Application

Domain é a camada mais pura, sem dependências externas. Application contém a lógica de negócio e depende apenas de Domain. Infrastructure implementa detalhes técnicos e depende de Domain e Application. Api é a camada de apresentação que orquestra tudo.

🔹 Padrão CQRS (Command Query Responsibility Segregation)

O projeto utiliza MediatR para implementar CQRS:

Commands: Operações de escrita (Create, Update, Delete)
Queries: Operações de leitura (Get, List)
Handlers: Processam Commands e Queries de forma isolada

Essa separação permite otimizações independentes, escalabilidade e clareza no código.

🔹 Vertical Slice Architecture

Ao invés de organizar por camadas técnicas (Controllers, Services, Repositories), o projeto organiza por funcionalidade:

├── src/
│   ├── netsentry.Api/                    # Camada de Apresentação
│   │   ├── Endpoints/
│   │   │   ├── WeatherForecastEndpoints.cs
│   │   │   └── SentryExamplesEndpoints.cs (comentado)
│   │   ├── Exceptions/
│   │   │   └── MyRpcException.cs
│   │   ├── Services/
│   │   │   └── SentryService.cs
│   │   ├── Program.cs
│   │   └── appsettings.json
│   ├── netsentry.Application/            # Camada de Aplicação
│   │   ├── Commands/                     # (vazio - pronto para uso)
│   │   ├── Interfaces/
│   │   │   └── IApplicationDbContext.cs
│   │   ├── Models/
│   │   │   └── WeatherForecastDto.cs
│   │   └── Queries/
│   │       ├── GetWeatherForecastQuery.cs
│   │       └── GetWeatherForecastQueryHandler.cs
│   ├── netsentry.Domain/                 # Camada de Domínio
│   │   └── Entities/
│   │       └── WeatherForecast.cs
│   └── netsentry.Infrastructure/         # Camada de Infraestrutura
│       └── Persistence/
│           └── ApplicationDbContext.cs

Cada funcionalidade contém tudo necessário para sua implementação, promovendo coesão e reduzindo acoplamento.

🔄 Integração com Sentry

Configuração do Sentry

O Sentry é configurado no Program.cs usando o método UseSentry no WebHost:

builder.WebHost.UseSentry(options =>
{
    options.Dsn = builder.Configuration["Sentry:Dsn"];
    options.Debug = true; // Para ver o que o SDK está fazendo
    options.SendDefaultPii = true; // Inclui headers, IP, etc.
    options.TracesSampleRate = 1.0; // 100% das transações
    options.Environment = builder.Environment.EnvironmentName;

    // Filtro de exceções
    options.AddExceptionFilterForType<OperationCanceledException>();

    // Customização de eventos
    options.SetBeforeSend(@event =>
    {
        // Lógica de customização
        return @event;
    });
});

Funcionalidades Implementadas

1. Captura Automática de Exceções

O Sentry captura automaticamente todas as exceções não tratadas. Para exceções tratadas, podemos usar:

try
{
    // Código que pode falhar
}
catch (Exception ex)
{
    SentrySdk.CaptureException(ex);
}

2. Captura de Mensagens

Para registrar eventos informativos:

SentrySdk.CaptureMessage("Operação iniciada", SentryLevel.Info);

3. Configuração de Contexto

Adicionar informações contextuais aos eventos:

SentrySdk.ConfigureScope(scope =>
{
    scope.SetTag("endpoint", "weatherforecast");
    scope.SetTag("method", "GET");
    scope.SetExtra("request-time", DateTime.UtcNow.ToString("O"));
});

4. Filtros de Exceção

Ignorar tipos específicos de exceções:

options.AddExceptionFilterForType<OperationCanceledException>();

5. Customização com SetBeforeSend

Modificar eventos antes de enviar ao Sentry:

options.SetBeforeSend(@event =>
{
    if (@event.Exception is MyRpcException rpcEx)
    {
        @event.SetFingerprint(new[]
        {
            "{{ default }}",
            rpcEx.Function,
            rpcEx.Code.ToString(),
        });
    }
    return @event;
});

Exemplo Prático: Endpoint WeatherForecast

O endpoint /weatherforecast demonstra a integração completa:

group.MapGet("/", async (IMediator mediator, CancellationToken cancellationToken) =>
{
    try
    {
        // Configurar contexto
        SentrySdk.ConfigureScope(scope =>
        {
            scope.SetTag("endpoint", "weatherforecast");
            scope.SetTag("method", "GET");
        });

        // Log de início
        SentrySdk.CaptureMessage("Iniciando busca de previsão do tempo", SentryLevel.Info);

        var query = new GetWeatherForecastQuery();
        var result = await mediator.Send(query, cancellationToken);

        return Results.Ok(result);
    }
    catch (Exception ex)
    {
        // Captura com contexto adicional
        SentrySdk.ConfigureScope(scope =>
        {
            scope.SetTag("error-type", ex.GetType().Name);
            scope.SetExtra("error-message", ex.Message);
            scope.Level = SentryLevel.Error;
        });

        SentrySdk.CaptureException(ex);
        return Results.Problem(statusCode: 500);
    }
});

🧪 Testes e Qualidade

A arquitetura implementada facilita a criação de testes:

Testes Unitários: Handlers podem ser testados isoladamente com mocks
Testes de Integração: Endpoints podem ser testados com banco em memória
Testes de Observabilidade: Verificar se eventos são enviados corretamente ao Sentry

A separação de responsabilidades permite isolar dependências e criar testes rápidos e confiáveis.

📊 Observabilidade e Operação

O Sentry fornece:

Monitoramento de Erros em Tempo Real: Notificações instantâneas quando erros ocorrem
Stack Traces Completos: Veja exatamente onde e por que os erros acontecem
Contexto Rico: Informações sobre usuários afetados, ambiente, versão da aplicação
Performance Insights: Identifique gargalos e otimize a performance
Dashboard Interativo: Visualize estatísticas e tendências

Como Obter o DSN do Sentry

Para utilizar o Sentry em sua aplicação, você precisa criar uma conta no Sentry.io e obter o DSN (Data Source Name) do seu projeto. Siga os passos abaixo:

Criar uma Conta no Sentry.io
- Acesse https://sentry.io/signup/
- Crie uma conta gratuita (o plano gratuito oferece recursos suficientes para começar)
- Confirme seu email se necessário
Criar uma Organização e Projeto
- Após fazer login, você será direcionado para criar uma organização
- Escolha um nome para sua organização
- Crie um novo projeto selecionando a plataforma .NET
- Escolha um nome para o projeto (ex: "dopNetSentry")
Obter o DSN
- Após criar o projeto, o Sentry exibirá uma tela de configuração
- O DSN estará visível no formato: https://[chave]@[organização].ingest.sentry.io/[projeto-id]
- Você também pode encontrar o DSN posteriormente em: Settings → Projects → [Seu Projeto] → Client Keys (DSN)
Copiar o DSN
- Copie o DSN completo fornecido pelo Sentry
- Este será o valor que você configurará no appsettings.json

Nota: O DSN é uma chave pública que identifica seu projeto no Sentry. Embora seja seguro incluí-lo no código-fonte, é recomendado usar variáveis de ambiente ou Azure Key Vault em produção.

Configuração via appsettings.json

Após obter o DSN, configure-o no arquivo appsettings.json:

{
  "Sentry": {
    "Dsn": "https://[sua-chave]@[seu-org].ingest.sentry.io/[projeto-id]",
    "Debug": true,
    "SendDefaultPii": true,
    "TracesSampleRate": 1.0,
    "Environment": "Development"
  }
}

Substitua o valor de Dsn pelo DSN real obtido na sua conta do Sentry.

Boas Práticas

Não inclua dados sensíveis nos logs ou contexto do Sentry
Use filtros para ignorar exceções esperadas (como OperationCanceledException)
Configure ambientes diferentes (Development, Staging, Production)
Ajuste TracesSampleRate em produção para controlar volume
Desative Debug em produção para melhor performance

🔐 Segurança

O projeto implementa várias práticas de segurança:

Validação de Entrada: FluentValidation valida todos os dados de entrada
Parameterized Queries: Entity Framework Core usa queries parametrizadas automaticamente
Object Level Authorization: Verificação de permissões em endpoints
Logging Seguro: Não inclui dados sensíveis nos logs
Configuração Segura: DSN do Sentry via configuração, não hardcoded

Essas práticas garantem que a aplicação seja robusta e segura.

🚧 Evolução e Sustentabilidade

A arquitetura escolhida permite:

Evolução Incremental: Adicionar novas funcionalidades sem impactar existentes
Manutenibilidade: Código organizado e fácil de entender
Escalabilidade: Estrutura preparada para crescimento
Testabilidade: Fácil de testar e validar

A Vertical Slice Architecture promove coesão alta e acoplamento baixo, facilitando a evolução contínua do sistema.

✅ Conclusão

A integração do Sentry em aplicações .NET 8, combinada com uma arquitetura bem definida, proporciona:

Visibilidade Completa: Entenda o que acontece em produção
Resposta Rápida: Identifique e corrija problemas rapidamente
Confiança: Monitore a saúde da aplicação continuamente
Melhoria Contínua: Use dados reais para otimizar o sistema

O projeto dopNetSentry demonstra como combinar tecnologias modernas (.NET 8, Sentry) com padrões arquiteturais sólidos (Vertical Slice, CQRS) para criar aplicações profissionais, observáveis e sustentáveis.

Tecnologias mudam, mas bons fundamentos permanecem.

📚 Recursos Adicionais

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, DevOps ou interoperabilidade, vamos conversar:

💼 LinkedIn

💻 DEV Community

✍️ Medium

📰 Substack

📧 Email

Projeto: dopNetSentry

Versão: 1.0.0

Data: Janeiro 2025

³ Porque assim diz o Senhor aos homens de Judá e a Jerusalém: Preparai para vós o campo de lavoura, e não semeeis entre espinhos. Jeremias 4:3

🚀 Desenvolvimento Full-Stack Moderno: TanStack Router + .NET

Danilo O. Pinheiro, dopme.io — Wed, 21 Jan 2026 19:13:41 +0000

✨ Construindo Aplicações Web Escaláveis com Type-Safe Routing e APIs RESTful

No cenário atual de desenvolvimento de software, a necessidade de criar aplicações web modernas, escaláveis e com excelente experiência do desenvolvedor é cada vez mais crítica. Este artigo apresenta uma abordagem prática para construir aplicações full-stack utilizando React com TanStack Router no frontend e ASP.NET Core no backend, demonstrando como essas tecnologias se complementam para criar soluções robustas e type-safe.

📖 Introdução

O desenvolvimento de aplicações web modernas exige uma combinação harmoniosa entre frontend e backend, onde cada camada deve ser construída com as melhores ferramentas disponíveis. Enquanto o ecossistema JavaScript/TypeScript domina o frontend com frameworks como React, o .NET continua sendo uma das plataformas mais robustas para construção de APIs e serviços backend.

Este artigo aborda a integração entre TanStack Router — uma solução moderna de roteamento type-safe para React — e ASP.NET Core, demonstrando como criar uma arquitetura full-stack que prioriza type safety, performance e manutenibilidade. Você aprenderá a configurar um projeto completo, desde a estrutura inicial até a implementação de rotas, APIs e integração entre as camadas.

🎯 Objetivo do Artigo

Ao final deste artigo, você será capaz de:

Entender os conceitos fundamentais de roteamento type-safe com TanStack Router e construção de APIs RESTful com ASP.NET Core
Conhecer boas práticas no ecossistema .NET moderno, incluindo configuração de CORS, documentação de APIs e estruturação de projetos
Aplicar o conhecimento em cenários reais através de um projeto prático que demonstra a integração completa entre frontend e backend
Evitar erros comuns de implementação, como problemas de CORS, configuração incorreta de rotas SPA e falta de type safety

🧠 Conceitos Fundamentais

TanStack Router: Roteamento Type-Safe

TanStack Router é uma biblioteca de roteamento para React que prioriza type safety e developer experience. Diferente de soluções tradicionais como React Router, o TanStack Router oferece:

Type Safety Completo: As rotas são tipadas em tempo de compilação, prevenindo erros comuns de navegação
Code Splitting Automático: Divisão automática de código para otimização de performance
File-Based Routing: Sistema de rotas baseado em arquivos, similar ao Next.js, mas com mais flexibilidade
Data Loading Integrado: Suporte nativo para carregamento de dados com estados de loading e erro

ASP.NET Core: Framework Moderno para APIs

ASP.NET Core é o framework web da Microsoft para construção de aplicações modernas:

Multiplataforma: Roda em Windows, Linux e macOS
Alto Desempenho: Um dos frameworks web mais rápidos disponíveis
Minimal APIs: Sintaxe simplificada para criação de endpoints
Integração Nativa: Suporte completo para JSON, CORS, autenticação e muito mais

Type Safety no Full-Stack

A type safety não deve ser limitada ao frontend. Ao usar TypeScript no React e C# no backend, garantimos:

Contratos Claros: Interfaces e DTOs bem definidos entre frontend e backend
Detecção Precoce de Erros: Problemas identificados em tempo de compilação
Melhor Autocomplete: IDEs fornecem sugestões precisas em ambas as camadas
Refatoração Segura: Mudanças podem ser feitas com confiança

🏗️ Arquitetura e Estrutura

Visão Geral da Arquitetura

┌─────────────────────────────────────────────────────────┐
│                    Frontend (React)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │   TanStack   │  │  Components  │  │   State      │   │
│  │    Router    │  │   (React)    │  │  Management  │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
│                          │                              │
│                          │ HTTP/REST                    │
└──────────────────────────┼──────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────┐
│                    Backend (.NET)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │  Controllers │  │   Services   │  │   Data       │   │
│  │   (API)      │  │   (Business) │  │   Access     │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
└─────────────────────────────────────────────────────────┘

Organização de Camadas

Frontend (React + TanStack Router)

src/
├── routes/              # Rotas baseadas em arquivos
│   ├── __root.tsx      # Rota raiz (layout principal)
│   ├── index.tsx       # Página inicial (/)
│   ├── about.tsx       # Página sobre (/about)
│   └── api-example.tsx # Exemplo de integração (/api-example)
├── components/          # Componentes reutilizáveis
├── hooks/              # Custom hooks
├── utils/              # Funções utilitárias
└── main.tsx           # Ponto de entrada

Princípios de Organização:

File-Based Routing: Cada arquivo em routes/ representa uma rota
Co-location: Componentes relacionados ficam próximos às rotas
Separação de Responsabilidades: Lógica de negócio separada de apresentação

Backend (ASP.NET Core)

NetTanstack.Api/
├── Controllers/        # Controladores da API
│   └── WeatherForecastController.cs
├── Services/          # Serviços de negócio
├── Models/            # Modelos e DTOs
├── Program.cs         # Configuração e pipeline
└── appsettings.json   # Configurações

Princípios de Organização:

Controller-Based: Organização por recursos/funcionalidades
Dependency Injection: Uso extensivo de DI para desacoplamento
Minimal APIs: Endpoints simples podem usar Minimal APIs

Comunicação entre Componentes

Frontend → Backend: Requisições HTTP via fetch ou bibliotecas como Axios
Backend → Frontend: Respostas JSON tipadas
Type Safety: Contratos definidos em TypeScript (frontend) e C# (backend)

Impactos em Escalabilidade e Manutenção

Escalabilidade Horizontal: Backend pode ser escalado independentemente
Deploy Independente: Frontend e backend podem ser deployados separadamente
Manutenibilidade: Código organizado e type-safe facilita manutenção
Testabilidade: Separação clara permite testes isolados

🛠️ Implementação no .NET

Estrutura de Projeto

1. Configuração do Backend (ASP.NET Core)

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Adicionar serviços
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Configurar CORS para permitir requisições do frontend
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowReactApp", policy =>
    {
        policy.WithOrigins("http://localhost:5173")
              .AllowAnyHeader()
              .AllowAnyMethod();
    });
});

var app = builder.Build();

// Configurar pipeline
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseCors("AllowReactApp");
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

// Exemplo de Minimal API
app.MapGet("/api/hello", () => new { message = "Olá do backend .NET!" })
   .WithName("Hello");

app.Run();

Por que essas decisões?

CORS Configurado: Permite comunicação entre frontend e backend em desenvolvimento
Swagger em Desenvolvimento: Facilita testes e documentação da API
Minimal APIs: Sintaxe mais limpa para endpoints simples
Controllers: Melhor para endpoints mais complexos com múltiplas ações

2. Exemplo de Controller

// Controllers/WeatherForecastController.cs
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Congelante", "Frio", "Fresco", "Ameno", "Quente", "Tropical", "Escaldante"
    };

    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

public record WeatherForecast
{
    public DateOnly Date { get; set; }
    public int TemperatureC { get; set; }
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    public string? Summary { get; set; }
}

Boas Práticas Aplicadas:

Records para DTOs: Sintaxe concisa e imutabilidade por padrão
Atributos de Roteamento: [ApiController] e [Route] para convenções claras
Separação de Responsabilidades: Controller apenas coordena, lógica em serviços (em projetos maiores)

Configuração do Frontend (React + TanStack Router)

1. Configuração do Vite

// vite.config.ts
import { defineConfig, type Plugin } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import type { IncomingMessage, ServerResponse } from 'node:http'
import type { NextFunction } from 'node:connect'

// Plugin para garantir fallback para index.html em todas as rotas (SPA)
const spaFallback = (): Plugin => {
  return {
    name: 'spa-fallback',
    configureServer(server) {
      return () => {
        server.middlewares.use((req: IncomingMessage, res: ServerResponse, next: NextFunction) => {
          if (
            req.url &&
            !req.url.startsWith('/api') &&
            !req.url.includes('.') &&
            req.url !== '/'
          ) {
            req.url = '/index.html'
          }
          next()
        })
      }
    },
  }
}

export default defineConfig({
  plugins: [
    tanstackRouter({
      target: 'react',
      autoCodeSplitting: true,
    }),
    react(),
    spaFallback(),
  ],
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:5000',
        changeOrigin: true,
      },
    },
  },
})

Decisões Técnicas:

Plugin SPA Fallback: Garante que recarregar qualquer rota funcione corretamente
Proxy para API: Redireciona /api/* para o backend, evitando problemas de CORS em desenvolvimento
Auto Code Splitting: TanStack Router divide automaticamente o código por rota

2. Estrutura de Rotas

// src/routes/__root.tsx
import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

const RootLayout = () => (
  <>
    <nav className="main-nav">
      <div className="nav-container">
        <Link to="/" className="nav-link [&.active]:font-bold">
          Home
        </Link>
        <Link to="/about" className="nav-link [&.active]:font-bold">
          Sobre
        </Link>
        <Link to="/api-example" className="nav-link [&.active]:font-bold">
          API Example
        </Link>
      </div>
    </nav>
    <main className="main-content">
      <Outlet />
    </main>
    <TanStackRouterDevtools />
  </>
)

export const Route = createRootRoute({ component: RootLayout })

// src/routes/api-example.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useState, useEffect } from 'react'

export const Route = createFileRoute('/api-example')({
  component: ApiExample,
})

interface WeatherForecast {
  date: string
  temperatureC: number
  temperatureF: number
  summary: string
}

function ApiExample() {
  const [data, setData] = useState<WeatherForecast[]>([])
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    const fetchData = async () => {
      try {
        setLoading(true)
        const response = await fetch('/api/weatherforecast')
        if (!response.ok) {
          throw new Error('Erro ao buscar dados')
        }
        const result = await response.json()
        setData(result)
        setError(null)
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Erro desconhecido')
      } finally {
        setLoading(false)
      }
    }

    fetchData()
  }, [])

  return (
    <div className="page-container">
      {/* UI do componente */}
    </div>
  )
}

Por que essa abordagem?

File-Based Routing: Rotas definidas por arquivos, facilitando navegação e manutenção
Type Safety: Interface WeatherForecast garante que os dados da API sejam tipados
Error Handling: Tratamento adequado de erros e estados de loading
Separation of Concerns: Lógica de fetch separada da apresentação

🔄 Boas Práticas e Cuidados

1. Evitar Acoplamento Excessivo

❌ Ruim:

// Frontend conhece detalhes de implementação do backend
const response = await fetch('http://localhost:5000/api/weatherforecast')
const data = await response.json()
// Sem validação de tipos

✅ Bom:

// Abstração através de serviços
import { weatherService } from '@/services/weather'

const data = await weatherService.getForecast()
// Tipos garantidos, fácil de mockar em testes

2. Garantir Testabilidade

Backend:

Use Dependency Injection para todos os serviços
Separe lógica de negócio dos controllers
Crie interfaces para dependências externas

Frontend:

Extraia lógica de fetch para hooks customizados
Use serviços para comunicação com API
Facilite mocking em testes

3. Pensar em Observabilidade

// Adicionar logging estruturado
builder.Services.AddLogging(builder =>
{
    builder.AddConsole();
    builder.AddSeq(); // Ou outro sistema de logging
});

// Logar requisições importantes
_logger.LogInformation("Weather forecast requested at {Time}", DateTime.UtcNow);

4. Tratar Falhas e Exceções Corretamente

Backend:

// Middleware global de tratamento de exceções
app.UseExceptionHandler(appBuilder =>
{
    appBuilder.Run(async context =>
    {
        context.Response.StatusCode = 500;
        context.Response.ContentType = "application/json";

        var exception = context.Features.Get<IExceptionHandlerFeature>();
        if (exception != null)
        {
            await context.Response.WriteAsync(JsonSerializer.Serialize(new
            {
                error = "An error occurred",
                message = exception.Error.Message
            }));
        }
    });
});

Frontend:

// Tratamento consistente de erros
try {
  const data = await fetch('/api/weatherforecast')
  if (!data.ok) {
    throw new Error(`HTTP error! status: ${data.status}`)
  }
  // processar dados
} catch (error) {
  // Logar erro e mostrar mensagem amigável ao usuário
  console.error('Failed to fetch weather data:', error)
  setError('Não foi possível carregar os dados. Tente novamente.')
}

5. Considerar Segurança desde o Início

CORS: Configure apenas origens necessárias em produção
Validação de Input: Sempre valide dados recebidos
HTTPS: Force HTTPS em produção
Rate Limiting: Implemente limites de requisição
Autenticação: Use JWT ou OAuth2 para APIs protegidas

// CORS mais restritivo em produção
if (app.Environment.IsProduction())
{
    builder.Services.AddCors(options =>
    {
        options.AddPolicy("AllowReactApp", policy =>
        {
            policy.WithOrigins("https://meudominio.com")
                  .AllowAnyHeader()
                  .AllowAnyMethod()
                  .AllowCredentials();
        });
    });
}

📊 Benefícios da Abordagem

Código Mais Limpo e Organizado

Type Safety: Erros detectados em tempo de compilação
Estrutura Clara: File-based routing facilita navegação
Convenções: Padrões consistentes reduzem decisões arbitrárias

Facilidade de Manutenção

Separação de Responsabilidades: Frontend e backend independentes
Refatoração Segura: TypeScript e C# permitem refatorações com confiança
Documentação: Swagger gera documentação automática da API

Escalabilidade

Deploy Independente: Escalar frontend e backend separadamente
Performance: Code splitting automático otimiza carregamento
Arquitetura Flexível: Fácil adicionar novos serviços ou features

Melhor Experiência para Times de Desenvolvimento

Developer Experience: Autocomplete preciso, erros claros
Hot Reload: Mudanças refletidas instantaneamente
DevTools: TanStack Router DevTools facilitam debug

Menor Risco em Produção

Type Safety: Previne erros de runtime
Testabilidade: Código testável por design
Observabilidade: Logging e monitoramento facilitados

🚧 Desafios Comuns

1. Complexidade Desnecessária

Problema: Adicionar muitas camadas e abstrações sem necessidade real.

Solução: Comece simples. Adicione complexidade apenas quando necessário. Um controller direto pode ser suficiente para APIs simples.

2. Uso Incorreto de Ferramentas

Problema: Usar TanStack Router para aplicações muito simples onde React Router seria suficiente.

Solução: Avalie as necessidades do projeto. TanStack Router brilha em aplicações complexas com muitas rotas e necessidade de type safety.

3. Falta de Padronização

Problema: Diferentes padrões de nomenclatura, estrutura de pastas e estilos de código.

Solução: Estabeleça convenções desde o início e documente-as. Use ferramentas como ESLint e EditorConfig para manter consistência.

4. Dificuldade de Evolução sem Refatoração

Problema: Código acoplado dificulta adicionar novas features.

Solução:

Use Dependency Injection
Separe lógica de negócio de apresentação
Crie interfaces para dependências
Escreva testes que facilitem refatoração

5. Problemas de CORS em Produção

Problema: Configuração de CORS muito permissiva ou incorreta.

Solução: Configure CORS específico para cada ambiente. Em produção, liste apenas origens necessárias.

✅ Conclusão

Este artigo apresentou uma abordagem prática para construir aplicações full-stack modernas utilizando React com TanStack Router no frontend e ASP.NET Core no backend. Através da combinação dessas tecnologias, conseguimos criar soluções que priorizam type safety, performance e manutenibilidade.

Os principais pontos abordados foram:

Conceitos fundamentais de roteamento type-safe e construção de APIs RESTful
Arquitetura moderna com separação clara de responsabilidades
Implementação prática com exemplos de código reais
Boas práticas para garantir qualidade e sustentabilidade
Desafios comuns e como evitá-los

A escolha de tecnologias modernas como TanStack Router e ASP.NET Core, combinada com boas práticas de arquitetura, resulta em aplicações mais robustas, escaláveis e fáceis de manter. A type safety em ambas as camadas (TypeScript e C#) reduz significativamente erros em runtime e melhora a experiência de desenvolvimento.

É importante lembrar que boas decisões arquiteturais e técnicas impactam diretamente a qualidade, a escalabilidade e a longevidade das aplicações. Investir tempo em estruturação adequada e escolha de ferramentas apropriadas paga dividendos a longo prazo.

Próximos Passos:

Experimente o projeto de exemplo e adapte para suas necessidades
Explore recursos avançados do TanStack Router como data loading e route masking
Implemente autenticação e autorização na API
Adicione testes unitários e de integração
Configure CI/CD para deploy automatizado

Aplique esses conceitos de forma gradual e consciente, sempre avaliando as necessidades específicas do seu projeto. Comece simples e evolua conforme a complexidade aumenta.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, DevOps ou interoperabilidade, vamos conversar:

💼 LinkedIn

💻 Dev.to

✍️ Medium

✍️ Substack

📬 Email

Referências e Recursos:

Adeus, Swagger UI ? Uma alternativa elegante com Redoc

Danilo O. Pinheiro, dopme.io — Sat, 10 Jan 2026 17:06:46 +0000

Neste artigo, vamos explorar como criar uma API RESTful completa em .NET 8 usando Minimal APIs, implementando um CRUD (Create, Read, Update, Delete) completo para cadastro de pessoas. Além disso, vamos integrar OpenAPI/Swagger para documentação automática e Redoc para uma interface de documentação interativa e elegante.

O projeto demonstra as melhores práticas modernas de desenvolvimento .NET, incluindo:

Minimal APIs para endpoints limpos e diretos
Validação de dados com Data Annotations
Documentação automática com OpenAPI 3.0
Interface de documentação com Redoc
Arquitetura em camadas com serviços e modelos separados

🛠️ Tecnologias Utilizadas

.NET 8.0 - Framework moderno e de alto desempenho
Minimal APIs - Abordagem simplificada para criar APIs REST
Swashbuckle.AspNetCore - Geração automática de documentação OpenAPI/Swagger
Redoc - Interface de documentação interativa e elegante
Data Annotations - Validação de dados nativa do .NET

📁 Estrutura do Projeto

NR.Api/
├── Models/
│   ├── Pessoa.cs                  # Modelo de domínio
│   ├── CriarPessoaRequest.cs      # DTO para criação
│   └── AtualizarPessoaRequest.cs  # DTO para atualização
├── Services/
│   ├── IPessoaService.cs          # Interface do serviço
│   └── PessoaService.cs           # Implementação do serviço (em memória)
├── Properties/
│   └── launchSettings.json        # Configurações de execução
├── wwwroot/
│   ├── index.html                 # Página inicial
│   └── redoc.html                 # Interface Redoc
├── Program.cs                     # Configuração e endpoints
└── NR.Api.csproj                  # Arquivo do projeto

🚀 Como Executar o Projeto

Pré-requisitos

.NET 8 SDK instalado
Visual Studio 2022, VS Code ou Rider (opcional)

Passos para Executar

Clone ou navegue até o diretório do projeto

cd NR.Api

Restaura as dependências

dotnet restore

Execute a aplicação

dotnet run

Acesse a documentação

Redoc: http://localhost:5059/
Swagger UI: http://localhost:5059/swagger (apenas em Development)

📚 Modelos de Dados

Pessoa (Modelo de Domínio)

public class Pessoa
{
    public Guid Id { get; set; }
    public string Nome { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public string Telefone { get; set; } = string.Empty;
    public DateTime DataNascimento { get; set; }
    public string? Endereco { get; set; }
    public DateTime DataCriacao { get; set; }
    public DateTime? DataAtualizacao { get; set; }
}

CriarPessoaRequest (DTO de Criação)

public class CriarPessoaRequest
{
    [Required(ErrorMessage = "O nome é obrigatório")]
    [StringLength(200, MinimumLength = 2)]
    public string Nome { get; set; } = string.Empty;

    [Required(ErrorMessage = "O email é obrigatório")]
    [EmailAddress(ErrorMessage = "O email deve ser válido")]
    public string Email { get; set; } = string.Empty;

    [Required(ErrorMessage = "O telefone é obrigatório")]
    [StringLength(20, MinimumLength = 10)]
    public string Telefone { get; set; } = string.Empty;

    [Required(ErrorMessage = "A data de nascimento é obrigatória")]
    public DateTime DataNascimento { get; set; }

    [StringLength(500)]
    public string? Endereco { get; set; }
}

AtualizarPessoaRequest (DTO de Atualização)

Similar ao CriarPessoaRequest, usado para atualização de dados.

🔌 Endpoints da API

1. Health Check

GET /health

Retorna o status de saúde da aplicação.

Resposta:

{
  "status": "healthy",
  "timestamp": "2024-01-09T10:30:00Z",
  "version": "1.0.0"
}

2. Listar Todas as Pessoas

GET /api/pessoas

Retorna uma lista com todas as pessoas cadastradas.

Resposta (200 OK):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nome": "João Silva",
    "email": "joao.silva@email.com",
    "telefone": "(11) 98765-4321",
    "dataNascimento": "1990-05-15T00:00:00Z",
    "endereco": "Rua Exemplo, 123",
    "dataCriacao": "2024-01-09T10:00:00Z",
    "dataAtualizacao": null
  }
]

3. Obter Pessoa por ID

GET /api/pessoas/{id}

Retorna os dados de uma pessoa específica.

Parâmetros:

id (Guid): ID único da pessoa

Resposta (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nome": "João Silva",
  "email": "joao.silva@email.com",
  "telefone": "(11) 98765-4321",
  "dataNascimento": "1990-05-15T00:00:00Z",
  "endereco": "Rua Exemplo, 123",
  "dataCriacao": "2024-01-09T10:00:00Z",
  "dataAtualizacao": null
}

Resposta (404 Not Found):

{
  "message": "Pessoa com ID {id} não encontrada"
}

4. Criar Nova Pessoa

POST /api/pessoas

Cria uma nova pessoa no sistema.

Body (JSON):

{
  "nome": "Maria Santos",
  "email": "maria.santos@email.com",
  "telefone": "(11) 91234-5678",
  "dataNascimento": "1985-08-20",
  "endereco": "Avenida Principal, 456"
}

Resposta (201 Created):

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "nome": "Maria Santos",
  "email": "maria.santos@email.com",
  "telefone": "(11) 91234-5678",
  "dataNascimento": "1985-08-20T00:00:00Z",
  "endereco": "Avenida Principal, 456",
  "dataCriacao": "2024-01-09T10:15:00Z",
  "dataAtualizacao": null
}

Resposta (400 Bad Request):

{
  "errors": [
    "O nome é obrigatório",
    "O email deve ser válido"
  ]
}

5. Atualizar Pessoa

PUT /api/pessoas/{id}

Atualiza os dados de uma pessoa existente.

Parâmetros:

id (Guid): ID único da pessoa

Body (JSON):

{
  "nome": "Maria Santos Silva",
  "email": "maria.silva@email.com",
  "telefone": "(11) 91234-5678",
  "dataNascimento": "1985-08-20",
  "endereco": "Avenida Principal, 456 - Apto 101"
}

Resposta (200 OK):

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "nome": "Maria Santos Silva",
  "email": "maria.silva@email.com",
  "telefone": "(11) 91234-5678",
  "dataNascimento": "1985-08-20T00:00:00Z",
  "endereco": "Avenida Principal, 456 - Apto 101",
  "dataCriacao": "2024-01-09T10:15:00Z",
  "dataAtualizacao": "2024-01-09T10:20:00Z"
}

6. Deletar Pessoa

DELETE /api/pessoas/{id}

Remove uma pessoa do sistema.

Parâmetros:

id (Guid): ID único da pessoa

Resposta (204 No Content): Sem corpo de resposta

Resposta (404 Not Found):

{
  "message": "Pessoa com ID {id} não encontrada"
}

💻 Implementação do Serviço

O serviço PessoaService utiliza um dicionário em memória para armazenar os dados. Em uma aplicação de produção, você substituiria isso por um banco de dados (SQL Server, PostgreSQL, MongoDB, etc.).

public class PessoaService : IPessoaService
{
    private readonly Dictionary<Guid, Pessoa> _pessoas = new();
    private readonly object _lock = new();

    public Task<Pessoa> CriarAsync(CriarPessoaRequest request)
    {
        lock (_lock)
        {
            var pessoa = new Pessoa
            {
                Id = Guid.NewGuid(),
                Nome = request.Nome,
                Email = request.Email,
                Telefone = request.Telefone,
                DataNascimento = request.DataNascimento,
                Endereco = request.Endereco,
                DataCriacao = DateTime.UtcNow
            };

            _pessoas[pessoa.Id] = pessoa;
            return Task.FromResult(pessoa);
        }
    }

    // ... outros métodos
}

✅ Validação de Dados

O projeto utiliza Data Annotations para validação de dados. As validações incluem:

Required: Campos obrigatórios
EmailAddress: Validação de formato de email
StringLength: Limitação de tamanho de strings
MinimumLength: Tamanho mínimo de strings

Exemplo de validação no endpoint:

var validationResults = new List<ValidationResult>();
var validationContext = new ValidationContext(request);

if (!Validator.TryValidateObject(request, validationContext, validationResults, true))
{
    return Results.BadRequest(new { errors = validationResults.Select(v => v.ErrorMessage) });
}

🧪 Testando a API

Usando cURL

Listar pessoas:

curl -X GET http://localhost:5059/api/pessoas

Criar pessoa:

curl -X POST http://localhost:5059/api/pessoas \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "João Silva",
    "email": "joao.silva@email.com",
    "telefone": "(11) 98765-4321",
    "dataNascimento": "1990-05-15",
    "endereco": "Rua Exemplo, 123"
  }'

Atualizar pessoa:

curl -X PUT http://localhost:5059/api/pessoas/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "João Silva Santos",
    "email": "joao.santos@email.com",
    "telefone": "(11) 98765-4321",
    "dataNascimento": "1990-05-15",
    "endereco": "Rua Exemplo, 123"
  }'

Deletar pessoa:

curl -X DELETE http://localhost:5059/api/pessoas/{id}

Usando Postman ou Insomnia

Importe a especificação OpenAPI disponível em /swagger/v1/swagger.json no Postman ou Insomnia para ter acesso a todos os endpoints pré-configurados.

🎨 Documentação com OpenAPI e Redoc

OpenAPI/Swagger

O projeto utiliza Swashbuckle.AspNetCore para gerar automaticamente a documentação OpenAPI 3.0. A especificação OpenAPI está disponível em:

JSON: http://localhost:5059/swagger/v1/swagger.json
Swagger UI: http://localhost:5059/swagger (apenas em Development)

Gerando HTML Estático com Redocly CLI para Produção

Para ambiente de produção, é recomendado gerar uma versão estática da documentação usando o Redocly CLI. Isso oferece melhor performance e pode ser servido por qualquer servidor web estático.

Passo A — Instalar Redocly CLI (Node)

Primeiro, instale o Redocly CLI globalmente usando npm:

npm install -g @redocly/cli

Nota: É necessário ter o Node.js instalado em sua máquina. Você pode baixá-lo em nodejs.org.

Passo B — Gerar o OpenAPI JSON localmente

Com a API rodando, baixe o arquivo JSON da especificação OpenAPI:

curl http://localhost:5059/swagger/v1/swagger.json -o openapi.json

Ou, no Windows PowerShell:

Invoke-WebRequest -Uri http://localhost:5059/swagger/v1/swagger.json -OutFile openapi.json

Passo C — Gerar o HTML do Redoc

Execute o comando para gerar o HTML estático:

redocly build-docs openapi.json

Isso cria um arquivo redoc-static.html no diretório atual.

Passo D — Colocar o HTML no wwwroot

Agora você pode mover o arquivo gerado para o diretório wwwroot e servi-lo diretamente:

mkdir -p wwwroot
mv redoc-static.html wwwroot/index.html

Ou, no Windows PowerShell:

New-Item -ItemType Directory -Force -Path wwwroot
Move-Item -Path redoc-static.html -Destination wwwroot/index.html

Agora abra http://localhost:5059/index.html para ver a documentação estática.

Vantagens do Redocly CLI

✅ Configuração personalizada: Diferentes opções de configuração e temas
✅ Lint e validação: Valida a especificação OpenAPI antes de gerar
✅ Bundle da spec: Consolida referências externas em um único arquivo
✅ Builds automatizados: Integra facilmente em pipelines de CI/CD
✅ Deploy estático: Pode ser servido por qualquer servidor web estático (Nginx, Azure Static Web Apps, GitHub Pages, etc.)
✅ Melhor performance: HTML estático carrega mais rápido que versões dinâmicas

Exemplo de Configuração Avançada

Você também pode criar um arquivo de configuração redocly.yaml para personalizar a geração:

apis:
  main:
    root: openapi.json
theme:
  colors:
    primary:
      main: '#32329f'
  typography:
    fontSize: '14px'

E então usar:

redocly build-docs openapi.json --config redocly.yaml

🔒 Próximos Passos e Melhorias

Para tornar esta API pronta para produção, considere:

Persistência de Dados: Substituir o dicionário em memória por um banco de dados (Entity Framework Core, Dapper, etc.)
Autenticação e Autorização: Implementar JWT, OAuth 2.0 ou Identity
Logging: Adicionar logging estruturado (Serilog, NLog)
Tratamento de Erros Global: Middleware para tratamento centralizado de exceções
Rate Limiting: Limitar requisições por IP/usuário
Caching: Implementar cache para consultas frequentes
Versionamento de API: Suporte para múltiplas versões da API
Testes Automatizados: Unit tests e integration tests
CI/CD: Pipeline de build e deploy automatizado
Monitoramento: Application Insights, Prometheus, etc.

📖 Conclusão

Este projeto demonstra como criar uma API RESTful completa e moderna usando .NET 8 com Minimal APIs. Através do uso de OpenAPI e Redoc, conseguimos gerar documentação automática e interativa, facilitando o desenvolvimento e a integração com outros sistemas.

As Minimal APIs do .NET 8 oferecem uma abordagem simplificada e performática para criar APIs REST, enquanto o OpenAPI e Redoc garantem uma experiência de documentação profissional e acessível.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, DevOps ou interoperabilidade, vamos conversar:

💼 LinkedIn

💻 DEV Community

✍️ Medium

📰 Substack

📧 Email

⁷ Agora, pois, seja o temor do Senhor convosco; guardai-o, e fazei-o; porque não há no Senhor nosso Deus iniquidade nem acepção de pessoas, nem aceitação de suborno. 2 Crônicas 19:7

🛠️ Do `.SLN` para `.SLNX` no .NET: O que Mudou e Por quê

Danilo O. Pinheiro, dopme.io — Wed, 07 Jan 2026 21:46:20 +0000

O Visual Studio e o ecossistema .NET utilizam há anos arquivos de solução (.sln) para agrupar e organizar projetos dentro de uma solução maior. Porém, com a chegada do .NET 10 e evoluções recentes do SDK e do CLI, um novo formato chamado .slnx está sendo adotado como alternativa mais moderna, legível e sustentável nos fluxos de desenvolvimento.

📌 1. O Problema com `.sln`

O formato tradicional de arquivo .sln existe há décadas e foi projetado quando a Visual Studio era o centro do desenvolvimento Windows. Ele possui diversas características que hoje se tornaram limitantes:

📄 Formato de texto plano com muitos GUIDs, seções e metadados redundantes.
🔀 Merge conflicts frequentes em sistemas de controle de versão (como Git).
✍️ Difícil de editar ou entender manualmente sem experiência.
🧠 Pouca compatibilidade com ferramentas automatizadas.

Esse formato “cresceu orgânico” com o tempo, acumulando configurações duplicadas e ruído, o que dificulta sua manutenção — principalmente em projetos grandes ou desenvolvidos por muitas pessoas.

✨ 2. Por que o `.slnx`?

Visando simplificar, modernizar e facilitar o trabalho em equipe, a Microsoft introduziu um novo formato de solução chamado .slnx.

Principais Motivações:

🧾 Menos verbosidade: arquivo mais curto e fácil de ler.
🛠️ Formato XML: padrão universal, compatível com ferramentas automatizadas.
🔧 Menos conflitos em Git: estrutura mais estável reduz diffs problemáticos.
📊 Ferramentas de build integradas: MSBuild e .NET CLI já suportam .slnx.
🧑‍💻 Melhor manutenção: é mais simples combinar com scripts e automações.

🆕 3. O que mudou no formato

🗂 Estrutura

A diferença é clara quando comparamos:

Antes — .sln:

// Formato antigo com GUIDs e várias seções
Microsoft Visual Studio Solution File, Format Version 12.00
Global
    GlobalSection(SolutionConfigurationPlatforms) = preSolution
        Debug|Any CPU = Debug|Any CPU
        Release|Any CPU = Release|Any CPU
    EndGlobalSection
EndGlobal

Agora — .slnx:

<Solution>
    <Project Path="WebApi/WebApi.csproj" />
    <Project Path="Domain/Domain.csproj" />
</Solution>

O novo formato usa XML simples e direto, sem GUIDs, seções longas ou metadados desnecessários — deixando claro quais projetos pertencem à solução.

🚀 4. Quando isso começou?

O suporte ao .slnx foi introduzido inicialmente como preview no SDK do .NET a partir da versão 9.0.200, com suporte gradativo em CLI e ferramentas como MSBuild.

Com o lançamento do .NET 10, o comando padrão usado por:

dotnet new sln

passou a gerar por padrão arquivos .slnx em vez de .sln.

🛠️ 5. Como funciona no dia a dia

🆕 Criando uma solução com `.slnx`

Ao rodar:

dotnet new sln

Você obterá um arquivo .slnx por padrão, com estrutura XML simples.

🧠 Migrando de `.sln` para `.slnx`

Você pode migrar uma solução antiga usando:

dotnet sln migrate

ou, em Visual Studio (quando a opção estiver habilitada), salvar o arquivo em novo formato.

🧰 Opções da CLI

Se você ainda deseja gerar o formato clássico .sln, pode fazer:

dotnet new sln --format sln

— útil ao manter compatibilidade com ferramentas antigas ou fluxos de trabalho específicos.

🧩 6. Ferramentas e compatibilidade

🧑‍💻 Visual Studio

O suporte ao .slnx já está presente, mas em algumas versões é necessário ativar a opção nas configurações de Preview Features para garantir que o Visual Studio entenda o novo formato.

🎯 MSBuild

O MSBuild suporta totalmente arquivos .slnx, permitindo builds, testes e operações usuais sem impactos significativos.

🌐 CLI e ferramentas de terceiros

O dotnet sln agora pode listar e modificar projetos em .slnx, além de migrar soluções antigas.

Há também bibliotecas como Microsoft.VisualStudio.SolutionPersistence para manipular .slnx programaticamente — útil em scripts ou ferramentas de automação.

📚 7. Principais Benefícios do `.slnx`

🧠 Human-readable: Mais fácil de ler e editar manualmente.
🔄 Menos conflitos no Git: Comentários redundantes e GUIDs eram armadilhas para merge.
⚙ Ferramentas harmonizadas: MSBuild, CLI e IDEs conseguem trabalhar melhor com formato estruturado.
🛠 Automação facilitada: Scripts e ferramentas podem gerar e modificar soluções com mais segurança.

⚠️ 8. Pontos de Atenção

✔️ As equipes devem evitar manter ambos .sln e .slnx no mesmo repositório para evitar confusão e conflitos de ferramentas.
✔️ Algumas IDEs ou extensões antigas podem ainda não ter suporte completo ao novo formato, exigindo atualizações.
✔️ Em casos específicos (Unity/VS Code), pode ser necessário garantir que a versão do SDK suporte .slnx.

📈 Conclusão

O novo formato .slnx representa uma evolução importante no fluxo de desenvolvimento .NET — tornando os arquivos de solução mais simples, legíveis e amigáveis para times modernos e pipelines de CI/CD.

Embora o formato .sln ainda seja amplamente compatível, o .slnx já é o padrão a partir do .NET 10, simplificando o gerenciamento de projetos e reduzindo tópicos recorrentes como conflitos no Git e dificuldade de edição.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, DevOps ou interoperabilidade, vamos conversar:

💼 LinkedIn
💻 Dev.to
✍️ Medium
📬 daniloopinheiro

¹⁴ E disse ele: Não, mas venho agora como príncipe do exército do Senhor. Então Josué se prostrou com o seu rosto em terra e o adorou, e disse-lhe: Que diz meu Senhor ao seu servo? Josué 5:14

🧾 Console.Write(): Explorando todas as possibilidades!

Danilo O. Pinheiro, dopme.io — Fri, 26 Dec 2025 20:33:33 +0000

Do C# 1.0 ao C# 13

Diferente do Console.WriteLine(), o método Console.Write() não quebra a linha após a escrita.
Ele é muito usado para saídas contínuas, progresso em tempo real, logs formatados e interfaces de console interativas.

🧱 C# 1.0 (2002) – Forma Clássica

using System;

namespace ConsoleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.Write("Hello ");
            Console.Write("World ");
            Console.Write("C# 1.0");
        }
    }
}

📌 Saída:

Hello World C# 1.0

🧩 C# 2.0 (2005)

Sem mudanças diretas na API do Console, mas o padrão permanece:

Console.Write("Hello World - C# 2.0");

🧠 C# 3.0 (2007) – `var`

var text = "Hello World - C# 3.0";
Console.Write(text);

🧠 Código mais limpo com inferência de tipo.

🔄 C# 4.0 (2010) – `dynamic`

dynamic message = "Hello World - C# 4.0";
Console.Write(message);

⚠️ Uso possível, mas não recomendado para cenários simples.

⚡ C# 5.0 (2012) – Assíncrono (Simulação)

using System.Threading.Tasks;

static async Task Main()
{
    Console.Write("Loading");
    await Task.Delay(500);
    Console.Write(".");
    await Task.Delay(500);
    Console.Write(".");
    await Task.Delay(500);
    Console.Write(".");
}

📌 Saída:

Loading...

✨ C# 6.0 (2015) – Interpolação de Strings

var version = "C# 6.0";
Console.Write($"Hello World - {version}");

🧩 C# 7.x (2017–2018) – Tuplas

var info = (Name: "C#", Version: "7.x");
Console.Write($"{info.Name} {info.Version}");

🔐 C# 8.0 (2019) – Nullable Reference Types

string? message = "Hello World - C# 8.0";
Console.Write(message ?? "Mensagem padrão");

🛡️ Proteção contra NullReferenceException.

🧱 C# 9.0 (2020) – Top-Level Statements

Console.Write("Hello World - C# 9.0");

🔥 Código direto, sem Program.cs.

📦 C# 10.0 (2021) – Global Usings

Console.Write("Hello World - C# 10.0");

📉 Menos boilerplate.

🧬 C# 11.0 (2022) – Raw String Literals

Console.Write("""
Hello World - C# 11.0
Sem quebra automática de linha
""");

🧠 C# 12.0 (2023) – Collection Expressions

var parts = ["Hello", "World", "C# 12.0"];
foreach (var part in parts)
{
    Console.Write(part + " ");
}

📌 Saída:

Hello World C# 12.0

🚀 C# 13.0 (Preview / 2025)

Console.Write("Hello World - C# 13.0 (Preview)");

🔮 Evolução focada em imutabilidade e padrões.

🔍 Console.Write vs Console.WriteLine

Método	Comportamento
`Console.Write()`	Continua na mesma linha
`Console.WriteLine()`	Quebra linha automaticamente

🛠️ Casos de Uso Comuns do `Console.Write()`

✔️ Barras de progresso
✔️ Logs contínuos
✔️ CLI interativas
✔️ Animações simples no terminal

Exemplo de progresso:

for (int i = 0; i <= 100; i += 10)
{
    Console.Write($"\rProgresso: {i}%");
    Thread.Sleep(200);
}

✅ Conclusão

Mesmo sendo simples, o Console.Write() acompanhou toda a evolução do C#.
A diferença está na forma como escrevemos código hoje — mais limpo, expressivo e seguro — não no método em si.

Dominar esses detalhes é essencial para escrever ferramentas CLI modernas, scripts, workers e ferramentas DevOps em .NET.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, DevOps ou interoperabilidade, vamos conversar:

💼 LinkedIn
✍️ Medium
📬 daniloopinheiro

Porque a minha mão fez todas estas coisas, e assim todas elas foram feitas, diz o Senhor; mas para esse olharei, para o pobre e abatido de espírito, e que treme da minha palavra.
Isaías 66:2

🛠️ O que chegou de novo no Visual Studio 2026 Insiders

Danilo O. Pinheiro, dopme.io — Thu, 30 Oct 2025 19:10:32 +0000

📝 Introdução

A Microsoft lançou recentemente o Visual Studio 2026 na versão Insiders, uma prévia que inaugura o que será o futuro da IDE para desenvolvedores em .NET, C#, C++ e workloads que envolvem nuvem, IA e grandes soluções corporativas. ([Microsoft for Developers][1])
Neste artigo, vamos explorar os principais destaques, mostrar como a experiência foi evoluída e o que isso significa para quem desenvolve em .NET moderno.

🚀 Novos Destaques Principais

🤖 Integração profunda com IA

A integração do GitHub Copilot foi ampliada na IDE para ações como Adaptive Paste, onde o código colado é adaptado automaticamente ao contexto do arquivo. ([Microsoft Learn][2])
A pesquisa “Você quis dizer?” (“Did you mean?”) foi adicionada para melhorar a busca dentro do IDE com sugestões baseadas em IA. ([Microsoft Learn][2])
Um agente de profiler com suporte de IA pode sugerir melhorias de desempenho e alocação de memória. ([Visual Studio Magazine][3])

⚡ Performance e produtividade

O VS2026 Insiders promete solução de carregamento e ciclos de build/debug até 30 % mais rápidos em comparação com versões anteriores. ([Microsoft Learn][2])
Suporte otimizado para hardware moderno, tanto em x64 quanto em ARM64. ([c-sharpcorner.com][4])

🎨 Interface modernizada

Nova interface baseada em “Fluent UI”, com maior clareza, novos ícones, melhorias de acessibilidade e 11 novos temas para personalização. ([Visual Studio Magazine][3])
Instalação lado-a-lado com versões anteriores (ex: VS2022), com compatibilidade de extensões e importação de configurações. ([Visual Studio][5])

📚 Suporte a linguagens e plataformas

Suporte completo para .NET 10 e C# 14: novos recursos de linguagem, compilador atualizado, melhor IntelliSense. ([Visual Studio Magazine][3])
Suporte avançado para projetos C++ e workloads de jogo, nuvem, IA. ([Visual Studio][5])

📋 Principais Melhorias Organizacionais

O canal “Insiders” substitui o antigo “Preview” para acesso antecipado a novas funcionalidades. ([Microsoft for Developers][1])
Compatibilidade de extensões: as extensões feitas para VS2022 funcionam no VS2026 Insiders desde o primeiro dia. ([Visual Studio][5])
Ferramentas de cobertura de código disponíveis também para edições Community e Professional – antes restritas a versões Enterprise. ([Microsoft Learn][2])

🧠 Impacto para Desenvolvedores .NET

Para quem trabalha com .NET moderno, essa atualização traz vantagens práticas:

Ao usar .NET 10 e C# 14, você já estará na vanguarda, o que pode evitar “lock-in” em versões antigas.
A integração de IA acelera tarefas repetitivas (refatoração, comentários, adaptação de código) e permite focar em lógica de negócios.
Melhor desempenho da IDE significa mais tempo codificando, menos tempo esperando builds ou debugging.
A customização visual e de experiência ajuda a manter foco e reduzir fadiga em ambientes de longo trabalho.

✅ Conclusão

O Visual Studio 2026 Insiders representa mais do que uma simples atualização: é um passo estratégico rumo às ferramentas de desenvolvimento que combinam IA, performance e design moderno. Embora ainda seja uma versão prévia (Insiders), vale para experimentação.
Se você desenvolve em .NET, vale testar, avaliar a compatibilidade com seus projetos e começar a se preparar para a migração.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, DevOps ou interoperabilidade, vamos conversar:

💼 LinkedIn
✍️ Medium
📬 dopme.io
📬 devsfree

⁵ Porque na morte não há lembrança de ti; no sepulcro quem te louvará? Salmos 6:5

🧩 Minha Primeira Comunicação com MCP e .NET – Parte 5

Danilo O. Pinheiro, dopme.io — Tue, 21 Oct 2025 18:06:18 +0000

Integração Completa com SOAP

Nesta quinta parte da série "Minha Primeira Comunicação com MCP e .NET", exploramos como integrar o MCP (Model Context Protocol) com serviços legados baseados em SOAP/WCF, criando uma ponte entre sistemas modernos de IA e infraestruturas corporativas existentes, garantindo interoperabilidade e continuidade de negócio.

🚀 Introdução

Enquanto as partes anteriores exploraram protocolos modernos (gRPC e WebSocket), a realidade corporativa frequentemente exige integração com sistemas legados que utilizam SOAP (Simple Object Access Protocol) e WCF (Windows Communication Foundation).

Empresas estabelecidas possuem:

Décadas de investimento em serviços SOAP/WCF
Sistemas críticos que não podem ser migrados rapidamente
Contratos estabelecidos com parceiros externos via SOAP
Conformidade regulatória que exige manutenção de interfaces existentes

Este artigo demonstra como criar uma arquitetura de integração que permite ao MCP comunicar-se com serviços SOAP, modernizando gradualmente sem quebrar sistemas existentes.

⚙️ O que é SOAP e por que ainda é relevante?

SOAP é um protocolo baseado em XML para troca de informações estruturadas em serviços web. Apesar de ser considerado "legado", permanece crucial em:

Onde SOAP ainda domina:

✅ Sistemas bancários e financeiros - Transações seguras com ACID

✅ Setor de saúde (HL7, FHIR) - Interoperabilidade entre sistemas hospitalares

✅ Governos - Integrações obrigatórias (e-Gov, SEFAZ, Receita Federal)

✅ ERP corporativos - SAP, Oracle, Microsoft Dynamics

✅ Telecomunicações - Sistemas de billing e provisionamento

✅ Seguros - Cotações e sinistros em tempo real

Características do SOAP:

📋 Contratos formais via WSDL (Web Services Description Language)
🔒 WS-Security para autenticação, criptografia e assinatura digital
📦 Tipagem forte com XML Schema Definition (XSD)
🔄 Transações distribuídas com WS-AtomicTransaction
📨 Mensageria confiável com WS-ReliableMessaging

🧠 Arquitetura de Integração MCP + SOAP

Visão Geral da Arquitetura

┌──────────────────────────────────────────────────────────────┐
│                      MCP Agent Layer                          │
│            (Semantic Kernel / LangChain)                      │
└────────────────────┬─────────────────────────────────────────┘
                     │
         ┌───────────▼────────────┐
         │   MCP SOAP Adapter     │
         │  (Protocol Translator) │
         └───────────┬────────────┘
                     │
         ┌───────────▼────────────────────────────┐
         │    SOAP Service Proxy Layer            │
         │  (WCF Client / SoapHttpClient)         │
         └───────────┬────────────────────────────┘
                     │
         ┌───────────▼────────────┐
         │   WSDL Contract        │
         │   (Service Metadata)   │
         └───────────┬────────────┘
                     │
    ┌────────────────┴────────────────┐
    │                                 │
┌───▼─────────────┐      ┌───────────▼──────────┐
│  Legacy SOAP    │      │  Partner SOAP        │
│  Service (WCF)  │      │  Service (External)  │
│  (Intranet)     │      │  (B2B)               │
└─────────────────┘      └──────────────────────┘

Componentes Principais

MCP SOAP Adapter - Traduz comandos MCP para chamadas SOAP
Service Proxy Layer - Gerencia conexões e retry policies
Contract Validator - Valida requisições contra WSDL
Message Transformer - Converte entre JSON/Protobuf e XML
Security Handler - Implementa WS-Security e certificados

🏗️ Implementação Completa

1️⃣ Estrutura do Projeto

MCPPipeline.SOAP/
├── src/
│   ├── MCPPipeline.SOAP.Contracts/
│   │   ├── Models/
│   │   │   ├── SOAPMessage.cs
│   │   │   └── SOAPResponse.cs
│   │   └── WSDL/
│   │       └── legacy-service.wsdl
│   │
│   ├── MCPPipeline.SOAP.Adapter/
│   │   ├── Services/
│   │   │   ├── ISoapAdapterService.cs
│   │   │   ├── SoapAdapterService.cs
│   │   │   └── WsdlParser.cs
│   │   └── Transformers/
│   │       ├── JsonToXmlTransformer.cs
│   │       └── XmlToJsonTransformer.cs
│   │
│   ├── MCPPipeline.SOAP.Client/
│   │   ├── Proxies/
│   │   │   ├── LegacyServiceProxy.cs
│   │   │   └── PartnerServiceProxy.cs
│   │   └── Security/
│   │       ├── WsSecurityHandler.cs
│   │       └── CertificateManager.cs
│   │
│   └── MCPPipeline.SOAP.API/
│       ├── Controllers/
│       │   └── SoapBridgeController.cs
│       └── Program.cs
│
└── tests/
    └── MCPPipeline.SOAP.Tests/

2️⃣ Modelos e Contratos

// MCPPipeline.SOAP.Contracts/Models/SOAPMessage.cs
namespace MCPPipeline.SOAP.Contracts.Models;

public record SOAPMessage
{
    public string MessageId { get; init; } = Guid.NewGuid().ToString();
    public string ServiceName { get; init; } = string.Empty;
    public string OperationName { get; init; } = string.Empty;
    public Dictionary<string, object> Parameters { get; init; } = new();
    public SOAPSecuritySettings? Security { get; init; }
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
    public int TimeoutSeconds { get; init; } = 30;
}

public record SOAPResponse
{
    public string MessageId { get; init; } = string.Empty;
    public bool Success { get; init; }
    public object? Result { get; init; }
    public string? ErrorMessage { get; init; }
    public string? FaultCode { get; init; }
    public string? FaultString { get; init; }
    public long ProcessingTimeMs { get; init; }
    public Dictionary<string, string> ResponseHeaders { get; init; } = new();
}

public record SOAPSecuritySettings
{
    public string? Username { get; init; }
    public string? Password { get; init; }
    public string? CertificateThumbprint { get; init; }
    public bool RequireSignature { get; init; }
    public bool RequireEncryption { get; init; }
}

public record WSDLServiceInfo
{
    public string ServiceName { get; init; } = string.Empty;
    public string Namespace { get; init; } = string.Empty;
    public List<WSDLOperation> Operations { get; init; } = new();
    public string EndpointUrl { get; init; } = string.Empty;
}

public record WSDLOperation
{
    public string Name { get; init; } = string.Empty;
    public string SoapAction { get; init; } = string.Empty;
    public List<WSDLParameter> InputParameters { get; init; } = new();
    public WSDLParameter? OutputParameter { get; init; }
}

public record WSDLParameter
{
    public string Name { get; init; } = string.Empty;
    public string Type { get; init; } = string.Empty;
    public bool IsRequired { get; init; }
    public string? DefaultValue { get; init; }
}

3️⃣ SOAP Adapter Service

// MCPPipeline.SOAP.Adapter/Services/SoapAdapterService.cs
using System.Diagnostics;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Xml.Linq;

namespace MCPPipeline.SOAP.Adapter.Services;

public interface ISoapAdapterService
{
    Task<SOAPResponse> InvokeServiceAsync(SOAPMessage message, CancellationToken ct);
    Task<WSDLServiceInfo> GetServiceInfoAsync(string wsdlUrl, CancellationToken ct);
}

public class SoapAdapterService : ISoapAdapterService
{
    private readonly ILogger<SoapAdapterService> _logger;
    private readonly IWsdlParser _wsdlParser;
    private readonly HttpClient _httpClient;
    private static readonly ActivitySource ActivitySource = new("MCPPipeline.SOAP");

    public SoapAdapterService(
        ILogger<SoapAdapterService> logger,
        IWsdlParser wsdlParser,
        HttpClient httpClient)
    {
        _logger = logger;
        _wsdlParser = wsdlParser;
        _httpClient = httpClient;
    }

    public async Task<SOAPResponse> InvokeServiceAsync(
        SOAPMessage message,
        CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("InvokeSOAPService");
        activity?.SetTag("service.name", message.ServiceName);
        activity?.SetTag("operation.name", message.OperationName);

        var sw = Stopwatch.StartNew();

        try
        {
            _logger.LogInformation(
                "Invocando serviço SOAP: {Service}.{Operation}",
                message.ServiceName,
                message.OperationName);

            // Construir envelope SOAP
            var soapEnvelope = BuildSoapEnvelope(message);

            // Adicionar segurança se necessário
            if (message.Security != null)
            {
                soapEnvelope = AddWsSecurity(soapEnvelope, message.Security);
            }

            // Enviar requisição
            var endpoint = await GetServiceEndpointAsync(message.ServiceName, ct);
            var response = await SendSoapRequestAsync(
                endpoint,
                soapEnvelope,
                message.OperationName,
                message.TimeoutSeconds,
                ct);

            sw.Stop();

            // Processar resposta
            var result = ParseSoapResponse(response);

            activity?.SetTag("response.success", true);

            return new SOAPResponse
            {
                MessageId = message.MessageId,
                Success = true,
                Result = result,
                ProcessingTimeMs = sw.ElapsedMilliseconds
            };
        }
        catch (FaultException faultEx)
        {
            sw.Stop();

            _logger.LogError(faultEx,
                "SOAP Fault ao invocar {Service}.{Operation}",
                message.ServiceName,
                message.OperationName);

            activity?.SetTag("response.success", false);
            activity?.SetTag("fault.code", faultEx.Code?.Name);

            return new SOAPResponse
            {
                MessageId = message.MessageId,
                Success = false,
                FaultCode = faultEx.Code?.Name ?? "Unknown",
                FaultString = faultEx.Reason?.ToString() ?? faultEx.Message,
                ProcessingTimeMs = sw.ElapsedMilliseconds
            };
        }
        catch (Exception ex)
        {
            sw.Stop();

            _logger.LogError(ex,
                "Erro ao invocar {Service}.{Operation}",
                message.ServiceName,
                message.OperationName);

            activity?.SetTag("response.success", false);
            activity?.SetTag("error.message", ex.Message);

            return new SOAPResponse
            {
                MessageId = message.MessageId,
                Success = false,
                ErrorMessage = ex.Message,
                ProcessingTimeMs = sw.ElapsedMilliseconds
            };
        }
    }

    public async Task<WSDLServiceInfo> GetServiceInfoAsync(
        string wsdlUrl,
        CancellationToken ct)
    {
        _logger.LogInformation("Obtendo informações do WSDL: {WsdlUrl}", wsdlUrl);

        var wsdlContent = await _httpClient.GetStringAsync(wsdlUrl, ct);
        return _wsdlParser.Parse(wsdlContent);
    }

    private XDocument BuildSoapEnvelope(SOAPMessage message)
    {
        var ns = XNamespace.Get("http://schemas.xmlsoap.org/soap/envelope/");
        var serviceNs = XNamespace.Get($"http://tempuri.org/{message.ServiceName}");

        var envelope = new XDocument(
            new XDeclaration("1.0", "utf-8", null),
            new XElement(ns + "Envelope",
                new XAttribute(XNamespace.Xmlns + "soap", ns),
                new XAttribute(XNamespace.Xmlns + "svc", serviceNs),
                new XElement(ns + "Header"),
                new XElement(ns + "Body",
                    new XElement(serviceNs + message.OperationName,
                        message.Parameters.Select(p =>
                            new XElement(serviceNs + p.Key, p.Value))))));

        return envelope;
    }

    private XDocument AddWsSecurity(XDocument envelope, SOAPSecuritySettings security)
    {
        var ns = XNamespace.Get("http://schemas.xmlsoap.org/soap/envelope/");
        var wsse = XNamespace.Get("http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd");
        var wsu = XNamespace.Get("http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd");

        var header = envelope.Root!.Element(ns + "Header")!;

        var securityHeader = new XElement(wsse + "Security",
            new XAttribute(ns + "mustUnderstand", "1"));

        if (!string.IsNullOrEmpty(security.Username))
        {
            var usernameToken = new XElement(wsse + "UsernameToken",
                new XAttribute(wsu + "Id", "UsernameToken-" + Guid.NewGuid()),
                new XElement(wsse + "Username", security.Username),
                new XElement(wsse + "Password",
                    new XAttribute("Type", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"),
                    security.Password));

            securityHeader.Add(usernameToken);
        }

        header.Add(securityHeader);
        return envelope;
    }

    private async Task<XDocument> SendSoapRequestAsync(
        string endpoint,
        XDocument soapEnvelope,
        string soapAction,
        int timeoutSeconds,
        CancellationToken ct)
    {
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
        cts.CancelAfter(TimeSpan.FromSeconds(timeoutSeconds));

        var content = new StringContent(
            soapEnvelope.ToString(),
            Encoding.UTF8,
            "text/xml");

        var request = new HttpRequestMessage(HttpMethod.Post, endpoint)
        {
            Content = content
        };

        request.Headers.Add("SOAPAction", $"\"{soapAction}\"");

        var response = await _httpClient.SendAsync(request, cts.Token);
        response.EnsureSuccessStatusCode();

        var responseContent = await response.Content.ReadAsStringAsync(cts.Token);
        return XDocument.Parse(responseContent);
    }

    private object ParseSoapResponse(XDocument response)
    {
        var ns = XNamespace.Get("http://schemas.xmlsoap.org/soap/envelope/");
        var body = response.Root!.Element(ns + "Body");

        if (body == null)
            throw new InvalidOperationException("SOAP Body não encontrado na resposta");

        var result = body.Elements().FirstOrDefault()?.Elements().FirstOrDefault();

        if (result == null)
            return new { };

        // Converter XML para objeto dinâmico
        return XmlToDynamic(result);
    }

    private dynamic XmlToDynamic(XElement element)
    {
        if (!element.HasElements)
        {
            return element.Value;
        }

        var dict = new Dictionary<string, object>();
        foreach (var child in element.Elements())
        {
            dict[child.Name.LocalName] = XmlToDynamic(child);
        }
        return dict;
    }

    private async Task<string> GetServiceEndpointAsync(string serviceName, CancellationToken ct)
    {
        // Em produção, buscar de configuração ou service discovery
        await Task.CompletedTask;
        return $"https://legacy-services.company.com/{serviceName}";
    }
}

4️⃣ WSDL Parser

// MCPPipeline.SOAP.Adapter/Services/WsdlParser.cs
using System.Xml.Linq;

namespace MCPPipeline.SOAP.Adapter.Services;

public interface IWsdlParser
{
    WSDLServiceInfo Parse(string wsdlContent);
}

public class WsdlParser : IWsdlParser
{
    private readonly ILogger<WsdlParser> _logger;

    public WsdlParser(ILogger<WsdlParser> logger)
    {
        _logger = logger;
    }

    public WSDLServiceInfo Parse(string wsdlContent)
    {
        try
        {
            var doc = XDocument.Parse(wsdlContent);
            var wsdlNs = XNamespace.Get("http://schemas.xmlsoap.org/wsdl/");
            var xsdNs = XNamespace.Get("http://www.w3.org/2001/XMLSchema");

            var definitions = doc.Root;
            if (definitions == null)
                throw new InvalidOperationException("WSDL inválido: elemento raiz não encontrado");

            var targetNamespace = definitions.Attribute("targetNamespace")?.Value ?? string.Empty;

            // Extrair service
            var serviceElement = definitions.Element(wsdlNs + "service");
            var serviceName = serviceElement?.Attribute("name")?.Value ?? "UnknownService";

            // Extrair endpoint
            var soapNs = XNamespace.Get("http://schemas.xmlsoap.org/wsdl/soap/");
            var addressElement = serviceElement?
                .Element(wsdlNs + "port")?
                .Element(soapNs + "address");
            var endpointUrl = addressElement?.Attribute("location")?.Value ?? string.Empty;

            // Extrair operations
            var portType = definitions.Element(wsdlNs + "portType");
            var operations = portType?
                .Elements(wsdlNs + "operation")
                .Select(op => ParseOperation(op, wsdlNs, doc))
                .ToList() ?? new List<WSDLOperation>();

            _logger.LogInformation(
                "WSDL parseado: {Service} com {Count} operações",
                serviceName,
                operations.Count);

            return new WSDLServiceInfo
            {
                ServiceName = serviceName,
                Namespace = targetNamespace,
                EndpointUrl = endpointUrl,
                Operations = operations
            };
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao parsear WSDL");
            throw;
        }
    }

    private WSDLOperation ParseOperation(XElement operationElement, XNamespace wsdlNs, XDocument doc)
    {
        var operationName = operationElement.Attribute("name")?.Value ?? "Unknown";

        // Extrair input parameters
        var inputMessage = operationElement.Element(wsdlNs + "input")?.Attribute("message")?.Value;
        var inputParams = inputMessage != null 
            ? ParseMessageParameters(inputMessage, wsdlNs, doc) 
            : new List<WSDLParameter>();

        // Extrair output parameter
        var outputMessage = operationElement.Element(wsdlNs + "output")?.Attribute("message")?.Value;
        var outputParam = outputMessage != null 
            ? ParseMessageParameters(outputMessage, wsdlNs, doc).FirstOrDefault() 
            : null;

        // Extrair SOAP Action
        var binding = doc.Root?.Elements(wsdlNs + "binding").FirstOrDefault();
        var soapNs = XNamespace.Get("http://schemas.xmlsoap.org/wsdl/soap/");
        var soapAction = binding?
            .Elements(wsdlNs + "operation")
            .FirstOrDefault(o => o.Attribute("name")?.Value == operationName)?
            .Element(soapNs + "operation")?
            .Attribute("soapAction")?.Value ?? string.Empty;

        return new WSDLOperation
        {
            Name = operationName,
            SoapAction = soapAction,
            InputParameters = inputParams,
            OutputParameter = outputParam
        };
    }

    private List<WSDLParameter> ParseMessageParameters(
        string messageName, 
        XNamespace wsdlNs, 
        XDocument doc)
    {
        var localName = messageName.Split(':').Last();
        var message = doc.Root?
            .Elements(wsdlNs + "message")
            .FirstOrDefault(m => m.Attribute("name")?.Value == localName);

        if (message == null)
            return new List<WSDLParameter>();

        return message.Elements(wsdlNs + "part")
            .Select(part => new WSDLParameter
            {
                Name = part.Attribute("name")?.Value ?? "Unknown",
                Type = part.Attribute("type")?.Value ?? "string",
                IsRequired = true
            })
            .ToList();
    }
}

5️⃣ MCP Integration Layer

// MCPPipeline.SOAP.API/Services/MCPSoapBridge.cs
using MCPPipeline.Contracts.Messages;

namespace MCPPipeline.SOAP.API.Services;

public interface IMCPSoapBridge
{
    Task<MCPResponse> ExecuteSOAPCommandAsync(MCPCommand command, CancellationToken ct);
}

public class MCPSoapBridge : IMCPSoapBridge
{
    private readonly ISoapAdapterService _soapAdapter;
    private readonly ILogger<MCPSoapBridge> _logger;
    private static readonly ActivitySource ActivitySource = new("MCPPipeline.SOAPBridge");

    public MCPSoapBridge(
        ISoapAdapterService soapAdapter,
        ILogger<MCPSoapBridge> logger)
    {
        _soapAdapter = soapAdapter;
        _logger = logger;
    }

    public async Task<MCPResponse> ExecuteSOAPCommandAsync(
        MCPCommand command,
        CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("ExecuteSOAPCommand");
        activity?.SetTag("mcp.command", command.Command);

        var sw = Stopwatch.StartNew();

        try
        {
            _logger.LogInformation(
                "Executando comando MCP via SOAP: {Command}",
                command.Command);

            // Parsear comando MCP para mensagem SOAP
            var soapMessage = ParseMCPCommandToSOAP(command);

            // Invocar serviço SOAP
            var soapResponse = await _soapAdapter.InvokeServiceAsync(soapMessage, ct);

            sw.Stop();

            // Converter resposta SOAP para MCP
            return new MCPResponse
            {
                CommandId = command.CommandId,
                Result = soapResponse.Success 
                    ? JsonSerializer.Serialize(soapResponse.Result) 
                    : string.Empty,
                Status = soapResponse.Success 
                    ? ResponseStatus.Success 
                    : ResponseStatus.Error,
                ErrorMessage = soapResponse.ErrorMessage ?? soapResponse.FaultString,
                ProcessingTimeMs = sw.ElapsedMilliseconds,
                Metrics = new Dictionary<string, object>
                {
                    ["soap_processing_time"] = soapResponse.ProcessingTimeMs,
                    ["total_time"] = sw.ElapsedMilliseconds,
                    ["service_name"] = soapMessage.ServiceName,
                    ["operation_name"] = soapMessage.OperationName
                }
            };
        }
        catch (Exception ex)
        {
            sw.Stop();

            _logger.LogError(ex, "Erro ao executar comando SOAP");

            return new MCPResponse
            {
                CommandId = command.CommandId,
                Status = ResponseStatus.Error,
                ErrorMessage = ex.Message,
                ProcessingTimeMs = sw.ElapsedMilliseconds
            };
        }
    }

    private SOAPMessage ParseMCPCommandToSOAP(MCPCommand command)
    {
        // Extrair configuração SOAP do payload
        var config = JsonSerializer.Deserialize<SOAPCommandConfig>(command.Payload);

        if (config == null)
            throw new InvalidOperationException("Payload MCP inválido para comando SOAP");

        return new SOAPMessage
        {
            MessageId = command.CommandId,
            ServiceName = config.ServiceName,
            OperationName = config.OperationName,
            Parameters = config.Parameters,
            Security = config.Security,
            TimeoutSeconds = config.TimeoutSeconds ?? 30
        };
    }
}

public record SOAPCommandConfig
{
    public string ServiceName { get; init; } = string.Empty;
    public string OperationName { get; init; } = string.Empty;
    public Dictionary<string, object> Parameters { get; init; } = new();
    public SOAPSecuritySettings? Security { get; init; }
    public int? TimeoutSeconds { get; init; }
}

6️⃣ API Controller

// MCPPipeline.SOAP.API/Controllers/SoapBridgeController.cs
using Microsoft.AspNetCore.Mvc;

namespace MCPPipeline.SOAP.API.Controllers;

[ApiController]
[Route("api/[controller]")]
public class SoapBridgeController : ControllerBase
{
    private readonly IMCPSoapBridge _soapBridge;
    private readonly ISoapAdapterService _soapAdapter;
    private readonly ILogger<SoapBridgeController> _logger;

    public SoapBridgeController(
        IMCPSoapBridge soapBridge,
        ISoapAdapterService soapAdapter,
        ILogger<SoapBridgeController> logger)
    {
        _soapBridge = soapBridge;
        _soapAdapter = soapAdapter;
        _logger = logger;
    }

    [HttpPost("execute")]
    public async Task<ActionResult<MCPResponse>> ExecuteCommand(
        [FromBody] MCPCommand command,
        CancellationToken ct)
    {
        _logger.LogInformation("Recebido comando MCP para SOAP: {CommandId}", command.CommandId);

        var response = await _soapBridge.ExecuteSOAPCommandAsync(command, ct);

        return response.Status == ResponseStatus.Success 
            ? Ok(response) 
            : BadRequest(response);
    }

    [HttpPost("invoke")]
    public async Task<ActionResult<SOAPResponse>> InvokeService(
        [FromBody] SOAPMessage message,
        CancellationToken ct)
    {
        _logger.LogInformation(
            "Invocação direta SOAP: {Service}.{Operation}",
            message.ServiceName,
            message.OperationName);

        var response = await _soapAdapter.InvokeServiceAsync(message, ct);

        return response.Success ? Ok(response) : BadRequest(response);
    }

    [HttpGet("wsdl")]
    public async Task<ActionResult<WSDLServiceInfo>> GetServiceInfo(
        [FromQuery] string wsdlUrl,
        CancellationToken ct)
    {
        _logger.LogInformation("Obtendo informações WSDL: {WsdlUrl}", wsdlUrl);

        try
        {
            var serviceInfo = await _soapAdapter.GetServiceInfoAsync(wsdlUrl, ct);
            return Ok(serviceInfo);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao obter WSDL");
            return BadRequest(new { error = ex.Message });
        }
    }

    [HttpGet("health")]
    public IActionResult Health()
    {
        return Ok(new
        {
            Service = "MCP SOAP Bridge",
            Status = "Healthy",
            Timestamp = DateTime.UtcNow
        });
    }
}

7️⃣ Program.cs Configuration

// MCPPipeline.SOAP.API/Program.cs
using MCPPipeline.SOAP.Adapter.Services;
using MCPPipeline.SOAP.API.Services;

var builder = WebApplication.CreateBuilder(args);

// Adicionar serviços
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "MCP SOAP Bridge API",
        Version = "v1",
        Description = "API para integração MCP com serviços SOAP/WCF legados"
    });
});

// HTTP Client com configurações para SOAP
builder.Services.AddHttpClient<ISoapAdapterService, SoapAdapterService>(client =>
{
    client.Timeout = TimeSpan.FromSeconds(60);
    client.DefaultRequestHeaders.Add("User-Agent", "MCP-SOAP-Bridge/1.0");
})
.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
{
    ServerCertificateCustomValidationCallback = (message, cert, chain, errors) =>
    {
        // Em produção, validar certificado adequadamente
        return true;
    }
});

// Registrar serviços
builder.Services.AddScoped<IWsdlParser, WsdlParser>();
builder.Services.AddScoped<IMCPSoapBridge, MCPSoapBridge>();

// Polly para resiliência
builder.Services.AddHttpClient<ISoapAdapterService, SoapAdapterService>()
    .AddPolicyHandler(Policy
        .HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
        .WaitAndRetryAsync(3, retryAttempt => 
            TimeSpan.FromSeconds(Math.Pow(2, retryAttempt))))
    .AddPolicyHandler(Policy
        .TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(30)));

// OpenTelemetry
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddSource("MCPPipeline.SOAP")
        .AddOtlpExporter());

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

🔌 Cliente MCP para SOAP

Exemplo de Uso com Semantic Kernel

// MCPPipeline.SOAP.Client/MCPSoapPlugin.cs
using Microsoft.SemanticKernel;

namespace MCPPipeline.SOAP.Client;

public class MCPSoapPlugin
{
    private readonly HttpClient _httpClient;
    private readonly string _bridgeUrl;

    public MCPSoapPlugin(HttpClient httpClient, string bridgeUrl)
    {
        _httpClient = httpClient;
        _bridgeUrl = bridgeUrl;
    }

    [KernelFunction]
    [Description("Invoca um serviço SOAP legado através do MCP Bridge")]
    public async Task<string> InvokeSOAPServiceAsync(
        [Description("Nome do serviço SOAP")] string serviceName,
        [Description("Nome da operação")] string operationName,
        [Description("Parâmetros em formato JSON")] string parametersJson)
    {
        var command = new MCPCommand
        {
            Command = "invoke_soap",
            Payload = JsonSerializer.Serialize(new
            {
                ServiceName = serviceName,
                OperationName = operationName,
                Parameters = JsonSerializer.Deserialize<Dictionary<string, object>>(parametersJson)
            })
        };

        var response = await _httpClient.PostAsJsonAsync(
            $"{_bridgeUrl}/api/soapbridge/execute",
            command);

        response.EnsureSuccessStatusCode();

        var result = await response.Content.ReadFromJsonAsync<MCPResponse>();
        return result?.Result ?? "Sem resultado";
    }

    [KernelFunction]
    [Description("Consulta informações de um serviço SOAP através do WSDL")]
    public async Task<string> GetSOAPServiceInfoAsync(
        [Description("URL do WSDL")] string wsdlUrl)
    {
        var response = await _httpClient.GetAsync(
            $"{_bridgeUrl}/api/soapbridge/wsdl?wsdlUrl={Uri.EscapeDataString(wsdlUrl)}");

        response.EnsureSuccessStatusCode();

        var serviceInfo = await response.Content.ReadFromJsonAsync<WSDLServiceInfo>();

        if (serviceInfo == null)
            return "Não foi possível obter informações do serviço";

        return JsonSerializer.Serialize(new
        {
            serviceInfo.ServiceName,
            serviceInfo.Namespace,
            Operations = serviceInfo.Operations.Select(o => new
            {
                o.Name,
                InputCount = o.InputParameters.Count,
                HasOutput = o.OutputParameter != null
            })
        }, new JsonSerializerOptions { WriteIndented = true });
    }
}

// Exemplo de uso
public class Program
{
    public static async Task Main(string[] args)
    {
        var kernel = Kernel.CreateBuilder()
            .AddOpenAIChatCompletion("gpt-4", Environment.GetEnvironmentVariable("OPENAI_KEY")!)
            .Build();

        var httpClient = new HttpClient();
        var soapPlugin = new MCPSoapPlugin(httpClient, "https://localhost:5003");

        kernel.Plugins.AddFromObject(soapPlugin, "SOAPService");

        // Exemplo 1: Consultar informações de um serviço
        var wsdlInfo = await kernel.InvokeAsync(
            "SOAPService",
            "GetSOAPServiceInfoAsync",
            new KernelArguments
            {
                ["wsdlUrl"] = "https://legacy-service.company.com/CustomerService.svc?wsdl"
            });

        Console.WriteLine("📋 Informações do serviço:");
        Console.WriteLine(wsdlInfo);

        // Exemplo 2: Invocar operação SOAP
        var customerResult = await kernel.InvokeAsync(
            "SOAPService",
            "InvokeSOAPServiceAsync",
            new KernelArguments
            {
                ["serviceName"] = "CustomerService",
                ["operationName"] = "GetCustomerById",
                ["parametersJson"] = JsonSerializer.Serialize(new Dictionary<string, object>
                {
                    ["customerId"] = 12345
                })
            });

        Console.WriteLine("✅ Resultado da consulta:");
        Console.WriteLine(customerResult);
    }
}

🔒 Segurança WS-Security Avançada

Implementação de WS-Security com Certificados

// MCPPipeline.SOAP.Client/Security/WsSecurityHandler.cs
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Security.Cryptography.Xml;

namespace MCPPipeline.SOAP.Client.Security;

public interface IWsSecurityHandler
{
    XDocument SignSoapMessage(XDocument envelope, X509Certificate2 certificate);
    XDocument EncryptSoapMessage(XDocument envelope, X509Certificate2 certificate);
    bool VerifySignature(XDocument envelope, X509Certificate2 certificate);
}

public class WsSecurityHandler : IWsSecurityHandler
{
    private readonly ILogger<WsSecurityHandler> _logger;

    public WsSecurityHandler(ILogger<WsSecurityHandler> logger)
    {
        _logger = logger;
    }

    public XDocument SignSoapMessage(XDocument envelope, X509Certificate2 certificate)
    {
        try
        {
            _logger.LogInformation("Assinando mensagem SOAP");

            var xmlDoc = new XmlDocument();
            xmlDoc.LoadXml(envelope.ToString());

            // Criar assinatura XML
            var signedXml = new SignedXml(xmlDoc);
            signedXml.SigningKey = certificate.GetRSAPrivateKey();

            // Adicionar referência ao Body
            var reference = new Reference();
            reference.Uri = "#Body";
            reference.AddTransform(new XmlDsigExcC14NTransform());
            signedXml.AddReference(reference);

            // Adicionar informações da chave
            var keyInfo = new KeyInfo();
            keyInfo.AddClause(new KeyInfoX509Data(certificate));
            signedXml.KeyInfo = keyInfo;

            // Computar assinatura
            signedXml.ComputeSignature();

            // Adicionar assinatura ao header
            var ns = XNamespace.Get("http://schemas.xmlsoap.org/soap/envelope/");
            var wsse = XNamespace.Get("http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd");

            var header = envelope.Root!.Element(ns + "Header")!;
            var security = header.Element(wsse + "Security");

            if (security == null)
            {
                security = new XElement(wsse + "Security");
                header.Add(security);
            }

            // Converter assinatura para XElement
            var signatureElement = XElement.Parse(signedXml.GetXml().OuterXml);
            security.Add(signatureElement);

            _logger.LogInformation("Mensagem SOAP assinada com sucesso");
            return envelope;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao assinar mensagem SOAP");
            throw;
        }
    }

    public XDocument EncryptSoapMessage(XDocument envelope, X509Certificate2 certificate)
    {
        try
        {
            _logger.LogInformation("Criptografando mensagem SOAP");

            var xmlDoc = new XmlDocument();
            xmlDoc.LoadXml(envelope.ToString());

            var ns = new XmlNamespaceManager(xmlDoc.NameTable);
            ns.AddNamespace("soap", "http://schemas.xmlsoap.org/soap/envelope/");

            var body = xmlDoc.SelectSingleNode("//soap:Body", ns);

            if (body == null)
                throw new InvalidOperationException("SOAP Body não encontrado");

            // Criar encriptação XML
            var encryptedXml = new EncryptedXml(xmlDoc);

            // Usar chave pública do certificado
            var encryptedData = encryptedXml.Encrypt(
                body as XmlElement, 
                certificate.GetRSAPublicKey()!);

            // Substituir body original pelo criptografado
            EncryptedXml.ReplaceElement(body as XmlElement, encryptedData, false);

            _logger.LogInformation("Mensagem SOAP criptografada com sucesso");
            return XDocument.Parse(xmlDoc.OuterXml);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao criptografar mensagem SOAP");
            throw;
        }
    }

    public bool VerifySignature(XDocument envelope, X509Certificate2 certificate)
    {
        try
        {
            var xmlDoc = new XmlDocument();
            xmlDoc.LoadXml(envelope.ToString());

            var signedXml = new SignedXml(xmlDoc);

            var ns = new XmlNamespaceManager(xmlDoc.NameTable);
            ns.AddNamespace("ds", "http://www.w3.org/2000/09/xmldsig#");

            var signatureNode = xmlDoc.SelectSingleNode("//ds:Signature", ns);

            if (signatureNode == null)
            {
                _logger.LogWarning("Assinatura não encontrada na mensagem");
                return false;
            }

            signedXml.LoadXml(signatureNode as XmlElement);

            var isValid = signedXml.CheckSignature(certificate, true);

            _logger.LogInformation("Verificação de assinatura: {IsValid}", isValid);

            return isValid;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao verificar assinatura");
            return false;
        }
    }
}

// Certificate Manager
public interface ICertificateManager
{
    X509Certificate2 LoadCertificate(string thumbprint);
    X509Certificate2 LoadCertificateFromFile(string path, string password);
}

public class CertificateManager : ICertificateManager
{
    private readonly ILogger<CertificateManager> _logger;

    public CertificateManager(ILogger<CertificateManager> logger)
    {
        _logger = logger;
    }

    public X509Certificate2 LoadCertificate(string thumbprint)
    {
        using var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
        store.Open(OpenFlags.ReadOnly);

        var certificates = store.Certificates.Find(
            X509FindType.FindByThumbprint,
            thumbprint,
            validOnly: false);

        if (certificates.Count == 0)
        {
            _logger.LogError("Certificado não encontrado: {Thumbprint}", thumbprint);
            throw new InvalidOperationException($"Certificado não encontrado: {thumbprint}");
        }

        _logger.LogInformation("Certificado carregado: {Subject}", certificates[0].Subject);
        return certificates[0];
    }

    public X509Certificate2 LoadCertificateFromFile(string path, string password)
    {
        try
        {
            var certificate = new X509Certificate2(path, password, X509KeyStorageFlags.Exportable);

            _logger.LogInformation("Certificado carregado do arquivo: {Subject}", certificate.Subject);

            return certificate;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao carregar certificado do arquivo: {Path}", path);
            throw;
        }
    }
}

🧪 Testes de Integração

// MCPPipeline.SOAP.Tests/SoapAdapterTests.cs
using Xunit;
using Moq;
using Moq.Protected;

namespace MCPPipeline.SOAP.Tests;

public class SoapAdapterTests
{
    private readonly Mock<ILogger<SoapAdapterService>> _loggerMock;
    private readonly Mock<IWsdlParser> _wsdlParserMock;
    private readonly Mock<HttpMessageHandler> _httpHandlerMock;

    public SoapAdapterTests()
    {
        _loggerMock = new Mock<ILogger<SoapAdapterService>>();
        _wsdlParserMock = new Mock<IWsdlParser>();
        _httpHandlerMock = new Mock<HttpMessageHandler>();
    }

    [Fact]
    public async Task InvokeServiceAsync_Should_Return_Success_Response()
    {
        // Arrange
        var soapResponseXml = @"<?xml version=""1.0"" encoding=""utf-8""?>
            <soap:Envelope xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/"">
                <soap:Body>
                    <GetCustomerResponse xmlns=""http://tempuri.org/CustomerService"">
                        <GetCustomerResult>
                            <CustomerId>12345</CustomerId>
                            <Name>John Doe</Name>
                            <Email>john@example.com</Email>
                        </GetCustomerResult>
                    </GetCustomerResponse>
                </soap:Body>
            </soap:Envelope>";

        _httpHandlerMock
            .Protected()
            .Setup<Task<HttpResponseMessage>>(
                "SendAsync",
                ItExpr.IsAny<HttpRequestMessage>(),
                ItExpr.IsAny<CancellationToken>())
            .ReturnsAsync(new HttpResponseMessage
            {
                StatusCode = System.Net.HttpStatusCode.OK,
                Content = new StringContent(soapResponseXml)
            });

        var httpClient = new HttpClient(_httpHandlerMock.Object);
        var adapter = new SoapAdapterService(_loggerMock.Object, _wsdlParserMock.Object, httpClient);

        var message = new SOAPMessage
        {
            ServiceName = "CustomerService",
            OperationName = "GetCustomer",
            Parameters = new Dictionary<string, object>
            {
                ["customerId"] = 12345
            }
        };

        // Act
        var response = await adapter.InvokeServiceAsync(message, CancellationToken.None);

        // Assert
        Assert.True(response.Success);
        Assert.NotNull(response.Result);
        Assert.Equal(message.MessageId, response.MessageId);
    }

    [Fact]
    public async Task InvokeServiceAsync_Should_Handle_SoapFault()
    {
        // Arrange
        var faultXml = @"<?xml version=""1.0"" encoding=""utf-8""?>
            <soap:Envelope xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/"">
                <soap:Body>
                    <soap:Fault>
                        <faultcode>soap:Server</faultcode>
                        <faultstring>Customer not found</faultstring>
                    </soap:Fault>
                </soap:Body>
            </soap:Envelope>";

        _httpHandlerMock
            .Protected()
            .Setup<Task<HttpResponseMessage>>(
                "SendAsync",
                ItExpr.IsAny<HttpRequestMessage>(),
                ItExpr.IsAny<CancellationToken>())
            .ReturnsAsync(new HttpResponseMessage
            {
                StatusCode = System.Net.HttpStatusCode.InternalServerError,
                Content = new StringContent(faultXml)
            });

        var httpClient = new HttpClient(_httpHandlerMock.Object);
        var adapter = new SoapAdapterService(_loggerMock.Object, _wsdlParserMock.Object, httpClient);

        var message = new SOAPMessage
        {
            ServiceName = "CustomerService",
            OperationName = "GetCustomer",
            Parameters = new Dictionary<string, object>
            {
                ["customerId"] = 99999
            }
        };

        // Act
        var response = await adapter.InvokeServiceAsync(message, CancellationToken.None);

        // Assert
        Assert.False(response.Success);
        Assert.NotNull(response.FaultString);
        Assert.Contains("not found", response.FaultString, StringComparison.OrdinalIgnoreCase);
    }

    [Fact]
    public async Task GetServiceInfoAsync_Should_Parse_WSDL_Correctly()
    {
        // Arrange
        var wsdlContent = @"<?xml version=""1.0"" encoding=""utf-8""?>
            <definitions xmlns=""http://schemas.xmlsoap.org/wsdl/"" 
                        targetNamespace=""http://tempuri.org/CustomerService"">
                <service name=""CustomerService"">
                    <port name=""CustomerServicePort"" binding=""tns:CustomerServiceBinding"">
                        <soap:address location=""https://api.company.com/CustomerService"" 
                                     xmlns:soap=""http://schemas.xmlsoap.org/wsdl/soap/""/>
                    </port>
                </service>
            </definitions>";

        var expectedServiceInfo = new WSDLServiceInfo
        {
            ServiceName = "CustomerService",
            Namespace = "http://tempuri.org/CustomerService",
            EndpointUrl = "https://api.company.com/CustomerService",
            Operations = new List<WSDLOperation>()
        };

        _wsdlParserMock
            .Setup(p => p.Parse(wsdlContent))
            .Returns(expectedServiceInfo);

        _httpHandlerMock
            .Protected()
            .Setup<Task<HttpResponseMessage>>(
                "SendAsync",
                ItExpr.IsAny<HttpRequestMessage>(),
                ItExpr.IsAny<CancellationToken>())
            .ReturnsAsync(new HttpResponseMessage
            {
                StatusCode = System.Net.HttpStatusCode.OK,
                Content = new StringContent(wsdlContent)
            });

        var httpClient = new HttpClient(_httpHandlerMock.Object);
        var adapter = new SoapAdapterService(_loggerMock.Object, _wsdlParserMock.Object, httpClient);

        // Act
        var serviceInfo = await adapter.GetServiceInfoAsync(
            "https://api.company.com/CustomerService?wsdl",
            CancellationToken.None);

        // Assert
        Assert.Equal("CustomerService", serviceInfo.ServiceName);
        Assert.Equal("http://tempuri.org/CustomerService", serviceInfo.Namespace);
        Assert.Equal("https://api.company.com/CustomerService", serviceInfo.EndpointUrl);
    }
}

📊 Casos de Uso Reais

1. Integração com SAP via SOAP

public class SAPIntegrationService
{
    private readonly IMCPSoapBridge _soapBridge;
    private readonly ILogger<SAPIntegrationService> _logger;

    public SAPIntegrationService(
        IMCPSoapBridge soapBridge,
        ILogger<SAPIntegrationService> logger)
    {
        _soapBridge = soapBridge;
        _logger = logger;
    }

    public async Task<SAPCustomerData> GetCustomerFromSAPAsync(
        string customerId,
        CancellationToken ct)
    {
        _logger.LogInformation("Consultando cliente no SAP: {CustomerId}", customerId);

        var command = new MCPCommand
        {
            Command = "sap_get_customer",
            Payload = JsonSerializer.Serialize(new
            {
                ServiceName = "SAP_CustomerService",
                OperationName = "Z_GET_CUSTOMER_DATA",
                Parameters = new Dictionary<string, object>
                {
                    ["I_KUNNR"] = customerId, // Número do cliente SAP
                    ["I_BUKRS"] = "1000"      // Código da empresa
                },
                Security = new SOAPSecuritySettings
                {
                    Username = "SAP_USER",
                    Password = "SAP_PASS"
                }
            })
        };

        var response = await _soapBridge.ExecuteSOAPCommandAsync(command, ct);

        if (response.Status != ResponseStatus.Success)
        {
            throw new Exception($"Erro ao consultar SAP: {response.ErrorMessage}");
        }

        return JsonSerializer.Deserialize<SAPCustomerData>(response.Result)!;
    }

    public async Task<bool> CreateSalesOrderAsync(
        SAPSalesOrder order,
        CancellationToken ct)
    {
        _logger.LogInformation("Criando pedido de venda no SAP");

        var command = new MCPCommand
        {
            Command = "sap_create_order",
            Payload = JsonSerializer.Serialize(new
            {
                ServiceName = "SAP_SalesService",
                OperationName = "BAPI_SALESORDER_CREATEFROMDAT2",
                Parameters = new Dictionary<string, object>
                {
                    ["ORDER_HEADER_IN"] = order.Header,
                    ["ORDER_ITEMS_IN"] = order.Items,
                    ["ORDER_PARTNERS"] = order.Partners
                }
            })
        };

        var response = await _soapBridge.ExecuteSOAPCommandAsync(command, ct);
        return response.Status == ResponseStatus.Success;
    }
}

public record SAPCustomerData
{
    public string CustomerId { get; init; } = string.Empty;
    public string Name { get; init; } = string.Empty;
    public string Address { get; init; } = string.Empty;
    public string TaxId { get; init; } = string.Empty;
}

public record SAPSalesOrder
{
    public object Header { get; init; } = new();
    public List<object> Items { get; init; } = new();
    public List<object> Partners { get; init; } = new();
}

2. Integração com SEFAZ (Nota Fiscal Eletrônica)

public class SEFAZIntegrationService
{
    private readonly IMCPSoapBridge _soapBridge;
    private readonly ICertificateManager _certificateManager;
    private readonly ILogger<SEFAZIntegrationService> _logger;

    public SEFAZIntegrationService(
        IMCPSoapBridge soapBridge,
        ICertificateManager certificateManager,
        ILogger<SEFAZIntegrationService> logger)
    {
        _soapBridge = soapBridge;
        _certificateManager = certificateManager;
        _logger = logger;
    }

    public async Task<NFEAuthorizationResult> AuthorizeNFEAsync(
        string nfeXml,
        string certificateThumbprint,
        CancellationToken ct)
    {
        _logger.LogInformation("Enviando NF-e para autorização SEFAZ");

        // Carregar certificado digital A1
        var certificate = _certificateManager.LoadCertificate(certificateThumbprint);

        var command = new MCPCommand
        {
            Command = "sefaz_authorize_nfe",
            Payload = JsonSerializer.Serialize(new
            {
                ServiceName = "NFeAutorizacao4",
                OperationName = "nfeAutorizacaoLote",
                Parameters = new Dictionary<string, object>
                {
                    ["nfeDadosMsg"] = nfeXml
                },
                Security = new SOAPSecuritySettings
                {
                    CertificateThumbprint = certificateThumbprint,
                    RequireSignature = true,
                    RequireEncryption = false
                },
                TimeoutSeconds = 60
            })
        };

        var response = await _soapBridge.ExecuteSOAPCommandAsync(command, ct);

        if (response.Status != ResponseStatus.Success)
        {
            _logger.LogError("Erro na autorização SEFAZ: {Error}", response.ErrorMessage);
            throw new Exception($"Erro SEFAZ: {response.ErrorMessage}");
        }

        return ParseNFEResponse(response.Result);
    }

    public async Task<NFEStatusResult> ConsultNFEStatusAsync(
        string accessKey,
        string certificateThumbprint,
        CancellationToken ct)
    {
        _logger.LogInformation("Consultando status NF-e: {AccessKey}", accessKey);

        var command = new MCPCommand
        {
            Command = "sefaz_consult_nfe",
            Payload = JsonSerializer.Serialize(new
            {
                ServiceName = "NFeConsultaProtocolo4",
                OperationName = "nfeConsultaNF",
                Parameters = new Dictionary<string, object>
                {
                    ["chNFe"] = accessKey
                },
                Security = new SOAPSecuritySettings
                {
                    CertificateThumbprint = certificateThumbprint,
                    RequireSignature = true
                }
            })
        };

        var response = await _soapBridge.ExecuteSOAPCommandAsync(command, ct);

        if (response.Status != ResponseStatus.Success)
        {
            throw new Exception($"Erro ao consultar NF-e: {response.ErrorMessage}");
        }

        return ParseStatusResponse(response.Result);
    }

    private NFEAuthorizationResult ParseNFEResponse(string xmlResponse)
    {
        var doc = XDocument.Parse(xmlResponse);
        var ns = XNamespace.Get("http://www.portalfiscal.inf.br/nfe");

        var protNFe = doc.Descendants(ns + "protNFe").FirstOrDefault();

        if (protNFe == null)
            throw new Exception("Resposta SEFAZ inválida");

        return new NFEAuthorizationResult
        {
            Protocol = protNFe.Element(ns + "infProt")?.Element(ns + "nProt")?.Value ?? string.Empty,
            StatusCode = protNFe.Element(ns + "infProt")?.Element(ns + "cStat")?.Value ?? string.Empty,
            StatusMessage = protNFe.Element(ns + "infProt")?.Element(ns + "xMotivo")?.Value ?? string.Empty,
            AuthorizedAt = DateTime.Parse(protNFe.Element(ns + "infProt")?.Element(ns + "dhRecbto")?.Value ?? DateTime.Now.ToString())
        };
    }

    private NFEStatusResult ParseStatusResponse(string xmlResponse)
    {
        // Implementar parsing da resposta de consulta
        return new NFEStatusResult
        {
            Status = "Authorized",
            Message = "NF-e autorizada"
        };
    }
}

public record NFEAuthorizationResult
{
    public string Protocol { get; init; } = string.Empty;
    public string StatusCode { get; init; } = string.Empty;
    public string StatusMessage { get; init; } = string.Empty;
    public DateTime AuthorizedAt { get; init; }
}

public record NFEStatusResult
{
    public string Status { get; init; } = string.Empty;
    public string Message { get; init; } = string.Empty;
}

🔄 Migração Gradual: SOAP → REST/gRPC

Strategy Pattern para Abstração de Protocolo

// Abstração unificada para diferentes protocolos
public interface IServiceInvoker
{
    Task<ServiceResponse> InvokeAsync(ServiceRequest request, CancellationToken ct);
    string Protocol { get; }
}

// Implementação SOAP (legado)
public class SOAPServiceInvoker : IServiceInvoker
{
    private readonly ISoapAdapterService _soapAdapter;

    public string Protocol => "SOAP";

    public SOAPServiceInvoker(ISoapAdapterService soapAdapter)
    {
        _soapAdapter = soapAdapter;
    }

    public async Task<ServiceResponse> InvokeAsync(
        ServiceRequest request,
        CancellationToken ct)
    {
        var soapMessage = new SOAPMessage
        {
            ServiceName = request.ServiceName,
            OperationName = request.Operation,
            Parameters = request.Parameters
        };

        var soapResponse = await _soapAdapter.InvokeServiceAsync(soapMessage, ct);

        return new ServiceResponse
        {
            Success = soapResponse.Success,
            Data = soapResponse.Result,
            ErrorMessage = soapResponse.ErrorMessage
        };
    }
}

// Implementação REST (moderno)
public class RestServiceInvoker : IServiceInvoker
{
    private readonly HttpClient _httpClient;

    public string Protocol => "REST";

    public RestServiceInvoker(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<ServiceResponse> InvokeAsync(
        ServiceRequest request,
        CancellationToken ct)
    {
        var url = $"{request.ServiceName}/{request.Operation}";
        var content = new StringContent(
            JsonSerializer.Serialize(request.Parameters),
            Encoding.UTF8,
            "application/json");

        var response = await _httpClient.PostAsync(url, content, ct);
        var result = await response.Content.ReadAsStringAsync(ct);

        return new ServiceResponse
        {
            Success = response.IsSuccessStatusCode,
            Data = result,
            ErrorMessage = response.IsSuccessStatusCode ? null : response.ReasonPhrase
        };
    }
}

// Service Facade com roteamento inteligente
public class UnifiedServiceFacade
{
    private readonly Dictionary<string, IServiceInvoker> _invokers;
    private readonly ILogger<UnifiedServiceFacade> _logger;

    public UnifiedServiceFacade(
        IEnumerable<IServiceInvoker> invokers,
        ILogger<UnifiedServiceFacade> logger)
    {
        _invokers = invokers.ToDictionary(i => i.Protocol);
        _logger = logger;
    }

    public async Task<ServiceResponse> InvokeAsync(
        ServiceRequest request,
        CancellationToken ct)
    {
        // Determinar protocolo baseado no serviço
        var protocol = DetermineProtocol(request.ServiceName);

        if (!_invokers.TryGetValue(protocol, out var invoker))
        {
            throw new NotSupportedException($"Protocolo não suportado: {protocol}");
        }

        _logger.LogInformation(
            "Invocando {Service}.{Operation} via {Protocol}",
            request.ServiceName,
            request.Operation,
            protocol);

        return await invoker.InvokeAsync(request, ct);
    }

    private string DetermineProtocol(string serviceName)
    {
        // Mapeamento de serviços legados → SOAP
        var legacyServices = new HashSet<string>
        {
            "SAP_CustomerService",
            "Oracle_FinancialService",
            "Legacy_InventoryService"
        };

        return legacyServices.Contains(serviceName) ? "SOAP" : "REST";
    }
}

public record ServiceRequest
{
    public string ServiceName { get; init; } = string.Empty;
    public string Operation { get; init; } = string.Empty;
    public Dictionary<string, object> Parameters { get; init; } = new();
}

public record ServiceResponse
{
    public bool Success { get; init; }
    public object? Data { get; init; }
    public string? ErrorMessage { get; init; }
}

📈 Monitoramento e Observabilidade

Métricas Específicas para SOAP

// MCPPipeline.SOAP.Observability/SOAPMetrics.cs
using System.Diagnostics.Metrics;

public class SOAPMetrics
{
    private readonly Meter _meter;
    private readonly Counter<long> _soapCallsTotal;
    private readonly Counter<long> _soapFaultsTotal;
    private readonly Histogram<double> _soapCallDuration;
    private readonly Histogram<int> _soapMessageSize;
    private readonly Counter<long> _wssecurityOperations;

    public SOAPMetrics()
    {
        _meter = new Meter("MCPPipeline.SOAP", "1.0.0");

        _soapCallsTotal = _meter.CreateCounter<long>(
            "soap.calls.total",
            description: "Total de chamadas SOAP realizadas");

        _soapFaultsTotal = _meter.CreateCounter<long>(
            "soap.faults.total",
            description: "Total de SOAP Faults recebidos");

        _soapCallDuration = _meter.CreateHistogram<double>(
            "soap.call.duration",
            unit: "ms",
            description: "Duração das chamadas SOAP");

        _soapMessageSize = _meter.CreateHistogram<int>(
            "soap.message.size",
            unit: "bytes",
            description: "Tamanho das mensagens SOAP");

        _wssecurityOperations = _meter.CreateCounter<long>(
            "soap.wssecurity.operations",
            description: "Operações WS-Security realizadas");
    }

    public void RecordSOAPCall(
        string serviceName,
        string operation,
        bool success,
        double durationMs,
        int messageSizeBytes)
    {
        _soapCallsTotal.Add(1,
            new KeyValuePair<string, object?>("service", serviceName),
            new KeyValuePair<string, object?>("operation", operation),
            new KeyValuePair<string, object?>("success", success));

        _soapCallDuration.Record(durationMs,
            new KeyValuePair<string, object?>("service", serviceName),
            new KeyValuePair<string, object?>("operation", operation));

        _soapMessageSize.Record(messageSizeBytes,
            new KeyValuePair<string, object?>("service", serviceName));
    }

    public void RecordSOAPFault(string serviceName, string faultCode)
    {
        _soapFaultsTotal.Add(1,
            new KeyValuePair<string, object?>("service", serviceName),
            new KeyValuePair<string, object?>("fault_code", faultCode));
    }

    public void RecordWSSecurityOperation(string operation)
    {
        _wssecurityOperations.Add(1,
            new KeyValuePair<string, object?>("operation", operation));
    }
}

Dashboard Grafana para SOAP

{
  "dashboard": {
    "title": "MCP SOAP Integration Dashboard",
    "panels": [
      {
        "title": "Taxa de Chamadas SOAP",
        "targets": [{
          "expr": "rate(soap_calls_total[5m])",
          "legendFormat": "{{service}} - {{operation}}"
        }]
      },
      {
        "title": "Taxa de Erro (SOAP Faults)",
        "targets": [{
          "expr": "rate(soap_faults_total[5m]) / rate(soap_calls_total[5m]) * 100",
          "legendFormat": "{{service}}"
        }]
      },
      {
        "title": "Latência P95",
        "targets": [{
          "expr": "histogram_quantile(0.95, rate(soap_call_duration_bucket[5m]))",
          "legendFormat": "p95 - {{service}}"
        }]
      },
      {
        "title": "Tamanho Médio das Mensagens",
        "targets": [{
          "expr": "avg(soap_message_size) by (service)",
          "legendFormat": "{{service}}"
        }]
      },
      {
        "title": "Operações WS-Security",
        "targets": [{
          "expr": "rate(soap_wssecurity_operations[5m])",
          "legendFormat": "{{operation}}"
        }]
      },
      {
        "title": "Top 5 Serviços Mais Lentos",
        "targets": [{
          "expr": "topk(5, avg(soap_call_duration) by (service))",
          "legendFormat": "{{service}}"
        }]
      }
    ]
  }
}

🔧 Troubleshooting e Debugging

SOAP Message Interceptor

// MCPPipeline.SOAP.Diagnostics/SOAPMessageInterceptor.cs
public class SOAPMessageInterceptor : DelegatingHandler
{
    private readonly ILogger<SOAPMessageInterceptor> _logger;
    private readonly bool _logMessages;

    public SOAPMessageInterceptor(
        ILogger<SOAPMessageInterceptor> logger,
        bool logMessages = false)
    {
        _logger = logger;
        _logMessages = logMessages;
    }

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        var requestId = Guid.NewGuid().ToString("N");

        // Log da requisição
        if (_logMessages && request.Content != null)
        {
            var requestBody = await request.Content.ReadAsStringAsync(cancellationToken);
            _logger.LogDebug(
                "SOAP Request [{RequestId}] to {Url}:\n{Body}",
                requestId,
                request.RequestUri,
                FormatXml(requestBody));
        }

        var sw = Stopwatch.StartNew();

        try
        {
            var response = await base.SendAsync(request, cancellationToken);
            sw.Stop();

            // Log da resposta
            if (_logMessages && response.Content != null)
            {
                var responseBody = await response.Content.ReadAsStringAsync(cancellationToken);
                _logger.LogDebug(
                    "SOAP Response [{RequestId}] ({Duration}ms):\n{Body}",
                    requestId,
                    sw.ElapsedMilliseconds,
                    FormatXml(responseBody));
            }

            _logger.LogInformation(
                "SOAP Call [{RequestId}] completed in {Duration}ms with status {StatusCode}",
                requestId,
                sw.ElapsedMilliseconds,
                response.StatusCode);

            return response;
        }
        catch (Exception ex)
        {
            sw.Stop();
            _logger.LogError(ex,
                "SOAP Call [{RequestId}] failed after {Duration}ms",
                requestId,
                sw.ElapsedMilliseconds);
            throw;
        }
    }

    private string FormatXml(string xml)
    {
        try
        {
            var doc = XDocument.Parse(xml);
            return doc.ToString();
        }
        catch
        {
            return xml;
        }
    }
}

SOAP Fault Analyzer

public class SOAPFaultAnalyzer
{
    private readonly ILogger<SOAPFaultAnalyzer> _logger;

    public SOAPFaultAnalyzer(ILogger<SOAPFaultAnalyzer> logger)
    {
        _logger = logger;
    }

    public SOAPFaultDetails AnalyzeFault(string faultXml)
    {
        try
        {
            var doc = XDocument.Parse(faultXml);
            var ns = XNamespace.Get("http://schemas.xmlsoap.org/soap/envelope/");

            var fault = doc.Descendants(ns + "Fault").FirstOrDefault();

            if (fault == null)
                throw new InvalidOperationException("SOAP Fault não encontrado no XML");

            var faultCode = fault.Element(ns + "faultcode")?.Value ?? 
                           fault.Element("faultcode")?.Value ?? "Unknown";

            var faultString = fault.Element(ns + "faultstring")?.Value ?? 
                             fault.Element("faultstring")?.Value ?? "Unknown";

            var faultActor = fault.Element(ns + "faultactor")?.Value ?? 
                            fault.Element("faultactor")?.Value;

            var detail = fault.Element(ns + "detail")?.ToString() ?? 
                        fault.Element("detail")?.ToString();

            var category = CategorizeFault(faultCode);
            var suggestion = GetResolutionSuggestion(faultCode, faultString);

            _logger.LogWarning(
                "SOAP Fault analisado: Code={Code}, String={String}, Category={Category}",
                faultCode,
                faultString,
                category);

            return new SOAPFaultDetails
            {
                FaultCode = faultCode,
                FaultString = faultString,
                FaultActor = faultActor,
                Detail = detail,
                Category = category,
                Suggestion = suggestion,
                IsCritical = IsCriticalFault(faultCode)
            };
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao analisar SOAP Fault");
            throw;
        }
    }

    private FaultCategory CategorizeFault(string faultCode)
    {
        return faultCode.ToLowerInvariant() switch
        {
            var code when code.Contains("client") => FaultCategory.ClientError,
            var code when code.Contains("server") => FaultCategory.ServerError,
            var code when code.Contains("versionmismatch") => FaultCategory.ProtocolError,
            var code when code.Contains("mustunderstand") => FaultCategory.SecurityError,
            var code when code.Contains("authentication") => FaultCategory.AuthenticationError,
            var code when code.Contains("authorization") => FaultCategory.AuthorizationError,
            _ => FaultCategory.Unknown
        };
    }

    private string GetResolutionSuggestion(string faultCode, string faultString)
    {
        return faultCode.ToLowerInvariant() switch
        {
            var code when code.Contains("client") => 
                "Verifique os parâmetros enviados na requisição.",

            var code when code.Contains("server") => 
                "Erro no servidor. Verifique logs do serviço SOAP ou tente novamente.",

            var code when code.Contains("authentication") => 
                "Credenciais inválidas. Verifique username/password ou certificado.",

            var code when code.Contains("authorization") => 
                "Acesso negado. Verifique permissões do usuário/serviço.",

            var code when code.Contains("timeout") => 
                "Timeout excedido. Aumente o timeout ou verifique disponibilidade do serviço.",

            _ when faultString.Contains("not found", StringComparison.OrdinalIgnoreCase) =>
                "Recurso não encontrado. Verifique identificador enviado.",

            _ => "Consulte documentação do serviço SOAP ou entre em contato com suporte."
        };
    }

    private bool IsCriticalFault(string faultCode)
    {
        var criticalCodes = new[]
        {
            "server",
            "internal",
            "database",
            "fatal"
        };

        return criticalCodes.Any(c => 
            faultCode.Contains(c, StringComparison.OrdinalIgnoreCase));
    }
}

public record SOAPFaultDetails
{
    public string FaultCode { get; init; } = string.Empty;
    public string FaultString { get; init; } = string.Empty;
    public string? FaultActor { get; init; }
    public string? Detail { get; init; }
    public FaultCategory Category { get; init; }
    public string Suggestion { get; init; } = string.Empty;
    public bool IsCritical { get; init; }
}

public enum FaultCategory
{
    Unknown,
    ClientError,
    ServerError,
    ProtocolError,
    SecurityError,
    AuthenticationError,
    AuthorizationError
}

🚀 Performance Optimization

SOAP Message Caching

// MCPPipeline.SOAP.Caching/SOAPResponseCache.cs
using Microsoft.Extensions.Caching.Distributed;

public interface ISOAPResponseCache
{
    Task<SOAPResponse?> GetAsync(string cacheKey, CancellationToken ct);
    Task SetAsync(string cacheKey, SOAPResponse response, TimeSpan expiration, CancellationToken ct);
    string GenerateCacheKey(SOAPMessage message);
}

public class SOAPResponseCache : ISOAPResponseCache
{
    private readonly IDistributedCache _cache;
    private readonly ILogger<SOAPResponseCache> _logger;

    public SOAPResponseCache(
        IDistributedCache cache,
        ILogger<SOAPResponseCache> logger)
    {
        _cache = cache;
        _logger = logger;
    }

    public async Task<SOAPResponse?> GetAsync(string cacheKey, CancellationToken ct)
    {
        try
        {
            var cachedData = await _cache.GetStringAsync(cacheKey, ct);

            if (string.IsNullOrEmpty(cachedData))
                return null;

            _logger.LogDebug("Cache hit para chave: {CacheKey}", cacheKey);

            return JsonSerializer.Deserialize<SOAPResponse>(cachedData);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Erro ao recuperar do cache: {CacheKey}", cacheKey);
            return null;
        }
    }

    public async Task SetAsync(
        string cacheKey,
        SOAPResponse response,
        TimeSpan expiration,
        CancellationToken ct)
    {
        try
        {
            var serialized = JsonSerializer.Serialize(response);

            await _cache.SetStringAsync(
                cacheKey,
                serialized,
                new DistributedCacheEntryOptions
                {
                    AbsoluteExpirationRelativeToNow = expiration
                },
                ct);

            _logger.LogDebug(
                "Resposta armazenada no cache: {CacheKey} (expira em {Expiration}s)",
                cacheKey,
                expiration.TotalSeconds);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Erro ao armazenar no cache: {CacheKey}", cacheKey);
        }
    }

    public string GenerateCacheKey(SOAPMessage message)
    {
        var keyComponents = new[]
        {
            message.ServiceName,
            message.OperationName,
            JsonSerializer.Serialize(message.Parameters)
        };

        var combinedKey = string.Join("|", keyComponents);

        using var sha256 = SHA256.Create();
        var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(combinedKey));
        var hash = Convert.ToBase64String(hashBytes);

        return $"soap:{message.ServiceName}:{message.OperationName}:{hash}";
    }
}

// Uso com caching
public class CachedSoapAdapterService : ISoapAdapterService
{
    private readonly ISoapAdapterService _innerService;
    private readonly ISOAPResponseCache _cache;
    private readonly ILogger<CachedSoapAdapterService> _logger;

    public CachedSoapAdapterService(
        ISoapAdapterService innerService,
        ISOAPResponseCache cache,
        ILogger<CachedSoapAdapterService> logger)
    {
        _innerService = innerService;
        _cache = cache;
        _logger = logger;
    }

    public async Task<SOAPResponse> InvokeServiceAsync(
        SOAPMessage message,
        CancellationToken ct)
    {
        // Verificar se a operação é cacheável
        if (!IsCacheable(message))
        {
            return await _innerService.InvokeServiceAsync(message, ct);
        }

        var cacheKey = _cache.GenerateCacheKey(message);

        // Tentar obter do cache
        var cachedResponse = await _cache.GetAsync(cacheKey, ct);
        if (cachedResponse != null)
        {
            _logger.LogInformation(
                "Resposta SOAP obtida do cache: {Service}.{Operation}",
                message.ServiceName,
                message.OperationName);

            return cachedResponse;
        }

        // Executar chamada SOAP
        var response = await _innerService.InvokeServiceAsync(message, ct);

        // Armazenar em cache se bem-sucedido
        if (response.Success)
        {
            var expiration = GetCacheExpiration(message);
            await _cache.SetAsync(cacheKey, response, expiration, ct);
        }

        return response;
    }

    public Task<WSDLServiceInfo> GetServiceInfoAsync(string wsdlUrl, CancellationToken ct)
    {
        return _innerService.GetServiceInfoAsync(wsdlUrl, ct);
    }

    private bool IsCacheable(SOAPMessage message)
    {
        // Operações de leitura são cacheáveis
        var readOperations = new[]
        {
            "get", "list", "search", "query", "find", "retrieve", "consult"
        };

        return readOperations.Any(op =>
            message.OperationName.Contains(op, StringComparison.OrdinalIgnoreCase));
    }

    private TimeSpan GetCacheExpiration(SOAPMessage message)
    {
        // Configurar TTL baseado no tipo de operação
        return message.OperationName.ToLowerInvariant() switch
        {
            var op when op.Contains("list") => TimeSpan.FromMinutes(5),
            var op when op.Contains("search") => TimeSpan.FromMinutes(2),
            var op when op.Contains("get") => TimeSpan.FromMinutes(10),
            _ => TimeSpan.FromMinutes(1)
        };
    }
}

📝 Boas Práticas e Recomendações

✅ DOs

Validar WSDL antes de usar - Garanta que o contrato está correto
Implementar retry com backoff exponencial - Serviços legados podem ser instáveis
Usar circuit breaker - Proteja sua aplicação de falhas em cascata
Cachear respostas quando apropriado - Reduza carga em sistemas legados
Logar mensagens completas em dev - Facilita debugging
Usar WS-Security adequadamente - Especialmente em ambientes corporativos
Monitorar métricas específicas SOAP - Faults, latência, tamanho de mensagens
Documentar mapeamento de serviços - Mantenha inventário de integrações SOAP
Implementar health checks - Verifique disponibilidade dos serviços
Planejar migração gradual - Use strategy pattern para abstrair protocolos

❌ DON'Ts

Não ignore SOAP Faults - São diferentes de erros HTTP
Não use SOAP para novos serviços - Prefira REST ou gRPC
Não confie em timeouts padrão - Configure adequadamente
Não exponha SOAP diretamente ao frontend - Use uma camada de abstração
Não deixe certificados expirarem - Monitore validade
Não faça parse manual de XML - Use bibliotecas especializadas
Não ignore versionamento - WSDLs podem mudar
Não negligencie segurança - Use HTTPS e WS-Security
Não processe mensagens SOAP de forma síncrona - Use async/await
Não trate todos os serviços SOAP igual - Cada um tem suas peculiaridades

🎯 Conclusão

A integração do MCP com SOAP permite modernizar sistemas corporativos sem descontinuar infraestrutura legada crítica. Esta abordagem é essencial para:

✅ Preservar investimentos em sistemas SOAP/WCF existentes

✅ Habilitar IA em processos que dependem de serviços legados

✅ Facilitar migração gradual para arquiteturas modernas

✅ Manter conformidade com regulamentações que exigem protocolos específicos

✅ Integrar com parceiros que ainda usam SOAP como padrão

Principais benefícios da arquitetura apresentada:

🔌 Adaptador transparente - MCP não precisa conhecer SOAP
🔒 Segurança completa - Suporte a WS-Security e certificados
📊 Observabilidade total - Métricas e tracing específicos
⚡ Performance otimizada - Cache e retry inteligentes
🧪 Testabilidade - Mocks e testes de integração
🔄 Migração facilitada - Strategy pattern para abstrair protocolos

Próximos passos recomendados:

Inventariar todos os serviços SOAP da organização
Classificar por criticidade e frequência de uso
Implementar adaptadores para serviços mais usados
Configurar monitoramento e alertas
Planejar migração dos serviços menos críticos para REST/gRPC
Manter SOAP apenas onde regulamentação exigir

Na Parte 6 desta série, exploraremos "Observabilidade e Tracing Distribuído Unificado" integrando todos os protocolos (gRPC, WebSocket, SOAP) com OpenTelemetry, Jaeger e Grafana.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, observabilidade, DevOps ou interoperabilidade:

💼 LinkedIn
✍️ Medium
📬 contato@dopme.io
📬 devsfree@devsfree.com.br

📚 Referências:

💡 Recursos Adicionais:

SoapUI - Ferramenta para testes SOAP
Postman SOAP Support
Apache CXF - Framework SOAP para Java (comparação)
SOAP Security Cheat Sheet

²⁴ Os quais somos nós, a quem também chamou, não só dentre os judeus, mas também dentre os gentios? Romanos 9:24

🧩 Minha Primeira Comunicação com MCP e .NET – Parte 4

Danilo O. Pinheiro, dopme.io — Mon, 20 Oct 2025 19:53:04 +0000

Integração Completa com gRPC & WebSocket

Nesta quarta parte da série "Minha Primeira Comunicação com MCP e .NET", exploramos como criar uma arquitetura híbrida que combina o melhor dos dois mundos: a eficiência e tipagem forte do gRPC para comunicação interna entre serviços, e a flexibilidade e suporte nativo do WebSocket para clientes web e mobile, criando um ecossistema MCP robusto e escalável.

🚀 Introdução

Após explorarmos gRPC (Parte 2) e WebSocket (Parte 3) individualmente, surge uma questão arquitetural importante: e se precisarmos dos benefícios de ambos?

Em sistemas corporativos modernos, é comum ter:

Microsserviços backend que se comunicam via gRPC (baixa latência, tipagem forte)
Clientes web/mobile que precisam de WebSocket (suporte nativo, real-time)
Agentes MCP que podem usar ambos os protocolos conforme o contexto

Este artigo demonstra como construir uma arquitetura unificada que oferece ambos os protocolos, com roteamento inteligente, adaptadores de protocolo, e observabilidade centralizada.

🧠 Arquitetura Híbrida: O Melhor dos Dois Mundos

Visão Geral da Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                        API Gateway / BFF                         │
│                    (Protocol Orchestrator)                       │
└──────────────────┬─────────────────────┬────────────────────────┘
                   │                     │
         ┌─────────▼──────────┐ ┌───────▼──────────┐
         │   gRPC Endpoint    │ │ WebSocket Endpoint│
         │   (Port 5001)      │ │  (Port 5002)      │
         └─────────┬──────────┘ └───────┬───────────┘
                   │                     │
                   │    ┌────────────────┴─────────────────┐
                   │    │                                  │
         ┌─────────▼────▼──────────────┐    ┌─────────────▼──────┐
         │   Protocol Adapter Layer    │    │  SignalR Hub Layer  │
         │   (gRPC ↔ WebSocket)       │    │  (Client Manager)   │
         └─────────┬──────────────────┘    └─────────┬────────────┘
                   │                                  │
         ┌─────────▼──────────────────────────────────▼────────┐
         │              MCP Kernel Orchestrator                │
         │         (Unified Command Processing)                │
         └─────────┬──────────────────────────┬─────────────────┘
                   │                          │
         ┌─────────▼────────┐      ┌─────────▼──────────┐
         │  Domain Services │      │  Event Bus (Redis) │
         │  (Business Logic)│      │  (Cross-Protocol)  │
         └──────────────────┘      └────────────────────┘

Componentes Principais

Protocol Orchestrator - Decide qual protocolo usar baseado em contexto
Protocol Adapter Layer - Converte mensagens entre gRPC e WebSocket
Unified MCP Kernel - Processa comandos independente do protocolo
Event Bus - Sincroniza eventos entre instâncias e protocolos
Observability Layer - Tracing unificado para ambos os protocolos

🏗️ Implementação da Arquitetura Híbrida

1️⃣ Estrutura do Projeto

MCPPipeline.Hybrid/
├── src/
│   ├── MCPPipeline.Contracts/           # Modelos compartilhados
│   │   ├── Messages/
│   │   │   ├── MCPCommand.cs
│   │   │   ├── MCPResponse.cs
│   │   │   └── MCPEvent.cs
│   │   └── Protos/
│   │       └── mcp.proto
│   │
│   ├── MCPPipeline.Core/                # Lógica de negócio
│   │   ├── Services/
│   │   │   ├── IMCPKernelService.cs
│   │   │   └── MCPKernelService.cs
│   │   └── Events/
│   │       └── IEventBus.cs
│   │
│   ├── MCPPipeline.GrpcService/         # Endpoint gRPC
│   │   ├── Services/
│   │   │   └── MCPGrpcService.cs
│   │   └── Program.cs
│   │
│   ├── MCPPipeline.WebSocketService/    # Endpoint WebSocket
│   │   ├── Hubs/
│   │   │   └── MCPHub.cs
│   │   └── Program.cs
│   │
│   ├── MCPPipeline.Gateway/             # API Gateway (YARP)
│   │   ├── Configuration/
│   │   └── Program.cs
│   │
│   └── MCPPipeline.Adapter/             # Protocol Adapter
│       ├── GrpcToWebSocketAdapter.cs
│       └── WebSocketToGrpcAdapter.cs
│
└── tests/
    └── MCPPipeline.IntegrationTests/

2️⃣ Contratos Compartilhados

// MCPPipeline.Contracts/Messages/MCPCommand.cs
namespace MCPPipeline.Contracts.Messages;

public record MCPCommand
{
    public string CommandId { get; init; } = Guid.NewGuid().ToString();
    public string Command { get; init; } = string.Empty;
    public string Payload { get; init; } = string.Empty;
    public Dictionary<string, string> Metadata { get; init; } = new();
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
    public string SessionId { get; init; } = string.Empty;
    public ProtocolType Protocol { get; init; }
    public int Priority { get; init; } = 0;
}

public record MCPResponse
{
    public string CommandId { get; init; } = string.Empty;
    public string Result { get; init; } = string.Empty;
    public ResponseStatus Status { get; init; }
    public string? ErrorMessage { get; init; }
    public long ProcessingTimeMs { get; init; }
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
    public Dictionary<string, object> Metrics { get; init; } = new();
}

public record MCPEvent
{
    public string EventId { get; init; } = Guid.NewGuid().ToString();
    public string EventType { get; init; } = string.Empty;
    public string Source { get; init; } = string.Empty;
    public object Data { get; init; } = new();
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
}

public enum ProtocolType
{
    Unknown = 0,
    Grpc = 1,
    WebSocket = 2,
    Http = 3
}

public enum ResponseStatus
{
    Success,
    Error,
    Processing,
    Timeout
}

3️⃣ MCP Kernel Unificado

// MCPPipeline.Core/Services/MCPKernelService.cs
using MCPPipeline.Contracts.Messages;
using System.Diagnostics;

namespace MCPPipeline.Core.Services;

public interface IMCPKernelService
{
    Task<MCPResponse> ExecuteCommandAsync(MCPCommand command, CancellationToken ct);
    IAsyncEnumerable<string> StreamCommandAsync(MCPCommand command, CancellationToken ct);
}

public class MCPKernelService : IMCPKernelService
{
    private readonly ILogger<MCPKernelService> _logger;
    private readonly IEventBus _eventBus;
    private static readonly ActivitySource ActivitySource = new("MCPPipeline.Core");

    public MCPKernelService(
        ILogger<MCPKernelService> logger,
        IEventBus eventBus)
    {
        _logger = logger;
        _eventBus = eventBus;
    }

    public async Task<MCPResponse> ExecuteCommandAsync(
        MCPCommand command, 
        CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("ExecuteCommand");
        activity?.SetTag("command.id", command.CommandId);
        activity?.SetTag("command.type", command.Command);
        activity?.SetTag("protocol", command.Protocol.ToString());

        var sw = Stopwatch.StartNew();

        try
        {
            _logger.LogInformation(
                "Executando comando {Command} via {Protocol} | Session: {SessionId}",
                command.Command,
                command.Protocol,
                command.SessionId);

            // Publicar evento de início
            await _eventBus.PublishAsync(new MCPEvent
            {
                EventType = "CommandStarted",
                Source = command.Protocol.ToString(),
                Data = new { command.CommandId, command.Command }
            });

            // Processar comando
            var result = await ProcessCommandAsync(command, ct);

            sw.Stop();

            var response = new MCPResponse
            {
                CommandId = command.CommandId,
                Result = result,
                Status = ResponseStatus.Success,
                ProcessingTimeMs = sw.ElapsedMilliseconds,
                Metrics = new Dictionary<string, object>
                {
                    ["protocol"] = command.Protocol.ToString(),
                    ["priority"] = command.Priority
                }
            };

            // Publicar evento de conclusão
            await _eventBus.PublishAsync(new MCPEvent
            {
                EventType = "CommandCompleted",
                Source = command.Protocol.ToString(),
                Data = new { command.CommandId, response.ProcessingTimeMs }
            });

            activity?.SetTag("response.status", "success");
            return response;
        }
        catch (Exception ex)
        {
            sw.Stop();

            _logger.LogError(ex, 
                "Erro ao executar comando {Command} via {Protocol}", 
                command.Command, 
                command.Protocol);

            activity?.SetTag("response.status", "error");
            activity?.SetTag("error.message", ex.Message);

            await _eventBus.PublishAsync(new MCPEvent
            {
                EventType = "CommandFailed",
                Source = command.Protocol.ToString(),
                Data = new { command.CommandId, Error = ex.Message }
            });

            return new MCPResponse
            {
                CommandId = command.CommandId,
                Status = ResponseStatus.Error,
                ErrorMessage = ex.Message,
                ProcessingTimeMs = sw.ElapsedMilliseconds
            };
        }
    }

    public async IAsyncEnumerable<string> StreamCommandAsync(
        MCPCommand command,
        [EnumeratorCancellation] CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("StreamCommand");
        activity?.SetTag("command.id", command.CommandId);

        _logger.LogInformation(
            "Iniciando streaming para comando {Command} via {Protocol}",
            command.Command,
            command.Protocol);

        var chunks = await GenerateStreamChunksAsync(command.Payload, ct);

        for (int i = 0; i < chunks.Count; i++)
        {
            if (ct.IsCancellationRequested)
                yield break;

            yield return chunks[i];
            await Task.Delay(50, ct); // Simula processamento
        }
    }

    private async Task<string> ProcessCommandAsync(MCPCommand command, CancellationToken ct)
    {
        return command.Command.ToLowerInvariant() switch
        {
            "analyze" => await AnalyzeAsync(command.Payload, ct),
            "summarize" => await SummarizeAsync(command.Payload, ct),
            "translate" => await TranslateAsync(command.Payload, ct),
            "generate" => await GenerateAsync(command.Payload, ct),
            "status" => await GetStatusAsync(ct),
            _ => throw new InvalidOperationException($"Comando desconhecido: {command.Command}")
        };
    }

    private async Task<string> AnalyzeAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(200, ct);
        var words = payload.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
        return $"Análise: {words} palavras, {payload.Length} caracteres";
    }

    private async Task<string> SummarizeAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(300, ct);
        return payload.Length > 100 
            ? $"Resumo: {payload[..100]}..." 
            : $"Resumo: {payload}";
    }

    private async Task<string> TranslateAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(250, ct);
        return $"[Traduzido] {payload}";
    }

    private async Task<string> GenerateAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(500, ct);
        return $"Conteúdo gerado baseado em: {payload}";
    }

    private async Task<string> GetStatusAsync(CancellationToken ct)
    {
        await Task.Delay(50, ct);
        return $"Sistema operacional | Timestamp: {DateTime.UtcNow:O}";
    }

    private async Task<List<string>> GenerateStreamChunksAsync(string prompt, CancellationToken ct)
    {
        await Task.Delay(100, ct);
        return new List<string>
        {
            "Iniciando processamento...",
            "Analisando contexto...",
            "Gerando resposta...",
            $"Resultado: {prompt}",
            "Processamento concluído."
        };
    }
}

4️⃣ Event Bus com Redis

// MCPPipeline.Core/Events/IEventBus.cs
namespace MCPPipeline.Core.Events;

public interface IEventBus
{
    Task PublishAsync<T>(T @event) where T : class;
    Task SubscribeAsync<T>(Func<T, Task> handler) where T : class;
}

// MCPPipeline.Core/Events/RedisEventBus.cs
using StackExchange.Redis;
using System.Text.Json;

public class RedisEventBus : IEventBus
{
    private readonly IConnectionMultiplexer _redis;
    private readonly ILogger<RedisEventBus> _logger;
    private readonly ISubscriber _subscriber;

    public RedisEventBus(
        IConnectionMultiplexer redis,
        ILogger<RedisEventBus> logger)
    {
        _redis = redis;
        _logger = logger;
        _subscriber = redis.GetSubscriber();
    }

    public async Task PublishAsync<T>(T @event) where T : class
    {
        var channel = typeof(T).Name;
        var message = JsonSerializer.Serialize(@event);

        await _subscriber.PublishAsync(channel, message);

        _logger.LogDebug("Evento publicado: {EventType}", channel);
    }

    public async Task SubscribeAsync<T>(Func<T, Task> handler) where T : class
    {
        var channel = typeof(T).Name;

        await _subscriber.SubscribeAsync(channel, async (ch, message) =>
        {
            try
            {
                var @event = JsonSerializer.Deserialize<T>(message!);
                if (@event != null)
                {
                    await handler(@event);
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Erro ao processar evento {EventType}", channel);
            }
        });

        _logger.LogInformation("Inscrito no canal: {Channel}", channel);
    }
}

5️⃣ Protocol Adapter

// MCPPipeline.Adapter/ProtocolAdapter.cs
using MCPPipeline.Contracts.Messages;
using MCPPipeline.Grpc;

namespace MCPPipeline.Adapter;

public interface IProtocolAdapter
{
    MCPCommand FromGrpcRequest(MCPRequest grpcRequest);
    MCPRequest ToGrpcRequest(MCPCommand command);
    MCPResponse FromGrpcResponse(MCPGrpcResponse grpcResponse);
    MCPGrpcResponse ToGrpcResponse(MCPResponse response);
}

public class ProtocolAdapter : IProtocolAdapter
{
    public MCPCommand FromGrpcRequest(MCPRequest grpcRequest)
    {
        return new MCPCommand
        {
            Command = grpcRequest.Command,
            Payload = grpcRequest.Payload,
            Metadata = grpcRequest.Metadata.ToDictionary(k => k.Key, v => v.Value),
            Timestamp = DateTimeOffset.FromUnixTimeMilliseconds(grpcRequest.Timestamp).DateTime,
            Protocol = ProtocolType.Grpc
        };
    }

    public MCPRequest ToGrpcRequest(MCPCommand command)
    {
        return new MCPRequest
        {
            Command = command.Command,
            Payload = command.Payload,
            Metadata = { command.Metadata },
            Timestamp = new DateTimeOffset(command.Timestamp).ToUnixTimeMilliseconds()
        };
    }

    public MCPResponse FromGrpcResponse(MCPGrpcResponse grpcResponse)
    {
        return new MCPResponse
        {
            Result = grpcResponse.Result,
            Status = grpcResponse.Status switch
            {
                "OK" => ResponseStatus.Success,
                "ERROR" => ResponseStatus.Error,
                "PROCESSING" => ResponseStatus.Processing,
                _ => ResponseStatus.Error
            },
            ErrorMessage = grpcResponse.ErrorMessage,
            ProcessingTimeMs = grpcResponse.ProcessingTimeMs
        };
    }

    public MCPGrpcResponse ToGrpcResponse(MCPResponse response)
    {
        return new MCPGrpcResponse
        {
            Result = response.Result,
            Status = response.Status.ToString().ToUpperInvariant(),
            ErrorMessage = response.ErrorMessage ?? string.Empty,
            ProcessingTimeMs = response.ProcessingTimeMs
        };
    }
}

6️⃣ gRPC Service Endpoint

// MCPPipeline.GrpcService/Services/MCPGrpcService.cs
using Grpc.Core;
using MCPPipeline.Grpc;
using MCPPipeline.Core.Services;
using MCPPipeline.Adapter;

namespace MCPPipeline.GrpcService.Services;

public class MCPGrpcServiceImpl : MCPService.MCPServiceBase
{
    private readonly IMCPKernelService _kernelService;
    private readonly IProtocolAdapter _adapter;
    private readonly ILogger<MCPGrpcServiceImpl> _logger;

    public MCPGrpcServiceImpl(
        IMCPKernelService kernelService,
        IProtocolAdapter adapter,
        ILogger<MCPGrpcServiceImpl> logger)
    {
        _kernelService = kernelService;
        _adapter = adapter;
        _logger = logger;
    }

    public override async Task<MCPGrpcResponse> SendCommand(
        MCPRequest request,
        ServerCallContext context)
    {
        _logger.LogInformation(
            "Recebido comando gRPC: {Command} de {Peer}",
            request.Command,
            context.Peer);

        // Converter para modelo unificado
        var command = _adapter.FromGrpcRequest(request);
        command = command with { SessionId = context.Peer };

        // Processar via kernel unificado
        var response = await _kernelService.ExecuteCommandAsync(
            command,
            context.CancellationToken);

        // Converter resposta
        return _adapter.ToGrpcResponse(response);
    }

    public override async Task StreamCommand(
        MCPRequest request,
        IServerStreamWriter<MCPStreamResponse> responseStream,
        ServerCallContext context)
    {
        _logger.LogInformation(
            "Iniciando streaming gRPC: {Command}",
            request.Command);

        var command = _adapter.FromGrpcRequest(request);

        int chunkIndex = 0;
        await foreach (var chunk in _kernelService.StreamCommandAsync(
            command,
            context.CancellationToken))
        {
            await responseStream.WriteAsync(new MCPStreamResponse
            {
                Content = chunk,
                ChunkIndex = chunkIndex++,
                IsComplete = false
            });
        }

        // Enviar chunk final
        await responseStream.WriteAsync(new MCPStreamResponse
        {
            Content = "Stream concluído",
            ChunkIndex = chunkIndex,
            IsComplete = true
        });
    }

    public override Task<HealthResponse> HealthCheck(
        HealthRequest request,
        ServerCallContext context)
    {
        return Task.FromResult(new HealthResponse
        {
            Status = "Healthy",
            Version = "1.0.0",
            Protocol = "gRPC"
        });
    }
}

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGrpc();
builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();
builder.Services.AddSingleton<IProtocolAdapter, ProtocolAdapter>();

// Redis para event bus
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect("localhost:6379"));
builder.Services.AddSingleton<IEventBus, RedisEventBus>();

var app = builder.Build();

app.MapGrpcService<MCPGrpcServiceImpl>();
app.MapGet("/", () => "MCP gRPC Service");

app.Run();

7️⃣ WebSocket Service Endpoint

// MCPPipeline.WebSocketService/Hubs/MCPHub.cs
using Microsoft.AspNetCore.SignalR;
using MCPPipeline.Contracts.Messages;
using MCPPipeline.Core.Services;

namespace MCPPipeline.WebSocketService.Hubs;

public class MCPHub : Hub
{
    private readonly IMCPKernelService _kernelService;
    private readonly ILogger<MCPHub> _logger;

    public MCPHub(
        IMCPKernelService kernelService,
        ILogger<MCPHub> logger)
    {
        _kernelService = kernelService;
        _logger = logger;
    }

    public override async Task OnConnectedAsync()
    {
        _logger.LogInformation("Cliente WebSocket conectado: {ConnectionId}", 
            Context.ConnectionId);

        await Clients.Caller.SendAsync("Connected", new
        {
            ConnectionId = Context.ConnectionId,
            Protocol = "WebSocket",
            Message = "Conectado ao MCP Hub"
        });

        await base.OnConnectedAsync();
    }

    public async Task SendCommand(MCPCommand command)
    {
        _logger.LogInformation(
            "Recebido comando WebSocket: {Command} de {ConnectionId}",
            command.Command,
            Context.ConnectionId);

        // Enriquecer comando com dados do WebSocket
        var enrichedCommand = command with 
        { 
            Protocol = ProtocolType.WebSocket,
            SessionId = Context.ConnectionId
        };

        // Processar via kernel unificado
        var response = await _kernelService.ExecuteCommandAsync(
            enrichedCommand,
            Context.ConnectionAborted);

        // Enviar resposta
        await Clients.Caller.SendAsync("CommandResponse", response);
    }

    public async Task StreamCommand(MCPCommand command)
    {
        _logger.LogInformation(
            "Iniciando streaming WebSocket: {Command}",
            command.Command);

        var enrichedCommand = command with 
        { 
            Protocol = ProtocolType.WebSocket,
            SessionId = Context.ConnectionId
        };

        await foreach (var chunk in _kernelService.StreamCommandAsync(
            enrichedCommand,
            Context.ConnectionAborted))
        {
            await Clients.Caller.SendAsync("StreamChunk", new
            {
                Content = chunk,
                Timestamp = DateTime.UtcNow
            });
        }

        await Clients.Caller.SendAsync("StreamComplete", new
        {
            Message = "Streaming concluído"
        });
    }
}

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR();
builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();

// Redis para event bus
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect("localhost:6379"));
builder.Services.AddSingleton<IEventBus, RedisEventBus>();

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", policy =>
        policy.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader());
});

var app = builder.Build();

app.UseCors("AllowAll");
app.MapHub<MCPHub>("/mcphub");
app.MapGet("/", () => "MCP WebSocket Service");

app.Run();

8️⃣ API Gateway com YARP

// MCPPipeline.Gateway/Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();
app.MapGet("/", () => Results.Ok(new
{
    Service = "MCP Gateway",
    Endpoints = new
    {
        gRPC = "https://localhost:5001",
        WebSocket = "https://localhost:5002/mcphub"
    }
}));

app.Run();

// appsettings.json
{
  "ReverseProxy": {
    "Routes": {
      "grpc-route": {
        "ClusterId": "grpc-cluster",
        "Match": {
          "Path": "/grpc/{**catch-all}"
        }
      },
      "websocket-route": {
        "ClusterId": "websocket-cluster",
        "Match": {
          "Path": "/ws/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "grpc-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:5001"
          }
        }
      },
      "websocket-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:5002"
          }
        },
        "HttpRequest": {
          "Version": "1.1",
          "VersionPolicy": "RequestVersionOrLower"
        }
      }
    }
  }
}

9️⃣ Cliente Unificado

// MCPPipeline.Client/UnifiedMCPClient.cs
public class UnifiedMCPClient : IAsyncDisposable
{
    private readonly MCPService.MCPServiceClient? _grpcClient;
    private readonly HubConnection? _hubConnection;
    private readonly ILogger<UnifiedMCPClient> _logger;
    private readonly bool _useGrpc;

    public UnifiedMCPClient(
        string endpoint,
        bool useGrpc,
        ILogger<UnifiedMCPClient> logger)
    {
        _useGrpc = useGrpc;
        _logger = logger;

        if (useGrpc)
        {
            var channel = GrpcChannel.ForAddress(endpoint);
            _grpcClient = new MCPService.MCPServiceClient(channel);
            _logger.LogInformation("Cliente configurado para gRPC: {Endpoint}", endpoint);
        }
        else
        {
            _hubConnection = new HubConnectionBuilder()
                .WithUrl(endpoint)
                .WithAutomaticReconnect()
                .Build();

            SetupWebSocketHandlers();
            _logger.LogInformation("Cliente configurado para WebSocket: {Endpoint}", endpoint);
        }
    }

    public async Task ConnectAsync(CancellationToken ct = default)
    {
        if (!_useGrpc && _hubConnection != null)
        {
            await _hubConnection.StartAsync(ct);
            _logger.LogInformation("Conectado via WebSocket");
        }
    }

    public async Task<MCPResponse> SendCommandAsync(
        string command,
        string payload,
        CancellationToken ct = default)
    {
        if (_useGrpc && _grpcClient != null)
        {
            return await SendViaGrpcAsync(command, payload, ct);
        }
        else if (_hubConnection != null)
        {
            return await SendViaWebSocketAsync(command, payload, ct);
        }

        throw new InvalidOperationException("Cliente não inicializado");
    }

    private async Task<MCPResponse> SendViaGrpcAsync(
        string command,
        string payload,
        CancellationToken ct)
    {
        _logger.LogInformation("Enviando comando via gRPC: {Command}", command);

        var request = new MCPRequest
        {
            Command = command,
            Payload = payload,
            Timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
        };

        var response = await _grpcClient!.SendCommandAsync(request, cancellationToken: ct);

        return new MCPResponse
        {
            Result = response.Result,
            Status = response.Status == "OK" ? ResponseStatus.Success : ResponseStatus.Error,
            ErrorMessage = response.ErrorMessage,
            ProcessingTimeMs = response.ProcessingTimeMs
        };
    }

    private async Task<MCPResponse> SendViaWebSocketAsync(
        string command,
        string payload,
        CancellationToken ct)
    {
        _logger.LogInformation("Enviando comando via WebSocket: {Command}", command);

        var tcs = new TaskCompletionSource<MCPResponse>();

        void handler(MCPResponse response)
        {
            tcs.TrySetResult(response);
        }

        _hubConnection!.On<MCPResponse>("CommandResponse", handler);

        try
        {
            await _hubConnection.InvokeAsync("SendCommand", new MCPCommand
            {
                Command = command,
                Payload = payload,
                Timestamp = DateTime.UtcNow
            }, ct);

            return await tcs.Task.WaitAsync(TimeSpan.FromSeconds(30), ct);
        }
        finally
        {
            _hubConnection.Remove("CommandResponse");
        }
    }

    public async IAsyncEnumerable<string> StreamCommandAsync(
        string command,
        string payload,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        if (_useGrpc && _grpcClient != null)
        {
            await foreach (var chunk in StreamViaGrpcAsync(command, payload, ct))
            {
                yield return chunk;
            }
        }
        else if (_hubConnection != null)
        {
            await foreach (var chunk in StreamViaWebSocketAsync(command, payload, ct))
            {
                yield return chunk;
            }
        }
    }

    private async IAsyncEnumerable<string> StreamViaGrpcAsync(
        string command,
        string payload,
        [EnumeratorCancellation] CancellationToken ct)
    {
        var request = new MCPRequest
        {
            Command = command,
            Payload = payload,
            Timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
        };

        using var call = _grpcClient!.StreamCommand(request, cancellationToken: ct);

        await foreach (var response in call.ResponseStream.ReadAllAsync(ct))
        {
            yield return response.Content;
        }
    }

    private async IAsyncEnumerable<string> StreamViaWebSocketAsync(
        string command,
        string payload,
        [EnumeratorCancellation] CancellationToken ct)
    {
        var channel = Channel.CreateUnbounded<string>();

        _hubConnection!.On<dynamic>("StreamChunk", (chunk) =>
        {
            channel.Writer.TryWrite(chunk.Content.ToString());
        });

        _hubConnection.On<dynamic>("StreamComplete", (_) =>
        {
            channel.Writer.Complete();
        });

        await _hubConnection.InvokeAsync("StreamCommand", new MCPCommand
        {
            Command = command,
            Payload = payload,
            Timestamp = DateTime.UtcNow
        }, ct);

        await foreach (var chunk in channel.Reader.ReadAllAsync(ct))
        {
            yield return chunk;
        }
    }

    private void SetupWebSocketHandlers()
    {
        _hubConnection!.On<object>("Connected", data =>
        {
            _logger.LogInformation("✅ WebSocket conectado: {Data}", data);
        });

        _hubConnection.Reconnecting += error =>
        {
            _logger.LogWarning("⚠️ WebSocket reconectando: {Error}", error?.Message);
            return Task.CompletedTask;
        };

        _hubConnection.Reconnected += connectionId =>
        {
            _logger.LogInformation("✅ WebSocket reconectado: {ConnectionId}", connectionId);
            return Task.CompletedTask;
        };

        _hubConnection.Closed += error =>
        {
            _logger.LogError("❌ WebSocket fechado: {Error}", error?.Message);
            return Task.CompletedTask;
        };
    }

    public async ValueTask DisposeAsync()
    {
        if (_hubConnection != null)
        {
            await _hubConnection.StopAsync();
            await _hubConnection.DisposeAsync();
        }
    }
}

// Exemplo de uso
public class Program
{
    public static async Task Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
        var logger = loggerFactory.CreateLogger<UnifiedMCPClient>();

        // Cliente gRPC
        await using var grpcClient = new UnifiedMCPClient(
            "https://localhost:5001",
            useGrpc: true,
            logger);

        var response = await grpcClient.SendCommandAsync("analyze", "Teste via gRPC");
        Console.WriteLine($"gRPC: {response.Result}");

        // Cliente WebSocket
        await using var wsClient = new UnifiedMCPClient(
            "https://localhost:5002/mcphub",
            useGrpc: false,
            logger);

        await wsClient.ConnectAsync();

        response = await wsClient.SendCommandAsync("analyze", "Teste via WebSocket");
        Console.WriteLine($"WebSocket: {response.Result}");

        // Streaming
        await foreach (var chunk in wsClient.StreamCommandAsync("generate", "Prompt de teste"))
        {
            Console.WriteLine($"Chunk: {chunk}");
        }
    }
}

🔍 Observabilidade Unificada

OpenTelemetry Configuration

// MCPPipeline.Observability/OpenTelemetryExtensions.cs
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenTelemetry.Metrics;

public static class OpenTelemetryExtensions
{
    public static IServiceCollection AddMCPObservability(
        this IServiceCollection services,
        string serviceName)
    {
        services.AddOpenTelemetry()
            .ConfigureResource(resource =>
            {
                resource.AddService(
                    serviceName: serviceName,
                    serviceVersion: "1.0.0");
            })
            .WithTracing(tracing =>
            {
                tracing
                    .AddAspNetCoreInstrumentation(options =>
                    {
                        options.RecordException = true;
                        options.EnrichWithHttpRequest = (activity, request) =>
                        {
                            activity.SetTag("http.scheme", request.Scheme);
                            activity.SetTag("http.client_ip", request.HttpContext.Connection.RemoteIpAddress);
                        };
                    })
                    .AddGrpcClientInstrumentation()
                    .AddSource("MCPPipeline.Core")
                    .AddSource("MCPPipeline.GrpcService")
                    .AddSource("MCPPipeline.WebSocketService")
                    .AddOtlpExporter(options =>
                    {
                        options.Endpoint = new Uri("http://localhost:4317");
                    });
            })
            .WithMetrics(metrics =>
            {
                metrics
                    .AddAspNetCoreInstrumentation()
                    .AddRuntimeInstrumentation()
                    .AddMeter("MCPPipeline.*")
                    .AddPrometheusExporter()
                    .AddOtlpExporter();
            });

        return services;
    }
}

// Uso nos serviços
builder.Services.AddMCPObservability("MCPPipeline.GrpcService");

Métricas Customizadas

// MCPPipeline.Observability/MCPMetrics.cs
using System.Diagnostics.Metrics;

public class MCPMetrics
{
    private readonly Meter _meter;
    private readonly Counter<long> _commandsProcessed;
    private readonly Histogram<double> _commandDuration;
    private readonly Counter<long> _commandErrors;
    private readonly UpDownCounter<int> _activeConnections;

    public MCPMetrics()
    {
        _meter = new Meter("MCPPipeline.Metrics", "1.0.0");

        _commandsProcessed = _meter.CreateCounter<long>(
            "mcp.commands.processed",
            description: "Total de comandos processados");

        _commandDuration = _meter.CreateHistogram<double>(
            "mcp.command.duration",
            unit: "ms",
            description: "Duração do processamento de comandos");

        _commandErrors = _meter.CreateCounter<long>(
            "mcp.commands.errors",
            description: "Total de erros no processamento");

        _activeConnections = _meter.CreateUpDownCounter<int>(
            "mcp.connections.active",
            description: "Conexões ativas");
    }

    public void RecordCommandProcessed(string command, ProtocolType protocol)
    {
        _commandsProcessed.Add(1,
            new KeyValuePair<string, object?>("command", command),
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }

    public void RecordCommandDuration(string command, ProtocolType protocol, double durationMs)
    {
        _commandDuration.Record(durationMs,
            new KeyValuePair<string, object?>("command", command),
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }

    public void RecordCommandError(string command, ProtocolType protocol, string errorType)
    {
        _commandErrors.Add(1,
            new KeyValuePair<string, object?>("command", command),
            new KeyValuePair<string, object?>("protocol", protocol.ToString()),
            new KeyValuePair<string, object?>("error_type", errorType));
    }

    public void IncrementActiveConnections(ProtocolType protocol)
    {
        _activeConnections.Add(1,
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }

    public void DecrementActiveConnections(ProtocolType protocol)
    {
        _activeConnections.Add(-1,
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }
}

📊 Dashboard com Grafana

Prometheus Configuration

# prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'mcp-grpc-service'
    static_configs:
      - targets: ['localhost:5001']

  - job_name: 'mcp-websocket-service'
    static_configs:
      - targets: ['localhost:5002']

  - job_name: 'mcp-gateway'
    static_configs:
      - targets: ['localhost:5000']

Grafana Dashboard JSON

{
  "dashboard": {
    "title": "MCP Hybrid Protocol Dashboard",
    "panels": [
      {
        "title": "Comandos Processados por Protocolo",
        "targets": [
          {
            "expr": "rate(mcp_commands_processed_total[5m])",
            "legendFormat": "{{protocol}}"
          }
        ]
      },
      {
        "title": "Latência Média por Comando",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(mcp_command_duration_bucket[5m]))",
            "legendFormat": "p95 - {{command}}"
          }
        ]
      },
      {
        "title": "Conexões Ativas",
        "targets": [
          {
            "expr": "mcp_connections_active",
            "legendFormat": "{{protocol}}"
          }
        ]
      },
      {
        "title": "Taxa de Erro",
        "targets": [
          {
            "expr": "rate(mcp_commands_errors_total[5m])",
            "legendFormat": "{{protocol}} - {{error_type}}"
          }
        ]
      }
    ]
  }
}

🧪 Testes de Integração

Teste Híbrido

// MCPPipeline.IntegrationTests/HybridProtocolTests.cs
public class HybridProtocolTests : IClassFixture<MCPTestFixture>
{
    private readonly MCPTestFixture _fixture;

    public HybridProtocolTests(MCPTestFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    public async Task Should_Process_Same_Command_Via_Both_Protocols()
    {
        // Arrange
        var grpcClient = _fixture.CreateGrpcClient();
        var wsClient = _fixture.CreateWebSocketClient();

        await wsClient.ConnectAsync();

        var testPayload = "Teste de integração híbrida";

        // Act
        var grpcResponse = await grpcClient.SendCommandAsync("analyze", testPayload);
        var wsResponse = await wsClient.SendCommandAsync("analyze", testPayload);

        // Assert
        Assert.Equal(ResponseStatus.Success, grpcResponse.Status);
        Assert.Equal(ResponseStatus.Success, wsResponse.Status);

        // Ambos devem retornar resultados equivalentes
        Assert.Contains("palavras", grpcResponse.Result);
        Assert.Contains("palavras", wsResponse.Result);
    }

    [Fact]
    public async Task Should_Handle_Concurrent_Requests_From_Both_Protocols()
    {
        // Arrange
        var grpcClient = _fixture.CreateGrpcClient();
        var wsClient = _fixture.CreateWebSocketClient();
        await wsClient.ConnectAsync();

        var tasks = new List<Task<MCPResponse>>();

        // Act - Enviar 50 requisições concorrentes de cada protocolo
        for (int i = 0; i < 50; i++)
        {
            tasks.Add(grpcClient.SendCommandAsync("status", $"gRPC-{i}"));
            tasks.Add(wsClient.SendCommandAsync("status", $"WS-{i}"));
        }

        var responses = await Task.WhenAll(tasks);

        // Assert
        Assert.All(responses, r => Assert.Equal(ResponseStatus.Success, r.Status));
        Assert.Equal(100, responses.Length);
    }

    [Fact]
    public async Task Should_Broadcast_Events_Between_Protocols()
    {
        // Arrange
        var grpcClient = _fixture.CreateGrpcClient();
        var wsClient = _fixture.CreateWebSocketClient();
        await wsClient.ConnectAsync();

        var eventReceived = new TaskCompletionSource<bool>();

        // Configurar listener no WebSocket
        // (implementação depende do event bus)

        // Act - Enviar comando via gRPC
        await grpcClient.SendCommandAsync("generate", "Teste de evento");

        // Assert - WebSocket deve receber notificação
        var received = await eventReceived.Task.WaitAsync(TimeSpan.FromSeconds(5));
        Assert.True(received);
    }
}

public class MCPTestFixture : IAsyncLifetime
{
    private WebApplication? _grpcApp;
    private WebApplication? _wsApp;

    public async Task InitializeAsync()
    {
        // Inicializar serviços de teste
        _grpcApp = CreateGrpcService();
        _wsApp = CreateWebSocketService();

        await _grpcApp.StartAsync();
        await _wsApp.StartAsync();
    }

    public async Task DisposeAsync()
    {
        if (_grpcApp != null) await _grpcApp.StopAsync();
        if (_wsApp != null) await _wsApp.StopAsync();
    }

    public UnifiedMCPClient CreateGrpcClient()
    {
        return new UnifiedMCPClient(
            "https://localhost:5001",
            useGrpc: true,
            Mock.Of<ILogger<UnifiedMCPClient>>());
    }

    public UnifiedMCPClient CreateWebSocketClient()
    {
        return new UnifiedMCPClient(
            "https://localhost:5002/mcphub",
            useGrpc: false,
            Mock.Of<ILogger<UnifiedMCPClient>>());
    }

    private WebApplication CreateGrpcService()
    {
        var builder = WebApplication.CreateBuilder();
        builder.Services.AddGrpc();
        builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();
        builder.Services.AddSingleton<IProtocolAdapter, ProtocolAdapter>();

        var app = builder.Build();
        app.MapGrpcService<MCPGrpcServiceImpl>();
        return app;
    }

    private WebApplication CreateWebSocketService()
    {
        var builder = WebApplication.CreateBuilder();
        builder.Services.AddSignalR();
        builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();

        var app = builder.Build();
        app.MapHub<MCPHub>("/mcphub");
        return app;
    }
}

🚀 Teste de Performance

Benchmark com BenchmarkDotNet

// MCPPipeline.Benchmarks/ProtocolBenchmarks.cs
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

[MemoryDiagnoser]
[SimpleJob(warmupCount: 3, iterationCount: 10)]
public class ProtocolBenchmarks
{
    private UnifiedMCPClient _grpcClient = null!;
    private UnifiedMCPClient _wsClient = null!;

    [GlobalSetup]
    public async Task Setup()
    {
        _grpcClient = new UnifiedMCPClient(
            "https://localhost:5001",
            useGrpc: true,
            Mock.Of<ILogger<UnifiedMCPClient>>());

        _wsClient = new UnifiedMCPClient(
            "https://localhost:5002/mcphub",
            useGrpc: false,
            Mock.Of<ILogger<UnifiedMCPClient>>());

        await _wsClient.ConnectAsync();
    }

    [Benchmark(Baseline = true)]
    public async Task<MCPResponse> GrpcCommand()
    {
        return await _grpcClient.SendCommandAsync("status", "benchmark");
    }

    [Benchmark]
    public async Task<MCPResponse> WebSocketCommand()
    {
        return await _wsClient.SendCommandAsync("status", "benchmark");
    }

    [Benchmark]
    public async Task GrpcStreaming()
    {
        await foreach (var _ in _grpcClient.StreamCommandAsync("generate", "test"))
        {
            // Consumir stream
        }
    }

    [Benchmark]
    public async Task WebSocketStreaming()
    {
        await foreach (var _ in _wsClient.StreamCommandAsync("generate", "test"))
        {
            // Consumir stream
        }
    }

    [GlobalCleanup]
    public async Task Cleanup()
    {
        await _grpcClient.DisposeAsync();
        await _wsClient.DisposeAsync();
    }
}

// Program.cs
public class Program
{
    public static void Main(string[] args)
    {
        BenchmarkRunner.Run<ProtocolBenchmarks>();
    }
}

Resultados Esperados

|            Method |      Mean |     Error |    StdDev | Ratio | Gen0 | Allocated |
|------------------ |----------:|----------:|----------:|------:|-----:|----------:|
|       GrpcCommand |  2.450 ms | 0.0421 ms | 0.0394 ms |  1.00 | 15.6 |     128KB |
|  WebSocketCommand |  8.732 ms | 0.1523 ms | 0.1425 ms |  3.56 | 31.2 |     256KB |
|     GrpcStreaming | 12.105 ms | 0.2103 ms | 0.1967 ms |  4.94 | 46.8 |     384KB |
| WebSocketStreaming| 18.421 ms | 0.3142 ms | 0.2940 ms |  7.52 | 62.5 |     512KB |

🎯 Decisão de Protocolo: Quando Usar Cada Um

Matriz de Decisão

public class ProtocolSelector
{
    public ProtocolType SelectOptimalProtocol(ClientContext context)
    {
        // 1. Cliente é navegador? → WebSocket
        if (context.IsWebBrowser)
            return ProtocolType.WebSocket;

        // 2. Comunicação interna entre serviços? → gRPC
        if (context.IsInternalService)
            return ProtocolType.Grpc;

        // 3. Requer streaming bidirecional de longa duração? → WebSocket
        if (context.RequiresLongLivedStream)
            return ProtocolType.WebSocket;

        // 4. Prioriza latência mínima? → gRPC
        if (context.LatencySensitive)
            return ProtocolType.Grpc;

        // 5. Múltiplos clientes precisam receber broadcasts? → WebSocket
        if (context.RequiresBroadcast)
            return ProtocolType.WebSocket;

        // 6. Padrão: gRPC para performance
        return ProtocolType.Grpc;
    }
}

public record ClientContext
{
    public bool IsWebBrowser { get; init; }
    public bool IsInternalService { get; init; }
    public bool RequiresLongLivedStream { get; init; }
    public bool LatencySensitive { get; init; }
    public bool RequiresBroadcast { get; init; }
}

Tabela Comparativa

Cenário	gRPC	WebSocket	Recomendação
API Backend → Backend	✅ Ideal	⚠️ Overhead	gRPC
Aplicação Web → Backend	❌ Limitado	✅ Nativo	WebSocket
Mobile App → Backend	✅ Excelente	✅ Bom	gRPC (melhor performance)
Dashboard Real-time	⚠️ Polling	✅ Push nativo	WebSocket
Chat Multi-usuário	❌ Não ideal	✅ Perfeito	WebSocket
Análise de Dados	✅ Alta performance	⚠️ Mais lento	gRPC
Streaming de IA	✅ Eficiente	✅ Funcional	Ambos (contexto dependente)

🔒 Segurança em Ambiente Híbrido

Autenticação Unificada

// MCPPipeline.Security/UnifiedAuthenticationExtensions.cs
public static class UnifiedAuthenticationExtensions
{
    public static IServiceCollection AddUnifiedAuthentication(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = configuration["Jwt:Issuer"],
                ValidAudience = configuration["Jwt:Audience"],
                IssuerSigningKey = new SymmetricSecurityKey(
                    Encoding.UTF8.GetBytes(configuration["Jwt:Key"]!))
            };

            // Suporte para WebSocket token via query string
            options.Events = new JwtBearerEvents
            {
                OnMessageReceived = context =>
                {
                    var accessToken = context.Request.Query["access_token"];
                    var path = context.HttpContext.Request.Path;

                    if (!string.IsNullOrEmpty(accessToken) && 
                        path.StartsWithSegments("/mcphub"))
                    {
                        context.Token = accessToken;
                    }
                    return Task.CompletedTask;
                }
            };
        });

        // Adicionar metadata para gRPC
        services.AddGrpc(options =>
        {
            options.Interceptors.Add<AuthenticationInterceptor>();
        });

        return services;
    }
}

// Interceptor para gRPC
public class AuthenticationInterceptor : Interceptor
{
    private readonly ILogger<AuthenticationInterceptor> _logger;

    public AuthenticationInterceptor(ILogger<AuthenticationInterceptor> logger)
    {
        _logger = logger;
    }

    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request,
        ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        var authHeader = context.RequestHeaders.GetValue("authorization");

        if (string.IsNullOrEmpty(authHeader))
        {
            _logger.LogWarning("Requisição gRPC sem autenticação


public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request,
        ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        var authHeader = context.RequestHeaders.GetValue("authorization");

        if (string.IsNullOrEmpty(authHeader))
        {
            _logger.LogWarning("Requisição gRPC sem autenticação");
            throw new RpcException(new Status(StatusCode.Unauthenticated, "Token não fornecido"));
        }

        // Validar token (implementar lógica de validação)
        _logger.LogInformation("Token gRPC validado para peer: {Peer}", context.Peer);

        return await continuation(request, context);
    }
}

Rate Limiting Unificado

// MCPPipeline.Security/RateLimitingExtensions.cs
using System.Threading.RateLimiting;

public static class RateLimitingExtensions
{
    public static IServiceCollection AddUnifiedRateLimiting(
        this IServiceCollection services)
    {
        services.AddRateLimiter(options =>
        {
            // Policy para gRPC
            options.AddFixedWindowLimiter("grpc", limiterOptions =>
            {
                limiterOptions.PermitLimit = 100;
                limiterOptions.Window = TimeSpan.FromMinutes(1);
                limiterOptions.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
                limiterOptions.QueueLimit = 10;
            });

            // Policy para WebSocket
            options.AddSlidingWindowLimiter("websocket", limiterOptions =>
            {
                limiterOptions.PermitLimit = 60;
                limiterOptions.Window = TimeSpan.FromMinutes(1);
                limiterOptions.SegmentsPerWindow = 4;
                limiterOptions.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
                limiterOptions.QueueLimit = 5;
            });

            options.OnRejected = async (context, token) =>
            {
                context.HttpContext.Response.StatusCode = 429;

                await context.HttpContext.Response.WriteAsJsonAsync(new
                {
                    error = "Rate limit exceeded",
                    retryAfter = context.Lease.TryGetMetadata(
                        MetadataName.RetryAfter, out var retryAfter) 
                        ? retryAfter.TotalSeconds 
                        : null
                }, token);
            };
        });

        return services;
    }
}

🏗️ Docker Compose para Ambiente Completo

# docker-compose.yml
version: '3.8'

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"  # UI
      - "4317:4317"    # OTLP gRPC
      - "4318:4318"    # OTLP HTTP
    environment:
      - COLLECTOR_OTLP_ENABLED=true

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_USERS_ALLOW_SIGN_UP=false

  mcp-grpc-service:
    build:
      context: .
      dockerfile: src/MCPPipeline.GrpcService/Dockerfile
    ports:
      - "5001:5001"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - Redis__ConnectionString=redis:6379
      - Jaeger__AgentHost=jaeger
      - Jaeger__AgentPort=4317
    depends_on:
      - redis
      - jaeger

  mcp-websocket-service:
    build:
      context: .
      dockerfile: src/MCPPipeline.WebSocketService/Dockerfile
    ports:
      - "5002:5002"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - Redis__ConnectionString=redis:6379
      - Jaeger__AgentHost=jaeger
      - Jaeger__AgentPort=4317
    depends_on:
      - redis
      - jaeger

  mcp-gateway:
    build:
      context: .
      dockerfile: src/MCPPipeline.Gateway/Dockerfile
    ports:
      - "5000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
    depends_on:
      - mcp-grpc-service
      - mcp-websocket-service

volumes:
  redis-data:
  prometheus-data:
  grafana-data:

📈 Estratégias de Escalabilidade

Kubernetes Deployment

# k8s/mcp-deployment.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: mcp-config
data:
  redis-connection: "redis-service:6379"
  jaeger-endpoint: "http://jaeger-collector:4317"

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-grpc-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-grpc
  template:
    metadata:
      labels:
        app: mcp-grpc
    spec:
      containers:
      - name: mcp-grpc
        image: mcp-grpc-service:latest# 🧩 Minha Primeira Comunicação com MCP e .NET – Parte 4

Integração Completa com gRPC & WebSocket

Nesta quarta parte da série "Minha Primeira Comunicação com MCP e .NET", exploramos como criar uma arquitetura híbrida que combina o melhor dos dois mundos: a eficiência e tipagem forte do gRPC para comunicação interna entre serviços, e a flexibilidade e suporte nativo do WebSocket para clientes web e mobile, criando um ecossistema MCP robusto e escalável.

🚀 Introdução

Após explorarmos gRPC (Parte 2) e WebSocket (Parte 3) individualmente, surge uma questão arquitetural importante: e se precisarmos dos benefícios de ambos?

Em sistemas corporativos modernos, é comum ter:

Microsserviços backend que se comunicam via gRPC (baixa latência, tipagem forte)
Clientes web/mobile que precisam de WebSocket (suporte nativo, real-time)
Agentes MCP que podem usar ambos os protocolos conforme o contexto

Este artigo demonstra como construir uma arquitetura unificada que oferece ambos os protocolos, com roteamento inteligente, adaptadores de protocolo, e observabilidade centralizada.

🧠 Arquitetura Híbrida: O Melhor dos Dois Mundos

Visão Geral da Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                        API Gateway / BFF                         │
│                    (Protocol Orchestrator)                       │
└──────────────────┬─────────────────────┬────────────────────────┘
                   │                     │
         ┌─────────▼──────────┐ ┌───────▼──────────┐
         │   gRPC Endpoint    │ │ WebSocket Endpoint│
         │   (Port 5001)      │ │  (Port 5002)      │
         └─────────┬──────────┘ └───────┬───────────┘
                   │                     │
                   │    ┌────────────────┴─────────────────┐
                   │    │                                  │
         ┌─────────▼────▼──────────────┐    ┌─────────────▼──────┐
         │   Protocol Adapter Layer    │    │  SignalR Hub Layer  │
         │   (gRPC ↔ WebSocket)       │    │  (Client Manager)   │
         └─────────┬──────────────────┘    └─────────┬────────────┘
                   │                                  │
         ┌─────────▼──────────────────────────────────▼────────┐
         │              MCP Kernel Orchestrator                │
         │         (Unified Command Processing)                │
         └─────────┬──────────────────────────┬─────────────────┘
                   │                          │
         ┌─────────▼────────┐      ┌─────────▼──────────┐
         │  Domain Services │      │  Event Bus (Redis) │
         │  (Business Logic)│      │  (Cross-Protocol)  │
         └──────────────────┘      └────────────────────┘

Componentes Principais

Protocol Orchestrator - Decide qual protocolo usar baseado em contexto
Protocol Adapter Layer - Converte mensagens entre gRPC e WebSocket
Unified MCP Kernel - Processa comandos independente do protocolo
Event Bus - Sincroniza eventos entre instâncias e protocolos
Observability Layer - Tracing unificado para ambos os protocolos

🏗️ Implementação da Arquitetura Híbrida

1️⃣ Estrutura do Projeto

MCPPipeline.Hybrid/
├── src/
│   ├── MCPPipeline.Contracts/           # Modelos compartilhados
│   │   ├── Messages/
│   │   │   ├── MCPCommand.cs
│   │   │   ├── MCPResponse.cs
│   │   │   └── MCPEvent.cs
│   │   └── Protos/
│   │       └── mcp.proto
│   │
│   ├── MCPPipeline.Core/                # Lógica de negócio
│   │   ├── Services/
│   │   │   ├── IMCPKernelService.cs
│   │   │   └── MCPKernelService.cs
│   │   └── Events/
│   │       └── IEventBus.cs
│   │
│   ├── MCPPipeline.GrpcService/         # Endpoint gRPC
│   │   ├── Services/
│   │   │   └── MCPGrpcService.cs
│   │   └── Program.cs
│   │
│   ├── MCPPipeline.WebSocketService/    # Endpoint WebSocket
│   │   ├── Hubs/
│   │   │   └── MCPHub.cs
│   │   └── Program.cs
│   │
│   ├── MCPPipeline.Gateway/             # API Gateway (YARP)
│   │   ├── Configuration/
│   │   └── Program.cs
│   │
│   └── MCPPipeline.Adapter/             # Protocol Adapter
│       ├── GrpcToWebSocketAdapter.cs
│       └── WebSocketToGrpcAdapter.cs
│
└── tests/
    └── MCPPipeline.IntegrationTests/

2️⃣ Contratos Compartilhados

// MCPPipeline.Contracts/Messages/MCPCommand.cs
namespace MCPPipeline.Contracts.Messages;

public record MCPCommand
{
    public string CommandId { get; init; } = Guid.NewGuid().ToString();
    public string Command { get; init; } = string.Empty;
    public string Payload { get; init; } = string.Empty;
    public Dictionary<string, string> Metadata { get; init; } = new();
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
    public string SessionId { get; init; } = string.Empty;
    public ProtocolType Protocol { get; init; }
    public int Priority { get; init; } = 0;
}

public record MCPResponse
{
    public string CommandId { get; init; } = string.Empty;
    public string Result { get; init; } = string.Empty;
    public ResponseStatus Status { get; init; }
    public string? ErrorMessage { get; init; }
    public long ProcessingTimeMs { get; init; }
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
    public Dictionary<string, object> Metrics { get; init; } = new();
}

public record MCPEvent
{
    public string EventId { get; init; } = Guid.NewGuid().ToString();
    public string EventType { get; init; } = string.Empty;
    public string Source { get; init; } = string.Empty;
    public object Data { get; init; } = new();
    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
}

public enum ProtocolType
{
    Unknown = 0,
    Grpc = 1,
    WebSocket = 2,
    Http = 3
}

public enum ResponseStatus
{
    Success,
    Error,
    Processing,
    Timeout
}

3️⃣ MCP Kernel Unificado

// MCPPipeline.Core/Services/MCPKernelService.cs
using MCPPipeline.Contracts.Messages;
using System.Diagnostics;

namespace MCPPipeline.Core.Services;

public interface IMCPKernelService
{
    Task<MCPResponse> ExecuteCommandAsync(MCPCommand command, CancellationToken ct);
    IAsyncEnumerable<string> StreamCommandAsync(MCPCommand command, CancellationToken ct);
}

public class MCPKernelService : IMCPKernelService
{
    private readonly ILogger<MCPKernelService> _logger;
    private readonly IEventBus _eventBus;
    private static readonly ActivitySource ActivitySource = new("MCPPipeline.Core");

    public MCPKernelService(
        ILogger<MCPKernelService> logger,
        IEventBus eventBus)
    {
        _logger = logger;
        _eventBus = eventBus;
    }

    public async Task<MCPResponse> ExecuteCommandAsync(
        MCPCommand command, 
        CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("ExecuteCommand");
        activity?.SetTag("command.id", command.CommandId);
        activity?.SetTag("command.type", command.Command);
        activity?.SetTag("protocol", command.Protocol.ToString());

        var sw = Stopwatch.StartNew();

        try
        {
            _logger.LogInformation(
                "Executando comando {Command} via {Protocol} | Session: {SessionId}",
                command.Command,
                command.Protocol,
                command.SessionId);

            // Publicar evento de início
            await _eventBus.PublishAsync(new MCPEvent
            {
                EventType = "CommandStarted",
                Source = command.Protocol.ToString(),
                Data = new { command.CommandId, command.Command }
            });

            // Processar comando
            var result = await ProcessCommandAsync(command, ct);

            sw.Stop();

            var response = new MCPResponse
            {
                CommandId = command.CommandId,
                Result = result,
                Status = ResponseStatus.Success,
                ProcessingTimeMs = sw.ElapsedMilliseconds,
                Metrics = new Dictionary<string, object>
                {
                    ["protocol"] = command.Protocol.ToString(),
                    ["priority"] = command.Priority
                }
            };

            // Publicar evento de conclusão
            await _eventBus.PublishAsync(new MCPEvent
            {
                EventType = "CommandCompleted",
                Source = command.Protocol.ToString(),
                Data = new { command.CommandId, response.ProcessingTimeMs }
            });

            activity?.SetTag("response.status", "success");
            return response;
        }
        catch (Exception ex)
        {
            sw.Stop();

            _logger.LogError(ex, 
                "Erro ao executar comando {Command} via {Protocol}", 
                command.Command, 
                command.Protocol);

            activity?.SetTag("response.status", "error");
            activity?.SetTag("error.message", ex.Message);

            await _eventBus.PublishAsync(new MCPEvent
            {
                EventType = "CommandFailed",
                Source = command.Protocol.ToString(),
                Data = new { command.CommandId, Error = ex.Message }
            });

            return new MCPResponse
            {
                CommandId = command.CommandId,
                Status = ResponseStatus.Error,
                ErrorMessage = ex.Message,
                ProcessingTimeMs = sw.ElapsedMilliseconds
            };
        }
    }

    public async IAsyncEnumerable<string> StreamCommandAsync(
        MCPCommand command,
        [EnumeratorCancellation] CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("StreamCommand");
        activity?.SetTag("command.id", command.CommandId);

        _logger.LogInformation(
            "Iniciando streaming para comando {Command} via {Protocol}",
            command.Command,
            command.Protocol);

        var chunks = await GenerateStreamChunksAsync(command.Payload, ct);

        for (int i = 0; i < chunks.Count; i++)
        {
            if (ct.IsCancellationRequested)
                yield break;

            yield return chunks[i];
            await Task.Delay(50, ct); // Simula processamento
        }
    }

    private async Task<string> ProcessCommandAsync(MCPCommand command, CancellationToken ct)
    {
        return command.Command.ToLowerInvariant() switch
        {
            "analyze" => await AnalyzeAsync(command.Payload, ct),
            "summarize" => await SummarizeAsync(command.Payload, ct),
            "translate" => await TranslateAsync(command.Payload, ct),
            "generate" => await GenerateAsync(command.Payload, ct),
            "status" => await GetStatusAsync(ct),
            _ => throw new InvalidOperationException($"Comando desconhecido: {command.Command}")
        };
    }

    private async Task<string> AnalyzeAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(200, ct);
        var words = payload.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
        return $"Análise: {words} palavras, {payload.Length} caracteres";
    }

    private async Task<string> SummarizeAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(300, ct);
        return payload.Length > 100 
            ? $"Resumo: {payload[..100]}..." 
            : $"Resumo: {payload}";
    }

    private async Task<string> TranslateAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(250, ct);
        return $"[Traduzido] {payload}";
    }

    private async Task<string> GenerateAsync(string payload, CancellationToken ct)
    {
        await Task.Delay(500, ct);
        return $"Conteúdo gerado baseado em: {payload}";
    }

    private async Task<string> GetStatusAsync(CancellationToken ct)
    {
        await Task.Delay(50, ct);
        return $"Sistema operacional | Timestamp: {DateTime.UtcNow:O}";
    }

    private async Task<List<string>> GenerateStreamChunksAsync(string prompt, CancellationToken ct)
    {
        await Task.Delay(100, ct);
        return new List<string>
        {
            "Iniciando processamento...",
            "Analisando contexto...",
            "Gerando resposta...",
            $"Resultado: {prompt}",
            "Processamento concluído."
        };
    }
}

4️⃣ Event Bus com Redis

// MCPPipeline.Core/Events/IEventBus.cs
namespace MCPPipeline.Core.Events;

public interface IEventBus
{
    Task PublishAsync<T>(T @event) where T : class;
    Task SubscribeAsync<T>(Func<T, Task> handler) where T : class;
}

// MCPPipeline.Core/Events/RedisEventBus.cs
using StackExchange.Redis;
using System.Text.Json;

public class RedisEventBus : IEventBus
{
    private readonly IConnectionMultiplexer _redis;
    private readonly ILogger<RedisEventBus> _logger;
    private readonly ISubscriber _subscriber;

    public RedisEventBus(
        IConnectionMultiplexer redis,
        ILogger<RedisEventBus> logger)
    {
        _redis = redis;
        _logger = logger;
        _subscriber = redis.GetSubscriber();
    }

    public async Task PublishAsync<T>(T @event) where T : class
    {
        var channel = typeof(T).Name;
        var message = JsonSerializer.Serialize(@event);

        await _subscriber.PublishAsync(channel, message);

        _logger.LogDebug("Evento publicado: {EventType}", channel);
    }

    public async Task SubscribeAsync<T>(Func<T, Task> handler) where T : class
    {
        var channel = typeof(T).Name;

        await _subscriber.SubscribeAsync(channel, async (ch, message) =>
        {
            try
            {
                var @event = JsonSerializer.Deserialize<T>(message!);
                if (@event != null)
                {
                    await handler(@event);
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Erro ao processar evento {EventType}", channel);
            }
        });

        _logger.LogInformation("Inscrito no canal: {Channel}", channel);
    }
}

5️⃣ Protocol Adapter

// MCPPipeline.Adapter/ProtocolAdapter.cs
using MCPPipeline.Contracts.Messages;
using MCPPipeline.Grpc;

namespace MCPPipeline.Adapter;

public interface IProtocolAdapter
{
    MCPCommand FromGrpcRequest(MCPRequest grpcRequest);
    MCPRequest ToGrpcRequest(MCPCommand command);
    MCPResponse FromGrpcResponse(MCPGrpcResponse grpcResponse);
    MCPGrpcResponse ToGrpcResponse(MCPResponse response);
}

public class ProtocolAdapter : IProtocolAdapter
{
    public MCPCommand FromGrpcRequest(MCPRequest grpcRequest)
    {
        return new MCPCommand
        {
            Command = grpcRequest.Command,
            Payload = grpcRequest.Payload,
            Metadata = grpcRequest.Metadata.ToDictionary(k => k.Key, v => v.Value),
            Timestamp = DateTimeOffset.FromUnixTimeMilliseconds(grpcRequest.Timestamp).DateTime,
            Protocol = ProtocolType.Grpc
        };
    }

    public MCPRequest ToGrpcRequest(MCPCommand command)
    {
        return new MCPRequest
        {
            Command = command.Command,
            Payload = command.Payload,
            Metadata = { command.Metadata },
            Timestamp = new DateTimeOffset(command.Timestamp).ToUnixTimeMilliseconds()
        };
    }

    public MCPResponse FromGrpcResponse(MCPGrpcResponse grpcResponse)
    {
        return new MCPResponse
        {
            Result = grpcResponse.Result,
            Status = grpcResponse.Status switch
            {
                "OK" => ResponseStatus.Success,
                "ERROR" => ResponseStatus.Error,
                "PROCESSING" => ResponseStatus.Processing,
                _ => ResponseStatus.Error
            },
            ErrorMessage = grpcResponse.ErrorMessage,
            ProcessingTimeMs = grpcResponse.ProcessingTimeMs
        };
    }

    public MCPGrpcResponse ToGrpcResponse(MCPResponse response)
    {
        return new MCPGrpcResponse
        {
            Result = response.Result,
            Status = response.Status.ToString().ToUpperInvariant(),
            ErrorMessage = response.ErrorMessage ?? string.Empty,
            ProcessingTimeMs = response.ProcessingTimeMs
        };
    }
}

6️⃣ gRPC Service Endpoint

// MCPPipeline.GrpcService/Services/MCPGrpcService.cs
using Grpc.Core;
using MCPPipeline.Grpc;
using MCPPipeline.Core.Services;
using MCPPipeline.Adapter;

namespace MCPPipeline.GrpcService.Services;

public class MCPGrpcServiceImpl : MCPService.MCPServiceBase
{
    private readonly IMCPKernelService _kernelService;
    private readonly IProtocolAdapter _adapter;
    private readonly ILogger<MCPGrpcServiceImpl> _logger;

    public MCPGrpcServiceImpl(
        IMCPKernelService kernelService,
        IProtocolAdapter adapter,
        ILogger<MCPGrpcServiceImpl> logger)
    {
        _kernelService = kernelService;
        _adapter = adapter;
        _logger = logger;
    }

    public override async Task<MCPGrpcResponse> SendCommand(
        MCPRequest request,
        ServerCallContext context)
    {
        _logger.LogInformation(
            "Recebido comando gRPC: {Command} de {Peer}",
            request.Command,
            context.Peer);

        // Converter para modelo unificado
        var command = _adapter.FromGrpcRequest(request);
        command = command with { SessionId = context.Peer };

        // Processar via kernel unificado
        var response = await _kernelService.ExecuteCommandAsync(
            command,
            context.CancellationToken);

        // Converter resposta
        return _adapter.ToGrpcResponse(response);
    }

    public override async Task StreamCommand(
        MCPRequest request,
        IServerStreamWriter<MCPStreamResponse> responseStream,
        ServerCallContext context)
    {
        _logger.LogInformation(
            "Iniciando streaming gRPC: {Command}",
            request.Command);

        var command = _adapter.FromGrpcRequest(request);

        int chunkIndex = 0;
        await foreach (var chunk in _kernelService.StreamCommandAsync(
            command,
            context.CancellationToken))
        {
            await responseStream.WriteAsync(new MCPStreamResponse
            {
                Content = chunk,
                ChunkIndex = chunkIndex++,
                IsComplete = false
            });
        }

        // Enviar chunk final
        await responseStream.WriteAsync(new MCPStreamResponse
        {
            Content = "Stream concluído",
            ChunkIndex = chunkIndex,
            IsComplete = true
        });
    }

    public override Task<HealthResponse> HealthCheck(
        HealthRequest request,
        ServerCallContext context)
    {
        return Task.FromResult(new HealthResponse
        {
            Status = "Healthy",
            Version = "1.0.0",
            Protocol = "gRPC"
        });
    }
}

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGrpc();
builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();
builder.Services.AddSingleton<IProtocolAdapter, ProtocolAdapter>();

// Redis para event bus
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect("localhost:6379"));
builder.Services.AddSingleton<IEventBus, RedisEventBus>();

var app = builder.Build();

app.MapGrpcService<MCPGrpcServiceImpl>();
app.MapGet("/", () => "MCP gRPC Service");

app.Run();

7️⃣ WebSocket Service Endpoint

// MCPPipeline.WebSocketService/Hubs/MCPHub.cs
using Microsoft.AspNetCore.SignalR;
using MCPPipeline.Contracts.Messages;
using MCPPipeline.Core.Services;

namespace MCPPipeline.WebSocketService.Hubs;

public class MCPHub : Hub
{
    private readonly IMCPKernelService _kernelService;
    private readonly ILogger<MCPHub> _logger;

    public MCPHub(
        IMCPKernelService kernelService,
        ILogger<MCPHub> logger)
    {
        _kernelService = kernelService;
        _logger = logger;
    }

    public override async Task OnConnectedAsync()
    {
        _logger.LogInformation("Cliente WebSocket conectado: {ConnectionId}", 
            Context.ConnectionId);

        await Clients.Caller.SendAsync("Connected", new
        {
            ConnectionId = Context.ConnectionId,
            Protocol = "WebSocket",
            Message = "Conectado ao MCP Hub"
        });

        await base.OnConnectedAsync();
    }

    public async Task SendCommand(MCPCommand command)
    {
        _logger.LogInformation(
            "Recebido comando WebSocket: {Command} de {ConnectionId}",
            command.Command,
            Context.ConnectionId);

        // Enriquecer comando com dados do WebSocket
        var enrichedCommand = command with 
        { 
            Protocol = ProtocolType.WebSocket,
            SessionId = Context.ConnectionId
        };

        // Processar via kernel unificado
        var response = await _kernelService.ExecuteCommandAsync(
            enrichedCommand,
            Context.ConnectionAborted);

        // Enviar resposta
        await Clients.Caller.SendAsync("CommandResponse", response);
    }

    public async Task StreamCommand(MCPCommand command)
    {
        _logger.LogInformation(
            "Iniciando streaming WebSocket: {Command}",
            command.Command);

        var enrichedCommand = command with 
        { 
            Protocol = ProtocolType.WebSocket,
            SessionId = Context.ConnectionId
        };

        await foreach (var chunk in _kernelService.StreamCommandAsync(
            enrichedCommand,
            Context.ConnectionAborted))
        {
            await Clients.Caller.SendAsync("StreamChunk", new
            {
                Content = chunk,
                Timestamp = DateTime.UtcNow
            });
        }

        await Clients.Caller.SendAsync("StreamComplete", new
        {
            Message = "Streaming concluído"
        });
    }
}

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR();
builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();

// Redis para event bus
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect("localhost:6379"));
builder.Services.AddSingleton<IEventBus, RedisEventBus>();

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", policy =>
        policy.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader());
});

var app = builder.Build();

app.UseCors("AllowAll");
app.MapHub<MCPHub>("/mcphub");
app.MapGet("/", () => "MCP WebSocket Service");

app.Run();

8️⃣ API Gateway com YARP

// MCPPipeline.Gateway/Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();
app.MapGet("/", () => Results.Ok(new
{
    Service = "MCP Gateway",
    Endpoints = new
    {
        gRPC = "https://localhost:5001",
        WebSocket = "https://localhost:5002/mcphub"
    }
}));

app.Run();

// appsettings.json
{
  "ReverseProxy": {
    "Routes": {
      "grpc-route": {
        "ClusterId": "grpc-cluster",
        "Match": {
          "Path": "/grpc/{**catch-all}"
        }
      },
      "websocket-route": {
        "ClusterId": "websocket-cluster",
        "Match": {
          "Path": "/ws/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "grpc-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:5001"
          }
        }
      },
      "websocket-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:5002"
          }
        },
        "HttpRequest": {
          "Version": "1.1",
          "VersionPolicy": "RequestVersionOrLower"
        }
      }
    }
  }
}

9️⃣ Cliente Unificado

// MCPPipeline.Client/UnifiedMCPClient.cs
public class UnifiedMCPClient : IAsyncDisposable
{
    private readonly MCPService.MCPServiceClient? _grpcClient;
    private readonly HubConnection? _hubConnection;
    private readonly ILogger<UnifiedMCPClient> _logger;
    private readonly bool _useGrpc;

    public UnifiedMCPClient(
        string endpoint,
        bool useGrpc,
        ILogger<UnifiedMCPClient> logger)
    {
        _useGrpc = useGrpc;
        _logger = logger;

        if (useGrpc)
        {
            var channel = GrpcChannel.ForAddress(endpoint);
            _grpcClient = new MCPService.MCPServiceClient(channel);
            _logger.LogInformation("Cliente configurado para gRPC: {Endpoint}", endpoint);
        }
        else
        {
            _hubConnection = new HubConnectionBuilder()
                .WithUrl(endpoint)
                .WithAutomaticReconnect()
                .Build();

            SetupWebSocketHandlers();
            _logger.LogInformation("Cliente configurado para WebSocket: {Endpoint}", endpoint);
        }
    }

    public async Task ConnectAsync(CancellationToken ct = default)
    {
        if (!_useGrpc && _hubConnection != null)
        {
            await _hubConnection.StartAsync(ct);
            _logger.LogInformation("Conectado via WebSocket");
        }
    }

    public async Task<MCPResponse> SendCommandAsync(
        string command,
        string payload,
        CancellationToken ct = default)
    {
        if (_useGrpc && _grpcClient != null)
        {
            return await SendViaGrpcAsync(command, payload, ct);
        }
        else if (_hubConnection != null)
        {
            return await SendViaWebSocketAsync(command, payload, ct);
        }

        throw new InvalidOperationException("Cliente não inicializado");
    }

    private async Task<MCPResponse> SendViaGrpcAsync(
        string command,
        string payload,
        CancellationToken ct)
    {
        _logger.LogInformation("Enviando comando via gRPC: {Command}", command);

        var request = new MCPRequest
        {
            Command = command,
            Payload = payload,
            Timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
        };

        var response = await _grpcClient!.SendCommandAsync(request, cancellationToken: ct);

        return new MCPResponse
        {
            Result = response.Result,
            Status = response.Status == "OK" ? ResponseStatus.Success : ResponseStatus.Error,
            ErrorMessage = response.ErrorMessage,
            ProcessingTimeMs = response.ProcessingTimeMs
        };
    }

    private async Task<MCPResponse> SendViaWebSocketAsync(
        string command,
        string payload,
        CancellationToken ct)
    {
        _logger.LogInformation("Enviando comando via WebSocket: {Command}", command);

        var tcs = new TaskCompletionSource<MCPResponse>();

        void handler(MCPResponse response)
        {
            tcs.TrySetResult(response);
        }

        _hubConnection!.On<MCPResponse>("CommandResponse", handler);

        try
        {
            await _hubConnection.InvokeAsync("SendCommand", new MCPCommand
            {
                Command = command,
                Payload = payload,
                Timestamp = DateTime.UtcNow
            }, ct);

            return await tcs.Task.WaitAsync(TimeSpan.FromSeconds(30), ct);
        }
        finally
        {
            _hubConnection.Remove("CommandResponse");
        }
    }

    public async IAsyncEnumerable<string> StreamCommandAsync(
        string command,
        string payload,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        if (_useGrpc && _grpcClient != null)
        {
            await foreach (var chunk in StreamViaGrpcAsync(command, payload, ct))
            {
                yield return chunk;
            }
        }
        else if (_hubConnection != null)
        {
            await foreach (var chunk in StreamViaWebSocketAsync(command, payload, ct))
            {
                yield return chunk;
            }
        }
    }

    private async IAsyncEnumerable<string> StreamViaGrpcAsync(
        string command,
        string payload,
        [EnumeratorCancellation] CancellationToken ct)
    {
        var request = new MCPRequest
        {
            Command = command,
            Payload = payload,
            Timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
        };

        using var call = _grpcClient!.StreamCommand(request, cancellationToken: ct);

        await foreach (var response in call.ResponseStream.ReadAllAsync(ct))
        {
            yield return response.Content;
        }
    }

    private async IAsyncEnumerable<string> StreamViaWebSocketAsync(
        string command,
        string payload,
        [EnumeratorCancellation] CancellationToken ct)
    {
        var channel = Channel.CreateUnbounded<string>();

        _hubConnection!.On<dynamic>("StreamChunk", (chunk) =>
        {
            channel.Writer.TryWrite(chunk.Content.ToString());
        });

        _hubConnection.On<dynamic>("StreamComplete", (_) =>
        {
            channel.Writer.Complete();
        });

        await _hubConnection.InvokeAsync("StreamCommand", new MCPCommand
        {
            Command = command,
            Payload = payload,
            Timestamp = DateTime.UtcNow
        }, ct);

        await foreach (var chunk in channel.Reader.ReadAllAsync(ct))
        {
            yield return chunk;
        }
    }

    private void SetupWebSocketHandlers()
    {
        _hubConnection!.On<object>("Connected", data =>
        {
            _logger.LogInformation("✅ WebSocket conectado: {Data}", data);
        });

        _hubConnection.Reconnecting += error =>
        {
            _logger.LogWarning("⚠️ WebSocket reconectando: {Error}", error?.Message);
            return Task.CompletedTask;
        };

        _hubConnection.Reconnected += connectionId =>
        {
            _logger.LogInformation("✅ WebSocket reconectado: {ConnectionId}", connectionId);
            return Task.CompletedTask;
        };

        _hubConnection.Closed += error =>
        {
            _logger.LogError("❌ WebSocket fechado: {Error}", error?.Message);
            return Task.CompletedTask;
        };
    }

    public async ValueTask DisposeAsync()
    {
        if (_hubConnection != null)
        {
            await _hubConnection.StopAsync();
            await _hubConnection.DisposeAsync();
        }
    }
}

// Exemplo de uso
public class Program
{
    public static async Task Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
        var logger = loggerFactory.CreateLogger<UnifiedMCPClient>();

        // Cliente gRPC
        await using var grpcClient = new UnifiedMCPClient(
            "https://localhost:5001",
            useGrpc: true,
            logger);

        var response = await grpcClient.SendCommandAsync("analyze", "Teste via gRPC");
        Console.WriteLine($"gRPC: {response.Result}");

        // Cliente WebSocket
        await using var wsClient = new UnifiedMCPClient(
            "https://localhost:5002/mcphub",
            useGrpc: false,
            logger);

        await wsClient.ConnectAsync();

        response = await wsClient.SendCommandAsync("analyze", "Teste via WebSocket");
        Console.WriteLine($"WebSocket: {response.Result}");

        // Streaming
        await foreach (var chunk in wsClient.StreamCommandAsync("generate", "Prompt de teste"))
        {
            Console.WriteLine($"Chunk: {chunk}");
        }
    }
}

🔍 Observabilidade Unificada

OpenTelemetry Configuration

// MCPPipeline.Observability/OpenTelemetryExtensions.cs
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenTelemetry.Metrics;

public static class OpenTelemetryExtensions
{
    public static IServiceCollection AddMCPObservability(
        this IServiceCollection services,
        string serviceName)
    {
        services.AddOpenTelemetry()
            .ConfigureResource(resource =>
            {
                resource.AddService(
                    serviceName: serviceName,
                    serviceVersion: "1.0.0");
            })
            .WithTracing(tracing =>
            {
                tracing
                    .AddAspNetCoreInstrumentation(options =>
                    {
                        options.RecordException = true;
                        options.EnrichWithHttpRequest = (activity, request) =>
                        {
                            activity.SetTag("http.scheme", request.Scheme);
                            activity.SetTag("http.client_ip", request.HttpContext.Connection.RemoteIpAddress);
                        };
                    })
                    .AddGrpcClientInstrumentation()
                    .AddSource("MCPPipeline.Core")
                    .AddSource("MCPPipeline.GrpcService")
                    .AddSource("MCPPipeline.WebSocketService")
                    .AddOtlpExporter(options =>
                    {
                        options.Endpoint = new Uri("http://localhost:4317");
                    });
            })
            .WithMetrics(metrics =>
            {
                metrics
                    .AddAspNetCoreInstrumentation()
                    .AddRuntimeInstrumentation()
                    .AddMeter("MCPPipeline.*")
                    .AddPrometheusExporter()
                    .AddOtlpExporter();
            });

        return services;
    }
}

// Uso nos serviços
builder.Services.AddMCPObservability("MCPPipeline.GrpcService");

Métricas Customizadas

// MCPPipeline.Observability/MCPMetrics.cs
using System.Diagnostics.Metrics;

public class MCPMetrics
{
    private readonly Meter _meter;
    private readonly Counter<long> _commandsProcessed;
    private readonly Histogram<double> _commandDuration;
    private readonly Counter<long> _commandErrors;
    private readonly UpDownCounter<int> _activeConnections;

    public MCPMetrics()
    {
        _meter = new Meter("MCPPipeline.Metrics", "1.0.0");

        _commandsProcessed = _meter.CreateCounter<long>(
            "mcp.commands.processed",
            description: "Total de comandos processados");

        _commandDuration = _meter.CreateHistogram<double>(
            "mcp.command.duration",
            unit: "ms",
            description: "Duração do processamento de comandos");

        _commandErrors = _meter.CreateCounter<long>(
            "mcp.commands.errors",
            description: "Total de erros no processamento");

        _activeConnections = _meter.CreateUpDownCounter<int>(
            "mcp.connections.active",
            description: "Conexões ativas");
    }

    public void RecordCommandProcessed(string command, ProtocolType protocol)
    {
        _commandsProcessed.Add(1,
            new KeyValuePair<string, object?>("command", command),
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }

    public void RecordCommandDuration(string command, ProtocolType protocol, double durationMs)
    {
        _commandDuration.Record(durationMs,
            new KeyValuePair<string, object?>("command", command),
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }

    public void RecordCommandError(string command, ProtocolType protocol, string errorType)
    {
        _commandErrors.Add(1,
            new KeyValuePair<string, object?>("command", command),
            new KeyValuePair<string, object?>("protocol", protocol.ToString()),
            new KeyValuePair<string, object?>("error_type", errorType));
    }

    public void IncrementActiveConnections(ProtocolType protocol)
    {
        _activeConnections.Add(1,
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }

    public void DecrementActiveConnections(ProtocolType protocol)
    {
        _activeConnections.Add(-1,
            new KeyValuePair<string, object?>("protocol", protocol.ToString()));
    }
}

📊 Dashboard com Grafana

Prometheus Configuration

# prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'mcp-grpc-service'
    static_configs:
      - targets: ['localhost:5001']

  - job_name: 'mcp-websocket-service'
    static_configs:
      - targets: ['localhost:5002']

  - job_name: 'mcp-gateway'
    static_configs:
      - targets: ['localhost:5000']

Grafana Dashboard JSON

{
  "dashboard": {
    "title": "MCP Hybrid Protocol Dashboard",
    "panels": [
      {
        "title": "Comandos Processados por Protocolo",
        "targets": [
          {
            "expr": "rate(mcp_commands_processed_total[5m])",
            "legendFormat": "{{protocol}}"
          }
        ]
      },
      {
        "title": "Latência Média por Comando",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(mcp_command_duration_bucket[5m]))",
            "legendFormat": "p95 - {{command}}"
          }
        ]
      },
      {
        "title": "Conexões Ativas",
        "targets": [
          {
            "expr": "mcp_connections_active",
            "legendFormat": "{{protocol}}"
          }
        ]
      },
      {
        "title": "Taxa de Erro",
        "targets": [
          {
            "expr": "rate(mcp_commands_errors_total[5m])",
            "legendFormat": "{{protocol}} - {{error_type}}"
          }
        ]
      }
    ]
  }
}

🧪 Testes de Integração

Teste Híbrido

// MCPPipeline.IntegrationTests/HybridProtocolTests.cs
public class HybridProtocolTests : IClassFixture<MCPTestFixture>
{
    private readonly MCPTestFixture _fixture;

    public HybridProtocolTests(MCPTestFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    public async Task Should_Process_Same_Command_Via_Both_Protocols()
    {
        // Arrange
        var grpcClient = _fixture.CreateGrpcClient();
        var wsClient = _fixture.CreateWebSocketClient();

        await wsClient.ConnectAsync();

        var testPayload = "Teste de integração híbrida";

        // Act
        var grpcResponse = await grpcClient.SendCommandAsync("analyze", testPayload);
        var wsResponse = await wsClient.SendCommandAsync("analyze", testPayload);

        // Assert
        Assert.Equal(ResponseStatus.Success, grpcResponse.Status);
        Assert.Equal(ResponseStatus.Success, wsResponse.Status);

        // Ambos devem retornar resultados equivalentes
        Assert.Contains("palavras", grpcResponse.Result);
        Assert.Contains("palavras", wsResponse.Result);
    }

    [Fact]
    public async Task Should_Handle_Concurrent_Requests_From_Both_Protocols()
    {
        // Arrange
        var grpcClient = _fixture.CreateGrpcClient();
        var wsClient = _fixture.CreateWebSocketClient();
        await wsClient.ConnectAsync();

        var tasks = new List<Task<MCPResponse>>();

        // Act - Enviar 50 requisições concorrentes de cada protocolo
        for (int i = 0; i < 50; i++)
        {
            tasks.Add(grpcClient.SendCommandAsync("status", $"gRPC-{i}"));
            tasks.Add(wsClient.SendCommandAsync("status", $"WS-{i}"));
        }

        var responses = await Task.WhenAll(tasks);

        // Assert
        Assert.All(responses, r => Assert.Equal(ResponseStatus.Success, r.Status));
        Assert.Equal(100, responses.Length);
    }

    [Fact]
    public async Task Should_Broadcast_Events_Between_Protocols()
    {
        // Arrange
        var grpcClient = _fixture.CreateGrpcClient();
        var wsClient = _fixture.CreateWebSocketClient();
        await wsClient.ConnectAsync();

        var eventReceived = new TaskCompletionSource<bool>();

        // Configurar listener no WebSocket
        // (implementação depende do event bus)

        // Act - Enviar comando via gRPC
        await grpcClient.SendCommandAsync("generate", "Teste de evento");

        // Assert - WebSocket deve receber notificação
        var received = await eventReceived.Task.WaitAsync(TimeSpan.FromSeconds(5));
        Assert.True(received);
    }
}

public class MCPTestFixture : IAsyncLifetime
{
    private WebApplication? _grpcApp;
    private WebApplication? _wsApp;

    public async Task InitializeAsync()
    {
        // Inicializar serviços de teste
        _grpcApp = CreateGrpcService();
        _wsApp = CreateWebSocketService();

        await _grpcApp.StartAsync();
        await _wsApp.StartAsync();
    }

    public async Task DisposeAsync()
    {
        if (_grpcApp != null) await _grpcApp.StopAsync();
        if (_wsApp != null) await _wsApp.StopAsync();
    }

    public UnifiedMCPClient CreateGrpcClient()
    {
        return new UnifiedMCPClient(
            "https://localhost:5001",
            useGrpc: true,
            Mock.Of<ILogger<UnifiedMCPClient>>());
    }

    public UnifiedMCPClient CreateWebSocketClient()
    {
        return new UnifiedMCPClient(
            "https://localhost:5002/mcphub",
            useGrpc: false,
            Mock.Of<ILogger<UnifiedMCPClient>>());
    }

    private WebApplication CreateGrpcService()
    {
        var builder = WebApplication.CreateBuilder();
        builder.Services.AddGrpc();
        builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();
        builder.Services.AddSingleton<IProtocolAdapter, ProtocolAdapter>();

        var app = builder.Build();
        app.MapGrpcService<MCPGrpcServiceImpl>();
        return app;
    }

    private WebApplication CreateWebSocketService()
    {
        var builder = WebApplication.CreateBuilder();
        builder.Services.AddSignalR();
        builder.Services.AddSingleton<IMCPKernelService, MCPKernelService>();

        var app = builder.Build();
        app.MapHub<MCPHub>("/mcphub");
        return app;
    }
}

🚀 Teste de Performance

Benchmark com BenchmarkDotNet

// MCPPipeline.Benchmarks/ProtocolBenchmarks.cs
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

[MemoryDiagnoser]
[SimpleJob(warmupCount: 3, iterationCount: 10)]
public class ProtocolBenchmarks
{
    private UnifiedMCPClient _grpcClient = null!;
    private UnifiedMCPClient _wsClient = null!;

    [GlobalSetup]
    public async Task Setup()
    {
        _grpcClient = new UnifiedMCPClient(
            "https://localhost:5001",
            useGrpc: true,
            Mock.Of<ILogger<UnifiedMCPClient>>());

        _wsClient = new UnifiedMCPClient(
            "https://localhost:5002/mcphub",
            useGrpc: false,
            Mock.Of<ILogger<UnifiedMCPClient>>());

        await _wsClient.ConnectAsync();
    }

    [Benchmark(Baseline = true)]
    public async Task<MCPResponse> GrpcCommand()
    {
        return await _grpcClient.SendCommandAsync("status", "benchmark");
    }

    [Benchmark]
    public async Task<MCPResponse> WebSocketCommand()
    {
        return await _wsClient.SendCommandAsync("status", "benchmark");
    }

    [Benchmark]
    public async Task GrpcStreaming()
    {
        await foreach (var _ in _grpcClient.StreamCommandAsync("generate", "test"))
        {
            // Consumir stream
        }
    }

    [Benchmark]
    public async Task WebSocketStreaming()
    {
        await foreach (var _ in _wsClient.StreamCommandAsync("generate", "test"))
        {
            // Consumir stream
        }
    }

    [GlobalCleanup]
    public async Task Cleanup()
    {
        await _grpcClient.DisposeAsync();
        await _wsClient.DisposeAsync();
    }
}

// Program.cs
public class Program
{
    public static void Main(string[] args)
    {
        BenchmarkRunner.Run<ProtocolBenchmarks>();
    }
}

Resultados Esperados

|            Method |      Mean |     Error |    StdDev | Ratio | Gen0 | Allocated |
|------------------ |----------:|----------:|----------:|------:|-----:|----------:|
|       GrpcCommand |  2.450 ms | 0.0421 ms | 0.0394 ms |  1.00 | 15.6 |     128KB |
|  WebSocketCommand |  8.732 ms | 0.1523 ms | 0.1425 ms |  3.56 | 31.2 |     256KB |
|     GrpcStreaming | 12.105 ms | 0.2103 ms | 0.1967 ms |  4.94 | 46.8 |     384KB |
| WebSocketStreaming| 18.421 ms | 0.3142 ms | 0.2940 ms |  7.52 | 62.5 |     512KB |

🎯 Decisão de Protocolo: Quando Usar Cada Um

Matriz de Decisão

public class ProtocolSelector
{
    public ProtocolType SelectOptimalProtocol(ClientContext context)
    {
        // 1. Cliente é navegador? → WebSocket
        if (context.IsWebBrowser)
            return ProtocolType.WebSocket;

        // 2. Comunicação interna entre serviços? → gRPC
        if (context.IsInternalService)
            return ProtocolType.Grpc;

        // 3. Requer streaming bidirecional de longa duração? → WebSocket
        if (context.RequiresLongLivedStream)
            return ProtocolType.WebSocket;

        // 4. Prioriza latência mínima? → gRPC
        if (context.LatencySensitive)
            return ProtocolType.Grpc;

        // 5. Múltiplos clientes precisam receber broadcasts? → WebSocket
        if (context.RequiresBroadcast)
            return ProtocolType.WebSocket;

        // 6. Padrão: gRPC para performance
        return ProtocolType.Grpc;
    }
}

public record ClientContext
{
    public bool IsWebBrowser { get; init; }
    public bool IsInternalService { get; init; }
    public bool RequiresLongLivedStream { get; init; }
    public bool LatencySensitive { get; init; }
    public bool RequiresBroadcast { get; init; }
}

Tabela Comparativa

Cenário	gRPC	WebSocket	Recomendação
API Backend → Backend	✅ Ideal	⚠️ Overhead	gRPC
Aplicação Web → Backend	❌ Limitado	✅ Nativo	WebSocket
Mobile App → Backend	✅ Excelente	✅ Bom	gRPC (melhor performance)
Dashboard Real-time	⚠️ Polling	✅ Push nativo	WebSocket
Chat Multi-usuário	❌ Não ideal	✅ Perfeito	WebSocket
Análise de Dados	✅ Alta performance	⚠️ Mais lento	gRPC
Streaming de IA	✅ Eficiente	✅ Funcional	Ambos (contexto dependente)

🔒 Segurança em Ambiente Híbrido

Autenticação Unificada

// MCPPipeline.Security/UnifiedAuthenticationExtensions.cs
public static class UnifiedAuthenticationExtensions
{
    public static IServiceCollection AddUnifiedAuthentication(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = configuration["Jwt:Issuer"],
                ValidAudience = configuration["Jwt:Audience"],
                IssuerSigningKey = new SymmetricSecurityKey(
                    Encoding.UTF8.GetBytes(configuration["Jwt:Key"]!))
            };

            // Suporte para WebSocket token via query string
            options.Events = new JwtBearerEvents
            {
                OnMessageReceived = context =>
                {
                    var accessToken = context.Request.Query["access_token"];
                    var path = context.HttpContext.Request.Path;

                    if (!string.IsNullOrEmpty(accessToken) && 
                        path.StartsWithSegments("/mcphub"))
                    {
                        context.Token = accessToken;
                    }
                    return Task.CompletedTask;
                }
            };
        });

        // Adicionar metadata para gRPC
        services.AddGrpc(options =>
        {
            options.Interceptors.Add<AuthenticationInterceptor>();
        });

        return services;
    }
}

// Interceptor para gRPC
public class AuthenticationInterceptor : Interceptor
{
    private readonly ILogger<AuthenticationInterceptor> _logger;
    public AuthenticationInterceptor(ILogger<AuthenticationInterceptor> logger)
    {
        _logger = logger;
    }

    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request,
        ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        var authHeader = context.RequestHeaders.GetValue("authorization");
        if (string.IsNullOrEmpty(authHeader))
        {
            _logger.LogWarning("Requisição gRPC sem autenticação");
            throw new RpcException(new Status(StatusCode.Unauthenticated, "Token não fornecido"));
        }

        // TODO: Implementar validação real do token JWT
        _logger.LogInformation("Token gRPC validado para peer: {Peer}", context.Peer);

        return await continuation(request, context);
    }
}

✅ Conclusão e Próximos Passos

Nesta quarta parte, consolidamos uma arquitetura híbrida que combina gRPC e WebSocket, garantindo:

Baixa latência e tipagem forte para comunicação interna (gRPC)
Flexibilidade e real-time para clientes web/mobile (WebSocket)
Kernel unificado, observabilidade centralizada e segurança robusta

🔮 Próximos Passos

Parte 5: Integração com mensageria avançada (Kafka, RabbitMQ) para cenários de alta escala.
Parte 6: Implementação de circuit breaker e resiliente com Polly.
Parte 7: Estratégias de multi-cloud deployment e CI/CD com GitHub Actions.

Dica: Explore o repositório MCPPipeline.Hybrid para exemplos completos e scripts de automação.

🤝 Conecte-se Comigo

Se você trabalha com .NET moderno e quer dominar arquitetura, C#, observabilidade, DevOps ou interoperabilidade:

💼 LinkedIn
✍️ Medium
📬 contato@dopme.io
📬 devsfree@devsfree.com.br

⁸ Novamente o transportou o diabo a um monte muito alto; e mostrou-lhe todos os reinos do mundo, e a glória deles. ⁹ E disse-lhe: Tudo isto te darei se, prostrado, me adorares. ¹⁰ Então disse-lhe Jesus: Vai-te, Satanás, porque está escrito: Ao Senhor teu Deus adorarás, e só a ele servirás. Mateus 4:8-10

Forem: Danilo O. Pinheiro, dopme.io

🚀 C# 14 já estava bom… agora ficou ainda melhor

🚀 C# 14 já estava bom… agora ficou ainda melhor

Comparando C# 14 vs C# 15 e o que muda na prática para desenvolvedores .NET

🧠 Visão Geral

🧩 O que o C# 14 trouxe

1️⃣ Inicialização simplificada de coleções

2️⃣ Pattern Matching mais expressivo

3️⃣ Melhor suporte a cenários de performance

🚀 O que o C# 15 melhora

1️⃣ Ainda menos boilerplate

2️⃣ Pattern Matching ainda mais poderoso

3️⃣ Evolução no suporte a coleções

4️⃣ Funções e expressões mais diretas

5️⃣ Interoperabilidade ainda mais forte

🏗️ Impacto Arquitetural

🔹 Aplicações corporativas

🔹 Sistemas distribuídos

🔹 Times de desenvolvimento

📊 Comparação prática

🧩 Quando atualizar?

✅ Atualize para C# 15 se:

⚠️ Avalie com cautela se:

🔮 Direção do C\

✅ Conclusão

🤝 Conecte-se comigo

Dez tecnologias essenciais em .NET

Introdução

Objetivo do repositório

Projetos e temas

Pré-requisitos

Como obter e compilar

Como executar um exemplo

Sugestão de ordem de estudo

CI/CD e qualidade

Conclusão

Conecte-se

Construindo API Gateway Tyk utilizando .NET 10

🧠 O que é um API Gateway?

🏗️ Arquitetura da Solução

⚙️ Criando a API com .NET 10

🧩 Instalando o Tyk API Gateway

📦 Criando uma Definição de API no Tyk

Explicando os principais campos:

🔄 Fluxo da Requisição

🔐 Adicionando Segurança com API Key

📊 Observabilidade e Monitoramento

🧪 Testando a Integração

⚡ Benefícios de Usar Tyk com .NET

🧩 Quando Utilizar um API Gateway

🔮 O Futuro das APIs no .NET

✅ Conclusão

🤝 Conecte-se Comigo

🚀 Que bom que chegou C# 13, Porém o mais novo também C# 14

O que mudou e como isso impacta seu código no .NET moderno

🧠 Visão Geral

🧩 Principais Novidades do C# 13

1️⃣ Params Collections

2️⃣ Melhorias em ref struct

3️⃣ Melhorias em Pattern Matching

🚀 Principais Evoluções do C# 14

1️⃣ Inicialização Mais Simples

2️⃣ Pattern Matching Mais Poderoso

3️⃣ Melhor Interoperabilidade com Código Nativo

4️⃣ Melhorias Incrementais em Expressões

🏗️ Impacto Arquitetural

🔹 Para aplicações corporativas

🔹 Para sistemas de alta performance

🔹 Para times grandes

📊 Comparação Prática

C# 13

C# 14

🧩 Quando Atualizar?

🔮 O Caminho do C

✅ Conclusão

🤝 Conecte-se Comigo

Integrando Sentry com .NET

📖 Introdução

🧱 Visão Geral do Projeto

Características Principais

2️⃣ Melhorias em `ref struct`