13. Serviços web
13.1. Introdução
No capítulo anterior, apresentamos várias aplicações cliente-servidor TCP/IP. Como os clientes e o servidor trocam linhas de texto, eles podem ser escritos em qualquer linguagem. O cliente só precisa conhecer o protocolo de comunicação esperado pelo servidor.
Os serviços web também são aplicações servidoras (TCP/IP). Eles têm as seguintes características:
- são hospedados por servidores web, e o protocolo de troca cliente-servidor é o HTTP (HyperText Transfer Protocol), um protocolo construído sobre o TCP/IP, que exploramos no capítulo anterior;
- o serviço web tem um protocolo de comunicação padrão, independentemente do serviço prestado. Um serviço web oferece vários serviços: S1, S2…, Sn. Cada um desses serviços espera parâmetros fornecidos pelo cliente e devolve um resultado ao cliente. Para cada serviço, o cliente precisa saber:
- como especificar o serviço Si;
- a lista de parâmetros a fornecer e seus tipos;
- o tipo de resultado devolvido pelo serviço. Conhecidos esses elementos, o diálogo cliente-servidor segue o mesmo formato, qualquer que seja o serviço web consultado. Isso padroniza a comunicação do cliente;
- Para se proteger de ataques vindos da Internet, muitas organizações abrem para o exterior apenas algumas portas de seus servidores: principalmente as portas 80 (HTTP) e 443 (HTTPS) para o serviço web. Todas as outras portas são bloqueadas. Consequentemente, aplicações cliente-servidor como as descritas no capítulo anterior ficam em geral restritas à rede privada da organização (intranet). Hospedar um serviço em um servidor web o torna acessível a toda a comunidade da Internet;
- o serviço web pode ser visto como um objeto remoto: os serviços que ele oferece passam a ser métodos desse objeto. Um cliente pode usar esse objeto remoto como se fosse local, por meio de um objeto intermediário chamado proxy, que oculta toda a comunicação de rede. Isso permite construir um cliente independente dessa camada: se a camada mudar, o restante do cliente não precisa ser modificado;
- Assim como nas aplicações cliente-servidor TCP/IP do capítulo anterior, o cliente e o servidor podem ser escritos em qualquer linguagem de programação. Eles trocam linhas de texto compostas de duas partes: os cabeçalhos exigidos pelo protocolo HTTP e o corpo da mensagem, cujo formato é combinado entre o cliente e o servidor.
A arquitetura de uma aplicação cliente-servidor baseada em serviço web é a seguinte:

Trata-se de uma extensão da arquitetura em camadas do Capítulo 6, à qual são acrescentadas camadas especializadas de comunicação de rede: o cliente do serviço web no lado do cliente e o próprio serviço web no lado do servidor. Já encontramos uma arquitetura semelhante com o servidor TCP de cálculo do imposto (versão 8) do capítulo anterior.
13.1.1. Ontem: SOAP e WSDL
Em 2008, este curso usava os serviços web SOAP do .NET Framework: arquivos [.asmx] criados com o Visual Web Developer, cujos métodos públicos eram marcados com o atributo [[WebMethod]]. O cliente enviava uma requisição HTTP POST cujo corpo era um documento XML no formato SOAP (Simple Object Access Protocol): um “envelope” contendo o nome do método e seus parâmetros. O servidor respondia com outro envelope XML contendo o resultado. Cada serviço era descrito por um documento XML no formato WSDL (Web Services Description Language), disponível na URL do serviço seguida de [?WSDL]: ele listava os métodos, seus parâmetros e seus tipos. A partir desse documento, ferramentas (o assistente “Add Web Reference” do Visual Studio, [wsimport] em Java) geravam automaticamente o proxy do serviço. Essa tecnologia, e depois sua sucessora WCF (Windows Communication Foundation), foi amplamente usada nos anos 2000. Hoje estão obsoletas: nem o ASMX nem o componente de servidor do WCF existem no .NET (Core); existe apenas um port da comunidade, o CoreWCF, para migrar aplicações legadas. Os motivos desse abandono são o peso do XML e dos envelopes SOAP, a complexidade dos padrões associados (WS-Security, WS-Addressing etc.) e a dificuldade de chamar esses serviços a partir de um navegador.
13.1.2. Hoje: REST e JSON
A maioria dos serviços web atuais segue o estilo REST (REpresentational State Transfer) e troca documentos JSON (JavaScript Object Notation, apresentado no Capítulo 5). O estilo REST se baseia nos seguintes princípios:
- o serviço expõe recursos, cada um designado por uma URL: [/tax], [/clients/12], [/clients/12/orders];
- esses recursos são acessados por meio dos métodos (também chamados de verbos) do protocolo HTTP, cada um com um significado específico;
- o resultado da ação é indicado pelo código de status HTTP da resposta;
- o corpo das requisições e das respostas é, na maioria das vezes, um documento JSON, mais compacto e mais simples que o XML;
- o serviço é sem estado (stateless): cada requisição contém todas as informações necessárias ao seu processamento; o servidor não guarda nenhuma informação de uma requisição para a seguinte para um determinado cliente.
Os métodos HTTP mais usados são os seguintes:
Método | Uso | Exemplo |
GET | Ler um recurso; os eventuais parâmetros estão na URL | GET /clients/12 |
POST | Criar um recurso ou solicitar um processamento; os dados estão no corpo da requisição | POST /clients |
PUT | Substituir um recurso | PUT /clients/12 |
PATCH | Modificar parte de um recurso | PATCH /clients/12 |
DELETE | Excluir um recurso | DELETE /clients/12 |
Os códigos de status, apresentados no capítulo anterior, ganham aqui todo o seu sentido:
Código | Significado |
200 OK | A requisição foi bem-sucedida; o corpo da resposta contém o resultado |
201 Created | O recurso foi criado; o cabeçalho [Location] fornece sua URL |
204 No Content | A requisição foi bem-sucedida; a resposta não tem corpo |
400 Bad Request | A requisição é inválida (parâmetro ausente ou inválido etc.) |
404 Not Found | O recurso solicitado não existe |
500 Internal Server Error | Ocorreu um erro inesperado no servidor |
Um serviço REST não tem um equivalente obrigatório ao WSDL. Contudo, é prática comum descrevê-lo com um documento OpenAPI (antes chamado Swagger), em formato JSON ou YAML, a partir do qual ferramentas podem gerar documentação, páginas de teste e clientes. Voltaremos a isso mais adiante.
Por fim, vale mencionar o gRPC, concebido pelo Google: os métodos do serviço e suas mensagens são descritos em um arquivo [.proto], a partir do qual ferramentas geram o servidor e o cliente, como se fazia na época do WSDL; as mensagens são codificadas em um formato binário compacto (Protocol Buffers) e transmitidas via HTTP/2. O gRPC é muito eficiente e popular para a comunicação entre serviços de uma mesma organização, mas é pouco adequado para navegadores. Está disponível para .NET com o pacote [Grpc.AspNetCore], que não usaremos.
13.1.3. ASP.NET Core e a Minimal API
Para desenvolver nossos serviços web, usaremos o ASP.NET Core, o framework de desenvolvimento web do .NET, e mais especificamente sua Minimal API (.NET 6, 2021): nesse framework, uma URL e um método HTTP são associados diretamente a uma função C#, quase sempre uma lambda. O servidor web é o Kestrel, um servidor HTTP escrito em C# e integrado à aplicação: não é necessário instalar um servidor web separado, como era o caso do IIS (Internet Information Services) em 2008. O ASP.NET Core faz parte do framework compartilhado [Microsoft.AspNetCore.App], instalado com o SDK do .NET: ele não exige nenhum pacote NuGet.
O Visual Web Developer, a ferramenta gratuita da Microsoft usada em 2008 para escrever serviços web, não existe mais: os comandos [dotnet] bastam, e qualquer editor de código serve (Visual Studio Code, Visual Studio, Rider).
13.2. Um primeiro serviço web
Vamos construir uma aplicação cliente-servidor simples, com a seguinte arquitetura simplificada:

Os projetos deste capítulo estão agrupados em uma solução chamada [13-web-services.slnx], criada com os comandos a seguir, digitados na pasta [13-web-services]:
Os projetos já estão incluídos no material do curso: a pasta [13-web-services] do arquivo ZIP contém a solução e os seis projetos, completos e modificados conforme descrito neste capítulo. O leitor, portanto, não precisa digitar os comandos acima (eles falhariam de qualquer modo, pois as pastas já existem): eles mostram como esses projetos foram criados e como criar os seus próprios. Para executar um projeto fornecido, basta ir até sua pasta e digitar [dotnet run] (ou abrir [13-web-services.slnx] no Visual Studio ou no VS Code). O mesmo vale, mais adiante, para os comandos [dotnet add ... reference] e [dotnet add ... package]: as referências e os pacotes já estão incluídos nos arquivos [.csproj] fornecidos.
O template [web] do [dotnet new] cria um projeto vazio de aplicação ASP.NET Core. Os três serviços web deste capítulo ([WsHello], [WsOperations], [WsTax]) são criados com esse template, e seus clientes são criados com o template padrão [console]. Isso resulta na seguinte estrutura de diretórios (apenas os arquivos principais são listados):
13.2.1. O lado do servidor

O arquivo de projeto [WsHello.csproj] gerado por [dotnet new web] é o seguinte:
Comentários:
- Linha 1: a única diferença em relação a um projeto de console é o SDK usado, [Microsoft.NET.Sdk.Web] em vez de [Microsoft.NET.Sdk]. O SDK web referencia o framework ASP.NET Core compartilhado e acrescenta os namespaces do ASP.NET Core aos namespaces [using] implícitos ([Microsoft.AspNetCore.Builder], [Microsoft.AspNetCore.Http], [Microsoft.Extensions.DependencyInjection], [Microsoft.Extensions.Logging]…);
- Não há uma linha para [OutputType]: uma aplicação web é sempre um executável.
O programa gerado [Program.cs] se reduz a quatro instruções:
- Linha 1: [WebApplication.CreateBuilder] prepara a aplicação web para a compilação: lê a configuração (arquivos [appsettings.json], variáveis de ambiente, argumentos de linha de comando), configura o log e configura o contêiner de injeção de dependência que usamos no Capítulo 6. [builder] permite completar essa preparação, por exemplo, registrando serviços no contêiner;
- linha 2: a aplicação é construída;
- linha 4: o método HTTP [GET] e a URL [/] (a raiz do site) são associados a uma lambda. Quando o servidor recebe a requisição [GET /], ele executa a lambda e envia o resultado, neste caso o texto [Hello World!], ao cliente;
- Linha 6: o servidor Kestrel é iniciado; ele aguarda requisições até que a aplicação seja interrompida (Ctrl-C).
O template também cria três arquivos de configuração:
- [appsettings.json]: a configuração da aplicação;
- [appsettings.Development.json]: valores que sobrescrevem os de [appsettings.json] quando a aplicação é executada no ambiente "Development";
- [Properties/launchSettings.json]: "perfis de execução" usados pelo [dotnet run] e pelo Visual Studio. Eles definem a porta de escuta, escolhida aleatoriamente pelo [dotnet new] (5273, por exemplo), e a variável de ambiente [ASPNETCORE_ENVIRONMENT=Development].
O ambiente de execução (Development, Staging, Production) altera o comportamento da aplicação. Em particular, no ambiente Development, uma exceção não tratada produz uma resposta contendo todos os detalhes da exceção, inclusive a pilha de chamadas: isso é útil para o desenvolvedor, mas seria uma vulnerabilidade de segurança em produção. Para que nossos resultados correspondam ao que um usuário veria, removemos [launchSettings.json] e [appsettings.Development.json] (eles, portanto, estão ausentes dos projetos entregues): nossos serviços são executados no ambiente padrão, Production. A porta de escuta é então definida em [appsettings.json]:
- Linhas 2–5: log: as mensagens de nível [Information] e superiores são exibidas, exceto as do próprio ASP.NET Core (categoria [Microsoft.AspNetCore.*]), que se limitam a avisos ([Warning]) e erros;
- linha 8: os nomes de máquina aceitos nos cabeçalhos HTTP e [Host] das requisições; [*] aceita todos eles;
- linha 9: acrescentamos esta linha: o servidor escuta na porta 5100 da máquina [localhost]. O endereço também poderia ser passado como argumento: [dotnet run --urls http://localhost:5100], ou pela variável de ambiente [ASPNETCORE_URLS].
O serviço web [WsHello] é uma continuação do serviço de 2008, cujo único método, [SayHelloToTheLady], retornava a string [Hello Mrs xx]. Seu código, [Program.cs], é o seguinte:
Comentários:
- linha 6: a página raiz do site exibe um texto explicando como usar o serviço;
- linha 11: o modelo de URL (chamado de rota) [/hello/{name}] contém um parâmetro de rota [{name}]: ele corresponde a qualquer segmento de URL colocado depois de [/hello/]. Assim, a URL [/hello/Carla%20Bruni] atribui o valor [Carla Bruni] a [{name}] (o código [%20] representa um espaço em uma URL). O ASP.NET Core passa automaticamente esse valor ao parâmetro de mesmo nome na lambda: é o binding de parâmetros. O método web de 2008 tornou-se uma URL. A lambda retorna uma string: ela é enviada como está ao cliente, como um documento de texto (tipo [text/plain]);
- Linha 14: a mesma coisa, mas a lambda retorna um objeto do tipo [Greeting]. O ASP.NET Core serializa em JSON usando [System.Text.Json] (Capítulo 5) e o envia ao cliente como um documento do tipo [application/json]. Esse é o formato padrão da resposta de um serviço web REST;
- linha 17: o servidor aguarda requisições;
- linha 20: o tipo do resultado, um [record] (Capítulo 4). Em uma linguagem de programação de alto nível, as declarações de tipos vêm depois das instruções.
O serviço é iniciado pelo comando [dotnet run], digitado na pasta do projeto. Ele exibe seu log:
- linha 3: o servidor está escutando na porta 5100;
- linha 5: a aplicação está pronta. Ela pode ser interrompida com Ctrl-C;
- linha 7: o ambiente de execução é Production;
- linha 9: a pasta raiz do conteúdo da aplicação, onde são procurados [appsettings.json] e a pasta [wwwroot] contendo os arquivos estáticos. Com [dotnet run], é a pasta do projeto (o curso substituiu o início do caminho por [...]);
- Linha 11: essa mensagem apareceu quando o servidor foi interrompido com Ctrl-C, após os testes descritos nos parágrafos seguintes.
Cada mensagem de log indica seu nível ([info], [warn], [fail], [crit]…) e sua categoria, neste caso [Microsoft.Hosting.Lifetime]—seguida de um número de evento entre colchetes.
13.2.2. Consultando o serviço com curl
Com o serviço em execução, vamos consultá-lo em uma segunda janela de comando usando a ferramenta [curl] apresentada no capítulo anterior. A opção [-i] exibe os cabeçalhos da resposta antes do corpo, e a opção [-s] (silent) suprime a barra de progresso:
- linha 2: a requisição foi bem-sucedida;
- linha 3: o documento é texto (UTF-8);
- linha 6: o documento é enviado em blocos (chunks), cada um precedido de seu tamanho: o Kestrel não precisou calcular o tamanho total do documento antes de começar a enviá-lo;
- linha 8: o resultado do método web.
Em 2008, o serviço ASMX respondia com um documento XML: [<string xmlns="http://st.istia.univ-angers.fr">Hello Mrs Carla Bruni</string>]. Vamos agora pedir a versão JSON:
- linha 3: o documento agora é do tipo [application/json];
- linha 8: o objeto [Greeting] serializado. Observe que os nomes das propriedades C# [Name] e [Message] se tornaram [name] e [message]: o ASP.NET Core usa as opções JSON “Web” do [System.Text.Json] ([JsonSerializerDefaults.Web], Capítulo 5), que escrevem os nomes em “camelCase”, como se usa em JavaScript.
Uma URL que não corresponde a nenhuma rota retorna uma resposta 404:
Também é possível digitar a URL [http://localhost:5100/hello/Carla Bruni] na barra de endereços de um navegador, que exibirá o texto recebido: um serviço web consultado por GET pode ser testado com muita facilidade. Em 2008, o servidor ASMX gerava uma página de teste (HTML) para cada método.
13.2.3. Um cliente de console

É possível implementar o cliente do serviço com um simples cliente TCP, como mostrado no capítulo anterior: basta enviar a requisição HTTP e ler a resposta. No entanto, usamos a classe [HttpClient], também apresentada no capítulo anterior, que cuida do protocolo HTTP para nós. O projeto [ClientWsHello] é um projeto de console padrão. Seu programa é o seguinte:
Comentários:
- linha 1: o namespace dos métodos de extensão de [HttpClient] que trocam JSON;
- linha 5: a URL do serviço é passada como argumento ou, na falta dele, assume por padrão [http://localhost:5100/]. Isso equivale ao arquivo [app.config] de 2008, que continha o endereço do serviço: se ele mudar, o cliente não precisa ser recompilado;
- Linha 8: um único [HttpClient] para todo o programa. Sua propriedade [BaseAddress] é a URL base, à qual são acrescentadas as URLs relativas das requisições. Atenção: a URL base deve terminar com [/] para que [hello/...] seja acrescentado a ela;
- Linha 22: o nome digitado se torna um segmento da URL. [Uri.EscapeDataString] codifica os caracteres não permitidos nela: um espaço se torna [%20], o caractere “é” se torna [%C3%A9]…;
- linha 24: uma requisição GET cuja resposta é lida como uma cadeia de caracteres;
- linha 27: uma requisição GET cuja resposta JSON é desserializada em um objeto do tipo [Greeting]. O cliente não tem acesso ao tipo [Greeting] do servidor: ele declara o seu próprio (linha 38), com os mesmos nomes de propriedades. A desserialização também usa as opções “Web”, que ignoram a diferença entre maiúsculas e minúsculas nos nomes: [name] é atribuído à propriedade [Name];
- linha 30: os dois métodos lançam uma [HttpRequestException] se o serviço estiver inacessível ou se responder com um código de erro (4xx, 5xx).
Resultados, com o serviço em execução:
A linha 4 exibe o objeto [Greeting] recebido no formato do método [ToString] gerado para o [record]. Se for indicado um endereço onde nenhum serviço está escutando, a conexão é recusada:
Em 2008, o cliente usava um proxy da classe [ServiceSoapClient], gerado pelo Visual Studio a partir do WSDL do serviço, e chamava o método remoto como se fosse um método local: [new ServiceSoapClient().SayHelloToTheLady("Carla Bruni")]. Aqui, chamamos diretamente a URL do serviço. Escreveremos um verdadeiro proxy para o serviço de cálculo do imposto.
13.2.4. A descrição do serviço: OpenAPI
O documento WSDL de 2008 descrevia o serviço em um formato padronizado. Seu equivalente atual é o documento OpenAPI. Desde a versão 9 do .NET, o ASP.NET Core pode gerá-lo a partir das rotas declaradas, usando o pacote [Microsoft.AspNetCore.OpenApi]:
O documento [/openapi/v1.json] descreve então cada rota: sua URL, seu método HTTP, seus parâmetros e respectivos tipos, e o esquema JSON de suas respostas. Ferramentas como Swagger UI ou Scalar geram a partir dele uma página web de testes, e geradores como Kiota ou NSwag geram um cliente tipado em várias linguagens, assim como o assistente “Add Web Reference” fazia com o WSDL. Como o pacote [Microsoft.AspNetCore.OpenApi] não está disponível em nossa máquina de teste (que não tem acesso à Internet), não podemos mostrar o documento gerado.
13.3. Um serviço web para operações aritméticas
O serviço anterior oferecia um único método. Vamos agora considerar, como fizemos em 2008, um serviço web que oferece as quatro operações aritméticas: add(a, b), subtract(a, b), multiply(a, b) e divide(a, b). Aproveitaremos para estudar as duas formas de passar parâmetros a um serviço web e como sinalizar erros.
13.3.1. O lado do servidor
O serviço [WsOperations] aceita dois tipos de requisição:
Requisição | Parâmetros |
GET /add?a=1.5&b=2 | A operação no caminho da URL, os números em sua query string |
POST /calculation | um documento JSON no corpo da requisição: [{"operation":"add","a":1.5,"b":2}] |
Nos dois casos, a resposta é um documento JSON: [{"operation":"add","a":1.5,"b":2,"result":3.5}]. O GET é adequado para requisições simples que não modificam nada no servidor: a URL pode ser digitada em um navegador, guardada nos favoritos, e sua resposta pode ser armazenada em cache. O POST é adequado para dados volumosos ou estruturados. Seu arquivo [appsettings.json] é idêntico ao de [WsHello], exceto pela porta (5110). Seu programa é o seguinte:
Comentários:
- Linha 6: é registrado o serviço que gera respostas de erro no formato Problem Details . Esse formato, padronizado pela RFC 9457, é um documento JSON do tipo [application/problem+json] que descreve um erro: seu tipo, um título, o código de status, um detalhe e eventuais informações adicionais. Essa é a forma padrão de um serviço REST indicar o que está errado;
- Linha 9: instalamos um middleware, isto é, um elo da cadeia de processamento pela qual passa toda requisição. Esse middleware acrescenta um corpo “Problem Details” às respostas de erro que não têm um, como as respostas 404 geradas pelo ASP.NET Core para requisições de URLs desconhecidas;
- Linhas 13–14: a requisição GET. O parâmetro [operation] da lambda é vinculado ao parâmetro de rota [{operation}]. Os parâmetros [a] e [b], que não aparecem na rota, são vinculados aos parâmetros de mesmo nome da query string ([?a=1.5&b=2]). Eles são declarados com o tipo [string?]: um parâmetro ausente é tratado como [null]. Poderíamos tê-los declarado com o tipo [double]: o ASP.NET Core faria então a conversão por conta própria e rejeitaria um valor ausente ou incorreto com uma resposta 400 sem explicação. Ao recebê-los como strings, mantemos o controle sobre as mensagens de erro;
- linhas 18–19: a requisição POST. O parâmetro [request] é de um tipo complexo ([CalculationRequest], linha 72): o ASP.NET Core o desserializa a partir do corpo JSON da requisição. Suas propriedades aceitam nulos: uma propriedade ausente do documento JSON recebe o valor [null];
- linhas 25–26: a conversão de uma string em número; se ela falhar, o resultado é [null]. Tanto na URL quanto no JSON, os números são escritos com ponto decimal: a conversão é feita com a cultura invariante (Capítulo 5), e não com a cultura do servidor, que poderia esperar uma vírgula (a cultura francesa, por exemplo). As funções locais [ReadNumber] e [Calculate] são declaradas depois de [app.Run]; elas são estáticas ([static]) porque não usam nenhuma variável do programa principal;
- linhas 33–39: a operação solicitada é representada por um delegate (Capítulo 7) selecionado por uma expressão [switch]: uma lambda por operação; [null] para uma operação desconhecida;
- linhas 42–53: os três parâmetros são verificados acumulando os erros em um dicionário que associa cada parâmetro à sua lista de mensagens de erro;
- linha 55: se um erro foi encontrado, uma resposta 400 é retornada. O filtro por padrão [a is not double x] é verdadeiro se [a] for igual a [null]; caso contrário, atribui o valor de [a] à variável [x]. O compilador sabe que, depois desse [if], [calculation], [x], e [y] têm valores: ele não emite nenhum aviso;
- linha 58: a classe estática [Results] retorna as respostas usuais. [ValidationProblem] retorna uma resposta 400 no formato “Problem Details” contendo os erros de validação (propriedade [errors]);
- Linhas 62–65: a divisão por zero é rejeitada com uma resposta 400 no formato “Problem Details”, gerada por [Results.Problem]. Essa rejeição é necessária: em C#, dividir um [double] por zero não lança uma exceção, mas retorna infinito ([double.PositiveInfinity]), que um documento JSON não consegue representar. O serviço de 2008, que não fazia essa verificação, teria retornado infinito, que a serialização XML do .NET escreve como [INF];
- linha 68: a resposta 200, cujo corpo é o objeto [CalculationResult] serializado em JSON;
- linhas 72–74: os dois tipos trocados com os clientes. Esses objetos, usados unicamente para transportar dados entre duas aplicações, são chamados de DTO (Data Transfer Object). Os objetos [record] são ideais para essa finalidade.
O método [Calculate] retorna um objeto do tipo [IResult]: essa é a interface dos objetos produzidos por [Results]. Cada um grava a resposta HTTP correspondente (código de status, cabeçalhos, corpo).
13.3.2. Testando com curl
O serviço é iniciado por [dotnet run] na pasta [WsOperations]. Uma adição:
Divisão por zero:
- Linha 2: a requisição é rejeitada;
- linha 3: o corpo é um documento “Problem Details”;
- linha 8: o documento contém as propriedades [type] (uma URL que documenta o tipo do erro, neste caso a seção da RFC 9110 que define o código 400), [title], [status] e [detail], definidas por nossa chamada a [Results.Problem], e [traceId], um identificador único da requisição que permite localizá-la nos logs do servidor.
Uma operação desconhecida, um número escrito com vírgula decimal e um número ausente:
A propriedade [errors] do documento contém os erros de validação, parâmetro por parâmetro. Agora, uma requisição POST. A opção [-d] do [curl] envia o texto que a segue no corpo de uma requisição POST, e a opção [-H] acrescenta um cabeçalho à requisição, neste caso o tipo do documento enviado:
Se o documento JSON enviado estiver incorreto, o ASP.NET Core não consegue construir o parâmetro [request]: ele responde por conta própria com um erro 400, sem executar nossa lambda:
O documento “Problem Details” da linha 8 foi gerado pelo middleware [UseStatusCodePages]. No ambiente Development, ele conteria a descrição completa do erro de desserialização.
13.3.3. O lado do cliente

O cliente gráfico de 2008 tinha uma lista de operações, dois campos de entrada e um botão. Nosso cliente de console pede ao usuário a operação e os dois números em uma única linha e, em seguida, consulta o serviço duas vezes: primeiro com GET, depois com POST, para demonstrar os dois métodos. Eis o programa:
Comentários:
- linhas 25–32: os números são validados localmente antes de qualquer chamada ao serviço, como fazia o cliente gráfico de 2008. Eles são digitados com ponto decimal (cultura en-US);
- linhas 40–41: a URL da requisição GET. Os números devem ser escritos nela com ponto: como a interpolação [$"..."] usa a localidade atual, a string é construída com [string.Create], que recebe a localidade a ser usada, neste caso a localidade invariante;
- linha 45: a requisição GET e a desserialização de sua resposta JSON em um objeto [CalculationResult]. Se o código de status da resposta não for um código de sucesso (2xx), [GetFromJsonAsync] lança uma [HttpRequestException]: o corpo da resposta, que explica o erro, é então perdido;
- linha 51: a propriedade [StatusCode] da exceção contém o código de status da resposta, ou [null] se o serviço não respondeu (serviço inacessível);
- linha 57: a requisição POST: o objeto [CalculationRequest] é serializado em JSON no corpo da requisição. [PostAsJsonAsync] não lança exceção para um código de erro: ele retorna a resposta ([HttpResponseMessage]), que examinamos;
- linha 58: [true] para um código 2xx;
- linha 61: em caso de sucesso, o corpo é desserializado em um objeto [CalculationResult];
- linhas 67–75: se a requisição falhar, o corpo é um documento “Problem Details”, desserializado em um objeto [Problem] (linha 90), a partir do qual são exibidos o título, os detalhes e os erros de validação. O laço [foreach] percorre cada elemento do dicionário [Errors] decompondo-o em uma tupla (Capítulo 5); [?? []] substitui um dicionário ausente por uma coleção vazia;
- linhas 87–90: os arquivos de DTO do cliente. Eles são declarados novamente aqui: um cliente não compartilha o código do servidor, apenas o formato dos documentos JSON trocados. O ASP.NET Core de fato fornece uma classe [ProblemDetails], mas ela faz parte do framework web; um simples [record] basta para o cliente.
Resultados, com o serviço em execução:
- linha 3: a URL da requisição GET: o número 1.5 digitado é escrito como 1.5;
- Linhas 6–8: observa-se o mesmo erro nas duas requisições: [GetFromJsonAsync] só reconhece o código 400, enquanto a leitura da resposta do POST revela a explicação fornecida pelo serviço;
- linhas 11–12: a operação desconhecida foi detectada pelo serviço;
- linha 14: o número incorreto foi detectado pelo cliente, que não consultou o serviço.
13.4. Aplicação de exemplo, versão 9: um serviço web de cálculo do imposto
Vamos retomar a aplicação de cálculo do imposto. No capítulo anterior (versão 8), havíamos criado um servidor TCP que podia ser consultado remotamente, com um protocolo de comunicação próprio. Vamos agora transformá-lo em um serviço web REST.
13.4.1. A arquitetura
A arquitetura da versão 9 é a seguinte:

- no lado do servidor, o serviço web [WsTax] recebe requisições HTTP e as faz ser processadas pelas camadas [business] e [dao] da versão 5 (Capítulo 6), que são reutilizadas sem alterações;
- no lado do cliente, a camada [ui] da versão 5 também é reutilizada sem alterações. Ela se comunica com um novo tipo de camada [business], [TaxBusinessHttp], que implementa a interface [ITaxBusiness] consultando o serviço web: ela atua como proxy do serviço. A camada [ui] não sabe que o cálculo é realizado em outra máquina;
- em ambos os lados, a integração das camadas fica a cargo do contêiner de injeção de dependência, que substitui o Spring.NET usado em 2008.
13.4.2. O serviço web
O contrato do serviço é o seguinte:
Requisição | Resposta em caso de sucesso | Resposta em caso de erro |
GET /tax?married=y&children=2&salary=60000 | 200: [{"tax":4282}] | 400: documento "Problem Details" |
POST /tax com o corpo [{"married":true,"children":2,"salary":60000}] | 200: [{"tax":4282}] | 400: documento "Problem Details" |
O projeto [WsTax] referencia os projetos das camadas [dao] e [business] da versão 5:
- Linhas 11–12: as duas referências de projeto. Elas são adicionadas com o comando [dotnet add WsTax reference ../06-architectures/TaxV5/Tax.Dao ../06-architectures/TaxV5/Tax.Business], digitado na pasta [13-web-services] (desnecessário para o projeto entregue, no qual já estão presentes). Os arquivos de dados [TaxData.txt] e [TaxData.json] do projeto [Tax.Dao] são copiados para junto do executável do serviço (Capítulo 6).
Em 2008, os arquivos DLL das camadas tinham de ser copiados para uma pasta [lib] do site e adicionados às referências do projeto. O arquivo de configuração [appsettings.json] é o seguinte:
- linha 9: o serviço escuta na porta 5120;
- Linhas 10–12: a configuração da camada [dao], no mesmo formato do arquivo [appsettings.json] da versão 5: a implementação a usar e seu arquivo de dados. Aqui, usamos o arquivo JSON.
O programa do serviço é o seguinte:
Comentários:
- Linhas 10–11: a configuração da camada [dao] é lida de [builder.Configuration]. Esse objeto combina todas as fontes de configuração: o arquivo [appsettings.json], as variáveis de ambiente e os argumentos de linha de comando. No Capítulo 6, tivemos de construir nós mesmos um [ConfigurationBuilder]; o ASP.NET Core faz isso por nós;
- linhas 12–20: registro das camadas [dao] e [business] no contêiner de injeção de dependência do ASP.NET Core, [builder.Services]. Essas linhas vêm do programa principal da versão 5: o contêiner é o mesmo ([IServiceCollection]); a única diferença é o local de onde ele é obtido. Em 2008, essa integração era feita pelo Spring.NET, configurado no arquivo [web.config];
- Linhas 28–35: as duas camadas são singletons, criados pelo contêiner na primeira requisição. Provocamos essa criação logo na inicialização, antes de processar qualquer requisição: se o arquivo de dados estiver ausente ou incorreto, o serviço para imediatamente com uma mensagem clara, em vez de devolver um erro 500 a todas as requisições. Esse é o papel que o método [Application_Start] do arquivo [Global.asax] desempenhava em 2008. [app.Logger] é o log da aplicação; [LogCritical] grava nele uma mensagem de nível crítico. O texto da mensagem é um template: [{Message}] e [{Cause}] são substituídos pelos argumentos seguintes, em ordem. Ao contrário de uma interpolação de strings, o template permite que as ferramentas de log registrem cada valor separadamente;
- linha 39: um componente de middleware que transforma uma exceção não tratada em uma resposta 500 no formato “Problem Details”, sem revelar os detalhes;
- Linhas 43–44: dois componentes de middleware para o cliente web descrito no parágrafo seguinte. [UseStaticFiles] serve os arquivos da pasta [wwwroot] do projeto (páginas HTML, imagens, scripts etc.); [UseDefaultFiles] serve o documento [index.html] para a URL [/]. São as mesmas linhas de qualquer site: um único servidor pode hospedar ao mesmo tempo um site e um serviço web;
- linhas 47–52: a requisição GET. O parâmetro [business] da lambda não está nem na rota nem na query string: o ASP.NET Core o encontra no contêiner de injeção de dependência, que fornece a camada [business]. Os outros três parâmetros são strings, convertidas pela lambda: [y]/[n] para [married], inteiros para [children] e [salary], e [null] em caso de erro;
- Linhas 55–56: a requisição POST: o corpo JSON é desserializado em um objeto [TaxRequest] (linha 92), cujas propriedades anuláveis permitem detectar valores ausentes. A mesma URL [/tax] é associada a duas lambdas, conforme o método HTTP da requisição;
- Linha 59: [app.Run] só devolve o controle quando o servidor é encerrado. Como o programa contém uma instrução [return 1], ele também deve retornar um código ao terminar normalmente;
- Linha 63: a função local que processa as duas requisições. Ela não é estática porque usa a variável [app] do programa principal para o log. Seu tipo de retorno, [Results<Ok<TaxResponse>, ValidationProblem>], lista as respostas possíveis: uma resposta 200 contendo um objeto [TaxResponse], ou uma resposta 400 de validação. Esses tipos são definidos no namespace [Microsoft.AspNetCore.Http.HttpResults] (linha 4), e seus objetos são criados pela classe [TypedResults] (linhas 71 e 88): é a versão tipada da classe [Results] usada por [WsOperations]. Voltaremos a isso nas notas complementares;
- linha 66: um filtro por padrão que verifica os três parâmetros e, se estiverem corretos, os atribui às variáveis [isMarried], [nbChildren] e [amount]. [children is int nbChildren and >= 0] é verdadeiro se [children] não for [null] e for positivo ou zero (padrões relacionais e lógicos do C# 9);
- linha 68: o cálculo é delegado à camada [business] da versão 5;
- linha 69: cada cálculo é registrado no log;
- linhas 74–88: em caso de erro, a lista de erros é construída, um aviso ([LogWarning]) é registrado no log e uma resposta 400 é retornada;
- linha 79: [children is not >= 0] é verdadeiro se [children] for igual a [null] ou negativo;
- Linhas 92–94: os DTOs do serviço.
Em 2008, o serviço web era um objeto criado a cada requisição e depois destruído: ele não podia reter nenhum estado entre requisições. O mesmo vale aqui: as lambdas são executadas a cada requisição e não retêm nenhum estado. Somente os singletons [ITaxDao] e [ITaxBusiness], criados uma única vez, persistem durante toda a aplicação; eles são compartilhados por todas as requisições, que podem ser processadas simultaneamente por threads diferentes. Isso não é um problema aqui, pois esses objetos nunca são modificados depois de criados: as faixas de imposto são lidas uma única vez. O contêiner do ASP.NET Core tem três tempos de vida: [AddSingleton] (um objeto para toda a aplicação), [AddScoped] (um objeto por requisição HTTP) e [AddTransient] (um objeto para cada solicitação ao contêiner).
13.4.3. Execução do serviço
Comecemos por um erro de configuração. Os argumentos de linha de comando na forma [--Key=value] fazem parte da configuração da aplicação e sobrescrevem os valores de [appsettings.json]; o caractere [:] separa os níveis da hierarquia. Vamos especificar um arquivo de dados inexistente:
O serviço para antes mesmo de abrir sua porta de escuta. As mensagens de exceção da camada [dao] (Capítulo 6) estão em inglês, como as do .NET. Agora vamos iniciar o serviço normalmente, com [dotnet run], e depois consultá-lo com [curl]:
Este é o valor de verificação esperado: um contribuinte casado, com dois filhos e salário anual de 60.000 euros, paga 4.282 euros de imposto (observe que a tabela de imposto usada, a de 2004, é mantida apenas para este exercício fiscal). Com parâmetros incorretos:
Depois, com POST e um documento JSON:
O log do serviço será mostrado no final do capítulo: ele contém o registro de todos os cálculos solicitados.
13.4.4. O cliente de console: uma nova camada [business]
O cliente da versão 9 reutiliza a camada [ui] da versão 5 sem modificá-la: a classe [Ui.Dialog], cujo método [Run(ITaxBusiness business)] interage com o usuário e solicita os cálculos à camada [business] que lhe é passada. Basta passar a ela uma camada chamada [business] que consulte o serviço web. O projeto [ClientWsTax] é o seguinte:
- Linhas 12–13: referências a projetos da versão 5: [Tax.Business] para a interface [ITaxBusiness], e [Tax.Ui] para a classe [Dialog]. Um projeto pode referenciar um projeto executável: neste caso, ele usa suas classes públicas sem executar seu programa principal. O projeto [Tax.Dao] é referenciado indiretamente (via [Tax.Business]): o cliente usa dele apenas a classe [TaxException];
- linha 18: este pacote integra a criação de objetos [HttpClient] ao contêiner de injeção de dependência. As referências e o pacote são adicionados na pasta [13-web-services] com os comandos [dotnet add ClientWsTax reference ../06-architectures/TaxV5/Tax.Business ../06-architectures/TaxV5/Tax.Ui] e [dotnet add ClientWsTax package Microsoft.Extensions.Http --version 10.0.12] (desnecessários para o projeto entregue). O pacote [Microsoft.Extensions.DependencyInjection] já é fornecido pelo projeto [Tax.Ui].
A nova camada [business] é a classe [TaxBusinessHttp]:
Comentários:
- linha 10: a classe implementa a interface [ITaxBusiness] da versão 5. Ela recebe, por meio de seu construtor primário (Capítulo 4), um [HttpClient] cuja URL base é a do serviço;
- Linhas 15–17: a requisição [POST tax]. Seu corpo é um objeto [JsonContent], que serializa o objeto [TaxRequest] em JSON usando as opções “Web”;
- linha 20: a requisição é enviada de forma síncrona (veja abaixo);
- linhas 22–26: uma resposta de erro é convertida em [TaxException], a exceção da aplicação de [Tax], cujo código é o código de status HTTP;
- linhas 30–31: o corpo da resposta é lido de forma síncrona como um stream e desserializado em um objeto [TaxResponse]. [JsonSerializerOptions.Web] (.NET 9) designa as opções “Web”;
- linhas 36–37: os objetos DTO, declarados dentro da classe ([private]) porque ninguém mais os usa.
É exatamente o que fazia a classe [ImpotMetierWs] de 2008, que implementava [IImpotMetier] delegando o cálculo ao proxy [ServiceImpotSoapClient] gerado pelo Visual Studio: a diferença é que hoje escrevemos nós mesmos as cerca de dez linhas do proxy.
Surge uma dificuldade: o método [CalculateTax] da interface [ITaxBusiness] é síncrono (retorna um [int]), ao passo que os métodos padrão de [HttpClient] ([GetFromJsonAsync], [PostAsJsonAsync]…) são assíncronos (retornam uma [Task]; veja o Capítulo 9). Há três soluções possíveis:
- chamar o método assíncrono e aguardar seu resultado de forma bloqueante: [client.PostAsJsonAsync(...).GetAwaiter().GetResult()]. Isso é chamado de “sync over async”. Funciona em uma aplicação de console, mas bloqueia uma thread que apenas espera e pode causar deadlocks em aplicações com contexto de sincronização (interfaces gráficas, ASP.NET legado). Essa solução deve ser evitada;
- usar os métodos síncronos de [HttpClient]: [Send] (desde o .NET 5) envia a requisição e retorna a resposta, e [HttpContent.ReadAsStream] lê seu corpo. A thread fica bloqueada durante a troca, que é o comportamento esperado de um método síncrono, mas sem o desvio por uma tarefa assíncrona. Foi a solução que adotamos: ela respeita a interface existente e permite, assim, reutilizar a camada [ui];
- tornar a interface assíncrona: [Task<int> CalculateTaxAsync(bool married, int nbChildren, int salary)]. Essa é a melhor solução para uma aplicação que precisa atender a um grande número de usuários, mas exige modificar a interface [ITaxBusiness], suas implementações e a camada [ui]: todas as camadas se tornam assíncronas. Não fizemos isso para manter intactas as camadas da versão 5.
O programa principal do cliente integra as seguintes camadas:
Comentários:
- linha 7: a URL do serviço, passada como argumento ou, por padrão, [http://localhost:5120/];
- linha 10: o contêiner de injeção de dependência, como na versão 5;
- linha 13: o método [AddHttpClient] do pacote [Microsoft.Extensions.Http] registra [TaxBusinessHttp] como implementação de [ITaxBusiness], como um “cliente tipado”: quando o contêiner cria um [TaxBusinessHttp], ele passa ao seu construtor um [HttpClient] configurado pela lambda, neste caso com a URL base do serviço. Os [HttpClient]s são produzidos por uma fábrica ([IHttpClientFactory]) que reutiliza as conexões de rede subjacentes: essa é a forma recomendada de criar [HttpClient]s em uma aplicação que usa injeção de dependência;
- linha 15: isso fornece a camada [business];
- linha 20: o diálogo da versão 5, sem nenhuma modificação;
- linhas 22–26: se o serviço não puder ser alcançado, a exceção se propaga da camada [business] pela camada [ui], que não a trata: ela é exibida pelo método [Dialog.DisplayError] da versão 5, e o programa é encerrado.
Resultados, com o serviço em execução:
Os valores de verificação do cálculo do imposto são: 4.282, 2.959 e 11.519 euros. A entrada incorreta na linha 8 foi detectada pela camada [ui], que não chamou a camada [business]: o serviço recebeu apenas requisições corretas. Se o serviço for interrompido:
A exceção [HttpRequestException], lançada pelo método [Send], encapsula a exceção [SocketException] da camada TCP (Capítulo 12).
13.5. Um cliente web para o serviço de cálculo do imposto
Em 2008, o curso desenvolvia em seguida um cliente web para o serviço: uma aplicação ASP.NET Web Forms cuja página [Default.aspx] exibia um formulário; a cada clique no botão [Calculer], o formulário era enviado ao servidor web, que consultava o serviço web remoto e devolvia ao navegador uma nova página completa contendo o valor do imposto. O ASP.NET Web Forms não existe no .NET (Core). Hoje, na maioria das vezes é o próprio navegador que consulta o serviço web, em JavaScript, e atualiza apenas a parte da página que mudou. A arquitetura agora é a seguinte:

- 1: o navegador solicita a página [/]; o servidor [WsTax] lhe envia o arquivo estático [wwwroot/index.html] (por meio dos componentes de middleware [UseDefaultFiles] e [UseStaticFiles] de seu programa);
- 2: a cada clique no botão [Calculate], o código JavaScript da página envia a requisição [POST /tax] ao serviço web e exibe na página o valor do imposto recebido, sem recarregá-la.
O serviço web não foi modificado: ele apenas serve um arquivo a mais. A página [index.html] é a seguinte:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | |
Comentários:
- linhas 15–44: o formulário, semelhante ao da versão de 2008: dois botões de opção para o estado civil, dois campos de entrada para o número de filhos e a renda, cada um seguido de uma célula onde será exibida uma mensagem de erro (se houver), um campo para o valor do imposto, um parágrafo para uma mensagem geral e dois botões;
- linhas 46–108: o código da página, em JavaScript, executado pelo navegador. O curso não aborda JavaScript; no entanto, esse código é próximo o bastante do C# para ser facilmente compreendido;
- linha 57: uma entrada que não seja um inteiro resulta em [null]; cabe ao serviço relatar o erro;
- linha 70: o manipulador de clique do botão [Calculate] (envio do formulário). Trata-se de uma função assíncrona ([async]), semelhante aos métodos assíncronos do C# (Capítulo 9);
- Linha 71: isso impede que o navegador envie o formulário por conta própria, o que causaria o carregamento de uma nova página;
- linhas 74–77: a requisição, um objeto JavaScript com o formato esperado por [POST /tax];
- linhas 80–83: a função [fetch] do navegador envia a requisição HTTP: o método [POST], o cabeçalho [Content-Type] e o corpo — a requisição serializada em JSON por [JSON.stringify]. A URL [tax] é relativa à página: a requisição é enviada ao servidor que forneceu a página. [await] aguarda a resposta sem bloquear o navegador;
- linha 85: o corpo da resposta é desserializado em um objeto;
- linhas 86–88: em caso de sucesso (código 2xx), o valor do imposto é exibido;
- linhas 91–94: se ocorrer um erro, o título do documento “Problem Details” é exibido, junto com as mensagens de erro sobre o número de filhos e o salário, cada uma ao lado do campo de entrada correspondente. Os operadores [?.] e [??] têm o mesmo significado que no C#;
- linhas 103–106: o botão [Clear] redefine o formulário localmente, sem consultar o serviço.
Agora que o serviço está em execução, vamos solicitar a URL [http://localhost:5120/] usando um navegador:

Depois de informar um cálculo e clicar no botão [Calculate]:

Se a entrada estiver incorreta, as mensagens de erro são as do serviço web:

Estas capturas de tela foram feitas com o navegador Chromium, controlado por um programa por meio da biblioteca Playwright: é assim que automatizamos o teste de uma interface web.
Aqui, a página e o serviço compartilham a mesma origem (mesmo protocolo, mesma máquina, mesma porta: [http://localhost:5120]). Se a página fosse servida por outro site, por exemplo [http://localhost:5000], o navegador aplicaria a política de mesma origem: ele só permitiria que o código JavaScript lesse a resposta do serviço se este a autorizasse por meio do cabeçalho [Access-Control-Allow-Origin]. Para uma requisição como a nossa (POST com corpo JSON), o navegador chegaria a solicitar essa autorização antes de enviar a requisição, por meio de uma requisição preliminar com o método OPTIONS (preflight). Esse é o mecanismo CORS (Cross-Origin Resource Sharing), que protege o usuário de páginas maliciosas que poderiam tentar usar, sem que ele perceba, serviços nos quais ele está autenticado. Para aceitar outras origens, o serviço deve declará-las com [builder.Services.AddCors] e instalar o middleware correspondente com [app.UseCors]. Clientes que não são navegadores ([curl], nossos clientes de console) não são afetados pelo CORS.
Por fim, observe que, a partir do .NET 9, [app.MapStaticAssets()] pode substituir [app.UseStaticFiles()]: os arquivos estáticos passam a ser identificados e compactados em tempo de compilação e servidos com cabeçalhos de cache otimizados. Para interfaces web mais ricas, o ASP.NET Core oferece Razor Pages, MVC e Blazor, que não são abordados neste curso.
13.6. Um serviço web é independente da linguagem de programação do cliente
Em 2008, o curso terminava com um cliente Java para o serviço de cálculo do imposto, cujo proxy era gerado pela IDE NetBeans a partir do WSDL do serviço. Foi até necessário renomear o parâmetro [marié] do serviço para [marie], pois o acento causava um problema de interoperabilidade. Com um serviço REST/JSON, qualquer linguagem que tenha um cliente HTTP e uma biblioteca JSON — ou seja, todas as linguagens atuais — pode consultar o serviço sem nenhuma ferramenta especial. Já vimos isso com [curl], que não é escrito nem em C# nem em Java, e com o JavaScript do navegador. Eis um cliente escrito para Node.js, o ambiente de execução do JavaScript fora do navegador:
- linha 3: a URL do serviço, passada como argumento ou definida com o valor padrão;
- linhas 6–9: três requisições de cálculo, a última das quais é incorreta;
- linhas 14–17: a mesma função [fetch] do navegador;
- linhas 20–23: exibição do valor do imposto ou dos erros.
Com o serviço em execução:
Em Java, você usaria de forma semelhante a classe [java.net.http.HttpClient]; em Python, o módulo [requests] ou [httpx] . Por fim, eis o log do serviço [WsTax] durante todos os testes deste capítulo ([curl], cliente de console, navegador, cliente Node.js), até ser interrompido com Ctrl-C:
- As mensagens do serviço pertencem à categoria [WsTax]; o nome da aplicação, que é a categoria de log [app.Logger];
- As linhas [info] registram os cálculos, enquanto as linhas [warn] registram as requisições inválidas, junto com os nomes dos parâmetros envolvidos.
13.7. Informações adicionais
13.7.1. Resultados tipados: TypedResults
O serviço [WsOperations] usa a classe [Results], cujos métodos retornam todos o tipo [IResult]: pela assinatura de [Calculate], não fica claro quais respostas ele pode produzir. O serviço [WsTax] usa a classe [TypedResults], cujos métodos retornam tipos específicos: [Ok<T>], [ValidationProblem], [NotFound], [Created<T>]… O tipo união [Results<T1, T2, ...>] (até seis tipos) lista as respostas possíveis de uma lambda. Isso traz duas vantagens: o compilador verifica que nenhuma resposta inesperada é retornada, e as ferramentas (em particular o gerador de documentos OpenAPI) reconhecem automaticamente os códigos de status e os esquemas JSON das respostas, sem precisar que sejam informados explicitamente. Um teste de unidade também pode chamar a função e examinar o resultado tipado sem passar pelo HTTP. Essa é a abordagem recomendada hoje.
13.7.2. Grupos de rotas: MapGroup
Quando várias rotas compartilham um prefixo e uma configuração, elas podem ser agrupadas com [MapGroup]. Por exemplo, para colocar as rotas do serviço de operações sob [/api/operations]:
Tudo o que é aplicado ao grupo (um filtro, uma exigência de autenticação, metadados para o OpenAPI) vale para todas as suas rotas.
13.7.3. Filtros e validação
Nossos serviços validam seus próprios parâmetros. O ASP.NET Core oferece dois mecanismos para extrair esse código das lambdas:
- filtros de endpoint: o método [AddEndpointFilter] adiciona a uma rota (ou grupo) uma função executada antes da lambda; essa função pode examinar os argumentos e responder por conta própria — por exemplo, com uma resposta 400 — sem chamar a lambda;
- validação automática (.NET 10): depois de [builder.Services.AddValidation()], os parâmetros e DTOs anotados com os atributos de [System.ComponentModel.DataAnnotations] ([[Required]], [[Range(0, 100)]]…) são validados antes da execução da lambda, e os erros são retornados em uma resposta 400 “Problem Details”, como as que construímos.
13.7.4. Hospedagem
Nossos serviços são executados por [dotnet run], o que é adequado para o desenvolvimento. Em produção:
- a aplicação é primeiro implantada ([dotnet publish -c Release]): isso gera uma pasta contendo a aplicação compilada, que é então copiada para o servidor;
- o Kestrel pode ser exposto diretamente à Internet, mas costuma ser colocado atrás de um proxy reverso (IIS no Windows, nginx ou Apache no Linux) que recebe as requisições (HTTPS), gerencia os certificados e distribui a carga entre várias instâncias da aplicação;
- a aplicação também pode ser implantada como uma imagem de contêiner (Docker), que o SDK pode gerar sem um arquivo [Dockerfile]: [dotnet publish -t:PublishContainer]. A imagem pode então ser executada em qualquer plataforma de contêineres, seja local ou em um provedor de hospedagem (Azure, AWS etc.);
- o HTTPS é essencial: [dotnet dev-certs https] instala um certificado de desenvolvimento, e [app.UseHttpsRedirection()] redireciona as requisições de HTTP para HTTPS.
13.8. Conclusão
Este capítulo substituiu os serviços web SOAP de 2008 por serviços REST/JSON escritos com a Minimal API do ASP.NET Core. Vimos:
- que um serviço web mapeia URLs e métodos HTTP para funções C#, cujos parâmetros são derivados da rota, da query string, do corpo JSON ou do contêiner de injeção de dependência;
- que os resultados são retornados em JSON, e os erros são sinalizados por um código de status e um documento “Problem Details”;
- que um cliente .NET usa [HttpClient] e os métodos de [System.Net.Http.Json], e que um cliente escrito em qualquer outra linguagem pode fazer o mesmo;
- que a arquitetura em camadas cumpriu sua promessa: a Versão 9 do cálculo do imposto reutiliza, sem modificação, as camadas do lado do servidor [dao] e [business] da Versão 5, bem como sua camada do lado do cliente [ui]. Bastou escrever o serviço web (cerca de 100 linhas) e uma nova implementação da interface [ITaxBusiness] (cerca de 30 linhas).