Skip to content

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:

Image

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:

Image

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]:

1
2
3
4
5
6
7
8
> dotnet new web -n WsHello -o WsHello
> dotnet new console -n ClientWsHello -o ClientWsHello
> dotnet new web -n WsOperations -o WsOperations
> dotnet new console -n ClientWsOperations -o ClientWsOperations
> dotnet new web -n WsTax -o WsTax
> dotnet new console -n ClientWsTax -o ClientWsTax
> dotnet new sln --format slnx -n 13-web-services
> dotnet sln 13-web-services.slnx add WsHello ClientWsHello WsOperations ClientWsOperations WsTax ClientWsTax

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-web-services/
  13-web-services.slnx
  WsHello/                  “Hello” web service
    WsHello.csproj
    Program.cs
    appsettings.json
  ClientWsHello/            its console client
    ClientWsHello.csproj
    Program.cs
  WsOperations/             web service of the four operations
    WsOperations.csproj
    Program.cs
    appsettings.json
  ClientWsOperations/       its console client
    ClientWsOperations.csproj
    Program.cs
  WsTax/                    tax calculation web service (version 9)
    WsTax.csproj
    Program.cs
    appsettings.json
    wwwroot/
      index.html            the web client
  ClientWsTax/              its console client (version 9)
    ClientWsTax.csproj
    TaxBusinessHttp.cs
    Program.cs
  ClientNode/               a JavaScript client
    client-tax.mjs

13.2.1. O lado do servidor

Image

O arquivo de projeto [WsHello.csproj] gerado por [dotnet new web] é o seguinte:

1
2
3
4
5
6
7
8
9
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

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:

1
2
3
4
5
6
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();
  • 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]:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Urls": "http://localhost:5100"
}
  • 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:

// o serviço web WsHello
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// a raiz do site: um texto de boas-vindas
app.MapGet("/", () => "WsHello web service: try /hello/{name} or /greeting/{name}");

// o método web de 2008 "SayHelloToTheLady", que virou uma URL
// o parâmetro {name} da rota é passado ao parâmetro [name] da lambda
// uma string é retornada como está (text/plain)
app.MapGet("/hello/{name}", (string name) => $"Hello Mrs {name}");

// a mesma coisa com uma resposta JSON: um objeto é serializado em JSON (application/json)
app.MapGet("/greeting/{name}", (string name) => new Greeting(name, $"Hello Mrs {name}"));

// o servidor web Kestrel espera as requisições
app.Run();

// o resultado do método /greeting
record Greeting(string Name, string Message);

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:

> dotnet run
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5100
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: .../13-web-services/WsHello
info: Microsoft.Hosting.Lifetime[0]
      Application is shutting down...
  • 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:

1
2
3
4
5
6
7
8
> curl -s -i http://localhost:5100/hello/Carla%20Bruni
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Sat, 03 Oct 2026 10:07:58 GMT
Server: Kestrel
Transfer-Encoding: chunked

Hello Mrs Carla Bruni
  • 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:

1
2
3
4
5
6
7
8
> curl -s -i http://localhost:5100/greeting/Carla%20Bruni
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 03 Oct 2026 10:07:58 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"name":"Carla Bruni","message":"Hello Mrs Carla Bruni"}
  • 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:

1
2
3
4
5
> curl -s -i http://localhost:5100/hi
HTTP/1.1 404 Not Found
Content-Length: 0
Date: Sat, 03 Oct 2026 10:07:58 GMT
Server: Kestrel

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

Image

É 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:

using System.Net.Http.Json;

// cliente console do serviço web WsHello
// a URL do serviço pode ser passada como argumento
string serviceUrl = args.Length > 0 ? args[0] : "http://localhost:5100/";

// um único cliente HTTP durante toda a execução do programa
using var client = new HttpClient { BaseAddress = new Uri(serviceUrl) };

while (true)
{
    // o nome da senhora
    Console.Write("Name of the lady (nothing to stop): ");
    string name = Console.ReadLine()?.Trim() ?? "";
    if (name == "")
    {
        break;
    }
    try
    {
        // o nome é colocado no caminho da URL: deve ser codificado ali
        string encodedName = Uri.EscapeDataString(name);
        // 1 - resposta de texto
        string text = await client.GetStringAsync($"hello/{encodedName}");
        Console.WriteLine($"[text] {text}");
        // 2 - resposta JSON, desserializada em um objeto Greeting
        Greeting? greeting = await client.GetFromJsonAsync<Greeting>($"greeting/{encodedName}");
        Console.WriteLine($"[JSON] {greeting}");
    }
    catch (HttpRequestException e)
    {
        // o serviço está inacessível ou respondeu com um erro
        Console.WriteLine($"Error: {e.GetType().Name} : {e.Message}");
    }
}

// a resposta JSON do serviço: mesmos nomes de propriedades que no lado do servidor
record Greeting(string Name, string Message);

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:

1
2
3
4
5
6
7
8
> dotnet run
Name of the lady (nothing to stop): Carla Bruni
[text] Hello Mrs Carla Bruni
[JSON] Greeting { Name = Carla Bruni, Message = Hello Mrs Carla Bruni }
Name of the lady (nothing to stop): Marie Curie
[text] Hello Mrs Marie Curie
[JSON] Greeting { Name = Marie Curie, Message = Hello Mrs Marie Curie }
Name of the lady (nothing to stop): 

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:

1
2
3
4
> dotnet run -- http://localhost:5199/
Name of the lady (nothing to stop): Carla Bruni
Error: HttpRequestException : Connection refused (localhost:5199)
Name of the lady (nothing to stop): 

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]:

1
2
3
builder.Services.AddOpenApi();    // antes de builder.Build()
...
app.MapOpenApi();                 // depois de builder.Build(): publica /openapi/v1.json

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:

using System.Globalization;

// o serviço web WsOperations: as quatro operações aritméticas
var builder = WebApplication.CreateBuilder(args);
// as respostas de erro terão um corpo no formato "Problem Details" (RFC 9457)
builder.Services.AddProblemDetails();
var app = builder.Build();
// os erros produzidos sem corpo (404, 400...) recebem um corpo "Problem Details"
app.UseStatusCodePages();

// GET /add?a=1.5&b=2 (idem para subtract, multiply, divide)
// [operation] vem do caminho da URL, [a] e [b] de sua query string
app.MapGet("/{operation}", (string operation, string? a, string? b) =>
    Calculate(operation, ReadNumber(a), ReadNumber(b)));

// POST /calculation com um corpo JSON: {"operation":"add","a":1.5,"b":2}
// o corpo JSON é desserializado no parâmetro [request]
app.MapPost("/calculation", (CalculationRequest request) =>
    Calculate(request.Operation, request.A, request.B));

// o servidor espera as requisições
app.Run();

// um número escrito com ponto decimal (cultura invariante), null se estiver ausente ou incorreto
static double? ReadNumber(string? text) =>
    double.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out double number) ? number : null;

// o cálculo comum aos dois métodos HTTP
static IResult Calculate(string? operation, double? a, double? b)
{
    // a operação solicitada, null se for desconhecida
    operation = operation?.ToLowerInvariant() ?? "";
    Func<double, double, double>? calculation = operation switch
    {
        "add" => (x, y) => x + y,
        "subtract" => (x, y) => x - y,
        "multiply" => (x, y) => x * y,
        "divide" => (x, y) => x / y,
        _ => null
    };
    // verificação dos parâmetros: acumulamos os erros
    var errors = new Dictionary<string, string[]>();
    if (calculation is null)
    {
        errors["operation"] = [$"Unknown operation [{operation}]: use add, subtract, multiply or divide"];
    }
    if (a is null)
    {
        errors["a"] = ["The number a is missing or incorrect"];
    }
    if (b is null)
    {
        errors["b"] = ["The number b is missing or incorrect"];
    }
    if (calculation is null || a is not double x || b is not double y)
    {
        // resposta 400 com a lista de erros
        return Results.ValidationProblem(errors, title: "Incorrect parameters");
    }
    // aqui, x e y são os valores de a e b
    // a divisão por zero é recusada: resposta 400
    if (operation == "divide" && y == 0)
    {
        return Results.Problem(statusCode: StatusCodes.Status400BadRequest,
            title: "Division by zero", detail: "The number b must be non-zero for a division");
    }
    // resposta 200 com o resultado em JSON
    return Results.Ok(new CalculationResult(operation, x, y, calculation(x, y)));
}

// a requisição de cálculo (corpo da requisição POST)
record CalculationRequest(string? Operation, double? A, double? B);
// o resultado de um cálculo (corpo da resposta)
record CalculationResult(string Operation, double A, double B, double Result);

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:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5110/add?a=1.5&b=2"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 03 Oct 2026 10:08:11 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"operation":"add","a":1.5,"b":2,"result":3.5}

Divisão por zero:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5110/divide?a=1&b=0"
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Date: Sat, 03 Oct 2026 10:08:11 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"Division by zero","status":400,"detail":"The number b must be non-zero for a division","traceId":"00-a5fad2ff940e8c70b8eb006b81067973-b7e871865336d57a-00"}
  • 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:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5110/power?a=1,5"
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Date: Sat, 03 Oct 2026 10:08:11 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"Incorrect parameters","status":400,"errors":{"operation":["Unknown operation [power]: use add, subtract, multiply or divide"],"a":["The number a is missing or incorrect"],"b":["The number b is missing or incorrect"]},"traceId":"00-8b98d505b89c7e682140c8614d8ec9e8-7e7407597c932cf1-00"}

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:

1
2
3
4
5
6
7
8
> curl -s -i -H "Content-Type: application/json" -d '{"operation":"multiply","a":1.5,"b":-4}' http://localhost:5110/calculation
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 03 Oct 2026 10:08:11 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"operation":"multiply","a":1.5,"b":-4,"result":-6}

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:

1
2
3
4
5
6
7
8
> curl -s -i -H "Content-Type: application/json" -d '{"operation":"multiply","a":1.5,' http://localhost:5110/calculation
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Date: Sat, 03 Oct 2026 10:08:11 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"Bad Request","status":400,"traceId":"00-ab3bb8a90826764bea4d8ea6581f1951-afaa69657c3a8680-00"}

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

Image

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:

using System.Globalization;
using System.Net.Http.Json;

// cliente console do serviço web WsOperations
string serviceUrl = args.Length > 0 ? args[0] : "http://localhost:5110/";
using var client = new HttpClient { BaseAddress = new Uri(serviceUrl) };

while (true)
{
    // entrada da operação e dos dois números (números na cultura atual)
    Console.Write("Operation a b (e.g. add 1.5 2), nothing to stop: ");
    string[] fields = (Console.ReadLine() ?? "").Split(' ', StringSplitOptions.RemoveEmptyEntries);
    if (fields.Length == 0)
    {
        break;
    }
    if (fields.Length != 3)
    {
        Console.WriteLine("Three elements are needed: operation a b");
        continue;
    }
    // verificação local dos dois números, como no cliente gráfico de 2008
    string operation = fields[0];
    bool error = false;
    if (!double.TryParse(fields[1], out double a))
    {
        Console.WriteLine("Incorrect number a...");
        error = true;
    }
    if (!double.TryParse(fields[2], out double b))
    {
        Console.WriteLine("Incorrect number b...");
        error = true;
    }
    if (error)
    {
        continue;
    }
    // 1 - requisição GET: na URL, os números são escritos com ponto decimal
    string url = string.Create(CultureInfo.InvariantCulture,
        $"{Uri.EscapeDataString(operation)}?a={a}&b={b}");
    try
    {
        // GetFromJsonAsync lança uma exceção se o código de status não for 2xx
        CalculationResult? result = await client.GetFromJsonAsync<CalculationResult>(url);
        Console.WriteLine($"[GET {url}] {operation}({a} ; {b}) = {result?.Result}");
    }
    catch (HttpRequestException e)
    {
        // e.StatusCode: o código de status HTTP, null se o serviço não respondeu
        string code = e.StatusCode is null ? "" : $" {(int)e.StatusCode}";
        Console.WriteLine($"[GET {url}] error{code}: {e.Message}");
    }
    // 2 - requisição POST: a requisição é enviada em JSON no corpo da requisição
    try
    {
        using HttpResponseMessage response = await client.PostAsJsonAsync("calculation", new CalculationRequest(operation, a, b));
        if (response.IsSuccessStatusCode)
        {
            // sucesso: o corpo contém o resultado
            CalculationResult? result = await response.Content.ReadFromJsonAsync<CalculationResult>();
            Console.WriteLine($"[POST calculation] {operation}({a} ; {b}) = {result?.Result}");
        }
        else
        {
            // falha: o corpo contém a descrição do problema
            Problem? problem = await response.Content.ReadFromJsonAsync<Problem>();
            Console.WriteLine($"[POST calculation] error {(int)response.StatusCode}: {problem?.Title}");
            if (problem?.Detail is not null)
            {
                Console.WriteLine($"  {problem.Detail}");
            }
            foreach (var (parameter, messages) in problem?.Errors ?? [])
            {
                Console.WriteLine($"  {parameter} : {string.Join(" ; ", messages)}");
            }
        }
    }
    catch (HttpRequestException e)
    {
        // o serviço está inacessível
        Console.WriteLine($"[POST calculation] error: {e.Message}");
    }
}

// os objetos trocados com o serviço (os nomes das propriedades são os do JSON, exceto pela caixa)
record CalculationRequest(string Operation, double A, double B);
record CalculationResult(string Operation, double A, double B, double Result);
// uma resposta de erro no formato "Problem Details"
record Problem(string? Title, string? Detail, int? Status, Dictionary<string, string[]>? Errors);

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:

> dotnet run
Operation a b (e.g. add 1.5 2), nothing to stop: add 1.5 2
[GET add?a=1.5&b=2] add(1.5 ; 2) = 3.5
[POST calculation] add(1.5 ; 2) = 3.5
Operation a b (e.g. add 1.5 2), nothing to stop: divide 1 0
[GET divide?a=1&b=0] error 400: Response status code does not indicate success: 400 (Bad Request).
[POST calculation] error 400: Division by zero
  The number b must be non-zero for a division
Operation a b (e.g. add 1.5 2), nothing to stop: power 2 3
[GET power?a=2&b=3] error 400: Response status code does not indicate success: 400 (Bad Request).
[POST calculation] error 400: Incorrect parameters
  operation : Unknown operation [power]: use add, subtract, multiply or divide
Operation a b (e.g. add 1.5 2), nothing to stop: multiply 2.5 x
Incorrect number b...
Operation a b (e.g. add 1.5 2), nothing to stop: 
  • 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:

Image

  • 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:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <!-- as camadas [dao] e [business] da versão 5, reutilizadas como estão -->
    <ProjectReference Include="../../06-architectures/TaxV5/Tax.Dao/Tax.Dao.csproj" />
    <ProjectReference Include="../../06-architectures/TaxV5/Tax.Business/Tax.Business.csproj" />
  </ItemGroup>

</Project>
  • 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:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Urls": "http://localhost:5120",
  "Dao": {
    "Implementation": "JsonTax",
    "File": "TaxData.json"
  }
}
  • 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:

using Dao;
using Entities;
using Business;
using Microsoft.AspNetCore.Http.HttpResults;

// o serviço web de cálculo de imposto (versão 9)
var builder = WebApplication.CreateBuilder(args);

// a camada [dao]: sua implementação e seu arquivo vêm da configuração (appsettings.json)
string implementation = builder.Configuration["Dao:Implementation"] ?? "HardwiredTax";
string file = builder.Configuration["Dao:File"] ?? "";
builder.Services.AddSingleton<ITaxDao>(_ => implementation switch
{
    "HardwiredTax" => new HardwiredTax(),
    "FileTax" => new FileTax(file),
    "JsonTax" => new JsonTax(file),
    _ => throw new TaxException($"Unknown implementation [{implementation}] of the [dao] layer")
});
// a camada [business]: o contêiner lhe passará a camada [dao]
builder.Services.AddSingleton<ITaxBusiness, TaxBusiness>();
// as respostas de erro no formato "Problem Details"
builder.Services.AddProblemDetails();

var app = builder.Build();

// as camadas [business] e [dao] são construídas na inicialização:
// um erro de configuração ou de dados interrompe o serviço antes de qualquer requisição
try
{
    app.Services.GetRequiredService<ITaxBusiness>();
}
catch (TaxException e)
{
    app.Logger.LogCritical("The service cannot start: {Message} ({Cause})", e.Message, e.InnerException?.Message);
    return 1;
}

// uma exceção não tratada gera uma resposta 500 "Problem Details"
app.UseExceptionHandler();
// os erros sem corpo (404...) recebem um corpo "Problem Details"
app.UseStatusCodePages();
// o cliente web: a requisição / serve o arquivo estático wwwroot/index.html
app.UseDefaultFiles();
app.UseStaticFiles();

// GET /tax?married=y&children=2&salary=60000
app.MapGet("/tax", (string? married, string? children, string? salary, ITaxBusiness business) =>
    Calculate(
        married?.ToLowerInvariant() switch { "y" => true, "n" => false, _ => null },
        int.TryParse(children, out int c) ? c : null,
        int.TryParse(salary, out int s) ? s : null,
        business));

// POST /tax com o corpo JSON {"married":true,"children":2,"salary":60000}
app.MapPost("/tax", (TaxRequest request, ITaxBusiness business) =>
    Calculate(request.Married, request.Children, request.Salary, business));

app.Run();
return 0;

// o processamento comum aos dois métodos HTTP
// o tipo retornado lista as duas respostas possíveis: 200 com o imposto, ou 400 com os erros
Results<Ok<TaxResponse>, ValidationProblem> Calculate(bool? married, int? children, int? salary, ITaxBusiness business)
{
    // parâmetros corretos: pedimos o cálculo à camada [business]
    if (married is bool isMarried && children is int nbChildren and >= 0 && salary is int amount and >= 0)
    {
        int tax = business.CalculateTax(isMarried, nbChildren, amount);
        app.Logger.LogInformation("Tax(married={Married}, children={Children}, salary={Salary}) = {Tax}",
            isMarried, nbChildren, amount, tax);
        return TypedResults.Ok(new TaxResponse(tax));
    }
    // parâmetros incorretos: a lista de erros
    var errors = new Dictionary<string, string[]>();
    if (married is null)
    {
        errors["married"] = ["Indicate whether the taxpayer is married: y/n (GET) or true/false (POST)"];
    }
    if (children is not >= 0)
    {
        errors["children"] = ["The number of children must be a positive or zero integer"];
    }
    if (salary is not >= 0)
    {
        errors["salary"] = ["The salary must be a positive or zero integer"];
    }
    app.Logger.LogWarning("Incorrect request: {Errors}", string.Join(", ", errors.Keys));
    return TypedResults.ValidationProblem(errors, title: "Incorrect parameters");
}

// a requisição de cálculo (corpo da requisição POST): as propriedades ausentes do JSON são null
record TaxRequest(bool? Married, int? Children, int? Salary);
// a resposta: o valor do imposto
record TaxResponse(int Tax);

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:

1
2
3
> dotnet run --Dao:File=missing.json
crit: WsTax[0]
      The service cannot start: Error while reading the file missing.json (The file [missing.json] does not exist)

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]:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5120/tax?married=y&children=2&salary=60000"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 03 Oct 2026 10:08:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"tax":4282}

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:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5120/tax?married=x&children=-2"
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Date: Sat, 03 Oct 2026 10:08:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"Incorrect parameters","status":400,"errors":{"married":["Indicate whether the taxpayer is married: y/n (GET) or true/false (POST)"],"children":["The number of children must be a positive or zero integer"],"salary":["The salary must be a positive or zero integer"]},"traceId":"00-74c7d1d992e476f4e89c85212bd1fe26-0b6527fb5d58f6c5-00"}

Depois, com POST e um documento JSON:

1
2
3
4
5
6
7
8
> curl -s -i -H "Content-Type: application/json" -d '{"married":true,"children":2,"salary":60000}' http://localhost:5120/tax
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 03 Oct 2026 10:08:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

{"tax":4282}

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:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- a interface da camada [business] e a camada [ui] da versão 5 -->
    <ProjectReference Include="../../06-architectures/TaxV5/Tax.Business/Tax.Business.csproj" />
    <ProjectReference Include="../../06-architectures/TaxV5/Tax.Ui/Tax.Ui.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- a factory de clientes HTTP integrada ao contêiner de injeção de dependência -->
    <PackageReference Include="Microsoft.Extensions.Http" Version="10.0.12" />
  </ItemGroup>

</Project>
  • 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]:

using System.Net.Http.Json;
using System.Text.Json;
using Entities;
using Business;

namespace Client;

// a camada [business] do lado do cliente: um proxy do serviço web de cálculo de imposto
// ela implementa a mesma interface que a camada [business] local da versão 5
public class TaxBusinessHttp(HttpClient client) : ITaxBusiness
{
    public int CalculateTax(bool married, int nbChildren, int salary)
    {
        // a requisição POST /tax, com a requisição em JSON em seu corpo
        using var request = new HttpRequestMessage(HttpMethod.Post, "tax")
        {
            Content = JsonContent.Create(new TaxRequest(married, nbChildren, salary))
        };
        // envio síncrono: o método da interface ITaxBusiness é síncrono
        using HttpResponseMessage response = client.Send(request);
        // o serviço aceitou a requisição?
        if (!response.IsSuccessStatusCode)
        {
            throw new TaxException($"The web service answered {(int)response.StatusCode} ({response.ReasonPhrase})")
            {
                Code = (int)response.StatusCode
            };
        }
        // leitura síncrona da resposta JSON {"tax":4282}
        using Stream stream = response.Content.ReadAsStream();
        TaxResponse? result = JsonSerializer.Deserialize<TaxResponse>(stream, JsonSerializerOptions.Web);
        return result?.Tax ?? throw new TaxException("The web service sent an empty response");
    }

    // os objetos trocados com o serviço web
    private record TaxRequest(bool Married, int Children, int Salary);
    private record TaxResponse(int Tax);
}

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:

using Client;
using Business;
using Microsoft.Extensions.DependencyInjection;
using Ui;

// a URL do serviço web: a passada como argumento ou a padrão
string serviceUrl = args.Length > 0 ? args[0] : "http://localhost:5120/";

// integração das camadas: a camada [business] agora é um cliente do serviço web
var services = new ServiceCollection();
// registra TaxBusinessHttp como implementação de ITaxBusiness,
// com um HttpClient configurado para a URL do serviço
services.AddHttpClient<ITaxBusiness, TaxBusinessHttp>(client => client.BaseAddress = new Uri(serviceUrl));
using ServiceProvider provider = services.BuildServiceProvider();
ITaxBusiness business = provider.GetRequiredService<ITaxBusiness>();

// o diálogo da versão 5, sem nenhuma modificação
try
{
    Dialog.Run(business);
}
catch (Exception e)
{
    // o serviço está inacessível ou recusou a requisição
    Dialog.DisplayError(e);
    return 1;
}
return 0;

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:

> dotnet run
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y -2 60000
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect NbChildren argument: type a positive or zero integer
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

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:

1
2
3
4
5
6
7
8
> dotnet run
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Exception chain:
----------------------------------------
System.Net.Http.HttpRequestException: Connection refused (localhost:5120)
----------------------------------------
System.Net.Sockets.SocketException: Connection refused
----------------------------------------

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:

Image

  • 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:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Calculate your tax</title>
  <style>
    body { font-family: sans-serif; background: #ffffe0; margin: 2em; }
    td { padding: 4px 8px; white-space: nowrap; }
    .error { color: #cc2200; }
    #tax:not(:empty) { background: #99ccff; padding: 2px 8px; font-weight: bold; }
  </style>
</head>
<body>
  <h2>Calculate your tax</h2>
  <form id="form">
    <table>
      <tr>
        <td>Are you married</td>
        <td>
          <label><input type="radio" name="married" value="yes"> Yes</label>
          <label><input type="radio" name="married" value="no" checked> No</label>
        </td>
      </tr>
      <tr>
        <td>Number of children</td>
        <td><input type="text" id="children" size="3"></td>
        <td class="error" id="childrenError"></td>
      </tr>
      <tr>
        <td>Annual salary</td>
        <td><input type="text" id="salary" size="8"></td>
        <td class="error" id="salaryError"></td>
      </tr>
      <tr>
        <td>Tax to pay</td>
        <td><span id="tax"></span></td>
      </tr>
    </table>
    <p class="error" id="message"></p>
    <p>
      <button type="submit">Calculate</button>
      <button type="button" id="clear">Clear</button>
    </p>
  </form>

  <script>
    // os elementos da página
    const form = document.getElementById("form");
    const children = document.getElementById("children");
    const salary = document.getElementById("salary");
    const tax = document.getElementById("tax");
    const childrenError = document.getElementById("childrenError");
    const salaryError = document.getElementById("salaryError");
    const message = document.getElementById("message");

    // um inteiro digitado, ou null se a entrada não for um inteiro
    function readInteger(text) {
      return /^\s*-?\d+\s*$/.test(text) ? parseInt(text, 10) : null;
    }

    // limpa o resultado e as mensagens de erro
    function clearMessages() {
      tax.textContent = "";
      childrenError.textContent = "";
      salaryError.textContent = "";
      message.textContent = "";
    }

    // botão [Calculate]: consultamos o serviço web, sem recarregar a página
    form.addEventListener("submit", async (event) => {
      event.preventDefault();
      clearMessages();
      // a requisição, no formato esperado por POST /tax
      const request = {
        married: form.married.value === "yes",
        children: readInteger(children.value),
        salary: readInteger(salary.value)
      };
      try {
        const response = await fetch("tax", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(request)
        });
        const body = await response.json();
        if (response.ok) {
          // 200: {"tax": 4282}
          tax.textContent = `${body.tax} euros`;
        } else {
          // 400: um documento "Problem Details" com os erros por parâmetro
          const errors = body.errors ?? {};
          childrenError.textContent = errors.children?.join(" ") ?? "";
          salaryError.textContent = errors.salary?.join(" ") ?? "";
          message.textContent = body.title;
        }
      } catch (e) {
        // o serviço está inacessível
        message.textContent = `Error communicating with the service: ${e.message}`;
      }
    });

    // botão [Clear]: reinicialização do formulário
    document.getElementById("clear").addEventListener("click", () => {
      children.value = "";
      salary.value = "";
      clearMessages();
    });
  </script>
</body>
</html>

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:

Image

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

Image

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

Image

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:

// um cliente JavaScript (Node.js) do serviço web de cálculo de imposto
// chamada: node client-tax.mjs [service url]
const serviceUrl = process.argv[2] ?? "http://localhost:5120/";

// as requisições a enviar: a última é incorreta
const requests = [
  { married: true, children: 2, salary: 60000 },
  { married: false, children: 0, salary: 60000 },
  { married: true, children: -1, salary: 60000 },
];

for (const request of requests) {
  // POST /tax com a requisição em JSON
  const response = await fetch(new URL("tax", serviceUrl), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
  });
  const body = await response.json();
  if (response.ok) {
    console.log(`${JSON.stringify(request)} -> tax = ${body.tax} euros`);
  } else {
    console.log(`${JSON.stringify(request)} -> error ${response.status}: ${JSON.stringify(body.errors)}`);
  }
}
  • 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:

1
2
3
4
> node client-tax.mjs
{"married":true,"children":2,"salary":60000} -> tax = 4282 euros
{"married":false,"children":0,"salary":60000} -> tax = 11519 euros
{"married":true,"children":-1,"salary":60000} -> error 400: {"children":["The number of children must be a positive or zero integer"]}

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:

> dotnet run
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5120
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: .../13-web-services/WsTax
info: WsTax[0]
      Tax(married=True, children=2, salary=60000) = 4282
warn: WsTax[0]
      Incorrect request: married, children, salary
info: WsTax[0]
      Tax(married=True, children=2, salary=60000) = 4282
info: WsTax[0]
      Tax(married=True, children=2, salary=60000) = 4282
info: WsTax[0]
      Tax(married=True, children=3, salary=60000) = 2959
info: WsTax[0]
      Tax(married=False, children=0, salary=60000) = 11519
info: WsTax[0]
      Tax(married=True, children=2, salary=60000) = 4282
warn: WsTax[0]
      Incorrect request: children, salary
info: WsTax[0]
      Tax(married=True, children=2, salary=60000) = 4282
info: WsTax[0]
      Tax(married=False, children=0, salary=60000) = 11519
warn: WsTax[0]
      Incorrect request: children
info: Microsoft.Hosting.Lifetime[0]
      Application is shutting down...
  • 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]:

1
2
3
var operations = app.MapGroup("/api/operations");
operations.MapGet("/{operation}", (string operation, string? a, string? b) => ...);  // GET /api/operations/add?a=1&b=2
operations.MapPost("/", (CalculationRequest request) => ...);                        // POST /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).