Skip to content

12. Programação web

12.1. Visão geral

12.1.1. Protocolos da Internet

Apresentamos aqui uma introdução aos protocolos de comunicação da Internet, também conhecidos como pilha de protocolos TCP/IP (Transmission Control Protocol / Internet Protocol), nome derivado dos dois principais protocolos. É útil que o leitor tenha uma compreensão geral de como as redes funcionam — em particular dos protocolos TCP/IP — antes de abordar o desenvolvimento de aplicações distribuídas. O curso de 2008 incluía um trecho traduzido do guia de administração “Lan Workplace for DOS”, da Novell (início dos anos 1990). Mantivemos sua estrutura e seu espírito, mas o atualizamos: a Internet de 2026 já não é exatamente a de 1990.

O conceito geral de criar uma rede de computadores heterogêneos nasceu de pesquisas conduzidas pela DARPA (Defense Advanced Research Projects Agency) nos Estados Unidos. A DARPA desenvolveu a suíte de protocolos conhecida como TCP/IP, que permite que máquinas heterogêneas se comuniquem entre si. Esses protocolos foram testados em uma rede chamada ARPAnet, que mais tarde se tornou a Internet (a ARPAnet adotou o TCP/IP em 1º de janeiro de 1983). Os protocolos TCP/IP definem formatos e regras de transmissão e recepção que são independentes da arquitetura de rede e do hardware utilizado.

A rede projetada pela DARPA e gerenciada pelos protocolos TCP/IP é uma rede de comutação de pacotes. Uma rede desse tipo transmite informações em pequenos fragmentos chamados pacotes. Assim, se um computador transmite um arquivo grande, ele será dividido em pequenos pedaços enviados pela rede para serem remontados no destino. O TCP/IP define o formato desses pacotes, incluindo, em particular:

  • a origem do pacote;
  • seu destino;
  • seu comprimento;
  • seu tipo.

Os protocolos da Internet são descritos em documentos públicos chamados RFC (Request for Comments), publicados pela IETF (Internet Engineering Task Force) e disponíveis em www.rfc-editor.org. Citaremos alguns desses documentos ao longo deste capítulo.

12.1.2. O modelo OSI

Os protocolos TCP/IP seguem, em geral, o modelo aberto de rede conhecido como OSI (Open Systems Interconnection Reference Model), definido pela ISO (International Organization for Standardization). Esse modelo descreve uma rede ideal na qual a comunicação entre máquinas pode ser representada por um modelo de sete camadas:

Image

Cada camada recebe serviços da camada inferior e fornece seus próprios serviços à camada superior. Suponha que duas aplicações situadas em máquinas diferentes, A e B, queiram se comunicar: elas o fazem na camada de Aplicação. Elas não precisam conhecer todos os detalhes do funcionamento da rede: cada aplicação passa a informação que deseja transmitir à camada imediatamente inferior, a camada de Apresentação. A aplicação só precisa, portanto, conhecer as regras de interface com a camada de Apresentação. Quando a informação está na camada de Apresentação, ela é repassada, segundo outras regras, à camada de Sessão, e assim por diante, até que a informação alcance o meio físico e seja fisicamente transmitida à máquina de destino. Ali, ela sofrerá o processo inverso ao que sofreu na máquina de origem.

Em cada camada, o processo emissor responsável por enviar a informação a envia a um processo receptor da outra máquina que pertence à mesma camada. Ele o faz segundo certas regras conhecidas como protocolo da camada. A comunicação real desce pelas camadas da Máquina A, atravessa a rede física e depois sobe pelas camadas da Máquina B; no entanto, cada camada percebe que está se comunicando diretamente com a camada correspondente da outra máquina.

Os papéis das diferentes camadas são os seguintes:

Camada
Papel
Física
Garante a transmissão de bits por um meio físico (cabo de cobre, cabo de fibra óptica, ondas de rádio). Os pontos importantes nesse nível incluem a codificação da informação em sinais e o método de transmissão.
Enlace de dados
Abstrai as características físicas da camada Física. Divide a informação em quadros, detecta (e às vezes corrige) erros de transmissão e gerencia o acesso ao meio compartilhado.
Rede
Gerencia o caminho que a informação enviada pela rede deve seguir. Isso se chama roteamento: determinar a rota que a informação deve percorrer para chegar ao destino.
Transporte
Permite a comunicação entre duas aplicações, enquanto as camadas anteriores só permitiam a comunicação entre máquinas. Um serviço prestado por essa camada é a multiplexação: a camada de transporte usa um único enlace de rede (de máquina a máquina) para transmitir dados pertencentes a várias aplicações.
Sessão
Fornece serviços que permitem a uma aplicação abrir e manter uma sessão de trabalho em uma máquina remota.
Apresentação
Padroniza a representação dos dados entre máquinas diferentes. Os dados da máquina A são “formatados” pela camada de Apresentação da máquina A segundo um formato padrão antes de serem enviados pela rede. Ao chegar à camada de Apresentação da máquina de destino B — que os reconhece com base em seu formato padrão —, os dados são reformatados para que a aplicação da máquina B possa reconhecê-los.
Aplicação
Nesse nível estão as aplicações geralmente mais próximas do usuário, como o e-mail, a Web ou a transferência de arquivos.

12.1.3. O modelo TCP/IP

O modelo OSI é um modelo de referência que nunca foi implementado como tal. A suíte de protocolos TCP/IP, que se tornou o padrão, organiza-se em apenas quatro camadas:

Image

As camadas de Sessão e de Apresentação não existem como tal no TCP/IP: suas funções, quando necessárias, são tratadas pelas próprias aplicações ou por protocolos intermediários como o TLS (criptografia das trocas de dados), que se insere entre o TCP e a aplicação.

A camada de acesso à rede

Nas redes locais, a tecnologia dominante hoje é o Ethernet para conexões com fio e o Wi-Fi (padrões IEEE 802.11) para conexões sem fio. O curso de 2008 também tratava do Token Ring, uma tecnologia que não é mais usada hoje.

Ethernet é o nome dado a uma tecnologia de rede local de comutação de pacotes inventada na Xerox no início dos anos 1970 e padronizada pela Xerox, pela Intel e pela Digital Equipment em 1980, e depois pelo IEEE (padrão 802.3). O Ethernet original consistia em um cabo coaxial ao qual todas as máquinas eram conectadas (topologia em barramento), com uma taxa de transferência de 10 megabits por segundo:

Image

Era uma rede de difusão (broadcast): uma máquina transmissora enviava pelo cabo uma informação que incluía o endereço da máquina de destino; todas as máquinas conectadas a recebiam, e apenas o destinatário a retinha. Como várias máquinas podiam decidir transmitir ao mesmo tempo, era preciso detectar colisões: era o método Carrier Sense Multiple Access/Collision Detect (CSMA/CD). Cada transmissor escutava o cabo antes de transmitir (CSMA) e, durante a transmissão, verificava se o que passava pelo cabo era de fato o que havia transmitido; se não fosse, ocorria uma colisão (CD): cada um interrompia a transmissão e tentava novamente após um atraso aleatório.

O Ethernet moderno evoluiu bastante: os dispositivos são conectados por cabos de par trançado ou de fibra óptica a um switch, que encaminha cada quadro à porta específica do destinatário. As conexões são full-duplex (transmissão e recepção simultâneas): não há mais colisões, e o CSMA/CD tornou-se obsoleto. As taxas de transferência típicas variam de 1 a 10 gigabits por segundo, e são muito maiores em data centers.

O que não mudou é o endereçamento de 48 bits: cada placa de rede tem um endereço, chamado endereço físico ou endereço MAC (Media Access Control), geralmente escrito como seis bytes hexadecimais (por exemplo, [00:1A:2B:3C:4D:5E]). Ele é gravado na placa pelo fabricante, mas — ao contrário do que afirmava o curso de 2008 — pode ser modificado por software: os sistemas operacionais atuais chegam a usar endereços MAC aleatórios em redes Wi-Fi para impedir que um dispositivo seja rastreado de rede em rede.

A camada de Internet (camada de rede)

Os protocolos a seguir são encontrados nessa camada:

Protocolo
Papel
IP (Internet Protocol)
entrega pacotes entre dois nós da rede, na versão 4 (IPv4) ou 6 (IPv6)
ICMP (Internet Control Message Protocol)
facilita a comunicação entre o programa do protocolo IP de uma máquina e o de outra máquina. É, portanto, um protocolo de troca de mensagens de controle dentro do próprio protocolo IP
ARP (Address Resolution Protocol)
associa o endereço IP de uma máquina ao endereço físico da máquina (no IPv6, esse papel é desempenhado pelo protocolo NDP, o Neighbor Discovery Protocol)

O curso de 2008 também mencionava o RARP (Reverse Address Resolution Protocol), que realizava o mapeamento inverso. Ele foi abandonado há muito tempo em favor do DHCP, do qual falaremos mais adiante.

A camada de transporte

Essa camada inclui os seguintes protocolos:

Protocolo
Papel
TCP (Transmission Control Protocol)
garante a entrega confiável e ordenada de informações entre duas aplicações
UDP (User Datagram Protocol)
realiza a entrega não confiável de informações entre duas aplicações

O protocolo QUIC (2021), no qual o HTTP/3 se baseia, é um protocolo de transporte confiável e criptografado construído sobre o UDP.

A camada de aplicação

Aqui encontramos diversos protocolos, que detalharemos um pouco mais adiante:

Protocolo
Papel
HTTP, HTTPS (HyperText Transfer Protocol)
O protocolo da Web: um cliente (navegador, aplicação) solicita recursos a um servidor web. O HTTPS é o HTTP criptografado com TLS
DNS (Domain Name System)
converte o nome de uma máquina em um endereço IP
SMTP (Simple Mail Transfer Protocol)
permite o envio de e-mails
POP3, IMAP
permitem ler os e-mails armazenados em um servidor
SSH (Secure Shell)
permite conectar-se a uma máquina remota e executar comandos nela, usando criptografia. Substituiu o TELNET, que desempenhava a mesma função sem criptografia
FTP (File Transfer Protocol), SFTP
permitem a transferência de arquivos
DHCP (Dynamic Host Configuration Protocol)
permite que uma máquina obtenha automaticamente seu endereço IP e sua configuração de rede

12.1.4. Como funcionam os protocolos da Internet

As aplicações desenvolvidas no ambiente TCP/IP geralmente usam vários dos protocolos desse ambiente. Um programa de aplicação se comunica com a camada mais alta dos protocolos. Essa camada repassa a informação à camada inferior, e assim por diante, até chegar ao meio físico. Ali, a informação é transferida fisicamente para a máquina receptora, onde passará novamente pelas mesmas camadas — dessa vez em ordem inversa — até chegar à aplicação que é a destinatária da informação enviada. O diagrama a seguir mostra o caminho da informação:

Image

Vejamos um exemplo: uma aplicação que envia um arquivo a outra máquina usando TCP.

  • A aplicação entrega à camada de transporte uma sequência de bytes a transmitir;
  • a camada de transporte divide essa sequência de bytes em segmentos TCP e adiciona ao início de cada segmento um cabeçalho contendo, entre outras coisas, os números das portas de origem e de destino, além de um número de sequência. Os segmentos são repassados à camada de rede, regida pelo protocolo IP;
  • a camada IP cria um pacote encapsulando o segmento TCP recebido. No cabeçalho desse pacote, ela coloca os endereços IP das máquinas de origem e de destino. Ela também determina o endereço físico da máquina à qual o pacote deve ser entregue (a própria máquina de destino ou um roteador). O pacote inteiro é repassado à camada de acesso à rede, isto é, à placa de rede que conecta a máquina à rede física;
  • ali, o pacote IP é, por sua vez, encapsulado em um quadro físico e enviado ao destinatário pelo meio;
  • na máquina de destino, a camada de acesso à rede realiza o processo inverso: desencapsula o pacote IP do quadro físico e o repassa à camada IP;
  • a camada IP verifica se o pacote é válido: calcula uma soma de verificação (checksum) de seu cabeçalho, que deve coincidir com a que consta no cabeçalho do pacote. Se não for o caso, o pacote é descartado;
  • se o pacote é considerado válido, a camada IP desencapsula o segmento TCP nele contido e o repassa para cima, à camada de transporte;
  • a camada TCP também verifica uma soma de verificação do segmento. Se ela estiver correta, envia uma confirmação (acknowledgment) à máquina de origem; caso contrário, o segmento é ignorado (e será reenviado pela origem);
  • usando os números de sequência, a camada TCP reorganiza os segmentos na ordem correta;
  • resta à camada TCP apenas transmitir a parte de dados dos segmentos à aplicação de destino, identificada pelo número da porta de destino.

12.1.5. Problemas de endereçamento na Internet

Um nó de rede pode ser um computador, uma impressora, um telefone, um dispositivo conectado — qualquer coisa, na verdade, que consiga se comunicar usando os protocolos TCP/IP. Cada nó tem um endereço físico cujo formato depende do tipo de rede. Em uma rede Ethernet ou Wi-Fi, o endereço físico é codificado com 6 bytes.

O endereço de Internet (IP) de um nó é um endereço lógico: é independente do hardware e da rede utilizados. No IPv4, é um endereço de 4 bytes que identifica ao mesmo tempo uma rede e um nó dessa rede. Costuma ser representado como quatro números — os valores dos quatro bytes — separados por ponto. Por exemplo, em 2008, o endereço da máquina chamada “Lagaffe”, na Faculdade de Ciências de Angers, era 193.49.144.1, e o da máquina chamada “Liny” era 193.49.144.9. Disso se podia deduzir que o endereço da rede local era 193.49.144.0 e que podia haver até 254 nós nessa rede.

Como os endereços IP são independentes da rede física, um computador da rede A pode se comunicar com um computador da rede B sem se preocupar com o tipo de rede em que este se encontra: basta conhecer o seu endereço IP. O protocolo IP de cada rede cuida da conversão entre endereços IP e endereços físicos, nos dois sentidos.

Todos os endereços IP públicos devem ser únicos. Sua alocação segue uma estrutura hierárquica: a IANA (Internet Assigned Numbers Authority) distribui blocos de endereços a cinco registros regionais, entre os quais o RIPE NCC para a Europa, que os redistribuem a operadoras e grandes organizações. Essas entidades os atribuem então a seus clientes. O administrador de uma rede que recebeu o bloco de 193.49.144.0 a 193.49.144.255 pode atribuir os endereços de 193.49.144.1 a 193.49.144.254 como achar conveniente. O curso de 2008 indicava que, na França, o INRIA era responsável pela atribuição de endereços; isso não é mais verdade há muito tempo.

12.1.5.1. Classes de endereços IP e notação CIDR

Um endereço IPv4 é uma sequência de 4 bytes escrita como I1.I2.I3.I4, que na verdade contém duas informações:

  • o endereço da rede (os bits mais significativos);
  • o endereço de um nó dentro dessa rede (os bits menos significativos).

Originalmente, o tamanho desses dois campos era determinado pelo valor do primeiro byte. Os endereços IP eram divididos em três classes principais:

Classe
Primeiro byte
Rede / Nó
Número de redes e de nós
A
1 a 126 (bit mais significativo 0)
R1.N1.N2.N3: rede de 1 byte (7 bits significativos), nó de 3 bytes
126 redes de 2²⁴ - 2 nós (cerca de 16 milhões)
B
128 a 191 (bits mais significativos 10)
R1.R2.N1.N2: rede de 2 bytes (14 bits significativos), nó de 2 bytes
2¹⁴ = 16.384 redes de 2¹⁶ - 2 = 65.534 nós
C
192 a 223 (bits mais significativos 110)
R1.R2.R3.N1: rede de 3 bytes (21 bits significativos), nó de 1 byte
2²¹ redes (cerca de 2 milhões) com 254 nós

Como o endereço da máquina Lagaffe é 193.49.144.1, o byte mais significativo é 193, que em binário é 11000001: a rede era uma rede de Classe C.

Essa classificação se revelou rígida demais: uma organização com 300 máquinas era obrigada a usar uma rede de Classe B, desperdiçando mais de 65.000 endereços. Desde 1993 (RFC 1518 e 1519), as classes foram abandonadas em favor do roteamento sem classes (CIDR, Classless Inter-Domain Routing). A fronteira entre a parte de rede e a parte de host pode ser definida em qualquer bit; ela é indicada pelo comprimento do prefixo de rede, após uma barra:

  • 193.49.144.0/24: os primeiros 24 bits designam a rede, e os últimos 8 bits designam o nó. Essa rede contém os endereços de 193.49.144.0 a 193.49.144.255;
  • 10.0.0.0/8: uma rede com 2²⁴ endereços;
  • 192.168.1.0/26: uma rede de 2⁶ = 64 endereços, de 192.168.1.0 a 192.168.1.63.

A antiga notação da máscara de sub-rede ainda é usada e expressa a mesma coisa: o prefixo /24 corresponde à máscara 255.255.255.0. Os termos “Classe A, B, C” continuam de uso corrente, mas já não correspondem a nenhum mecanismo real.

12.1.5.2. Endereços reservados, endereços privados e NAT

Certos endereços têm uma finalidade específica:

  • um endereço cuja parte de host é composta inteiramente de 0s refere-se à própria rede: 193.49.144.0 é o endereço da rede 193.49.144.0/24;
  • um endereço cuja parte de host é composta inteiramente de 1s é um endereço de broadcast: 193.49.144.255 refere-se a todos os hosts da rede 193.49.144.0/24. Esses dois endereços, portanto, não podem ser atribuídos a um nó: uma rede /24 com 256 endereços oferece apenas 254 endereços utilizáveis;
  • os endereços 127.0.0.0/8 e, na prática, 127.0.0.1, são endereços de loopback: uma máquina os usa para se referir a si mesma sem passar pela rede. O nome [localhost] está associado a eles;
  • os blocos 10.0.0.0/8, 172.16.0.0/12 e 192.168.0.0/16 (RFC 1918) são reservados para redes privadas: podem ser usados livremente dentro de uma empresa ou de uma residência, mas não são roteados na Internet;
  • os blocos 192.0.2.0/24, 198.51.100.0/24 e 203.0.113.0/24 (RFC 5737) são reservados para documentação e exemplos.

O número de endereços IPv4 (2³², ou pouco mais de 4 bilhões) é insuficiente para todas as máquinas conectadas. O estoque central de endereços da IANA se esgotou em 2011, e o do RIPE NCC em 2019. A escassez foi contornada pela tradução de endereços de rede (NAT, Network Address Translation): os dispositivos de uma residência têm endereços privados (como 192.168.1.x), e o roteador que os conecta à Internet os “traduz” para o seu próprio endereço público único. A solução de longo prazo é o IPv6.

12.1.5.3. Endereços IPv6

O IPv6 (RFC 2460 em 1998, hoje RFC 8200) codifica os endereços com 128 bits, o que dá 2¹²⁸ endereços possíveis — aproximadamente 3,4 × 10³⁸ —, de modo que não há mais motivo para se preocupar com escassez. Um endereço IPv6 é escrito como oito grupos de quatro dígitos hexadecimais separados por dois-pontos:

2001:0db8:0000:0000:8a2e:0000:0370:7334

Os zeros à esquerda de cada grupo podem ser omitidos, e uma única sequência de grupos de zeros pode ser substituída por [::]. O endereço anterior, portanto, é escrito como [2001:db8::8a2e:0:370:7334]. O endereço de loopback, equivalente a 127.0.0.1, é [::1]. Em uma URL, um endereço IPv6 é colocado entre colchetes para evitar confundir seus dois-pontos com o que precede a porta: [http://[::1]:8080/].

O IPv6 introduz outras simplificações: o cabeçalho do pacote tem comprimento fixo, a configuração automática de endereços é nativa e a tradução de endereços NAT deixa de ser necessária. Sua adoção foi lenta, mas uma parcela significativa e crescente do tráfego da Internet já passa pelo IPv6 (o Google, por exemplo, publica a proporção de seus usuários que o acessam via IPv6), e os principais provedores de acesso franceses o oferecem a seus assinantes. As duas versões coexistem: a maioria das máquinas tem endereços IPv4 e IPv6 (fala-se em “dual stack”), e os programas precisam ser capazes de lidar com ambos.

12.1.5.4. Protocolos de conversão entre endereços IP e endereços físicos

Vimos que, quando dados são transmitidos de uma máquina a outra, ao passar pela camada IP eles são encapsulados em pacotes. Esses pacotes têm a seguinte forma:

Image

O pacote IP contém, portanto, os endereços IP das máquinas de origem e de destino. Quando esse pacote é transmitido à camada responsável por enviá-lo pela rede física, informações adicionais são acrescentadas para formar o quadro físico que será finalmente enviado pela rede. Por exemplo, o formato de um quadro em uma rede Ethernet é o seguinte:

Image

Os primeiros 8 bytes (preâmbulo) servem para sincronização; o campo de 2 bytes que precede os dados indica, na forma mais comum do quadro Ethernet, o tipo de protocolo transportado (IPv4, IPv6, ARP…) em vez do comprimento do pacote. No quadro final, estão os endereços físicos das máquinas de origem e de destino (no quadro real, o endereço de destino precede o de origem, ao contrário da ordem mostrada no diagrama). Como eles são obtidos?

A máquina emissora, conhecendo o endereço IP da máquina com a qual deseja se comunicar, obtém o endereço físico dessa máquina usando o protocolo ARP (Address Resolution Protocol):

  • ela envia um tipo especial de pacote, chamado pacote ARP, contendo o endereço IP da máquina cujo endereço físico está sendo procurado. O pacote inclui também o seu próprio endereço IP, bem como o seu endereço físico;
  • esse pacote é enviado a todos os nós da rede local (broadcast);
  • esses nós reconhecem a natureza especial do pacote. O nó que reconhece seu endereço IP no pacote responde enviando seu endereço físico ao remetente. Ele pode fazer isso porque encontrou no pacote o endereço IP e o endereço físico do remetente;
  • o remetente recebe, portanto, o endereço físico que procurava. Ele o armazena em um cache para poder usá-lo mais tarde, caso outros pacotes precisem ser enviados ao mesmo destinatário.

No IPv6, o mesmo serviço é prestado pelo protocolo NDP (Neighbor Discovery Protocol), que se baseia em mensagens ICMPv6.

Resta a pergunta: como uma máquina conhece seu próprio endereço IP? Ele pode ser especificado em um arquivo de configuração da máquina — essa ainda é a prática habitual para servidores. No entanto, quando um administrador precisa reorganizar a rede, modificar um a um os arquivos de configuração de todas as máquinas é trabalhoso e sujeito a erros. O curso de 2008 apresentava o protocolo RARP, por meio do qual uma máquina solicitava seu endereço IP a um servidor com base em seu endereço físico. Ele foi substituído pelo DHCP (Dynamic Host Configuration Protocol, RFC 2131): ao iniciar, a máquina transmite uma solicitação por broadcast na rede; um servidor (como um roteador doméstico ou um servidor dedicado em uma empresa) atribui a ela um endereço por tempo limitado (uma concessão, ou lease), junto com o restante de sua configuração: prefixo de rede, endereço do roteador e endereços dos servidores DNS. O administrador só precisa, então, configurar o servidor DHCP. No IPv6, um dispositivo também pode construir seu próprio endereço a partir do prefixo anunciado pelo roteador (autoconfiguração SLAAC).

12.1.6. A camada de rede, ou camada IP, da Internet

O protocolo IP define o formato que os pacotes devem ter e como devem ser tratados ao serem enviados ou recebidos. Esse tipo particular de pacote é chamado de datagrama IP. Já falamos dele:

Image

O ponto importante é que, além dos dados a transmitir, o datagrama IP contém os endereços IP das máquinas de origem e de destino. Assim, a máquina de destino sabe quem lhe envia uma mensagem.

Ao contrário de um quadro de rede, cujo comprimento é determinado pelas características físicas da rede por onde ele trafega, o comprimento do datagrama IP é definido pelo software e será, portanto, o mesmo em diferentes redes físicas. Vimos que, ao descer da camada de rede para a camada física, o datagrama IP é encapsulado em um quadro físico.

Os quadros físicos trafegam de nó em nó em direção ao destino, que pode não estar na mesma rede física que a máquina emissora. O pacote IP pode, portanto, ser encapsulado sucessivamente em diferentes quadros físicos nos nós que conectam duas redes de tipos diferentes. Também é possível que o pacote IP seja grande demais para ser encapsulado em um quadro físico (a carga útil de um quadro Ethernet é limitada a 1.500 bytes). No IPv4, o nó em que esse problema ocorre divide então o pacote IP em fragmentos, que só serão remontados em seu destino final. No IPv6, os roteadores não fragmentam mais os pacotes: cabe ao remetente determinar o tamanho máximo aceito ao longo do caminho e ajustar o tamanho de seus pacotes de acordo.

12.1.6.1. Roteamento

Roteamento é o método de direcionar os pacotes IP até o destino. Há dois métodos: roteamento direto e roteamento indireto.

Roteamento direto

O roteamento direto designa a transmissão de um pacote IP diretamente do remetente ao destinatário dentro de uma mesma rede:

  • a máquina que envia um datagrama IP possui o endereço IP do destinatário;
  • ela obtém o endereço físico do destinatário por meio do protocolo ARP, ou de seu cache, se esse endereço já tiver sido obtido;
  • ela envia o pacote pela rede a esse endereço físico.

Roteamento indireto

O roteamento indireto designa a transmissão de um pacote IP a um destino situado em uma rede diferente daquela à qual o remetente pertence. Nesse caso, as partes de “rede” dos endereços IP das máquinas de origem e de destino são diferentes; a máquina de origem detecta isso comparando o endereço de destino com o seu próprio prefixo de rede. Ela envia então o pacote a um nó especial chamado roteador, que conecta a rede local a outras redes e cujo endereço IP é conhecido da máquina de origem (é o chamado gateway padrão, geralmente fornecido pelo DHCP). Um roteador está conectado a pelo menos duas redes e tem um endereço IP em cada uma delas:

Image

No nosso exemplo acima:

  • a rede nº 1 tem o endereço 193.49.144.0/24 e a rede nº 2 tem o endereço 193.49.145.0/24;
  • dentro da rede nº 1, o roteador tem o endereço 193.49.144.6 e, dentro da rede nº 2, tem o endereço 193.49.145.3.

O papel do roteador é pegar o pacote IP que ele recebe — contido em um quadro físico da rede nº 1 — e colocá-lo em um quadro físico que possa trafegar pela rede nº 2. Se o endereço IP de destino do pacote estiver na rede nº 2, o roteador enviará o pacote diretamente a ele; caso contrário, o enviará a outro roteador que conecta a rede nº 2 à rede nº 3, e assim por diante. Os roteadores da Internet trocam constantemente informações sobre as redes que conseguem alcançar (protocolos de roteamento como o BGP entre operadoras) para construir suas tabelas de roteamento.

12.1.6.2. Mensagens de erro e de controle

Também na camada de rede — e, portanto, no mesmo nível do protocolo IP — está o protocolo ICMP (Internet Control Message Protocol). Ele é usado para enviar mensagens sobre o funcionamento interno da rede: nó inacessível, pacote que atravessou roteadores demais etc. As mensagens ICMP são encapsuladas em pacotes IP e enviadas pela rede. As camadas IP dos diversos nós tomam as providências apropriadas com base nas mensagens ICMP que recebem. Assim, uma aplicação nunca vê, ela própria, esses problemas específicos da rede. Os comandos [ping] (que enviam mensagens ICMP “Echo Request” e aguardam mensagens “Echo Reply”) e [traceroute] / [tracert] (que exibe os roteadores atravessados) baseiam-se no ICMP.

12.1.7. A camada de transporte: os protocolos UDP e TCP

12.1.7.1. O protocolo UDP: User Datagram Protocol

O protocolo UDP permite uma troca não confiável de dados entre dois pontos; ou seja, não é garantida a entrega bem-sucedida de um pacote ao destino, nem a ordem em que os pacotes chegam. A aplicação, se quiser, pode tratar isso por conta própria — por exemplo, aguardando uma confirmação após enviar uma mensagem antes de enviar a seguinte.

Até agora, no nível da rede, falamos dos endereços IP das máquinas. No entanto, em uma mesma máquina podem coexistir simultaneamente diferentes processos, e todos eles podem se comunicar entre si. Portanto, ao enviar uma mensagem, é preciso especificar não apenas o endereço IP da máquina de destino, mas também o “nome” do processo de destino. Esse nome é, na verdade, um número de 16 bits (de 1 a 65.535), chamado número de porta. Certos números são reservados para aplicações padrão: porta 53 para DNS, 80 para HTTP, 443 para HTTPS, 25 para SMTP, e assim por diante. As portas abaixo de 1024 são chamadas de “bem conhecidas” (well-known); no Linux, são necessários privilégios especiais para abrir um serviço em uma delas. Os exemplos deste capítulo usam portas das faixas 27100–27199 e 27200–27299.

Os pacotes tratados pelo protocolo UDP são chamados de datagramas. Eles têm a seguinte forma:

Image

Esses datagramas são encapsulados em pacotes IP e, depois, em quadros físicos. O UDP é usado quando a velocidade é mais importante que a confiabilidade, ou quando a própria aplicação trata a perda de pacotes: DNS (uma pergunta, uma resposta), streaming de áudio e vídeo ao vivo, jogos online e o protocolo QUIC do HTTP/3.

12.1.7.2. O protocolo TCP: Transmission Control Protocol

Para comunicações seguras, o protocolo UDP é insuficiente: o desenvolvedor da aplicação precisa criar ele mesmo um protocolo que garanta que os pacotes sejam encaminhados corretamente. O protocolo TCP evita esses problemas. Suas características são as seguintes:

  • O processo que deseja transmitir dados estabelece primeiro uma conexão com o processo que receberá as informações que ele está prestes a transmitir. Essa conexão é estabelecida entre uma porta da máquina emissora e uma porta da máquina receptora por meio de uma troca de três segmentos (SYN, SYN-ACK, ACK: o “three-way handshake”). Cria-se assim um circuito virtual entre as duas portas, que será reservado exclusivamente aos dois processos que estabeleceram a conexão;
  • todos os bytes transmitidos pelo processo de origem chegam ao destino na ordem em que foram transmitidos, o que não é garantido pelo protocolo UDP, já que os pacotes podem seguir caminhos diferentes;
  • a informação transmitida é contínua: é um fluxo de bytes. O processo transmissor envia as informações em seu próprio ritmo. Essas informações não são necessariamente enviadas imediatamente: o protocolo TCP pode esperar até ter dados suficientes para enviar. Os dados são colocados em uma estrutura chamada segmento TCP. Quando esse segmento está cheio, ele é transmitido à camada IP, onde é encapsulado em um pacote IP. Uma implicação importante para o programador: uma “linha” enviada de uma só vez pode chegar em vários pedaços, e várias linhas podem chegar juntas. Cabe à aplicação identificar os limites de suas mensagens (usaremos o caractere de fim de linha para isso);
  • Cada segmento enviado pelo protocolo TCP é numerado. O protocolo TCP receptor verifica se está recebendo os segmentos em sequência. Para cada segmento recebido corretamente, ele envia uma confirmação (acknowledgment) ao remetente;
  • se, após um certo tempo, o protocolo TCP que enviou um segmento não recebe a confirmação, ele retransmite o segmento em questão, garantindo assim a qualidade do serviço de entrega das informações;
  • O circuito virtual estabelecido entre os dois processos que se comunicam é full-duplex: as informações podem trafegar nos dois sentidos simultaneamente. Assim, o processo de destino pode enviar confirmações mesmo enquanto o processo de origem continua enviando informações. Isso permite, por exemplo, que o protocolo TCP de origem envie vários segmentos sem esperar as confirmações. Se, após um certo tempo, ele perceber que não recebeu a confirmação de um segmento específico de número n, retomará a transmissão dos segmentos a partir desse ponto;
  • O TCP também regula sua taxa de transmissão de dados para evitar sobrecarregar o destinatário (controle de fluxo) ou a rede (controle de congestionamento).

12.1.8. A camada de aplicação

Acima dos protocolos UDP e TCP há diversos protocolos padronizados:

TELNET e SSH

O TELNET permite que um usuário da máquina A se conecte à máquina B (frequentemente chamada de máquina host) como se tivesse um terminal ligado a essa máquina. O TELNET se baseia no TCP. Suas trocas de dados, inclusive as senhas, são transmitidas em texto puro: ele foi substituído pelo SSH (Secure Shell), que oferece o mesmo serviço de forma criptografada e também é usado para transferência segura de arquivos (SFTP, SCP) e para a criação de túneis. Em 2008, o programa cliente [telnet] continuava sendo uma ferramenta prática para se comunicar “manualmente” com um servidor TCP: veremos como substituí-lo.

FTP (File Transfer Protocol)

Esse protocolo permite a troca de arquivos entre duas máquinas remotas, bem como operações sobre arquivos, como a criação de diretórios. Ele se baseia no protocolo TCP. Como o TELNET, transmite as senhas em texto puro; está sendo abandonado em favor do SFTP e do HTTPS.

TFTP (Trivial File Transfer Protocol)

Esse protocolo é uma variante simplificada do FTP. Ele se baseia no protocolo UDP. Ainda é usado para inicializar máquinas pela rede.

DNS (Domain Name System)

Quando um usuário quer trocar informações com uma máquina remota, precisa conhecer o endereço IP dessa máquina. É bem mais cômodo designar uma máquina por um nome do que por seu endereço IP. Isso levanta a questão da unicidade dos nomes: há bilhões de máquinas interconectadas. Poderíamos imaginar uma autoridade centralizada atribuindo os nomes, mas isso seria muito pesado. O controle dos nomes foi distribuído por domínios. Cada domínio é gerenciado por uma organização que tem total liberdade para escolher os nomes dentro de seu domínio. Assim, as máquinas da França pertencem com frequência ao domínio [fr], gerenciado pela AFNIC (o INRIA o gerenciou até a criação da AFNIC em 1997). Para simplificar ainda mais, o controle é distribuído ainda mais: criam-se domínios dentro do domínio [fr]. Por exemplo, a Universidade de Angers possui o domínio [univ-angers.fr]; o departamento que o administra tem total liberdade para nomear os computadores da rede da universidade e para criar subdomínios.

O nome completo de uma máquina (FQDN, Fully Qualified Domain Name) especifica a hierarquia de domínios a que ela pertence, do mais específico ao mais geral: [www.univ-angers.fr]. Dentro de um domínio, é possível usar com frequência nomes relativos, que são completados automaticamente pelo sistema.

Uma aplicação pode, portanto, designar uma máquina pelo nome. No fim das contas, porém, é preciso obter o endereço IP dessa máquina. Suponha que você queira se comunicar da máquina A com a máquina B:

  • A máquina A consulta primeiro um arquivo local de correspondências ([/etc/hosts] no Linux e no macOS, [C:\Windows\System32\drivers\etc\hosts] no Windows), depois seu cache;
  • caso contrário, consulta o servidor DNS, cujo endereço consta em sua configuração (em geral fornecido por DHCP). Ela envia uma requisição DNS contendo o nome da máquina procurada. Se o servidor consultado souber a resposta ou a tiver em cache, devolve o endereço IP correspondente à máquina A. Caso contrário, ele por sua vez consulta, a partir dos servidores raiz, os servidores responsáveis pelo domínio [fr], depois por [univ-angers.fr], e assim por diante, até obter a resposta, que será então repassada de volta até a máquina A.

O domínio DNS associa a um nome diversos tipos de registros: A (endereço IPv4), AAAA (endereço IPv6), CNAME (alias para outro nome), MX (servidores de e-mail do domínio), etc.

HTTP e HTTPS (HyperText Transfer Protocol)

Esse é o protocolo da Web, de longe o mais usado hoje: não só pelos navegadores, mas também por aplicações que trocam dados (os serviços web abordados no próximo capítulo). Vamos examiná-lo em detalhe. O HTTPS é o HTTP transmitido por uma conexão criptografada por TLS (Transport Layer Security); essa é hoje a forma padrão da Web.

SMTP, POP3 e IMAP

O SMTP serve para enviar e-mails, enquanto o POP3 e o IMAP servem para ler e-mails armazenados em um servidor. Também falaremos deles.

XDR, RPC, NFS

O curso de 2008 abordava ainda três protocolos definidos pela Sun Microsystems: XDR (eXternal Data Representation), que especifica uma representação de dados padrão e independente da máquina; RPC (Remote Procedure Call), um protocolo de chamada de procedimento remoto baseado no XDR; e NFS (Network File System), que permite a uma máquina “enxergar” o sistema de arquivos de outra máquina e se baseia no RPC. O NFS continua em uso no mundo Unix. O conceito de chamada de procedimento remoto foi adotado por numerosos sucessores; hoje, entre eles estão os serviços web REST (baseados em HTTP) e o gRPC (baseado em HTTP/2).

12.1.9. Conclusão

Nesta introdução, apresentamos algumas das principais características dos protocolos da Internet. Para aprofundar esse campo, o leitor pode consultar a obra de referência de Douglas Comer, “Internetworking with TCP/IP, Volume 1” (Pearson, 6ª edição) — cujas edições anteriores foram traduzidas para o francês —, bem como as RFC citadas neste capítulo. Para o HTTP, a documentação da Mozilla em developer.mozilla.org/en-US/docs/Web/HTTP é uma excelente introdução.

12.2. As classes do .NET para o gerenciamento de endereços IP

Uma máquina na Internet é identificada por um endereço IP, que pode assumir duas formas:

  • IPv4: codificado em 32 bits e representado por uma cadeia da forma "I1.I2.I3.I4", em que In é um número entre 0 e 255;
  • IPv6: codificado em 128 bits e representado por uma cadeia de oito grupos de dígitos hexadecimais separados por dois-pontos, como "2001:db8::8a2e:370:7334". O curso de 2008 anunciava que não usaria endereços IPv6; hoje isso não é mais possível: nossos programas os aceitarão.

Uma máquina também pode ser identificada por um nome. Esse nome não é obrigatório, pois as aplicações sempre usam, em última instância, os endereços IP das máquinas. Os nomes existem para facilitar a vida dos usuários: é mais fácil pedir a um navegador a URL [https://learn.microsoft.com] do que a URL formada a partir de um dos endereços IP desse site, que, aliás, muda conforme o local de onde a requisição é feita.

Uma máquina pode ter vários endereços IP: um endereço de loopback, um endereço por rede à qual está conectada, e endereços IPv4 e IPv6.

Um endereço IP pode ser representado de duas maneiras no .NET:

  • como uma cadeia "I1.I2.I3.I4" ou "2001:db8::1";
  • como um objeto do tipo [IPAddress] (namespace [System.Net]).

A classe IPAddress

Entre os métodos M, as propriedades P e os campos estáticos F da classe [IPAddress] estão os seguintes:

Membro
Tipo
Função
AddressFamily AddressFamily
P
família do endereço IP. O tipo [AddressFamily] (namespace [System.Net.Sockets]) é uma enumeração cujos dois valores atuais são [AddressFamily.InterNetwork] (IPv4) e [AddressFamily.InterNetworkV6] (IPv6)
static IPAddress Any
F
o endereço IPv4 0.0.0.0. Quando um serviço é associado a esse endereço, ele aceita clientes em todos os endereços IPv4 da máquina
static IPAddress Loopback
F
o endereço de loopback 127.0.0.1. Um serviço associado a esse endereço aceita apenas clientes situados na mesma máquina que ele
static IPAddress Broadcast
F
o endereço de broadcast 255.255.255.255 ([IPAddress.None] tem o mesmo valor)
static IPAddress IPv6Any, IPv6Loopback
F
os equivalentes em IPv6 de [Any] (::) e de [Loopback] (::1)
static IPAddress Parse(string ipString)
M
converte uma cadeia IPv4 ou IPv6 em um objeto [IPAddress]; lança uma [FormatException] se a cadeia não for um endereço IP
static bool TryParse(string ipString, out IPAddress address)
M
Igual ao anterior, mas devolve [false] em vez de lançar uma exceção
static bool IsLoopback(IPAddress address)
M
devolve [true] se o endereço for um endereço de loopback (127.x.y.z ou ::1)
byte[] GetAddressBytes()
M
devolve os bytes do endereço (4 em IPv4, 16 em IPv6)
string ToString()
M
devolve o endereço em sua forma textual padrão

Dois outros tipos complementam [IPAddress]:

  • [IPEndPoint] representa um ponto de conexão: um endereço IP e um número de porta. Suas propriedades [Address] e [Port] fornecem essas duas informações; o método estático [IPEndPoint.Parse] analisa uma cadeia como "127.0.0.1:27100" ou "[::1]:27100";
  • [IPNetwork] (desde o .NET 8) representa uma rede em notação CIDR, como 193.49.144.0/24. Seu método [Contains] determina se um endereço pertence à rede.

O programa [internet-01.cs] ilustra esses três tipos:

using System.Net;
using System.Net.Sockets;

// as classes IPAddress, IPEndPoint e IPNetwork

// endereços IPv4 e IPv6, corretos ou não
string[] addresses = ["193.49.144.1", "127.0.0.1", "192.168.1", "::1",
    "2001:db8::8a2e:370:7334", "256.1.1.1", "machine"];
foreach (string str in addresses)
{
    // TryParse: nenhuma exceção se a string não for um endereço IP
    if (IPAddress.TryParse(str, out IPAddress? address))
    {
        string family = address.AddressFamily == AddressFamily.InterNetwork ? "IPv4" : "IPv6";
        string bytes = Convert.ToHexString(address.GetAddressBytes());
        int nbBytes = address.GetAddressBytes().Length;
        bool loopback = IPAddress.IsLoopback(address);
        Console.WriteLine($"[{str}] -> {address} ({family}, {nbBytes} bytes: {bytes}, loopback: {loopback})");
    }
    else
    {
        Console.WriteLine($"[{str}] is not an IP address");
    }
}

// Parse lança uma exceção se a string estiver incorreta
try
{
    IPAddress.Parse("256.1.1.1");
}
catch (FormatException ex)
{
    Console.WriteLine($"Parse(\"256.1.1.1\"): {ex.GetType().Name} : {ex.Message}");
}

// alguns endereços predefinidos
Console.WriteLine($"Any={IPAddress.Any}, Loopback={IPAddress.Loopback}, Broadcast={IPAddress.Broadcast}");
Console.WriteLine($"IPv6Any={IPAddress.IPv6Any}, IPv6Loopback={IPAddress.IPv6Loopback}");

// um endpoint = um endereço IP + uma porta
var point = new IPEndPoint(IPAddress.Loopback, 27100);
Console.WriteLine($"IPEndPoint: {point} (address={point.Address}, port={point.Port})");
var point6 = IPEndPoint.Parse("[::1]:27100");
Console.WriteLine($"IPv6 IPEndPoint: {point6} (address={point6.Address}, port={point6.Port})");

// uma rede em notação CIDR: endereço da rede / comprimento do prefixo
var network = IPNetwork.Parse("193.49.144.0/24");
string[] machines = ["193.49.144.1", "193.49.145.3"];
foreach (string str in machines)
{
    Console.WriteLine($"{str} belongs to {network}: {network.Contains(IPAddress.Parse(str))}");
}

Resultados:

> dotnet run internet-01.cs
[193.49.144.1] -> 193.49.144.1 (IPv4, 4 bytes: C1319001, loopback: False)
[127.0.0.1] -> 127.0.0.1 (IPv4, 4 bytes: 7F000001, loopback: True)
[192.168.1] -> 192.168.0.1 (IPv4, 4 bytes: C0A80001, loopback: False)
[::1] -> ::1 (IPv6, 16 bytes: 00000000000000000000000000000001, loopback: True)
[2001:db8::8a2e:370:7334] -> 2001:db8::8a2e:370:7334 (IPv6, 16 bytes: 20010DB80000000000008A2E03707334, loopback: False)
[256.1.1.1] is not an IP address
[machine] is not an IP address
Parse("256.1.1.1"): FormatException : An invalid IP address was specified.
Any=0.0.0.0, Loopback=127.0.0.1, Broadcast=255.255.255.255
IPv6Any=::, IPv6Loopback=::1
IPEndPoint: 127.0.0.1:27100 (address=127.0.0.1, port=27100)
IPv6 IPEndPoint: [::1]:27100 (address=::1, port=27100)
193.49.144.1 belongs to 193.49.144.0/24: True
193.49.145.3 belongs to 193.49.144.0/24: False

Comentários:

  • linha 7: uma expressão de coleção inicializa o array de cadeias a serem analisadas;
  • Linha 12: [TryParse] devolve [true] se a cadeia for um endereço IPv4 ou IPv6 e, nesse caso, atribui o objeto [IPAddress] resultante à variável [address]. O tipo anulável [IPAddress?] indica que essa variável recebe [null] quando a análise falha;
  • linha 14: a propriedade [AddressFamily] distingue as duas versões do IP;
  • linha 15: [GetAddressBytes] devolve os bytes do endereço, que [Convert.ToHexString] exibe em hexadecimal. Vemos (linha 2 dos resultados) que 193.49.144.1 é composto pelos quatro bytes C1, 31, 90, 01 e (linha 5) que ::1 é composto por 15 bytes zero seguidos de um byte com valor 1;
  • Linha 4 dos resultados: uma surpresa. A cadeia "192.168.1" foi aceita e convertida em 192.168.0.1. [TryParse] de fato aceita as formas abreviadas históricas de endereços IPv4 (nas quais o último número ocupa todos os bytes restantes). Para verificar se uma entrada é um endereço IPv4 completo, é preciso, portanto, verificar também que ela contém quatro números;
  • linha 6: o endereço IPv6 é reexibido em sua forma compacta padronizada. O prefixo 2001:db8::/32 é, como 192.0.2.0/24 em IPv4, reservado para documentação;
  • linhas 27–31: [IPAddress.Parse] gera uma [FormatException] para a cadeia “256.1.1.1” (256 não cabe em um único byte). Como em todo o curso, a mensagem da exceção está em inglês (o .NET não fornece tradução para o francês);
  • linha 41: um objeto [IPEndPoint] associa um endereço e uma porta. Sua exibição (linha 12 dos resultados) tem a forma endereço:porta; em IPv6 (linha 13), o endereço vem entre colchetes;
  • linha 47: uma rede em notação CIDR. As linhas 14–15 dos resultados mostram que 193.49.144.1 pertence à rede 193.49.144.0/24 e que 193.49.145.3 (o endereço do roteador em nosso diagrama, em sua segunda rede) não pertence a ela. É exatamente o teste que uma máquina realiza para escolher entre roteamento direto e indireto.

A classe Dns

A correspondência entre o endereço IP e o nome da máquina é tratada pelo DNS. Os métodos estáticos da classe [Dns] (namespace [System.Net]) permitem consultá-lo:

Método
Função
Task<IPHostEntry> GetHostEntryAsync(string hostNameOrAddress)
Devolve um objeto [IPHostEntry] a partir de um nome de máquina ou de um endereço IP na forma de cadeia. Lança uma [SocketException] se a máquina não for encontrada
Task<IPHostEntry> GetHostEntryAsync(IPAddress address)
Igual ao anterior, mas a partir de um objeto [IPAddress]
Task<IPAddress[]> GetHostAddressesAsync(string hostNameOrAddress)
devolve apenas os endereços IP da máquina
string GetHostName()
devolve o nome da máquina em que o programa está sendo executado

Cada um desses métodos assíncronos tem uma versão síncrona ([GetHostEntry], [GetHostAddresses]), que era usada no curso de 2008. Uma requisição DNS pode levar várias dezenas de milissegundos, ou até vários segundos se um servidor não responder: como vimos no capítulo sobre programação assíncrona, o melhor é não bloquear uma thread durante a espera.

Um objeto [IPHostEntry] encapsula endereços IP, aliases e um nome de máquina:

Propriedade
Tipo
Função
IPAddress[] AddressList
P
tabela de endereços IP da máquina
string[] Aliases
P
outros nomes da máquina conhecidos pelo sistema (frequentemente vazio)
string HostName
P
o nome principal da máquina

O programa [internet-02.cs] exibe o nome da máquina em que está sendo executado e, em seguida, lista de forma interativa as correspondências entre o nome da máquina e os endereços IP:

using System.Net;
using System.Net.Sockets;

// exibe o nome da máquina local
// e depois fornece, de forma interativa, informações sobre as máquinas da rede
// identificadas por um nome ou um endereço IP

// máquina local
Console.WriteLine($"Local machine = {Dns.GetHostName()}");

// perguntas e respostas interativas
while (true)
{
    // entrada do nome ou do endereço IP da máquina procurada
    Console.Write("Machine looked for (nothing to stop): ");
    string machine = (Console.ReadLine() ?? "").Trim().ToLower();
    // terminou?
    if (machine == "")
    {
        break;
    }
    try
    {
        // consulta (assíncrona) ao DNS
        IPHostEntry entry = await Dns.GetHostEntryAsync(machine);
        // o nome da máquina
        Console.WriteLine($"Machine: {entry.HostName}");
        // seus endereços IP
        Console.WriteLine($"IP addresses: {string.Join(", ", entry.AddressList.Select(ip => ip.ToString()))}");
        // seus possíveis aliases
        if (entry.Aliases.Length != 0)
        {
            Console.WriteLine($"Aliases: {string.Join(", ", entry.Aliases)}");
        }
    }
    catch (SocketException ex)
    {
        // a máquina não foi encontrada
        Console.WriteLine($"Unable to find the machine [{machine}]: {ex.SocketErrorCode} ({ex.Message})");
    }
}

Resultados:

> dotnet run internet-02.cs
Local machine = vm
Machine looked for (nothing to stop): localhost
Machine: localhost
IP addresses: 127.0.0.1
Machine looked for (nothing to stop): vm
Machine: vm
IP addresses: 127.0.0.1, 192.0.2.2
Machine looked for (nothing to stop): 127.0.0.1
Machine: localhost
IP addresses: 127.0.0.1
Machine looked for (nothing to stop): ::1
Unable to find the machine [::1]: HostNotFound (Name or service not known)
Machine looked for (nothing to stop): xx
Unable to find the machine [xx]: HostNotFound (Name or service not known)
Machine looked for (nothing to stop): 

Comentários:

  • linha 9: o nome da máquina local. Nossa máquina de teste é uma máquina virtual Linux chamada [vm]; para o leitor, será naturalmente o nome do próprio computador;
  • linha 25: a consulta DNS assíncrona. Se o nome (ou endereço) for desconhecido, uma [SocketException] é lançada; sua propriedade [SocketErrorCode] (linha 39) informa a natureza do erro na forma de uma enumeração, que é mais fácil de testar do que a mensagem;
  • Linha 29: os endereços IP da máquina são reunidos em uma única cadeia por [string.Join], depois de convertidos em cadeias por [Select] (LINQ).

Os resultados merecem alguns comentários. Eles dependem da configuração da máquina: não espere obter exatamente os mesmos resultados no seu sistema.

  • Linha 4: o nome [localhost] corresponde ao endereço de loopback 127.0.0.1. Em uma máquina em que o IPv6 está ativo, você também obteria ::1;
  • Linha 8: o nome da máquina corresponde a dois endereços: o endereço de loopback e o endereço de sua interface de rede. Em uma máquina Windows com o nome PC conectada a um roteador, você obteria tipicamente um endereço privado da forma 192.168.x.y e um ou mais endereços IPv6;
  • linha 9: dado um endereço IP, [GetHostEntryAsync] realiza uma consulta “reversa” e devolve o nome associado ao endereço;
  • linha 13: a consulta reversa de ::1 falhou porque o arquivo [/etc/hosts] de nossa máquina de teste não associa nenhum nome a esse endereço e nenhuma interface IPv6 está ativa nela. No Windows, o nome da máquina seria devolvido;
  • linha 15: o nome [xx] é desconhecido. A mensagem da exceção vem aqui da biblioteca de sistema do Linux; seria diferente no Windows, mas [SocketErrorCode] equivale a [HostNotFound] nos dois casos.

Em uma máquina conectada à Internet, também é possível consultar um nome público como [learn.microsoft.com]. Em geral, isso devolve um nome principal diferente do nome solicitado (o site é servido por uma rede de distribuição de conteúdo e o nome solicitado é um alias DNS), junto com endereços que variam conforme o local e o momento da consulta. Não reproduzimos esse resultado, pois nossa máquina de teste não tem acesso à Internet.

12.3. Fundamentos da programação web

12.3.1. Visão geral

Considere a comunicação entre duas máquinas remotas, A e B:

Image

Quando uma aplicação AppA da máquina A quer se comunicar com uma aplicação AppB da máquina B na Internet, ela precisa conhecer várias coisas:

  • o endereço IP ou o nome da máquina B;
  • o número da porta usada pela aplicação AppB. Isso porque a máquina B pode hospedar muitas aplicações que funcionam na Internet. Quando recebe informações da rede, ela precisa saber a qual aplicação elas se destinam. As aplicações da máquina B acessam a rede por meio de interfaces chamadas portas de comunicação. O número da porta de destino está contido no segmento recebido pela máquina B para que ela possa entregá-lo à aplicação correta;
  • os protocolos de comunicação compreendidos pela máquina B. Em nosso estudo, usaremos apenas os protocolos TCP/IP;
  • o protocolo de comunicação aceito pela aplicação AppB. De fato, as máquinas A e B vão “conversar” entre si. O que elas dizem será encapsulado nos protocolos TCP/IP. Contudo, quando a aplicação AppB, no fim da cadeia, recebe as informações enviadas pela aplicação AppA, ela precisa ser capaz de interpretá-las. É uma situação análoga à de duas pessoas, A e B, que se comunicam por telefone: a conversa é transportada pela linha telefônica, mas se A fala francês e B não entende essa língua, A e B não conseguirão ter uma conversa significativa. As duas aplicações que se comunicam devem, portanto, combinar o tipo de comunicação que usarão. Por exemplo, a comunicação com um servidor web não é a mesma que com um servidor de e-mail: esses dois serviços não aceitam os mesmos comandos. Eles têm protocolos de comunicação diferentes.

12.3.2. Características do protocolo TCP

Aqui nos interessaremos apenas pelas comunicações de rede que usam o protocolo de transporte TCP. Vamos rever suas principais características para o programador:

  • Uma conexão é estabelecida primeiro entre uma porta da máquina cliente e uma porta da máquina servidora. Ela é identificada por quatro informações: o endereço IP e a porta do cliente, e o endereço IP e a porta do servidor;
  • a conexão transporta dois fluxos de bytes, um em cada sentido (full-duplex). Os bytes chegam na ordem em que foram transmitidos, sem perda nem duplicação;
  • o TCP não conhece o conceito de mensagem: cabe ao protocolo de comunicação da aplicação delimitar as requisições e as respostas (por uma quebra de linha, um comprimento especificado, o fechamento da conexão etc.);
  • Uma das duas partes fecha a conexão; a outra detecta isso ao chegar ao fim do fluxo de leitura.

12.3.3. A relação cliente-servidor

A comunicação pela Internet costuma ser assimétrica: a máquina A inicia uma conexão para solicitar um serviço à máquina B. Ela especifica que deseja estabelecer uma conexão com o serviço SB1 da máquina B. A máquina B aceita ou recusa a solicitação. Se aceitar, a máquina A pode enviar suas requisições ao serviço SB1. Essas requisições devem respeitar o protocolo de comunicação compreendido pelo serviço SB1. Estabelece-se assim um diálogo de requisição-resposta entre a máquina A, chamada máquina cliente, e a máquina B, chamada máquina servidora. Um dos dois parceiros fechará a conexão.

12.3.4. Arquitetura de um cliente

A arquitetura de um programa de rede que solicita os serviços de uma aplicação servidora será a seguinte:

open the connection with the SB1 service of machine B
if successful then
    while not finished
        prepare a request
        send it to machine B
        wait for and retrieve the response
        process it
    end while
end if
close the connection

12.3.5. Arquitetura de um servidor

A arquitetura de um programa que oferece serviços será a seguinte:

1
2
3
4
5
6
open the service on the local machine
while the service is open
    listen for connection requests on a port called the listening port
    when there is a request, accept it and have the resulting connection
        (service connection) handled by another task
end while

O programa servidor trata de modo diferente o pedido inicial de conexão de um cliente e seus pedidos posteriores de serviço. O programa que escuta não presta o serviço em si: se o fizesse, deixaria de escutar os pedidos de conexão enquanto o serviço estivesse em andamento, e os outros clientes não seriam atendidos. Ele procede, portanto, de outra forma: assim que um pedido de conexão é recebido na porta de escuta e então aceito, o servidor cria uma tarefa encarregada de prestar o serviço solicitado pelo cliente pela conexão de serviço que acabou de ser estabelecida. Isso torna possível atender vários clientes ao mesmo tempo:

Image

O curso de 2008 afirmava que a conexão de serviço usava, no lado do servidor, uma outra porta, escolhida aleatoriamente. Isso é incorreto: todas as conexões de serviço usam a porta de escuta do servidor; elas se distinguem umas das outras pelo endereço e pela porta do cliente, que são diferentes. Veremos isso na saída do nosso servidor de eco.

Uma tarefa de serviço terá a seguinte estrutura:

1
2
3
4
5
6
while the service has not been fully provided
    wait for a request on the service connection
    when there is one, build the response
    send the response over the service connection
end while
close the service connection

12.4. Explorando os protocolos de comunicação da Internet

12.4.1. Introdução

Quando um cliente se conecta a um servidor, estabelece-se um diálogo entre eles. A natureza desse diálogo constitui o que se chama de protocolo de comunicação do servidor. Entre os protocolos mais comuns da Internet estão os seguintes:

  • HTTP: HyperText Transfer Protocol, o protocolo de comunicação com um servidor web (servidor HTTP);
  • SMTP: Simple Mail Transfer Protocol, o protocolo de comunicação com um servidor de envio de e-mails (servidor SMTP);
  • POP: Post Office Protocol, o protocolo de comunicação com um servidor de armazenamento de e-mails (servidor POP). Serve para recuperar os e-mails recebidos, não para enviá-los. O IMAP tem a mesma finalidade;
  • FTP: File Transfer Protocol, o protocolo de comunicação com um servidor de armazenamento de arquivos (servidor FTP).

Esses protocolos, em suas versões históricas, caracterizam-se por serem baseados em texto: o cliente e o servidor trocam linhas de texto terminadas pelos dois caracteres \r\n (carriage return, line feed). Se você dispõe de um cliente capaz de:

  • estabelecer uma conexão com um servidor TCP;
  • exibir no console as linhas de texto enviadas pelo servidor;
  • enviar ao servidor as linhas de texto que um usuário digita no teclado,

então podemos nos comunicar com um servidor TCP que usa um protocolo textual, desde que conheçamos as regras desse protocolo.

O programa [telnet], que antigamente estava disponível em máquinas Unix e Windows, é um desses clientes; o curso de 2008 usava a ferramenta PuTTY, configurada no modo de conexão bruta (raw). O cliente [telnet] não vem mais instalado por padrão no Windows, e a maioria dos servidores públicos não aceita mais comunicação sem criptografia. Vamos proceder de outra forma:

  • para o HTTP, usaremos a ferramenta [curl], disponível por padrão no Windows 10 e 11, bem como no Linux, que exibe os detalhes das trocas, e em seguida o cliente TCP genérico que escreveremos mais adiante neste capítulo. No Windows, no PowerShell, [curl] é um alias do comando [Invoke-WebRequest]: é preciso digitar [curl.exe];
  • como não temos acesso a servidores reais, consultaremos um pequeno servidor web que nós mesmos escrevemos e que roda na máquina local;
  • Para SMTP, POP e FTP, apresentaremos exemplos de diálogos conformes com as RFC que definem esses protocolos.

12.4.2. Um servidor web de teste

Nosso servidor web de teste é uma aplicação ASP.NET Core de arquivo único chamada “Minimal API”. O ASP.NET Core é o framework de desenvolvimento web do .NET; vamos explorá-lo no próximo capítulo. Por ora, não é necessário entender esse programa em detalhe — basta saber o que ele produz. O programa [internet-03.cs] é o seguinte:

#:sdk Microsoft.NET.Sdk.Web

// um pequeno servidor web local que servirá de alvo para nossos clientes HTTP
// chamada: dotnet run internet-03.cs [-- port]
int port = args.Length == 1 && int.TryParse(args[0], out int p) ? p : 27110;

var builder = WebApplication.CreateBuilder(args);
// nenhum log do ASP.NET (apenas os avisos): escrevemos o nosso
builder.Logging.SetMinimumLevel(LogLevel.Warning);
var app = builder.Build();

// acompanhamento no console: cada requisição e o código de status de sua resposta
app.Use(async (context, next) =>
{
    await next(context);
    var request = context.Request;
    string url = $"{request.Path}{request.QueryString}";
    Console.WriteLine($"{request.Method} {url} {request.Protocol} -> {context.Response.StatusCode}");
});

// as URLs aceitam os métodos GET e HEAD
string[] getHead = ["GET", "HEAD"];

// a página inicial: um documento HTML
app.MapMethods("/", getHead, () => Results.Content("""
    <!DOCTYPE html>
    <html lang="en">
    <head><meta charset="utf-8"><title>Test server</title></head>
    <body><h1>Welcome to the test server of the C# course</h1></body>
    </html>

    """, "text/html; charset=utf-8"));

// um documento de texto construído a partir de um parâmetro da URL
app.MapMethods("/hello", getHead, (string? name) => $"Hello {name ?? "unknown"}!");

// redirecionamento temporário (302) para um endereço relativo
app.MapMethods("/old", getHead, () => Results.Redirect("/hello?name=visitor"));

// redirecionamento permanente (301) para um endereço absoluto
app.MapMethods("/moved", getHead, () => Results.Redirect($"http://localhost:{port}/", permanent: true));

// um redirecionamento que entra em laço consigo mesmo
app.MapMethods("/loop", getHead, () => Results.Redirect("/loop"));

// qualquer outra URL recebe a resposta 404 Not Found (comportamento padrão)
Console.WriteLine($"Web server started on http://localhost:{port}");
app.Run($"http://127.0.0.1:{port}");

Comentários:

  • Linha 1: essa diretiva especifica que a aplicação de arquivo único usa a versão web do SDK do ASP.NET Core ([Microsoft.NET.Sdk.Web]) em vez do SDK usual para console. Os namespaces do ASP.NET Core ([Microsoft.AspNetCore.Builder], [Microsoft.AspNetCore.Http]…) passam então a fazer parte dos [using] padrão;
  • linha 5: a porta de escuta, 27110 por padrão;
  • linhas 13–18: cada requisição processada é exibida no console junto com o código de status da resposta;
  • linha 25: a URL [/] devolve um pequeno documento HTML. O texto do documento é escrito com um literal de cadeia bruta [""" ... """] (C# 11), o que evita a necessidade de escapar as aspas;
  • linha 35: a URL [/hello?name=xx] devolve o texto [Hello xx!]. O parâmetro [name] da lambda é preenchido automaticamente com o parâmetro [name] da URL;
  • linha 38: a URL [/old] provoca um redirecionamento temporário (código de status 302) para o endereço relativo [/hello?name=visitor];
  • linha 41: a URL [/moved] provoca um redirecionamento permanente (código de status 301) para o endereço absoluto [http://localhost:27110/];
  • linha 44: a URL [/loop] redireciona para si mesma: um cliente que seguisse cegamente os redirecionamentos nunca pararia;
  • qualquer outra URL recebe uma resposta 404 (página não encontrada);
  • linha 48: o servidor escuta no endereço de loopback 127.0.0.1: ele só é acessível a partir da própria máquina.

O servidor é iniciado em uma janela de comando. Ele exibe:

1
2
3
4
> dotnet run internet-03.cs
Web server started on http://localhost:27110
GET / HTTP/1.1 -> 200
GET /unknown HTTP/1.1 -> 404

As linhas 3–4 apareceram durante os testes descritos no parágrafo seguinte. O servidor é interrompido pressionando Ctrl-C.

12.4.3. O protocolo HTTP (HyperText Transfer Protocol)

Com o servidor em execução, solicitamos, em uma segunda janela de comando, a raiz [/] do site [http://localhost:27110] por meio da ferramenta [curl]. Sua opção [-v] (verbose) exibe todo o diálogo HTTP:

> curl -v http://localhost:27110/
* Host localhost:27110 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying 127.0.0.1:27110...
* Connected to localhost (127.0.0.1) port 27110
> GET / HTTP/1.1
> Host: localhost:27110
> User-Agent: curl/8.5.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Length: 169
< Content-Type: text/html; charset=utf-8
< Date: Sat, 03 Oct 2026 09:48:36 GMT
< Server: Kestrel
< 
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Test server</title></head>
<body><h1>Welcome to the test server of the C# course</h1></body>
</html>
* Connection #0 to host localhost left intact

Comentários:

  • As linhas que começam com [*] contêm informações do [curl]; as linhas que começam com [>] foram enviadas ao servidor; as que começam com [<] foram recebidas do servidor; as demais compõem o documento recebido;
  • Linhas 2–6: [curl] obteve os endereços de [localhost] (::1 em IPv6 e 127.0.0.1 em IPv4) e se conectou à porta 27110 do endereço 127.0.0.1;
  • linhas 7–10: a requisição do cliente. Ela consiste em uma primeira linha com a sintaxe [method URL version] (aqui, o método [GET] é usado para solicitar o documento [/], isto é, a raiz do site, em HTTP/1.1), seguida de cabeçalhos HTTP da forma [Name: value], e termina com uma linha em branco;
  • linha 8: o cabeçalho [Host] especifica a máquina e a porta consultadas; ele é obrigatório no HTTP/1.1, pois um mesmo servidor pode hospedar vários sites;
  • linha 9: o identificador do software cliente;
  • linha 10: os tipos de documento aceitos pelo cliente — neste caso, todos;
  • Linhas 12–16: os cabeçalhos da resposta, que também terminam com uma linha em branco;
  • linha 12: a linha de status, com a sintaxe [version code message]. O código 200 indica que o documento solicitado foi encontrado;
  • linha 13: o tamanho do documento em bytes. Isso informa ao cliente onde o documento termina;
  • linha 14: o tipo do documento (um documento HTML) e sua codificação (UTF-8);
  • linha 15: a data e a hora do servidor, sempre em Tempo Universal Coordenado (GMT);
  • linha 16: o software que fornece o serviço web, neste caso o Kestrel, o servidor web do ASP.NET Core. No curso de 2008, era um servidor Apache 1.3 com PHP 4;
  • linhas 18–22: o documento enviado pelo servidor;
  • linha 23: no HTTP/1.1, a conexão permanece aberta por padrão após a resposta (modo “keep-alive”) para que outras requisições possam ser atendidas; o [curl] a deixa aberta e a fecha ao terminar.

Vamos agora solicitar um documento que não existe:

> curl -v http://localhost:27110/unknown
* Host localhost:27110 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying 127.0.0.1:27110...
* Connected to localhost (127.0.0.1) port 27110
> GET /unknown HTTP/1.1
> Host: localhost:27110
> User-Agent: curl/8.5.0
> Accept: */*
> 
< HTTP/1.1 404 Not Found
< Content-Length: 0
< Date: Sat, 03 Oct 2026 09:48:36 GMT
< Server: Kestrel
< 
* Connection #0 to host localhost left intact
  • linha 7: solicitamos um documento inexistente;
  • linha 12: o servidor respondeu com o código de status 404, o que significa que o documento solicitado não foi encontrado;
  • linha 13: o documento enviado está vazio. Por padrão, o Kestrel não anexa nenhum documento a uma resposta 404; o servidor Apache consultado em 2008 enviava uma pequena página HTML explicativa. Um navegador que recebe uma resposta 404 sem documento exibe sua própria página de erro.

Os códigos de status se dividem em cinco categorias: 1xx (informação), 2xx (sucesso, 200 OK), 3xx (redirecionamento, 301 e 302, que veremos adiante), 4xx (erro do cliente: 404 Not Found, 401 Unauthorized, 403 Forbidden…), 5xx (erro do servidor: 500 Internal Server Error…).

O navegador faz a mesma coisa que o [curl]: envia uma requisição HTTP, recebe os cabeçalhos e o documento e depois exibe o documento. As ferramentas de desenvolvedor do navegador (tecla F12, aba Rede) permitem visualizar os cabeçalhos trocados.

Algumas observações sobre o estado atual do HTTP:

  • O HTTPS é hoje o padrão: os navegadores sinalizam como “não seguro” um site que usa HTTP simples. Com o HTTPS, uma negociação TLS precede o diálogo HTTP, e tudo o que vem depois é criptografado. Já não é, portanto, possível se comunicar “manualmente” com um servidor HTTPS usando um simples cliente TCP. Ainda é possível, porém, observar o diálogo com o [curl], que realiza o handshake TLS e depois exibe os cabeçalhos em texto puro. A título meramente ilustrativo (não reproduzimos o resultado, pois nossa máquina de teste não tem acesso à Internet), o comando seria [curl -v https://learn.microsoft.com/];
  • O HTTP/1.1 (hoje RFC 9112) é um protocolo textual, o que estamos estudando. O HTTP/2 (2015, hoje RFC 9113) mantém os mesmos métodos, cabeçalhos e códigos de status, mas os transmite em um formato binário comprimido e envia várias requisições simultaneamente por uma única conexão TCP. O HTTP/3 (2022, RFC 9114) faz o mesmo sobre o QUIC e, portanto, sobre o UDP. Navegadores e servidores escolhem automaticamente a versão mais recente que têm em comum; o [curl], sem nenhuma opção específica, usa o HTTP/1.1 para uma URL [http://].

12.4.4. O protocolo SMTP (Simple Mail Transfer Protocol)

Os servidores SMTP trocam e-mails entre si na porta 25. Um cliente de e-mail que envia uma mensagem a submete ao servidor SMTP de seu provedor na porta 587 (submissão, com passagem para o modo criptografado pelo comando [STARTTLS]) ou 465 (conexão criptografada desde o início), após se autenticar. Os provedores de acesso à Internet geralmente bloqueiam as conexões de saída para a porta 25 dos roteadores de seus assinantes, para limitar o spam enviado por máquinas infectadas: o diálogo sem criptografia mostrado no curso de 2008 não é mais viável a partir de um computador pessoal.

Eis, a título ilustrativo, um diálogo SMTP típico, conforme a RFC 5321. Não se trata de uma execução real: as linhas prefixadas por [C:] são enviadas pelo cliente, as prefixadas por [S:] pelo servidor, e os domínios [example.org] e [example.com] são reservados para exemplos:

S: 220 mail.example.com ESMTP ready
C: EHLO pc.example.org
S: 250-mail.example.com
S: 250-SIZE 10240000
S: 250-STARTTLS
S: 250 8BITMIME
C: MAIL FROM:<alice@example.org>
S: 250 2.1.0 Ok
C: RCPT TO:<bob@example.com>
S: 250 2.1.5 Ok
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: From: alice@example.org
C: To: bob@example.com
C: Subject: test
C:
C: line1
C: line2
C: .
S: 250 2.0.0 Ok: queued as 4F2A81C0
C: QUIT
S: 221 2.0.0 Bye
  • Linha 1: mensagem de boas-vindas do servidor. Cada resposta do servidor começa com um código de três dígitos: 2xx indica sucesso, 3xx significa “prossiga” e 4xx e 5xx indicam um erro;
  • linha 2: o cliente se identifica. O comando [EHLO] substituiu o comando [HELO] do curso de 2008: ele pede ao servidor a lista das extensões que suporta;
  • Linhas 3–6: a resposta do servidor, em várias linhas. O hífen que segue o código indica que a resposta continua; a última linha tem um espaço no lugar dele. Aqui, o servidor declara que aceita mensagens de até 10 MB, que suporta o modo criptografado e que aceita caracteres de 8 bits;
  • linha 7: o endereço do remetente;
  • linha 9: o endereço do destinatário (o comando pode ser repetido para vários destinatários);
  • linha 11: o cliente anuncia a mensagem;
  • linha 12: o servidor convida o cliente a enviar a mensagem e lembra como terminá-la;
  • linhas 13–19: a mensagem, composta por cabeçalhos ([From], [To], [Subject]…), uma linha em branco e o corpo, e terminando com uma linha contendo apenas um ponto;
  • linha 20: o servidor aceitou a mensagem e a colocou em sua fila;
  • linhas 21–22: o cliente sinaliza que terminou; o servidor fecha a conexão.

12.4.5. O protocolo POP (Post Office Protocol)

Os servidores POP3 funcionam na porta 110 ou, para uma conexão criptografada com TLS, na porta 995 — a única opção oferecida atualmente pela maioria dos provedores, já que a senha é transmitida durante o diálogo. Eis um diálogo POP3 típico, conforme a RFC 1939, apresentado com as mesmas convenções do anterior:

S: +OK POP3 server ready
C: USER bob
S: +OK
C: PASS ********
S: +OK Logged in.
C: LIST
S: +OK 2 messages:
S: 1 1205
S: 2 1916
S: .
C: RETR 2
S: +OK 1916 octets
S: Return-Path: <alice@example.org>
S: Delivered-To: bob@example.com
S: ...
S: Date: Sat, 03 Oct 2026 10:59:25 +0200
S: From: alice@example.org
S: To: bob@example.com
S: Subject: test
S:
S: line1
S: line2
S: .
C: QUIT
S: +OK Logging out.
  • Linha 1: mensagem de boas-vindas do servidor. As respostas do POP3 começam com [+OK] (sucesso) ou [-ERR] (erro);
  • linha 2: o cliente fornece seu nome de usuário, isto é, o nome com que lê seus e-mails;
  • linha 4: a senha do cliente (ocultada aqui);
  • linha 6: o cliente solicita a lista de seus e-mails;
  • linhas 7–10: a lista das mensagens da caixa de correio do cliente, no formato [message number, size in bytes], terminando com uma linha contendo apenas um ponto;
  • linha 11: a mensagem nº 2 é solicitada;
  • linhas 12–23: a mensagem nº 2, com seus cabeçalhos, uma linha em branco e seu corpo, que também termina com um ponto;
  • linhas 24–25: o cliente indica que terminou; o servidor fecha a conexão.

O POP3 foi concebido para baixar e-mails para o computador do usuário. Hoje ele enfrenta forte concorrência do IMAP (porta 143, ou 993 com TLS; RFC 9051), que deixa as mensagens no servidor e permite consultá-las e organizá-las a partir de vários dispositivos, bem como por meio de clientes de e-mail baseados na web.

12.4.6. O protocolo FTP (File Transfer Protocol)

O protocolo FTP (RFC 959) é mais complexo que os descritos anteriormente: o diálogo (comandos e suas respostas) ocorre em uma conexão de controle aberta na porta 21 do servidor, e cada transferência de arquivo ou de lista de arquivos usa uma segunda conexão, aberta especificamente para esse fim. Eis um diálogo típico pela conexão de controle:

S: 220 FTP service ready
C: USER anonymous
S: 331 Please specify the password.
C: PASS guest@example.org
S: 230 Login successful.
C: PWD
S: 257 "/" is the current directory
C: EPSV
S: 229 Entering Extended Passive Mode (|||40312|)
C: RETR readme.txt
S: 150 Opening BINARY mode data connection for readme.txt (1250 bytes).
S: 226 Transfer complete.
C: QUIT
S: 221 Goodbye.
  • linha 2: conexão anônima, como a oferecida por servidores públicos de download;
  • linha 8: o cliente pede ao servidor que abra uma porta para a conexão de dados. O servidor responde (linha 9) que aguarda essa conexão na porta 40312;
  • linha 10: o cliente solicita o arquivo [readme.txt]. O arquivo chega pela conexão de dados, e a conexão de controle recebe as respostas 150 (início da transferência) e 226 (fim da transferência).

O curso de 2008 recomendava acompanhar esses comandos no log do cliente FileZilla, o que continua possível. No entanto, o FTP está se tornando obsoleto: ele transmite as senhas em texto puro, tem dificuldade para funcionar com firewalls por causa da segunda conexão, e os navegadores deixaram de suportá-lo desde 2021 (Chrome 88, Firefox 90). É preferível usar o SFTP, transferência de arquivos via SSH, e o simples download via HTTPS.

12.5. As classes do .NET na programação web

12.5.1. Escolha da classe adequada

O .NET oferece diversas classes para trabalhar com a rede:

Image

  • A classe [Socket] opera mais perto da rede. Ela permite um gerenciamento fino da conexão de rede. O termo inglês “socket” designa uma tomada elétrica; seu sentido foi estendido para designar um soquete de rede de software. Em uma comunicação TCP/IP entre duas máquinas, A e B, dois sockets se comunicam entre si. Uma aplicação pode trabalhar diretamente com os sockets: é o caso da aplicação A acima. Um socket pode ser de cliente ou de servidor;
  • se você deseja trabalhar em um nível mais alto que o da classe [Socket], pode usar a classe [TcpClient] para criar um cliente (TCP) e a classe [TcpListener] para criar um servidor (TCP) (aplicação B acima). Essas duas classes oferecem à aplicação uma visão mais simples da comunicação de rede, cuidando por ela dos detalhes técnicos dos sockets. A classe [UdpClient] cumpre o mesmo papel para o UDP;
  • O .NET também oferece classes especializadas em um protocolo específico. A mais importante hoje é [HttpClient] (aplicação C acima), que gerencia o protocolo HTTP nas versões 1.1, 2 e 3, incluindo a criptografia TLS do HTTPS. O curso de 2008 abordava as classes [WebClient] e [WebRequest], hoje obsoletas e substituídas por [HttpClient] (voltaremos a isso na segunda parte deste capítulo), bem como a classe [SmtpClient] para o envio de e-mails, que não foi declarada obsoleta, mas não é mais recomendada pela Microsoft para novos desenvolvimentos.

Vale notar que a classe [Socket] basta por si só para tratar toda a comunicação TCP/IP, mas buscaremos usar principalmente as classes de mais alto nível para simplificar o desenvolvimento das aplicações.

12.5.2. A classe TcpClient

A classe [TcpClient] (namespace [System.Net.Sockets]) é a classe adequada na maioria dos casos para criar um cliente de um serviço TCP. Entre seus construtores C, métodos M e propriedades P, ela tem os seguintes:

Membro
Tipo
Função
TcpClient()
C
cria um cliente que ainda não está conectado
Task ConnectAsync(string machine, int port), ValueTask ConnectAsync(string machine, int port, CancellationToken token)
M
estabelece (de forma assíncrona) uma conexão TCP com o serviço que roda na porta [port] da máquina [machine]. Por exemplo, [await client.ConnectAsync("localhost", 27110)]. Há sobrecargas que aceitam um [IPAddress] ou um [IPEndPoint]. Lança uma [SocketException] se a conexão falhar
NetworkStream GetStream()
M
obtém um fluxo de leitura e escrita com o servidor. Esse fluxo permite a comunicação cliente-servidor
Socket Client
P
O socket usado pelo cliente para se comunicar com o servidor. Suas propriedades [LocalEndPoint] e [RemoteEndPoint] representam as duas extremidades da conexão
bool Connected
P
true se a conexão foi estabelecida (e não foi fechada pelo cliente)
void Close(), void Dispose()
M
Fecha a conexão. O socket e o fluxo [NetworkStream] também são fechados

O curso de 2008 usava o construtor [TcpClient(string machine, int port)], que se conecta de forma bloqueante: a thread que o executa fica bloqueada durante todo o estabelecimento da conexão, que pode levar várias dezenas de segundos se a máquina remota não responder. Usaremos [ConnectAsync].

A classe [NetworkStream] representa o fluxo de rede entre o cliente e o servidor. Ela deriva da classe [Stream] e, portanto, oferece os métodos [ReadAsync] e [WriteAsync] , que leem e escrevem bytes. Muitas aplicações cliente-servidor trocam linhas de texto. Por isso, é útil usar os objetos [StreamReader] e [StreamWriter] , apresentados no capítulo sobre arquivos, para ler e escrever essas linhas no fluxo de rede:

1
2
3
NetworkStream stream = client.GetStream();
var reader = new StreamReader(stream);
var writer = new StreamWriter(stream) { AutoFlush = true };

A propriedade [AutoFlush = true] significa que cada escrita em [writer] é imediatamente transmitida pela rede, sem esperar que o buffer interno do [StreamWriter] se encha. Esse é um ponto importante. Em geral, quando um cliente envia uma linha de texto a seu parceiro, espera uma resposta. Essa resposta jamais chegará se a linha permanecer no buffer da máquina emissora sem ser enviada. Sem [AutoFlush], é preciso chamar explicitamente [FlushAsync] depois de escrever uma requisição completa.

Para enviar uma linha de texto ao servidor, escreva:

await writer.WriteLineAsync("some text");

e para ler a resposta do servidor:

        string? response = await reader.ReadLineAsync();

[ReadLineAsync] devolve [null] quando o parceiro fechou a conexão e tudo o que ele enviou foi lido: isso marca o fim do fluxo.

Um ponto merece atenção: o caractere de fim de linha. [WriteLineAsync] termina a linha com o valor da propriedade [NewLine] de [StreamWriter], que por padrão é [Environment.NewLine], isto é, \r\n no Windows, mas apenas \n no Linux e no macOS. Os protocolos da Internet (HTTP, SMTP, POP, FTP) exigem \r\n. Alguns servidores, como o Kestrel, toleram um único \n, enquanto outros não; portanto, um programa portável que use um desses protocolos deve definir [NewLine = "\r\n"]. Na leitura, [ReadLineAsync] aceita tanto \r\n quanto \n.

Já temos os elementos para escrever a arquitetura básica de um cliente TCP com o seguinte protocolo básico de comunicação com o servidor:

  • o cliente envia uma requisição contida em uma única linha;
  • o servidor envia uma resposta contida em uma única linha.
try
{
    // conexão com o serviço
    using var client = new TcpClient();
    await client.ConnectAsync(server, port);
    // fluxo de rede, fluxos de leitura e de escrita
    await using NetworkStream stream = client.GetStream();
    using var reader = new StreamReader(stream);
    await using var writer = new StreamWriter(stream) { AutoFlush = true };
    // laço requisição - resposta
    while (true)
    {
        // preparação da requisição
        string request = ...;
        // envio da requisição ao servidor
        await writer.WriteLineAsync(request);
        // leitura da resposta do servidor
        string? response = await reader.ReadLineAsync();
        // processamento da resposta
        ...
    }
}
catch (SocketException ex)
{
    // conexão impossível
    ...
}
catch (IOException ex)
{
    // erro durante as trocas
    ...
}
  • Linha 4: criação do cliente. A declaração [using] (C# 8) garante que a conexão será fechada ao sair do bloco que a contém, aconteça o que acontecer. O curso de 2008 aninhava quatro instruções [using (...) { ... }]; as declarações [using] evitam esse aninhamento;
  • linha 5: conexão assíncrona ao serviço;
  • Linha 7: obtenção do fluxo de rede. [await using] (C# 8) libera o objeto chamando seu método [DisposeAsync], a versão assíncrona de [Dispose]: liberar um [StreamWriter] pode, de fato, disparar uma última escrita na rede;
  • linhas 8–9: criação dos fluxos de leitura e escrita sobre o fluxo de rede;
  • linhas 11–19: o ciclo requisição do cliente/resposta do servidor;
  • linha 16: o cliente envia sua requisição ao servidor;
  • linha 18: o cliente aguarda a resposta do servidor. Essa espera termina quando chega uma linha terminada por \n ou quando o fluxo termina, caso o servidor feche a conexão. Durante a espera, nenhuma thread fica bloqueada;
  • linhas 23–28: uma [SocketException] indica uma conexão que falhou (máquina desconhecida, nenhum serviço na porta solicitada etc.), enquanto uma [IOException] indica um erro durante a comunicação (conexão perdida etc.).

12.5.3. A classe TcpListener

A classe [TcpListener] é a classe adequada na maioria dos casos para criar um serviço TCP. Entre seus construtores C, métodos M e propriedades P, ela tem os seguintes:

Membro
Tipo
Função
TcpListener(IPAddress address, int port)
C
cria um serviço TCP que escutará os pedidos dos clientes na porta [port] — chamada porta de escuta — no endereço [address]. Com [IPAddress.Any], o serviço escuta em todos os endereços IPv4 da máquina; com [IPAddress.Loopback], escuta apenas no endereço de loopback
static TcpListener Create(int port)
M
cria um serviço que escuta tanto em IPv4 quanto em IPv6, em todos os endereços da máquina
void Start()
M
inicia a escuta dos pedidos dos clientes
Task<TcpClient> AcceptTcpClientAsync(), ValueTask<TcpClient> AcceptTcpClientAsync(CancellationToken token)
M
aguarda (de forma assíncrona) um pedido de cliente e o aceita. Devolve o objeto [TcpClient] associado, no lado do servidor, à conexão de serviço aberta com esse cliente
void Stop()
M
interrompe a escuta dos pedidos dos clientes
EndPoint LocalEndpoint
P
endereço e porta de escuta
Socket Server
P
o socket de escuta do servidor

O construtor [TcpListener(int port)] usado no curso de 2008 foi declarado obsoleto: é preciso especificar o endereço de escuta ou usar [TcpListener.Create].

A estrutura básica de um servidor TCP que se comunica com seus clientes usando o protocolo “uma linha de requisição, uma linha de resposta” pode ser esta:

// o serviço de escuta, em todas as interfaces de rede da máquina
var listener = new TcpListener(IPAddress.Any, port);
listener.Start();
// laço de espera dos clientes
while (true)
{
    // espera por um cliente
    TcpClient client = await listener.AcceptTcpClientAsync();
    // o cliente é atendido por outra tarefa, que não aguardamos
    _ = ServeAsync(client);
    // próximo cliente
}

// o serviço prestado a um cliente
static async Task ServeAsync(TcpClient client)
{
    try
    {
        using (client)
        {
            await using NetworkStream stream = client.GetStream();
            using var reader = new StreamReader(stream);
            await using var writer = new StreamWriter(stream) { AutoFlush = true };
            // laço de leitura da requisição / escrita da resposta
            while (await reader.ReadLineAsync() is string request)
            {
                // preparação da resposta
                string response = ...;
                // envio da resposta ao cliente
                await writer.WriteLineAsync(response);
            }
        }
    }
    catch (IOException ex)
    {
        // erro
        ...
    }
}
  • Linha 2: o serviço de escuta é criado para uma porta e um endereço IP determinados. Uma máquina tem pelo menos dois endereços IP: o endereço de loopback 127.0.0.1 e o endereço que ela tem na rede à qual está conectada. Pode ter outros se estiver conectada a várias redes. [IPAddress.Any] designa todos os endereços IPv4 da máquina;
  • linha 3: o serviço de escuta é iniciado. Ele havia sido criado antes, mas ainda não escutava. Escutar significa aguardar os pedidos de conexão dos clientes;
  • Linhas 5–11: o laço de espera de um cliente e de início de seu atendimento, repetido para cada novo cliente;
  • linha 8: o pedido de um cliente é aceito. [AcceptTcpClientAsync] devolve uma instância de serviço chamada [TcpClient]:
    • o cliente fez seu pedido usando sua própria instância, [TcpClient], que chamaremos de [TcpClientRequest];
    • o servidor aceita esse pedido com [AcceptTcpClientAsync], que cria uma instância [TcpClient] do lado do servidor, que chamaremos de [TcpClientService]. Temos então uma conexão TCP aberta, com as instâncias [TcpClientRequest] ↔ [TcpClientService] em cada extremidade;
    • a comunicação cliente/servidor que ocorre em seguida se dá por essa conexão. O serviço de escuta não participa mais dela;
  • Linha 10: para permitir que o servidor atenda vários clientes ao mesmo tempo, o serviço é prestado por uma tarefa assíncrona. O servidor não a aguarda (sem [await]); volta imediatamente a esperar o próximo cliente. A tarefa devolvida por [ServeAsync] é atribuída à variável de descarte [_], o que indica ao leitor (e ao compilador) que seu resultado é ignorado intencionalmente;
  • linha 15: o método que atende um cliente. Ele recebe como parâmetro a instância [TcpClient], que já está conectada ao cliente a ser atendido;
  • linha 25: aqui vemos um código semelhante ao do cliente TCP básico visto anteriormente. O laço para quando [ReadLineAsync] devolve [null], isto é, quando o cliente fechou a conexão. O padrão [is string request] verifica que o valor lido não é [null] e o atribui à variável [request];
  • linha 34: as exceções devem ser capturadas em [ServeAsync]: como ninguém aguarda a tarefa, uma exceção não capturada passaria despercebida.

12.5.4. Uma thread por cliente ou uma tarefa por cliente?

O servidor do curso de 2008 atribuía cada cliente a uma thread do pool ([ThreadPool.QueueUserWorkItem]), que realizava leituras e escritas bloqueantes: enquanto o cliente “pensava”, sua thread permanecia bloqueada em [ReadLine]. Cada thread consome memória (uma pilha reservada de cerca de 1 MB) e tempo de processador, pois o sistema precisa alternar entre elas. Com algumas dezenas de clientes, isso não é problema; com milhares de conexões simultâneas — cenário comum para um servidor real —, o servidor entra em colapso. Na verdade, o curso limitava o pool a 10 threads: o décimo primeiro cliente precisava esperar que um dos dez primeiros se desconectasse.

Com métodos assíncronos ([AcceptTcpClientAsync], [ReadLineAsync], [WriteLineAsync]), um cliente que não envia nada não consome nenhuma thread: sua tarefa fica suspensa e somente quando chegam dados o restante dela é executado por uma das threads do pool. Poucas threads bastam, portanto, para atender milhares de clientes. É assim que funcionam os servidores modernos, em particular o Kestrel, o servidor web do ASP.NET Core. Os princípios vistos no capítulo sobre programação assíncrona se aplicam integralmente aqui: [async] / [await] do início ao fim e um [CancellationToken] para encerrar de forma limpa as operações em andamento.

12.6. Exemplos de clientes e servidores TCP

Os programas desta seção são aplicações de arquivo único da pasta [12-internet]. Os servidores e os clientes são iniciados em janelas de comando separadas, na mesma máquina; as portas usadas têm a forma 271xx.

12.6.1. Um servidor de eco

Vamos escrever um servidor de eco, que será iniciado em uma janela de comando por meio de:

dotnet run internet-04.cs -- port

O servidor funciona na porta passada como argumento. Ele simplesmente devolve ao cliente cada linha que este lhe envia, entre colchetes. O programa [internet-04.cs] é o seguinte:

using System.Net;
using System.Net.Sockets;

// servidor de eco: devolve a cada cliente as linhas que ele envia
// chamada: dotnet run internet-04.cs -- port

const string syntax = "Syntax: dotnet run internet-04.cs -- port";
// é necessário um argumento: uma porta entre 1 e 65535
if (args.Length != 1 || !int.TryParse(args[0], out int port) || port is < 1 or > 65535)
{
    Console.WriteLine(syntax);
    return;
}

// Ctrl-C cancela o token: o servidor para de forma limpa
using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) =>
{
    // impedimos o encerramento abrupto do processo
    e.Cancel = true;
    cancellation.Cancel();
};

// o serviço de escuta, em todas as interfaces de rede da máquina
var listener = new TcpListener(IPAddress.Any, port);
// as tarefas de serviço em andamento
var services = new List<Task>();
int clientNumber = 0;
try
{
    // iniciamos o servidor
    listener.Start();
    Console.WriteLine($"Echo server started on {listener.LocalEndpoint}");
    // laço de espera dos clientes - interrompido por Ctrl-C
    while (true)
    {
        // espera (assíncrona) por um cliente
        TcpClient client = await listener.AcceptTcpClientAsync(cancellation.Token);
        // o cliente é atendido por uma tarefa que não aguardamos aqui
        services.Add(ServeAsync(client, clientNumber++, cancellation.Token));
        // esquecemos as tarefas concluídas
        services.RemoveAll(service => service.IsCompleted);
    }
}
catch (OperationCanceledException)
{
    Console.WriteLine("Server stop requested");
}
catch (SocketException ex)
{
    Console.WriteLine($"The following error occurred on the server: {ex.SocketErrorCode} ({ex.Message})");
}
finally
{
    // fim da escuta
    listener.Stop();
}
// esperamos o fim dos serviços em andamento antes de sair
await Task.WhenAll(services);

// --------------------------------------------------------------------
// o serviço prestado a um cliente
static async Task ServeAsync(TcpClient client, int clientNumber, CancellationToken token)
{
    Console.WriteLine($"Start of service to client {clientNumber} ({client.Client.RemoteEndPoint})");
    try
    {
        // a conexão e o fluxo de rede são liberados ao sair do bloco
        using (client)
        {
            await using NetworkStream stream = client.GetStream();
            using var reader = new StreamReader(stream);
            await using var writer = new StreamWriter(stream) { AutoFlush = true };
            // laço de leitura da requisição / escrita da resposta
            // ReadLineAsync retorna null quando o cliente fecha a conexão
            while (await reader.ReadLineAsync(token) is string request)
            {
                Console.WriteLine($"<--- client {clientNumber} : {request}");
                // eco da requisição ao cliente, entre colchetes
                await writer.WriteLineAsync($"[{request}]");
                Console.WriteLine($"---> client {clientNumber} : [{request}]");
            }
        }
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine($"Service to client {clientNumber} interrupted by the server stop");
    }
    catch (IOException ex)
    {
        Console.WriteLine($"The following error occurred while serving client {clientNumber}: {ex.Message}");
    }
    finally
    {
        Console.WriteLine($"End of service to client {clientNumber}");
    }
}

A estrutura do servidor de eco segue a arquitetura básica dos servidores TCP descrita anteriormente, com alguns acréscimos:

  • linha 9: a porta deve ser um inteiro entre 1 e 65.535. O padrão relacional combinado [is < 1 or > 65535] (C# 9) expressa essa condição de forma concisa;
  • Linhas 16–21: encerramento do servidor. O servidor de 2008 era encerrado abruptamente por Ctrl-C: o processo terminava sem fechar as conexões. Aqui, o evento [Console.CancelKeyPress] é disparado por Ctrl-C. Seu manipulador impede que o processo termine imediatamente (linha 20) e cancela o token [cancellation] (linha 21);
  • linha 38: a espera por um cliente recebe o token de cancelamento. Quando o token é cancelado, a espera termina com uma [OperationCanceledException], que é interceptada na linha 45;
  • linhas 40–42: cada cliente é atendido por uma tarefa que o laço não aguarda. Essas tarefas são mantidas em uma lista, da qual as tarefas concluídas são removidas à medida que terminam;
  • linha 56: fim da escuta, executado em todos os casos por meio do [finally];
  • linha 59: antes de sair, aguardamos o término dos atendimentos em andamento. Como eles receberam o mesmo token de cancelamento, terminam rapidamente.

A parte “atendimento do cliente”:

  • linha 65: o endereço e a porta do cliente;
  • linha 76: a requisição do cliente é lida. O token de cancelamento interrompe a espera se o servidor for encerrado. [ReadLineAsync] devolve [null] quando o cliente fecha a conexão: o laço e o atendimento então terminam;
  • linha 80: a requisição é devolvida ao cliente, entre colchetes;
  • linhas 85–89: tratam-se o encerramento do servidor e uma conexão terminada pelo cliente;
  • linha 95: [finally] sinaliza o fim do atendimento, qualquer que seja a causa.

Para ver o servidor em ação, precisamos de um cliente. O curso de 2008 usava o PuTTY; vamos escrever nosso próprio cliente na próxima seção e apresentar os resultados depois.

12.6.2. Um cliente para o servidor de eco

Vamos agora escrever um cliente para o servidor anterior. Ele será chamado assim:

dotnet run internet-05.cs -- machine port

Ele se conecta à máquina [machine] na porta [port]e depois envia ao servidor o texto digitado no teclado, que o devolve como eco. O programa [internet-05.cs] é o seguinte:

using System.Net.Sockets;

// cliente de eco: envia ao servidor as linhas digitadas no teclado
// e exibe as respostas do servidor
// chamada: dotnet run internet-05.cs -- machine port

const string syntax = "Syntax: dotnet run internet-05.cs -- machine port";
if (args.Length != 2 || !int.TryParse(args[1], out int port) || port is < 1 or > 65535)
{
    Console.WriteLine(syntax);
    return;
}
string server = args[0];

try
{
    // conexão (assíncrona) com o serviço
    using var client = new TcpClient();
    await client.ConnectAsync(server, port);
    Console.WriteLine($"Connected to the server {client.Client.RemoteEndPoint} from {client.Client.LocalEndPoint}");
    // fluxos de leitura e de escrita na conexão
    await using NetworkStream stream = client.GetStream();
    using var reader = new StreamReader(stream);
    // AutoFlush: cada linha escrita sai imediatamente para a rede
    await using var writer = new StreamWriter(stream) { AutoFlush = true };
    // laço requisição - resposta
    while (true)
    {
        // a requisição vem do teclado
        Console.Write("Request (bye to stop): ");
        string? request = Console.ReadLine();
        // terminou?
        if (request is null || request.Trim().Equals("bye", StringComparison.OrdinalIgnoreCase))
        {
            break;
        }
        // enviamos a requisição ao servidor
        await writer.WriteLineAsync(request);
        // esperamos sua resposta
        string? response = await reader.ReadLineAsync();
        if (response is null)
        {
            Console.WriteLine("The server has closed the connection");
            break;
        }
        Console.WriteLine($"Response: {response}");
    }
}
catch (SocketException ex)
{
    Console.WriteLine($"The following error occurred: {ex.SocketErrorCode} ({ex.Message})");
}
catch (IOException ex)
{
    Console.WriteLine($"The following error occurred: {ex.Message}");
}

A estrutura desse cliente segue a arquitetura básica proposta para clientes TCP:

  • linha 19: conexão assíncrona ao servidor;
  • linha 20: as duas extremidades da conexão são exibidas: [RemoteEndPoint] (o servidor) e [LocalEndPoint] (o cliente). A porta do cliente foi escolhida pelo sistema;
  • linha 25: cada linha escrita é enviada imediatamente;
  • linha 31: a requisição é digitada no teclado. [Console.ReadLine] devolve [null] se a entrada padrão estiver fechada (Ctrl-D no Linux, Ctrl-Z seguido de Enter no Windows);
  • linha 33: a comparação com [bye] não diferencia maiúsculas de minúsculas;
  • linha 38: a requisição é enviada ao servidor;
  • linhas 40–43: a resposta é aguardada; [null] indica que o servidor fechou a conexão;
  • linhas 49–53: erros de conexão e de troca de dados.

Eis os resultados obtidos com a seguinte configuração:

  • o servidor está em execução na porta 27100, em uma janela de comando;
  • na mesma máquina, dois clientes, A e B, estão em execução em duas outras janelas; o cliente B foi iniciado enquanto o cliente A ainda se comunicava com o servidor.

Na janela do cliente A:

1
2
3
4
5
6
7
8
9
> dotnet run internet-05.cs -- localhost 27100
Connected to the server 127.0.0.1:27100 from 127.0.0.1:41404
Request (bye to stop): line1A
Response: [line1A]
Request (bye to stop): line2A
Response: [line2A]
Request (bye to stop): line3A
Response: [line3A]
Request (bye to stop): bye

O cliente A enviou três linhas, que foram devolvidas como eco, e depois digitou [bye]: ele fechou a conexão sem enviar nada ao servidor.

Na janela do cliente B:

1
2
3
4
5
6
7
8
> dotnet run internet-05.cs -- localhost 27100
Connected to the server 127.0.0.1:27100 from 127.0.0.1:47282
Request (bye to stop): line1B
Response: [line1B]
Request (bye to stop): line2B
Response: [line2B]
Request (bye to stop): line3B
The server has closed the connection

O cliente B enviou duas linhas e, antes de digitar a terceira, o servidor foi encerrado com Ctrl-C. A linha [line3B] foi enviada por uma conexão que já havia sido fechada pelo servidor: a leitura da resposta (linha 8) devolveu [null].

Na janela do servidor:

> dotnet run internet-04.cs -- 27100
Echo server started on 0.0.0.0:27100
Start of service to client 0 (127.0.0.1:41404)
<--- client 0 : line1A
---> client 0 : [line1A]
Start of service to client 1 (127.0.0.1:47282)
<--- client 0 : line2A
---> client 0 : [line2A]
<--- client 0 : line3A
---> client 0 : [line3A]
End of service to client 0
<--- client 1 : line1B
---> client 1 : [line1B]
<--- client 1 : line2B
---> client 1 : [line2B]
Server stop requested
Service to client 1 interrupted by the server stop
End of service to client 1
  • Linha 2: o servidor escuta na porta 27100 em todos os endereços IPv4 da máquina (0.0.0.0);
  • linhas 3–6: os dois clientes chegaram da mesma máquina (127.0.0.1) usando portas diferentes, escolhidas pelo sistema. Essas portas distinguem as duas conexões, que terminam ambas na porta 27100 do servidor;
  • Linha 6: o cliente 1 (B) está sendo atendido enquanto o cliente 0 (A) ainda está sendo atendido: o servidor de fato atende vários clientes simultaneamente;
  • Linha 11: o servidor detectou que o cliente A fechou a conexão;
  • linhas 16–18: Ctrl-C foi pressionado na janela do servidor. A espera por um novo cliente foi cancelada e, em seguida, o atendimento do cliente 1 — que aguardava uma linha — foi interrompido pelo mesmo token de cancelamento. O servidor foi encerrado de forma limpa.

Por fim, eis o que acontece quando se tenta conectar a uma porta na qual nenhum serviço escuta:

> dotnet run internet-05.cs -- localhost 27199
The following error occurred: ConnectionRefused (Connection refused)

[ConnectAsync] lançou uma [SocketException] com o código [ConnectionRefused]: a máquina respondeu, mas nenhum programa escuta na porta 27199. A mensagem vem do sistema operacional; ela é diferente no Windows.

12.6.3. Um cliente TCP genérico

Vamos escrever um cliente TCP genérico, que será iniciado da seguinte forma:

dotnet run internet-06.cs -- machine port

Ele funcionará de modo semelhante aos clientes [telnet] e PuTTY: permitirá a comunicação com qualquer servidor TCP baseado em texto.

Na aplicação anterior, o protocolo de comunicação era conhecido: o cliente enviava uma única linha e o servidor respondia com uma única linha. Cada serviço tem seu protocolo específico, e também podem surgir as seguintes situações:

  • o cliente deve enviar várias linhas de texto antes de receber uma resposta (uma requisição HTTP);
  • a resposta de um servidor pode consistir em várias linhas de texto (a resposta [EHLO] de um servidor SMTP, um documento HTML);
  • o servidor pode falar primeiro (a mensagem de boas-vindas dos servidores SMTP e POP).

O ciclo “enviar uma única linha ao servidor / receber uma única linha enviada pelo servidor” nem sempre é adequado. Para tratar protocolos mais complexos que o protocolo de eco, o cliente TCP genérico executa duas tarefas em paralelo:

  • o programa principal lê as linhas de texto digitadas no teclado e as envia ao servidor;
  • uma tarefa separada é dedicada à leitura das linhas de texto enviadas pelo servidor. Assim que recebe uma, ela a exibe no console. Só para quando a conexão é fechada.

O curso de 2008 atribuía a tarefa de ler as respostas do servidor a uma thread do pool. O programa [internet-06.cs] é o seguinte:

using System.Net.Sockets;

// cliente TCP genérico
// - conecta-se ao serviço (machine, port)
// - envia ao servidor cada linha digitada no teclado
// - uma tarefa separada exibe continuamente as linhas enviadas pelo servidor
// chamada: dotnet run internet-06.cs -- machine port

const string syntax = "Syntax: dotnet run internet-06.cs -- machine port";
if (args.Length != 2 || !int.TryParse(args[1], out int port) || port is < 1 or > 65535)
{
    Console.WriteLine(syntax);
    return;
}
string server = args[0];

// conexão com o serviço
using var client = new TcpClient();
try
{
    await client.ConnectAsync(server, port);
}
catch (SocketException ex)
{
    Console.WriteLine($"Unable to connect to the service ({server}, {port}): {ex.Message}");
    return;
}

NetworkStream stream = client.GetStream();
// as linhas enviadas terminam com \r\n, como exigem HTTP, SMTP, POP, FTP...
var writer = new StreamWriter(stream) { AutoFlush = true, NewLine = "\r\n" };

// a leitura das linhas do servidor é entregue a uma tarefa que trabalha em paralelo
Task reception = ReceiveAsync(new StreamReader(stream));

// a leitura dos comandos do teclado é feita no programa principal
Console.WriteLine("Type your commands (bye to stop):");
try
{
    while (true)
    {
        // Console.ReadLine é bloqueante: nós o executamos em uma tarefa do pool
        Task<string?> input = Task.Run(Console.ReadLine);
        // esperamos ou por uma linha digitada no teclado, ou pelo fim da recepção
        if (await Task.WhenAny(input, reception) == reception)
        {
            // o servidor fechou a conexão: não adianta esperar pela entrada
            Console.WriteLine("[the server has closed the connection]");
            break;
        }
        string? command = await input;
        // terminou?
        if (command is null || command.Trim().Equals("bye", StringComparison.OrdinalIgnoreCase))
        {
            break;
        }
        // enviamos o comando ao servidor
        await writer.WriteLineAsync(command);
    }
}
catch (IOException ex)
{
    Console.WriteLine($"The following error occurred while writing: {ex.Message}");
}
// fechamos a conexão: a tarefa de recepção termina se ainda não tiver terminado
client.Close();
await reception;

// --------------------------------------------------------------------
// exibe as linhas enviadas pelo servidor até que a conexão seja fechada
static async Task ReceiveAsync(StreamReader reader)
{
    try
    {
        while (await reader.ReadLineAsync() is string response)
        {
            Console.WriteLine($"<-- {response}");
        }
    }
    catch (Exception ex) when (ex is IOException or ObjectDisposedException)
    {
        // a conexão foi fechada durante a leitura: a tarefa termina
    }
}
  • linha 21: o cliente se conecta ao servidor;
  • linha 31: as linhas enviadas terminam com \r\n, como exigem os protocolos que queremos explorar;
  • linha 34: a leitura das linhas enviadas pelo servidor é delegada ao método assíncrono [ReceiveAsync]. Não o aguardamos imediatamente: a tarefa [reception] é executada em paralelo com o programa principal;
  • Linhas 40–58: o laço de entrada pelo teclado e de envio de dados ao servidor;
  • linha 43: não existe entrada de teclado realmente assíncrona. Por isso, [Console.ReadLine], que é bloqueante, é executado em uma tarefa do pool;
  • linha 45: [Task.WhenAny] devolve a primeira das duas tarefas a terminar: a digitação de uma linha no teclado ou a recepção, que termina quando o servidor fecha a conexão. Neste último caso, não há necessidade de esperar que o usuário digite algo: sai-se do laço. O cliente de 2008, por outro lado, esperava que o usuário digitasse [bye];
  • linha 51: a linha digitada no teclado;
  • linha 58: ela é enviada ao servidor;
  • linhas 66–67: a conexão é fechada e, em seguida, o programa aguarda o término da tarefa de recepção, que por sua vez termina caso ainda estivesse lendo. Quando o programa termina, qualquer entrada de teclado em andamento é descartada;
  • linhas 71–82: o método executado pela tarefa de recepção. Ele exibe cada linha recebida, precedida de [<--], até o fim do fluxo. Se o cliente fechar a conexão enquanto a leitura está em andamento, a operação de leitura em curso termina com uma exceção, que é capturada: o filtro [when] (C# 6) captura apenas os dois tipos de exceção esperados.

Podemos agora enviar manualmente uma requisição HTTP ao nosso servidor web de teste, que está em execução em outra janela. As linhas precedidas por [<--] são as enviadas pelo servidor; as outras foram digitadas manualmente:

> dotnet run internet-06.cs -- localhost 27110
Type your commands (bye to stop):
GET /hello?name=Serge HTTP/1.1
Host: localhost:27110
Connection: close

<-- HTTP/1.1 200 OK
<-- Connection: close
<-- Content-Type: text/plain; charset=utf-8
<-- Date: Sat, 03 Oct 2026 09:49:07 GMT
<-- Server: Kestrel
<-- Transfer-Encoding: chunked
<-- 
<-- c
<-- Hello Serge!
<-- 0
<-- 
[the server has closed the connection]
  • linhas 3–5: a requisição, digitada no teclado: solicitamos o documento [/hello?name=Serge]. O cabeçalho [Connection: close] instrui o servidor a fechar a conexão depois de enviar sua resposta;
  • a linha em branco que se segue encerra a requisição. Ela dispara a resposta do servidor;
  • linha 7: o documento foi encontrado;
  • linha 8: o servidor anuncia que fechará a conexão depois de enviar sua resposta;
  • linha 9: desta vez, o documento é texto simples;
  • linha 12: o servidor não especificou o tamanho do documento ([Content-Length]); ele o envia em blocos (chunks), cada um precedido de seu tamanho em hexadecimal;
  • linhas 14–16: um único bloco de 0x0c = 12 bytes, o texto [Hello Serge!], seguido de um bloco de tamanho zero que marca o fim do documento;
  • linha 18: conforme solicitado, o servidor fechou a conexão. O cliente detectou isso e encerrou por conta própria.

Vamos tentar de novo sem o cabeçalho [Connection: close], solicitando a raiz do site:

> dotnet run internet-06.cs -- localhost 27110
Type your commands (bye to stop):
GET / HTTP/1.1
Host: localhost:27110

<-- HTTP/1.1 200 OK
<-- Content-Length: 169
<-- Content-Type: text/html; charset=utf-8
<-- Date: Sat, 03 Oct 2026 09:49:13 GMT
<-- Server: Kestrel
<-- 
<-- <!DOCTYPE html>
<-- <html lang="en">
<-- <head><meta charset="utf-8"><title>Test server</title></head>
<-- <body><h1>Welcome to the test server of the C# course</h1></body>
<-- </html>
bye
  • linha 7: o documento é anunciado junto com seu tamanho, 169 bytes. O cliente sabe, portanto, onde ele termina;
  • linha 16: o documento foi totalmente recebido, mas o servidor não fechou a conexão: no HTTP/1.1, ela permanece aberta por padrão para outras requisições. O servidor aguarda uma nova requisição; o usuário então digita [bye] para fechar a conexão.

Quando o servidor está indisponível, a conexão falha:

> dotnet run internet-06.cs -- localhost 27199
Unable to connect to the service (localhost, 27199): Connection refused

O leitor pode usar esse cliente TCP genérico com o servidor de eco ou, se dispuser de um servidor SMTP ou POP3 que aceite conexões sem criptografia (como um servidor de teste instalado localmente), para reproduzir os exemplos de diálogos mostrados acima.

12.6.4. Um servidor TCP genérico

Vamos agora nos concentrar em um servidor:

  • que exibe na tela as linhas enviadas por seus clientes;
  • que devolve como respostas as linhas de texto digitadas no teclado por um usuário. O usuário, portanto, faz o papel de servidor.

O programa é iniciado em uma janela de comando por meio de [dotnet run internet-07.cs -- port], em que [port] é a porta à qual os clientes devem se conectar. O atendimento a um cliente é feito por dois processos:

  • o programa principal:
    • atende os clientes um após o outro, não em paralelo. Como o console não pode ser usado por dois clientes simultaneamente, nosso servidor atende apenas um cliente por vez. Os clientes que se conectam nesse intervalo têm a conexão estabelecida pelo sistema, mas precisam esperar que o programa os aceite;
    • lê as linhas digitadas pelo usuário no teclado e as envia ao cliente. O usuário sinaliza com o comando [bye] que está fechando a conexão com o cliente;
  • uma tarefa separada é dedicada exclusivamente à leitura das linhas de texto enviadas pelo cliente.

O servidor nunca para, a menos que o usuário pressione Ctrl-C no teclado.

O programa [internet-07.cs] é o seguinte:

using System.Net;
using System.Net.Sockets;

// servidor TCP genérico
// - exibe as linhas enviadas pelo cliente
// - envia-lhe como respostas as linhas digitadas no teclado pelo usuário
// os clientes são atendidos um após o outro (um único console)
// chamada: dotnet run internet-07.cs -- port

const string syntax = "Syntax: dotnet run internet-07.cs -- port";
if (args.Length != 1 || !int.TryParse(args[0], out int port) || port is < 1 or > 65535)
{
    Console.WriteLine(syntax);
    return;
}

// o serviço de escuta
var listener = new TcpListener(IPAddress.Any, port);
listener.Start();
Console.WriteLine($"Generic server started on {listener.LocalEndpoint}");

// a entrada de teclado em andamento (ela pode sobreviver à conexão de um cliente)
Task<string?>? input = null;
// laço de serviço - o servidor é interrompido por Ctrl-C
while (true)
{
    // espera por um cliente
    Console.WriteLine("Waiting for the next client...");
    using TcpClient client = await listener.AcceptTcpClientAsync();
    Console.WriteLine($"Client {client.Client.RemoteEndPoint}");
    NetworkStream stream = client.GetStream();
    var writer = new StreamWriter(stream) { AutoFlush = true, NewLine = "\r\n" };
    // uma tarefa separada exibe as linhas enviadas pelo cliente
    Task reception = ReceiveAsync(new StreamReader(stream));
    // a leitura das respostas no teclado é feita no programa principal
    Console.WriteLine("Type your responses (bye to close the connection with the client):");
    try
    {
        while (true)
        {
            // iniciamos uma entrada de teclado se nenhuma estiver em andamento
            input ??= Task.Run(Console.ReadLine);
            // esperamos ou por uma linha digitada no teclado, ou pela saída do cliente
            if (await Task.WhenAny(input, reception) == reception)
            {
                // a entrada em andamento atenderá o próximo cliente
                Console.WriteLine("[the client has closed the connection]");
                break;
            }
            string? response = await input;
            input = null;
            // fim da entrada de teclado (Ctrl-D, Ctrl-Z): parada do servidor
            if (response is null)
            {
                listener.Stop();
                return;
            }
            // fim da conexão com este cliente?
            if (response.Trim().Equals("bye", StringComparison.OrdinalIgnoreCase))
            {
                Console.WriteLine("[connection closed by the server]");
                break;
            }
            // enviamos a resposta ao cliente
            await writer.WriteLineAsync(response);
        }
    }
    catch (IOException ex)
    {
        Console.WriteLine($"The following error occurred while writing: {ex.Message}");
    }
    // fechamos a conexão com o cliente
    client.Close();
    await reception;
}

// --------------------------------------------------------------------
// exibe as linhas enviadas pelo cliente até que a conexão seja fechada
static async Task ReceiveAsync(StreamReader reader)
{
    try
    {
        while (await reader.ReadLineAsync() is string request)
        {
            Console.WriteLine($"<-- {request}");
        }
    }
    catch (Exception ex) when (ex is IOException or ObjectDisposedException)
    {
        // a conexão foi fechada durante a leitura: a tarefa termina
    }
}
  • linhas 18–19: o serviço de escuta é criado e iniciado. Ele escuta em todas as interfaces de rede da máquina;
  • linha 23: a entrada de teclado em andamento. Ela é declarada fora do laço de clientes, por uma razão explicada adiante;
  • linha 25: laço infinito de espera por clientes. O usuário interromperá o servidor pressionando Ctrl-C;
  • linha 29: espera por um cliente. Quando um cliente chega, a instância [TcpClient] devolvida por [AcceptTcpClientAsync] representa o lado servidor da conexão aberta com esse cliente. A declaração [using] a libera ao final de cada iteração do laço;
  • linha 34: a leitura das linhas enviadas pelo cliente é tratada por uma tarefa separada, como no cliente genérico;
  • linhas 39–65: o laço de entrada, pelo teclado, das respostas a enviar ao cliente;
  • Linha 42: o operador [??=] (C# 8) inicia uma nova entrada apenas se nenhuma estiver em andamento. De fato, quando um cliente fecha a conexão (linha 44), o programa passa ao cliente seguinte sem esperar uma entrada, e a entrada de teclado iniciada para o cliente anterior ainda está em andamento: ela será usada pelo próximo cliente. Iniciar uma segunda faria duas entradas disputarem as mesmas teclas digitadas;
  • linha 53: se a entrada padrão for fechada, o servidor para;
  • linha 59: o comando [bye] fecha a conexão com o cliente atual;
  • linha 65: a linha digitada é enviada ao cliente;
  • linhas 73–74: fechamento da conexão e espera pelo término da operação de leitura;
  • linhas 79–90: o método que exibe continuamente no console as linhas de texto enviadas pelo cliente. É semelhante ao que vimos para o cliente TCP genérico.

O curso de 2008 usava esse servidor para simular um servidor web consultado por um navegador. Faremos o mesmo, substituindo o navegador pelo [curl]. O servidor genérico está em execução na porta 27101. Em outra janela, pedimos ao [curl] a URL [http://localhost:27101/example.html]. [curl] conecta-se então à porta 27101 da máquina [localhost] e solicita o documento [/example.html]. Eis a janela do servidor:

> dotnet run internet-07.cs -- 27101
Generic server started on 0.0.0.0:27101
Waiting for the next client...
Client 127.0.0.1:52208
<-- GET /example.html HTTP/1.1
<-- Host: localhost:27101
<-- User-Agent: curl/8.5.0
<-- Accept: */*
<-- 
Type your responses (bye to close the connection with the client):
HTTP/1.1 200 OK
Server: generic tcp server
Connection: close
Content-Type: text/html; charset=utf-8

<html><head><title>Generic server</title></head>
<body><h1>Response of the generic server</h1></body></html>
bye
[connection closed by the server]
Waiting for the next client...
  • linha 4: um cliente chegou;
  • linhas 5–8: vemos a requisição HTTP enviada pelo [curl], terminando com uma linha em branco. Um navegador enviaria muitos outros cabeçalhos (idiomas e formatos suportados, compressão, cookies etc.): o leitor pode testar isso solicitando a mesma URL ao seu navegador;
  • Linhas 10–17: o usuário ao teclado é aqui o verdadeiro servidor, e ele elabora a resposta manualmente. Limita-se ao mínimo indispensável: uma linha de status, três cabeçalhos, uma linha em branco e o documento HTML. Não especifica o tamanho do documento ([Content-Length]), mas indica que fechará a conexão depois de enviá-lo ([Connection: close]). Isso basta: quando o cliente vir a conexão se fechar, saberá que a resposta está completa;
  • linha 19: o usuário digitou [bye]: o servidor fecha a conexão com o cliente;
  • linha 20: o servidor aguarda um novo cliente. Vamos interrompê-lo com Ctrl-C.

E eis o que o [curl] exibiu:

> curl -v http://localhost:27101/example.html
* Host localhost:27101 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying 127.0.0.1:27101...
* Connected to localhost (127.0.0.1) port 27101
> GET /example.html HTTP/1.1
> Host: localhost:27101
> User-Agent: curl/8.5.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Server: generic tcp server
< Connection: close
< Content-Type: text/html; charset=utf-8
< 
<html><head><title>Generic server</title></head>
<body><h1>Response of the generic server</h1></body></html>
* Closing connection

O [curl] recebeu exatamente o que foi digitado na janela do servidor (linhas 12–18) e detectou que a conexão foi fechada (linha 19). Um navegador teria exibido a página HTML recebida, com o título [Generic server] na aba.

12.6.5. Um cliente web

No exemplo anterior, vimos os cabeçalhos HTTP enviados pelo [curl]. Vamos escrever um cliente web que recebe uma URL como parâmetro e exibe na tela tudo o que o servidor lhe envia. Vamos supor que o servidor suporte o protocolo HTTP/1.1. Nosso cliente enviará a seguinte requisição:

1
2
3
4
GET /document HTTP/1.1
Host: machine:port
User-Agent: web-client-csharp-course
Connection: close
  • a primeira linha especifica o documento desejado;
  • o cabeçalho [Host] identifica o servidor consultado;
  • o cabeçalho [User-Agent] identifica nosso cliente;
  • o cabeçalho [Connection] indica que queremos que o servidor feche a conexão depois de nos responder: leremos sua resposta até o fim do fluxo;
  • a linha em branco encerra a requisição.

Se, na primeira linha, substituirmos [GET] por [HEAD], o servidor nos enviará apenas os cabeçalhos HTTP da resposta, e não o documento.

Nosso cliente web será chamado da seguinte forma: [dotnet run internet-08.cs -- URL command], em que [URL] é a URL desejada e [command] é uma das duas palavras-chave [GET] ou [HEAD]. O programa [internet-08.cs] é o seguinte:

using System.Net.Sockets;

// cliente web: solicita uma URL com uma requisição HTTP/1.1 escrita "à mão"
// e exibe tudo o que o servidor devolve (cabeçalhos HTTP e documento)
// chamada: dotnet run internet-08.cs -- URL GET|HEAD

const string syntax = "Syntax: dotnet run internet-08.cs -- http://machine[:port][/document] GET|HEAD";
if (args.Length != 2)
{
    Console.WriteLine(syntax);
    return;
}

// verificação da URL: ela deve ser absoluta e usar o esquema http
if (!Uri.TryCreate(args[0], UriKind.Absolute, out Uri? uri) || uri.Scheme != Uri.UriSchemeHttp)
{
    Console.WriteLine($"Incorrect URL [{args[0]}]. {syntax}");
    return;
}
// verificação do comando
string command = args[1].ToUpper();
if (command is not ("GET" or "HEAD"))
{
    Console.WriteLine($"The second parameter must be GET or HEAD. {syntax}");
    return;
}

try
{
    // conexão com o servidor web
    using var client = new TcpClient();
    await client.ConnectAsync(uri.Host, uri.Port);
    await using NetworkStream stream = client.GetStream();
    using var reader = new StreamReader(stream);
    // o HTTP exige o fim de linha \r\n (Environment.NewLine é \n no Linux)
    await using var writer = new StreamWriter(stream) { NewLine = "\r\n" };
    // a requisição: linha de comando, cabeçalhos HTTP, linha vazia
    await writer.WriteLineAsync($"{command} {uri.PathAndQuery} HTTP/1.1");
    await writer.WriteLineAsync($"Host: {uri.Authority}");
    await writer.WriteLineAsync("User-Agent: web-client-csharp-course");
    await writer.WriteLineAsync("Connection: close");
    await writer.WriteLineAsync();
    // a requisição sai para a rede de uma só vez
    await writer.FlushAsync();
    // a resposta é lida até que o servidor feche a conexão
    while (await reader.ReadLineAsync() is string line)
    {
        Console.WriteLine(line);
    }
}
catch (SocketException ex)
{
    Console.WriteLine($"The following error occurred: {ex.SocketErrorCode} ({ex.Message})");
}
catch (IOException ex)
{
    Console.WriteLine($"The following error occurred: {ex.Message}");
}

Uma novidade deste programa é o uso da classe [Uri] (namespace [System]). O programa recebe uma URL (Uniform Resource Locator), uma forma específica de URI (Uniform Resource Identifier), no formato [http://server:port/path?param1=val1&param2=val2]. A classe [Uri] permite decompor essa cadeia em seus diversos componentes:

  • Linha 15: [Uri.TryCreate] constrói um objeto [Uri] a partir da cadeia [args[0]] e retorna [false] se a cadeia não for uma URI absoluta válida (sem esquema, servidor etc.). O curso de 2008 usava o construtor [new Uri(...)] dentro de um [try/catch]; [TryCreate] evita a exceção. Verificamos também se o esquema é [http]: nosso cliente não sabe realizar a negociação TLS para [https]. Depois que o objeto [Uri] é construído, temos acesso aos diversos elementos da URI. Assim, se o objeto [uri] tiver sido construído a partir da cadeia [http://localhost:27110/hello?name=Serge], temos:
    • [uri.Scheme]: http;
    • [uri.Host]: localhost;
    • [uri.Port]: 27110 (80 se a porta não for especificada na URL, 443 para HTTPS);
    • [uri.Authority]: localhost:27110 (a porta é omitida se for a porta padrão do esquema);
    • [uri.AbsolutePath]: /hello;
    • [uri.Query]: ?name=Serge;
    • [uri.PathAndQuery]: /hello?name=Serge;
  • linha 22: o padrão [not (... or ...)] (C# 9) verifica se o comando é [GET] ou [HEAD];
  • linha 32: conecta-se ao servidor especificado pela URL;
  • linha 36: o HTTP exige finais de linha \r\n;
  • linhas 38–42: a requisição HTTP;
  • linha 44: [AutoFlush] não foi usado: a requisição é enviada de uma só vez, depois de totalmente escrita;
  • linhas 46–48: a resposta é exibida até que o servidor feche a conexão.

Vamos solicitar apenas os cabeçalhos da raiz do nosso servidor de teste:

1
2
3
4
5
6
7
> dotnet run internet-08.cs -- http://localhost:27110/ HEAD
HTTP/1.1 200 OK
Content-Length: 169
Connection: close
Content-Type: text/html; charset=utf-8
Date: Sat, 03 Oct 2026 09:49:51 GMT
Server: Kestrel

Obtemos a linha de status e os cabeçalhos, seguidos de uma linha em branco, mas não o documento. O cabeçalho [Content-Length] indica o tamanho que o documento teria com o comando [GET]. Com o comando [GET] e um documento enviado em partes (chunks):

> dotnet run internet-08.cs -- "http://localhost:27110/hello?name=Serge" GET
HTTP/1.1 200 OK
Connection: close
Content-Type: text/plain; charset=utf-8
Date: Sat, 03 Oct 2026 09:49:53 GMT
Server: Kestrel
Transfer-Encoding: chunked

c
Hello Serge!
0

Observe as aspas em torno da URL no comando: sem elas, alguns interpretadores de comandos atribuiriam um significado específico ao caractere [?]. O documento ([Hello Serge!]) é emoldurado pelos tamanhos de suas partes, como já vimos. Nosso cliente exibe a resposta bruta; um verdadeiro cliente HTTP, por outro lado, deve reconstruir o documento a partir das partes.

Um documento inexistente:

1
2
3
4
5
6
> dotnet run internet-08.cs -- http://localhost:27110/unknown GET
HTTP/1.1 404 Not Found
Content-Length: 0
Connection: close
Date: Sat, 03 Oct 2026 09:49:54 GMT
Server: Kestrel

Uma URL sujeita a um redirecionamento:

1
2
3
4
5
6
7
> dotnet run internet-08.cs -- http://localhost:27110/old GET
HTTP/1.1 302 Found
Content-Length: 0
Connection: close
Date: Sat, 03 Oct 2026 09:49:56 GMT
Server: Kestrel
Location: /hello?name=visitor
  • Linha 2: o código 302 indica um redirecionamento; o documento solicitado está temporariamente em outro endereço;
  • linha 7: esse endereço é fornecido pelo cabeçalho [Location]. Aqui ele é relativo: o endereço completo é [http://localhost:27110/hello?name=visitor].

Nosso cliente parou por aí. Um navegador, por outro lado, teria solicitado automaticamente o novo endereço. É isso que nosso próximo cliente fará.

Por fim, uma requisição a uma URL [https] é rejeitada:

> dotnet run internet-08.cs -- https://learn.microsoft.com/ GET
Incorrect URL [https://learn.microsoft.com/]. Syntax: dotnet run internet-08.cs -- http://machine[:port][/document] GET|HEAD

12.6.6. Um cliente web que trata redirecionamentos

O cliente web anterior não trata um possível redirecionamento da URL solicitada. Os códigos de status de redirecionamento são os seguintes:

Código
Significado
301 Moved Permanently
O documento foi movido permanentemente para um novo endereço; um navegador pode guardar o novo endereço
302 Found
O documento está temporariamente em outro endereço
303 See Other
A resposta deve ser solicitada a outro endereço usando o método [GET] (usado após o envio de um formulário)
307 Temporary Redirect, 308 Permanent Redirect
Igual a 302 e 301, mas o cliente deve reenviar a requisição usando o mesmo método ([POST] continua sendo [POST])

Em qualquer caso, o novo endereço é fornecido pelo cabeçalho [Location], como URL absoluta ou relativa. O cliente de 2008 detectava um redirecionamento pela presença da palavra [moved] na linha de status. Isso não é confiável: a mensagem que segue o código é arbitrária, e o Kestrel responde com [302 Found], sem a palavra [moved]. Nós nos baseamos no próprio código de status.

O programa [internet-09.cs] é o seguinte:

using System.Net.Sockets;

// cliente web que segue os redirecionamentos (códigos 301, 302, 303, 307, 308)
// chamada: dotnet run internet-09.cs -- URL GET|HEAD

const string syntax = "Syntax: dotnet run internet-09.cs -- http://machine[:port][/document] GET|HEAD";
if (args.Length != 2)
{
    Console.WriteLine(syntax);
    return;
}
if (!Uri.TryCreate(args[0], UriKind.Absolute, out Uri? uri) || uri.Scheme != Uri.UriSchemeHttp)
{
    Console.WriteLine($"Incorrect URL [{args[0]}]. {syntax}");
    return;
}
string command = args[1].ToUpper();
if (command is not ("GET" or "HEAD"))
{
    Console.WriteLine($"The second parameter must be GET or HEAD. {syntax}");
    return;
}

// os códigos de status HTTP que sinalizam um redirecionamento
int[] redirectionCodes = [301, 302, 303, 307, 308];
// número máximo de redirecionamentos seguidos
const int maxRedirections = 3;

try
{
    // uma iteração por URL solicitada
    for (int nbRedirections = 0; ; nbRedirections++)
    {
        // solicitamos a URL e obtemos o possível endereço de redirecionamento
        string? location = await RequestAsync(uri, command, redirectionCodes);
        // sem redirecionamento: terminamos
        if (location is null)
        {
            break;
        }
        // redirecionamentos demais: desistimos
        if (nbRedirections == maxRedirections)
        {
            Console.WriteLine($"<-- Giving up: more than {maxRedirections} redirections -->");
            break;
        }
        // a nova URL: o endereço de redirecionamento pode ser absoluto ou relativo à URL atual
        uri = new Uri(uri, location);
        Console.WriteLine($"<-- Redirection to {uri} -->{Environment.NewLine}");
    }
}
catch (SocketException ex)
{
    Console.WriteLine($"The following error occurred: {ex.SocketErrorCode} ({ex.Message})");
}
catch (Exception ex) when (ex is IOException or UriFormatException)
{
    Console.WriteLine($"The following error occurred: {ex.Message}");
}

// --------------------------------------------------------------------
// solicita a URL [uri], exibe a resposta do servidor
// retorna o endereço de redirecionamento, ou null se não houver redirecionamento
static async Task<string?> RequestAsync(Uri uri, string command, int[] redirectionCodes)
{
    using var client = new TcpClient();
    await client.ConnectAsync(uri.Host, uri.Port);
    await using NetworkStream stream = client.GetStream();
    using var reader = new StreamReader(stream);
    await using var writer = new StreamWriter(stream) { NewLine = "\r\n" };
    // a requisição HTTP
    await writer.WriteLineAsync($"{command} {uri.PathAndQuery} HTTP/1.1");
    await writer.WriteLineAsync($"Host: {uri.Authority}");
    await writer.WriteLineAsync("User-Agent: web-client-csharp-course");
    await writer.WriteLineAsync("Connection: close");
    await writer.WriteLineAsync();
    await writer.FlushAsync();

    // a linha de status, por exemplo: HTTP/1.1 302 Found
    string statusLine = await reader.ReadLineAsync() ?? "";
    Console.WriteLine(statusLine);
    string[] fields = statusLine.Split(' ');
    bool redirection = fields.Length >= 2 && int.TryParse(fields[1], out int code)
        && redirectionCodes.Contains(code);

    // os cabeçalhos HTTP, até a linha vazia
    string? location = null;
    while (await reader.ReadLineAsync() is string header && header != "")
    {
        Console.WriteLine(header);
        // o nome de um cabeçalho HTTP não diferencia maiúsculas de minúsculas
        if (redirection && header.StartsWith("Location:", StringComparison.OrdinalIgnoreCase))
        {
            location = header["Location:".Length..].Trim();
        }
    }
    Console.WriteLine();
    // o possível documento
    while (await reader.ReadLineAsync() is string line)
    {
        Console.WriteLine(line);
    }
    return location;
}

Em relação à versão anterior, as mudanças são as seguintes:

  • linha 25: os códigos de status que indicam um redirecionamento;
  • linha 27: o número máximo de redirecionamentos consecutivos. Sem um limite, um servidor mal configurado poderia prender nosso cliente em um laço infinito (os navegadores desistem após cerca de vinte redirecionamentos);
  • linha 32: o código que antes era executado para uma única URL agora pode ser executado sucessivamente para várias URLs;
  • linha 35: o método [RequestAsync] solicita a URL atual, exibe a resposta e retorna a URL de redirecionamento — ou [null] se não houver redirecionamento;
  • linhas 42–44: o processo é interrompido se o número máximo de redirecionamentos for atingido;
  • linha 48: o construtor [Uri(Uri base, string relative)] calcula a nova URL. Se [location] for um endereço absoluto, ele é usado como está; se for relativo, é completado com base na URL atual, [uri]. O curso de 2008 distinguia os dois casos com um teste: o compilador cuida disso;
  • linhas 64–103: a requisição de uma URL:
    • linha 80: leitura da linha de status, por exemplo [HTTP/1.1 302 Found];
    • linhas 82–84: extração do código (o segundo campo da linha) e verificação se é um dos códigos de redirecionamento;
    • linhas 88–94: leitura dos cabeçalhos até a linha vazia. Se houver redirecionamento, busca-se o cabeçalho [Location], ignorando maiúsculas e minúsculas, já que os nomes de cabeçalhos em HTTP não diferenciam caixa. A expressão [header["Location:".Length..]] usa um intervalo (range, C# 8) para extrair o que vem depois do nome do cabeçalho;
    • linhas 98–103: o restante da resposta é exibido e, em seguida, a URL de redirecionamento encontrada é retornada.

Vamos retomar a URL [/old]:

> dotnet run internet-09.cs -- http://localhost:27110/old GET
HTTP/1.1 302 Found
Content-Length: 0
Connection: close
Date: Sat, 03 Oct 2026 09:50:00 GMT
Server: Kestrel
Location: /hello?name=visitor

<-- Redirection to http://localhost:27110/hello?name=visitor -->

HTTP/1.1 200 OK
Connection: close
Content-Type: text/plain; charset=utf-8
Date: Sat, 03 Oct 2026 09:50:00 GMT
Server: Kestrel
Transfer-Encoding: chunked

e
Hello visitor!
0
  • linhas 2–7: o redirecionamento temporário para um endereço relativo;
  • linha 9: a nova URL, completada por [new Uri(uri, location)];
  • linhas 11–19: a resposta à nova URL. O documento, de 0x0e = 14 bytes, foi enviado em partes (chunks).

A URL [/moved] é redirecionada permanentemente para um endereço absoluto:

> dotnet run internet-09.cs -- http://localhost:27110/moved GET
HTTP/1.1 301 Moved Permanently
Content-Length: 0
Connection: close
Date: Sat, 03 Oct 2026 09:50:02 GMT
Server: Kestrel
Location: http://localhost:27110/

<-- Redirection to http://localhost:27110/ -->

HTTP/1.1 200 OK
Content-Length: 169
Connection: close
Content-Type: text/html; charset=utf-8
Date: Sat, 03 Oct 2026 09:50:02 GMT
Server: Kestrel

<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Test server</title></head>
<body><h1>Welcome to the test server of the C# course</h1></body>
</html>

A URL [/loop] redireciona para si mesma:

> dotnet run internet-09.cs -- http://localhost:27110/loop HEAD
HTTP/1.1 302 Found
Connection: close
Date: Sat, 03 Oct 2026 09:50:04 GMT
Server: Kestrel
Location: /loop

<-- Redirection to http://localhost:27110/loop -->

HTTP/1.1 302 Found
Connection: close
Date: Sat, 03 Oct 2026 09:50:04 GMT
Server: Kestrel
Location: /loop

<-- Redirection to http://localhost:27110/loop -->

HTTP/1.1 302 Found
Connection: close
Date: Sat, 03 Oct 2026 09:50:04 GMT
Server: Kestrel
Location: /loop

<-- Redirection to http://localhost:27110/loop -->

HTTP/1.1 302 Found
Connection: close
Date: Sat, 03 Oct 2026 09:50:04 GMT
Server: Kestrel
Location: /loop

<-- Giving up: more than 3 redirections -->

Nosso cliente seguiu três redirecionamentos e depois desistiu (linha 32). Com o comando [HEAD], nenhum documento foi enviado.

O log do servidor web registrou todas as requisições para as entradas [A web client] e [A web client that handles redirects]:

> dotnet run internet-03.cs
Web server started on http://localhost:27110
HEAD / HTTP/1.1 -> 200
GET /hello?name=Serge HTTP/1.1 -> 200
GET /unknown HTTP/1.1 -> 404
GET /old HTTP/1.1 -> 302
GET /old HTTP/1.1 -> 302
GET /hello?name=visitor HTTP/1.1 -> 200
GET /moved HTTP/1.1 -> 301
GET / HTTP/1.1 -> 200
HEAD /loop HTTP/1.1 -> 302
HEAD /loop HTTP/1.1 -> 302
HEAD /loop HTTP/1.1 -> 302
HEAD /loop HTTP/1.1 -> 302

Para cada redirecionamento, ele mostra a requisição que o provocou, seguida da requisição ao novo endereço (linhas 7–8), e as quatro requisições do laço interrompido (linhas 11–14).

Escrever um cliente HTTP sobre TCP ajuda a entender o protocolo, mas um cliente real precisa tratar muitas outras coisas: criptografia TLS, transmissão em partes, compressão, conexões persistentes, HTTP/2 e HTTP/3… A segunda parte deste capítulo apresenta a classe [HttpClient] do .NET, que cuida de tudo isso para nós.

12.7. As classes do .NET especializadas em um protocolo

Nos exemplos anteriores, o protocolo HTTP foi tratado com um cliente TCP: tivemos de construir as requisições nós mesmos, analisar as linhas de status e os cabeçalhos e acompanhar os redirecionamentos. Poderíamos ter construído um cliente SMTP ou POP da mesma forma. O .NET oferece classes especializadas nos protocolos HTTP e SMTP. Essas classes entendem o protocolo de comunicação entre o cliente e o servidor, poupando o desenvolvedor de gerenciá-lo. Vamos apresentá-las agora.

Os programas desta segunda parte, como os da primeira, são aplicativos de arquivo único na pasta [12-internet], numerados em sequência (de [internet-10.cs] a [internet-19.cs]). O aplicativo de exemplo ao final do capítulo constitui uma solução separada, [TaxV8]. As portas usadas têm a forma 272xx.

12.7.1. As classes WebClient e WebRequest, agora obsoletas

O curso de 2008 apresentava duas famílias de classes:

  • A classe [WebClient], que solicitava um documento com uma única instrução (métodos [DownloadString], [DownloadData], [DownloadFile], [OpenRead]) ou enviava um (métodos [UploadString], [UploadValues] para um formulário…);
  • as classes [WebRequest] / [WebResponse] e suas derivadas [HttpWebRequest] / [HttpWebResponse], que eram mais flexíveis: permitiam escolher o método HTTP ([GET], [HEAD], [POST]), adicionar cabeçalhos e ler a resposta à medida que ela chega.

Essas classes ainda existem no .NET 10 por compatibilidade, mas estão marcadas como obsoletas desde o .NET 6. O pequeno programa a seguir as utiliza:

1
2
3
4
5
using System.Net;

using var client = new WebClient();
Console.WriteLine(client.DownloadString("http://localhost:27210/"));
var request = WebRequest.Create("http://localhost:27210/");

A compilação produz os dois avisos a seguir (reproduzimos apenas estas duas linhas da saída de [dotnet build]):

1
2
3
> dotnet build webclient.cs
webclient.cs(3,20): warning SYSLIB0014: 'WebClient.WebClient()' is obsolete: 'WebRequest, HttpWebRequest, ServicePoint, and WebClient are obsolete. Use HttpClient instead.' (https://aka.ms/dotnet-warnings/SYSLIB0014)
webclient.cs(5,15): warning SYSLIB0014: 'WebRequest.Create(string)' is obsolete: 'WebRequest, HttpWebRequest, ServicePoint, and WebClient are obsolete. Use HttpClient instead.' (https://aka.ms/dotnet-warnings/SYSLIB0014)

A mensagem é clara: é preciso usar a classe [HttpClient]. Essa classe foi introduzida com o .NET 4.5 (2012); foi projetada desde o início para a programação assíncrona (todos os seus métodos de rede são assíncronos), oferece suporte a HTTP/1.1, HTTP/2 e HTTP/3, reutiliza suas conexões e pode ser usada por várias tarefas simultaneamente. No .NET atual, [WebClient], e [WebRequest] nada mais são, na verdade, que fachadas construídas sobre [HttpClient]. Não vamos examiná-las mais a fundo e retomaremos com [HttpClient], usando os exemplos que o curso de 2008 tratava com elas.

12.7.2. A classe HttpClient

12.7.2.1. Um servidor web de teste

Para ilustrar os recursos de [HttpClient], precisamos de um servidor web mais completo que o da Parte 1 ([internet-03.cs]): ele deve aceitar formulários, trocar JSON e saber lidar com atrasos. Vamos então escrever um segundo servidor de teste, [internet-10.cs], um aplicativo ASP.NET Core chamado “Minimal API”, assim como o primeiro. Mais uma vez, não é necessário entender esse programa em detalhes por ora (o ASP.NET Core será estudado no próximo capítulo): basta saber o que cada URL responde.

#:sdk Microsoft.NET.Sdk.Web
#:property PublishAot=false

// um servidor web local que servirá de alvo para os clientes HttpClient
// chamada: dotnet run internet-10.cs [-- port]
int port = args.Length == 1 && int.TryParse(args[0], out int p) ? p : 27210;

var builder = WebApplication.CreateBuilder(args);
// nenhum log do ASP.NET (apenas os avisos): escrevemos o nosso
builder.Logging.SetMinimumLevel(LogLevel.Warning);
var app = builder.Build();

// acompanhamento no console: cada requisição, a porta do cliente e o código de status da resposta
app.Use(async (context, next) =>
{
    var request = context.Request;
    string start = $"{request.Method} {request.Path}{request.QueryString} {request.Protocol}"
        + $" (client port {context.Connection.RemotePort})";
    try
    {
        await next(context);
        Console.WriteLine($"{start} -> {context.Response.StatusCode}");
    }
    catch (OperationCanceledException) when (context.RequestAborted.IsCancellationRequested)
    {
        // o cliente desistiu da requisição antes da resposta
        Console.WriteLine($"{start} -> abandoned by the client");
    }
});

// as URLs de consulta aceitam os métodos GET e HEAD
string[] getHead = ["GET", "HEAD"];

// a página inicial: um documento HTML
app.MapMethods("/", getHead, () => Results.Content("""
    <!DOCTYPE html>
    <html lang="en">
    <head><meta charset="utf-8"><title>Test server</title></head>
    <body><h1>Welcome to the HttpClient test server</h1></body>
    </html>

    """, "text/html; charset=utf-8"));

// um documento de texto construído a partir de um parâmetro da URL
app.MapMethods("/hello", getHead, (string? name) => $"Hello {name ?? "unknown"}!");

// os cabeçalhos HTTP recebidos pelo servidor, devolvidos ao cliente como texto
app.MapMethods("/headers", getHead, (HttpRequest request) =>
    string.Join("\n", request.Headers.Select(header => $"{header.Key}: {header.Value}")));

// redirecionamento temporário (302) para um endereço relativo
app.MapMethods("/old", getHead, () => Results.Redirect("/hello?name=visitor"));

// um redirecionamento que entra em laço consigo mesmo
app.MapMethods("/loop", getHead, () => Results.Redirect("/loop"));

// um erro de servidor (500 Internal Server Error)
app.MapMethods("/error", getHead, () => Results.StatusCode(500));

// uma resposta que demora
app.MapGet("/slow", async (int seconds, CancellationToken token) =>
{
    await Task.Delay(TimeSpan.FromSeconds(seconds), token);
    return $"Response obtained after {seconds} s";
});

// um formulário enviado por POST: descrevemos o que foi recebido
app.MapPost("/form", async (HttpRequest request) =>
{
    IFormCollection form = await request.ReadFormAsync();
    string fields = string.Join(", ", form.Select(field => $"{field.Key}=[{field.Value}]"));
    return $"Content-Type received: {request.ContentType}\nFields received: {fields}";
});

// qualquer texto enviado por POST: o devolvemos em letras maiúsculas
app.MapPost("/text", async (HttpRequest request) =>
{
    using var reader = new StreamReader(request.Body);
    string text = await reader.ReadToEndAsync();
    return $"Content-Type received: {request.ContentType}\nText received in upper case: {text.ToUpper()}";
});

// um pequeno "banco de dados" de pessoas, trocadas no formato JSON
List<Person> persons = [new(1, "Dupont", 42), new(2, "Durand", 35)];
Lock padlock = new();

// a lista de pessoas
app.MapGet("/api/persons", () =>
{
    lock (padlock)
    {
        return persons.ToList();
    }
});

// uma pessoa designada pelo seu número, ou 404 se ela não existir
app.MapGet("/api/persons/{id:int}", (int id) =>
{
    lock (padlock)
    {
        return persons.Find(person => person.Id == id) is Person person
            ? Results.Ok(person)
            : Results.NotFound();
    }
});

// adição de uma pessoa: o servidor lhe atribui um número e responde 201 Created
app.MapPost("/api/persons", (Person newPerson) =>
{
    lock (padlock)
    {
        Person created = newPerson with { Id = persons.Max(person => person.Id) + 1 };
        persons.Add(created);
        return Results.Created($"/api/persons/{created.Id}", created);
    }
});

// qualquer outra URL recebe a resposta 404 Not Found (comportamento padrão)
Console.WriteLine($"Web server started on http://localhost:{port}");
app.Run($"http://127.0.0.1:{port}");

// uma pessoa
record Person(int Id, string Name, int Age);

Comentários:

  • linha 2: os aplicativos de arquivo único são configurados por padrão para compilação nativa (AOT), o que desabilita a serialização (JSON) baseada em reflexão. Como no Capítulo 5, nós a reabilitamos: o servidor poderá converter automaticamente seus objetos em JSON;
  • Linhas 14–27: cada requisição é registrada no console, junto com a porta do cliente e o código de status da resposta. A porta do cliente nos permitirá determinar se duas requisições usaram a mesma conexão TCP. Se o cliente abortar uma requisição antes de receber uma resposta, o Kestrel revoga o token [RequestAborted], e a operação em andamento termina com uma [OperationCanceledException]: também exibimos isso;
  • linha 35: a URL [/] retorna um pequeno documento HTML;
  • linha 45: a URL [/hello?name=xx] gera o texto [Hello xx!];
  • linha 48: a URL [/headers] devolve ao cliente, como texto, os cabeçalhos HTTP da requisição do cliente. Isso nos permitirá ver o que [HttpClient] envia. O curso de 2008 usava para isso o servidor TCP genérico, ao qual o usuário diante do teclado tinha de fazer responder;
  • linhas 52–55: um redirecionamento temporário para [/hello?name=visitor] e um redirecionamento que volta para si mesmo, como no servidor da Parte 1;
  • linha 58: uma resposta 500 (erro interno do servidor);
  • linha 61: a URL [/slow?seconds=n] só responde depois de decorridos n segundos. O token [token] é cancelado se o cliente abortar a requisição: a espera é então interrompida;
  • linha 68: a URL [/form] recebe um formulário enviado pelo método [POST] e descreve o que recebeu;
  • linha 76: a URL [/text] recebe um texto qualquer por [POST] e o devolve em maiúsculas;
  • Linhas 84–114: um pequeno “conjunto de dados” de pessoas, trocado no formato JSON. [GET /api/persons] retorna a lista de pessoas; [GET /api/persons/n] retorna a pessoa de número n (ou uma resposta 404); [POST /api/persons] adiciona a pessoa enviada pelo cliente, atribui-lhe um número e responde com o código de status 201 (Created). Como várias requisições podem ser processadas simultaneamente por threads diferentes, a lista é protegida por um lock [Lock] (Capítulo 8);
  • linha 123: o tipo [Person], um registro ([record]);
  • linha 120: o servidor escuta na porta 27210, no endereço de loopback.

O servidor é iniciado em uma janela de comando e permanece nela durante todos os testes desta seção. As requisições que ele recebeu serão apresentadas no final da seção.

12.7.2.2. Baixando um documento: GetStringAsync

A maneira mais fácil de obter um documento com [HttpClient] é usar um dos seguintes métodos:

Método
Função
Task<string> GetStringAsync(string url)
solicita a URL [url] com o método [GET] e retorna o documento recebido como uma cadeia de caracteres
Task<byte[]> GetByteArrayAsync(string url)
Igual ao anterior, com o documento retornado como um array de bytes (uma imagem, por exemplo)
Task<Stream> GetStreamAsync(string url)
Igual ao anterior, com o documento retornado como um fluxo (stream) a ser lido à medida que chega (um arquivo grande, por exemplo)

Cada um deles também existe com um parâmetro do tipo [Uri] e com um parâmetro adicional do tipo [CancellationToken]. Esses métodos lançam uma [HttpRequestException] se o servidor responder com um código de erro.

O programa [internet-11.cs] é o seguinte:

// primeiros passos com HttpClient: baixar um documento como string
// o servidor de teste [internet-10.cs] deve estar em execução na porta 27210

// um cliente HTTP e o endereço base das URLs relativas que lhe serão solicitadas
using var client = new HttpClient { BaseAddress = new Uri("http://localhost:27210/") };

// 1 - um documento de texto
string text = await client.GetStringAsync("hello?name=Serge");
Console.WriteLine($"Document received: {text}");

// 2 - os cabeçalhos HTTP enviados pelo HttpClient, como o servidor os recebeu
Console.WriteLine("--- headers sent by default");
Console.WriteLine(await client.GetStringAsync("headers"));

// 3 - adicionamos cabeçalhos a todas as requisições deste cliente
client.DefaultRequestHeaders.UserAgent.ParseAdd("csharp-course-client/1.0");
client.DefaultRequestHeaders.Add("Accept-Language", "en-US");
Console.WriteLine("--- headers after adding User-Agent and Accept-Language");
Console.WriteLine(await client.GetStringAsync("headers"));

// 4 - um documento HTML, como um array de bytes
byte[] bytes = await client.GetByteArrayAsync("/");
Console.WriteLine($"--- the home page is {bytes.Length} bytes long");

// 5 - um documento que não existe
try
{
    await client.GetStringAsync("unknown");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"--- {ex.GetType().Name} : {ex.Message}");
    Console.WriteLine($"Status code: {(int?)ex.StatusCode} ({ex.StatusCode})");
}

Resultados (com o servidor [internet-10.cs] iniciado em outra janela):

> dotnet run internet-11.cs
Document received: Hello Serge!
--- headers sent by default
Host: localhost:27210
--- headers after adding User-Agent and Accept-Language
Host: localhost:27210
User-Agent: csharp-course-client/1.0
Accept-Language: en-US
--- the home page is 163 bytes long
--- HttpRequestException : Response status code does not indicate success: 404 (Not Found).
Status code: 404 (NotFound)

Comentários:

  • Linha 5: criação do cliente. A propriedade [BaseAddress] define o endereço ao qual as URLs relativas usadas em seguida são associadas: [hello?name=Serge] refere-se, portanto, a [http://localhost:27210/hello?name=Serge]. A barra final no endereço base é importante: sem ela, o último segmento do caminho seria substituído pela URL relativa;
  • linha 8: uma única instrução basta para obter o documento. [HttpClient] montou a requisição, conectou-se, analisou a resposta e reconstruiu o documento enviado em partes ([Transfer-Encoding: chunked]), que nosso cliente TCP da primeira parte exibia tal como estava;
  • Linha 13: na linha 3 dos resultados, vemos que [HttpClient] envia por padrão apenas o cabeçalho obrigatório [Host]. A versão de 2008 de [WebClient] acrescentava [Connection: Keep-Alive]; isso é desnecessário no HTTP/1.1, em que a conexão é mantida por padrão. Também não há cabeçalho [User-Agent]: alguns servidores públicos rejeitam requisições que não o têm;
  • Linhas 16–17: a coleção [DefaultRequestHeaders] contém os cabeçalhos adicionados a todas as requisições deste cliente. Os cabeçalhos comuns têm uma propriedade tipada, como [UserAgent]; os demais são adicionados pelo nome, como [Add]. As linhas 7–8 dos resultados mostram que eles foram de fato recebidos pelo servidor;
  • linha 22: o documento é recebido como bytes. Observe a URL [/]: uma URL relativa que começa com uma barra designa a raiz do site a partir do endereço base;
  • linhas 26–33: um documento inexistente. [GetStringAsync] lança uma [HttpRequestException] cuja propriedade [StatusCode] (do tipo [HttpStatusCode?], .NET 5) retorna o código de status recebido. O curso de 2008 recebia uma [WebException] nesse caso.

12.7.2.3. Requisição e resposta: HttpRequestMessage e HttpResponseMessage

Os métodos [GetXxxAsync] retornam apenas o documento. Para controlar a requisição (método, cabeçalhos) ou examinar a resposta (status, cabeçalhos), usam-se as classes [HttpRequestMessage] e [HttpResponseMessage] :

Membro
Função
new HttpRequestMessage(HttpMethod method, Uri url)
Uma requisição. [HttpMethod] tem propriedades estáticas para os seguintes métodos: [HttpMethod.Get], [HttpMethod.Head], [HttpMethod.Post]…
HttpRequestMessage.Headers, Content
os cabeçalhos da requisição e o eventual documento enviado (método [POST])
Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
Método de [HttpClient] que envia a requisição e retorna a resposta. [GetAsync(url)] é um atalho para uma requisição [GET]
HttpResponseMessage.StatusCode, ReasonPhrase, Version
linha de status: código (enumeração [HttpStatusCode]), mensagem e versão do HTTP
HttpResponseMessage.IsSuccessStatusCode
true se o código de status estiver entre 200 e 299
HttpResponseMessage.EnsureSuccessStatusCode()
lança uma [HttpRequestException] se o código de status não estiver entre 200 e 299
HttpResponseMessage.Headers
os cabeçalhos da própria resposta ([Date], [Server], [Location]…)
HttpResponseMessage.Content
o documento recebido ([HttpContent]): seus cabeçalhos próprios ([Content.Headers]: [Content-Type], [Content-Length]…) e os métodos [ReadAsStringAsync], [ReadAsByteArrayAsync], [ReadAsStreamAsync] para lê-lo
HttpResponseMessage.RequestMessage
a requisição a que a resposta corresponde: em caso de redirecionamento, é a última requisição enviada

Usaremos essas classes para implementar o cliente web da Parte 1 ([internet-08.cs], [internet-09.cs]), que era chamado com uma URL e o método [GET] ou [HEAD] . O curso de 2008 fazia o mesmo com as classes [HttpWebRequest] / [HttpWebResponse]. O programa [internet-12.cs] é o seguinte:

using System.Net.Http.Headers;

// cliente web baseado em HttpClient: exibe o status, os cabeçalhos e o documento recebido
// chamada: dotnet run internet-12.cs -- URL GET/HEAD

const string syntax = "Syntax: dotnet run internet-12.cs -- URL GET/HEAD";
if (args.Length != 2)
{
    Console.WriteLine(syntax);
    return;
}
// a URL deve ser uma URL http ou https absoluta
if (!Uri.TryCreate(args[0], UriKind.Absolute, out Uri? uri) || (uri.Scheme != "http" && uri.Scheme != "https"))
{
    Console.WriteLine($"Incorrect URL [{args[0]}]: give a URL of the form http://machine[:port]/document");
    return;
}
// o método HTTP
string command = args[1].ToUpper();
if (command is not ("GET" or "HEAD"))
{
    Console.WriteLine(syntax);
    return;
}

// o handler que faz o trabalho de rede: no máximo 3 redirecionamentos seguidos
var handler = new SocketsHttpHandler { MaxAutomaticRedirections = 3 };
// o cliente HTTP: no máximo 10 segundos para obter uma resposta
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(10) };
try
{
    // a requisição: método, URL, cabeçalhos
    using var request = new HttpRequestMessage(new HttpMethod(command), uri);
    request.Headers.UserAgent.ParseAdd("csharp-course-client/1.0");
    // a enviamos e esperamos a resposta
    using HttpResponseMessage response = await client.SendAsync(request);
    // a linha de status
    Console.WriteLine($"The server {response.RequestMessage?.RequestUri} answered: "
        + $"HTTP/{response.Version} {(int)response.StatusCode} {response.ReasonPhrase}");
    // os cabeçalhos da resposta, depois os do documento
    Console.WriteLine("--- headers");
    DisplayHeaders(response.Headers);
    DisplayHeaders(response.Content.Headers);
    // um código de status fora do intervalo 200-299 lança uma HttpRequestException
    response.EnsureSuccessStatusCode();
    // o documento
    Console.WriteLine("--- document");
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"{ex.GetType().Name} [{ex.HttpRequestError}] : {ex.Message}");
}
catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
{
    Console.WriteLine("The server did not answer within the allotted time");
}

// exibe uma coleção de cabeçalhos: um nome pode ter vários valores
static void DisplayHeaders(HttpHeaders headers)
{
    foreach ((string name, IEnumerable<string> values) in headers)
    {
        Console.WriteLine($"{name}: {string.Join(", ", values)}");
    }
}

Comentários:

  • Linha 13: como em [internet-08.cs], verifica-se se a URL é válida. O esquema [https] é aceito desta vez: [HttpClient] sabe realizar a negociação TLS;
  • Linha 27: um [HttpClient] delega o processamento de rede a um handler — por padrão, um objeto [SocketsHttpHandler] criado para ele. Nós mesmos o criamos para definir uma de suas propriedades: [MaxAutomaticRedirections] limita a 3 o número de redirecionamentos seguidos (50 por padrão). O handler também gerencia o pool de conexões, os cookies ([UseCookies]), a descompressão ([AutomaticDecompression]) e o proxy ([Proxy]);
  • linha 29: a propriedade [Timeout] define o tempo máximo para receber uma resposta (100 segundos por padrão);
  • linhas 33–34: a requisição, com o método solicitado e um cabeçalho [User-Agent] específico dessa requisição. O curso de 2008 não descobriu como fazer uma requisição [HEAD] com [WebClient]: com [HttpRequestMessage], basta escolher o método;
  • Linha 36: a requisição é enviada; a resposta fica disponível assim que seus cabeçalhos e, por padrão, seu documento forem recebidos. [HttpResponseMessage] é [IDisposable]: a declaração [using] libera seus recursos;
  • linhas 38–39: a linha de status. [response.RequestMessage.RequestUri] é a URL da última requisição: em caso de redirecionamento, ela difere da URL solicitada;
  • linhas 42–43: [HttpClient] organiza os cabeçalhos em duas coleções: os da resposta e os que descrevem o documento;
  • linha 45: se o código de status não indicar sucesso, uma [HttpRequestException] é lançada;
  • linha 48: o documento é lido como uma cadeia de caracteres. O conjunto de caracteres especificado pelo cabeçalho [Content-Type] ([charset=utf-8]) é usado para decodificar os bytes recebidos;
  • linha 50: a partir do .NET 8, a propriedade [HttpRequestError] da exceção indica a natureza do erro na forma de uma enumeração: [ConnectionError], [NameResolutionError], [SecureConnectionError]… Ela vale [Unknown] para um código de status de erro;
  • linha 54: por razões históricas, um timeout resulta em uma [TaskCanceledException], cuja exceção interna é uma [TimeoutException]; o filtro [when] verifica isso;
  • linhas 60–64: um nome de cabeçalho pode ter vários valores; cada elemento da coleção [HttpHeaders] é um par (nome, valores) que é percorrido no [foreach].

Vamos solicitar a raiz do site:

> dotnet run internet-12.cs -- http://localhost:27210/ GET
The server http://localhost:27210/ answered: HTTP/1.1 200 OK
--- headers
Date: Sat, 03 Oct 2026 10:18:56 GMT
Server: Kestrel
Content-Length: 163
Content-Type: text/html; charset=utf-8
--- document
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Test server</title></head>
<body><h1>Welcome to the HttpClient test server</h1></body>
</html>

Encontramos as informações que obtínhamos analisando nós mesmos a resposta com o cliente TCP: a linha de status, os cabeçalhos da resposta [Date] e [Server] e, em seguida, os cabeçalhos do documento [Content-Length] e [Content-Type].

Uma URL que é redirecionada:

1
2
3
4
5
6
7
8
9
> dotnet run internet-12.cs -- http://localhost:27210/old GET
The server http://localhost:27210/hello?name=visitor answered: HTTP/1.1 200 OK
--- headers
Date: Sat, 03 Oct 2026 10:18:58 GMT
Server: Kestrel
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8
--- document
Hello visitor!

O redirecionamento foi tratado automaticamente: a resposta recebida é a da URL [/hello?name=visitor] (linha 2). Comparemos com a primeira parte: o cliente [internet-09.cs] precisava ler a linha de status, extrair o código, procurar o cabeçalho [Location], calcular a nova URL e recomeçar, em um laço limitado a três redirecionamentos. Aqui, tudo isso é tratado pelo handler [SocketsHttpHandler]. O documento, enviado em partes (linha 6), foi reconstruído. Para tratar os redirecionamentos por conta própria, basta definir [AllowAutoRedirect = false] no handler: a resposta 302 é então retornada como está.

Um documento inexistente:

1
2
3
4
5
6
7
> dotnet run internet-12.cs -- http://localhost:27210/unknown GET
The server http://localhost:27210/unknown answered: HTTP/1.1 404 Not Found
--- headers
Date: Sat, 03 Oct 2026 10:19:00 GMT
Server: Kestrel
Content-Length: 0
HttpRequestException [Unknown] : Response status code does not indicate success: 404 (Not Found).

O código 404 está incluído na resposta, junto com seus cabeçalhos. Foi [EnsureSuccessStatusCode] que lançou a exceção. No curso de 2008, com [HttpWebRequest], obtinha-se diretamente uma [WebException], e a resposta tinha de ser recuperada a partir da exceção; com [HttpClient], somente os métodos [GetStringAsync], [GetByteArrayAsync], e [GetStreamAsync] lançam uma exceção para um código de erro; [SendAsync] e [GetAsync] retornam a resposta, e cabe ao programa decidir.

A URL [/loop], que redireciona para si mesma:

1
2
3
4
5
6
7
> dotnet run internet-12.cs -- http://localhost:27210/loop HEAD
The server http://localhost:27210/loop answered: HTTP/1.1 302 Found
--- headers
Date: Sat, 03 Oct 2026 10:19:02 GMT
Server: Kestrel
Location: /loop
HttpRequestException [Unknown] : Response status code does not indicate success: 302 (Found).

Após três redirecionamentos, o handler desiste e retorna a última resposta recebida, uma resposta 302. Como ela não está no intervalo 200–299, [EnsureSuccessStatusCode] lança uma exceção.

Um erro de servidor:

1
2
3
4
5
6
> dotnet run internet-12.cs -- http://localhost:27210/error HEAD
The server http://localhost:27210/error answered: HTTP/1.1 500 Internal Server Error
--- headers
Date: Sat, 03 Oct 2026 10:19:04 GMT
Server: Kestrel
HttpRequestException [Unknown] : Response status code does not indicate success: 500 (Internal Server Error).

Uma porta na qual nenhum servidor está escutando:

> dotnet run internet-12.cs -- http://localhost:27299/ GET
HttpRequestException [ConnectionError] : Connection refused (localhost:27299)

A propriedade [HttpRequestError] é igual a [ConnectionError]: não foi possível alcançar o servidor. Por fim, uma URL [https] enviada ao nosso servidor, que só fala HTTP em texto simples:

> dotnet run internet-12.cs -- https://localhost:27210/ GET
HttpRequestException [SecureConnectionError] : The SSL connection could not be established, see inner exception.

A negociação TLS falhou ([SecureConnectionError]). Em uma máquina conectada à Internet, uma requisição a uma URL como [https://learn.microsoft.com/] normalmente seria atendida em HTTP/2 ou HTTP/3, conforme as capacidades do servidor.

Uma última observação sobre proxies. O curso de 2008 dedicava um parágrafo aos proxies HTTP — as máquinas pelas quais as estações de uma rede corporativa devem passar para acessar a Web. Por padrão, [HttpClient] usa o proxy configurado no sistema (configurações do Windows, variáveis de ambiente [HTTP_PROXY] e [HTTPS_PROXY] no Linux e no macOS). Você pode especificar outro por meio da propriedade [Proxy] do handler, [new SocketsHttpHandler { Proxy = new WebProxy("proxy.example.org:3128") }], ou não usar nenhum com [UseProxy = false].

12.7.2.4. Enviando dados ao servidor: GET e POST

Um cliente pode enviar informações ao servidor de duas maneiras:

  • com o método [GET], as informações fazem parte da URL: [/document?param1=value1&param2=value2];
  • com o método [POST], as informações formam o documento anexado à requisição, após a linha em branco que encerra os cabeçalhos. O cabeçalho [Content-Type] especifica seu formato. Para um formulário HTML, o documento tem o mesmo formato da parte de parâmetros de uma URL: [param1=value1&param2=value2], com o tipo [application/x-www-form-urlencoded].

Nos dois casos, os valores devem ser codificados: certos caracteres (espaços, [&], [=], [?], letras acentuadas etc.) não podem aparecer como estão em uma URL ou em um formulário. O curso de 2008 usava o método [HttpUtility.UrlEncode] para isso; hoje usamos [Uri.EscapeDataString] para um valor a ser colocado em uma URL, e a própria classe [FormUrlEncodedContent]codifica um formulário.

Os métodos de [HttpClient] para enviar dados são [PostAsync], [PutAsync] e [PatchAsync]. Eles recebem uma URL e o documento a ser enviado, um objeto derivado de [HttpContent]:

Classe
Documento enviado
FormUrlEncodedContent
um formulário, construído a partir de uma coleção de pares (nome, valor)
StringContent
texto, com sua codificação e seu tipo ([text/plain], [application/json]…)
ByteArrayContent, StreamContent
bytes arbitrários, um fluxo (um arquivo, por exemplo)
MultipartFormDataContent
um formulário contendo arquivos ([multipart/form-data])
JsonContent
um objeto transformado em JSON (namespace [System.Net.Http.Json])

O programa [internet-13.cs] é o seguinte:

using System.Text;

// enviar dados ao servidor: parâmetros de URL (GET), formulário e texto (POST)
// o servidor de teste [internet-10.cs] deve estar em execução na porta 27210

using var client = new HttpClient { BaseAddress = new Uri("http://localhost:27210/") };

// 1 - GET: os parâmetros fazem parte da URL; devem ser codificados nela
string name = "Jean & Marie";
string url = $"hello?name={Uri.EscapeDataString(name)}";
Console.WriteLine($"--- GET {url}");
Console.WriteLine(await client.GetStringAsync(url));

// 2 - POST de um formulário: os parâmetros formam o documento enviado ao servidor
var form = new FormUrlEncodedContent(
[
    new("name", "Jean & Marie"),
    new("age", "42"),
    new("city", "Angers"),
]);
// o documento como será enviado
Console.WriteLine($"--- POST form, document sent: {await form.ReadAsStringAsync()}");
using (HttpResponseMessage response = await client.PostAsync("form", form))
{
    response.EnsureSuccessStatusCode();
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

// 3 - POST de um texto qualquer, com seu tipo
var text = new StringContent("summer and winter", Encoding.UTF8, "text/plain");
Console.WriteLine("--- POST text");
using (HttpResponseMessage response = await client.PostAsync("text", text))
{
    response.EnsureSuccessStatusCode();
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

Resultados:

1
2
3
4
5
6
7
8
9
> dotnet run internet-13.cs
--- GET hello?name=Jean%20%26%20Marie
Hello Jean & Marie!
--- POST form, document sent: name=Jean+%26+Marie&age=42&city=Angers
Content-Type received: application/x-www-form-urlencoded
Fields received: name=[Jean & Marie], age=[42], city=[Angers]
--- POST text
Content-Type received: text/plain; charset=utf-8
Text received in upper case: SUMMER AND WINTER

Comentários:

  • Linhas 9–10: o valor [Jean & Marie] é colocado dentro da URL. Sem codificação, o caractere [&] seria interpretado como o separador entre dois parâmetros, e o servidor receberia o parâmetro [name] com o valor [Jean]. Na linha 2 dos resultados, vemos que o espaço virou [%20] e o caractere [&] virou [%26]: é o código hexadecimal do caractere, precedido de [%];
  • Linhas 15–19: o formulário é construído a partir de uma coleção de pares, [KeyValuePair<string, string>]; como o tipo de cada elemento é conhecido, [new(...)] é suficiente;
  • linha 22: para verificar isso, lemos o documento que será enviado: na linha 4 dos resultados, encontramos o formato [name=value&name=value]. Em um formulário, um espaço é codificado como [+];
  • linha 23: o formulário é enviado com o método [POST] para a URL [/form]. O servidor indica (linhas 5–6) que recebeu um documento do tipo [application/x-www-form-urlencoded] e que extraiu e decodificou os três campos dele;
  • linha 30: texto, codificado em UTF-8, do tipo [text/plain]. O servidor o devolve em maiúsculas (linha 9).

Observe os blocos [using (...) { ... }]: não poderíamos usar uma declaração [using] aqui, pois há duas variáveis [response] no mesmo bloco de código. A diferença entre [GET] e [POST], observada no curso de 2008, continua válida: um navegador exibe na barra de endereços os parâmetros de uma requisição [GET], e não os de uma requisição [POST]; além disso, uma requisição [GET] deve ser usada apenas para obter informações, enquanto uma requisição [POST] serve para enviar informações ou modificar o estado do servidor.

12.7.2.5. Trocando objetos no formato JSON

Atualmente, os aplicativos trocam a maior parte de seus dados no formato JSON, descrito no Capítulo 5. O namespace [System.Net.Http.Json] adiciona métodos de extensão a [HttpClient] e a [HttpContent] que, em uma única instrução, realizam a requisição HTTP e a conversão entre objetos e JSON usando [System.Text.Json]:

Método
Função
Task<T?> GetFromJsonAsync<T>(string url)
obtém a URL por [GET] e converte o documento JSON recebido em um objeto do tipo [T]
Task<HttpResponseMessage> PostAsJsonAsync<T>(string url, T object)
envia o objeto, convertido em JSON, por [POST] (tipo [application/json]) e retorna a resposta. [PutAsJsonAsync] faz o mesmo com o método [PUT]
Task<T?> ReadFromJsonAsync<T>()
Método de [HttpContent]: converte o documento JSON de uma resposta em um objeto do tipo [T]

O programa [internet-14.cs] é o seguinte:

#:property PublishAot=false
using System.Net.Http.Json;

// trocar objetos no formato JSON com um servidor web
// o servidor de teste [internet-10.cs] deve estar em execução na porta 27210

using var client = new HttpClient { BaseAddress = new Uri("http://localhost:27210/") };

// 1 - a lista de pessoas: o documento JSON é transformado diretamente em objetos
List<Person>? persons = await client.GetFromJsonAsync<List<Person>>("api/persons");
Console.WriteLine("--- list of persons");
foreach (Person person in persons ?? [])
{
    Console.WriteLine(person);
}

// 2 - uma pessoa
Person? durand = await client.GetFromJsonAsync<Person>("api/persons/2");
Console.WriteLine($"--- person no. 2: {durand}");

// 3 - adição de uma pessoa: o objeto é enviado no formato JSON
var martin = new Person(0, "Martin", 25);
using (HttpResponseMessage response = await client.PostAsJsonAsync("api/persons", martin))
{
    Console.WriteLine($"--- addition of {martin}");
    Console.WriteLine($"Status: {(int)response.StatusCode} {response.ReasonPhrase}, Location: {response.Headers.Location}");
    // o documento JSON recebido, bruto e depois como objeto
    Console.WriteLine($"JSON received: {await response.Content.ReadAsStringAsync()}");
    Person? created = await response.Content.ReadFromJsonAsync<Person>();
    Console.WriteLine($"Person created: {created}");
}

// 4 - uma pessoa que não existe
try
{
    await client.GetFromJsonAsync<Person>("api/persons/99");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"--- person no. 99: {ex.GetType().Name} : {ex.Message}");
}

// uma pessoa: o mesmo tipo que no lado do servidor
record Person(int Id, string Name, int Age);

Resultados:

> dotnet run internet-14.cs
--- list of persons
Person { Id = 1, Name = Dupont, Age = 42 }
Person { Id = 2, Name = Durand, Age = 35 }
--- person no. 2: Person { Id = 2, Name = Durand, Age = 35 }
--- addition of Person { Id = 0, Name = Martin, Age = 25 }
Status: 201 Created, Location: /api/persons/3
JSON received: {"id":3,"name":"Martin","age":25}
Person created: Person { Id = 3, Name = Martin, Age = 25 }
--- person no. 99: HttpRequestException : Response status code does not indicate success: 404 (Not Found).

Comentários:

  • Linha 1: como no servidor, reabilitamos a serialização JSON por reflexão. A outra solução, discutida no Capítulo 6 para a camada [dao] da Versão 5, é um contexto de serialização gerado em tempo de compilação ([JsonSerializerContext]): cada um dos métodos acima tem uma sobrecarga que o aceita;
  • Linha 10: a lista de pessoas. O documento JSON [[{"id":1,"name":"Dupont","age":42},...]] enviado pelo servidor é convertido diretamente em uma lista de objetos [Person]. O resultado é do tipo [List<Person>?]: o documento JSON poderia ser [null];
  • linha 12: se for o caso, uma lista vazia é percorrida;
  • linha 18: uma única pessoa;
  • linha 23: o objeto [martin] é convertido em JSON e enviado ao servidor. O servidor responde com o código de status 201 (Created) e o cabeçalho [Location], que fornece a URL do novo recurso (linha 7 dos resultados);
  • linha 28: o documento JSON recebido: os nomes das propriedades estão no formato “camelCase” ([id], [name], [age]), seguindo as convenções da web. Os métodos de [System.Net.Http.Json] usam as opções [JsonSerializerDefaults.Web], que realizam a conversão com as propriedades C# [Id], [Name] e [Age];
  • linha 29: o mesmo documento, convertido em objeto. Observe que o documento pode ter sido lido duas vezes: [HttpClient] o manteve em memória, pois a requisição foi feita sem a opção [HttpCompletionOption.ResponseHeadersRead], que abordaremos mais adiante;
  • linhas 34–40: como [GetStringAsync], [GetFromJsonAsync] lança uma [HttpRequestException] se o código de status indicar um erro.

Voltaremos a esses métodos no próximo capítulo, em que o servidor de cálculo de imposto se tornará um serviço web JSON.

12.7.2.6. Timeout, cancelamento e reutilização do cliente

O programa [internet-15.cs] ilustra três pontos importantes para o uso de [HttpClient] em um aplicativo real:

using System.Diagnostics;

// timeout, cancelamento e reutilização de um HttpClient
// o servidor de teste [internet-10.cs] deve estar em execução na porta 27210

// 1 - uma única instância de HttpClient para toda a aplicação
//     timeout de 2 segundos para cada requisição
var client = new HttpClient
{
    BaseAddress = new Uri("http://localhost:27210/"),
    Timeout = TimeSpan.FromSeconds(2),
};

// 2 - requisições sucessivas: a mesma conexão TCP é reutilizada
Console.WriteLine("--- three successive requests");
for (int i = 1; i <= 3; i++)
{
    Console.WriteLine(await client.GetStringAsync($"hello?name=trial{i}"));
}

// 3 - uma resposta obtida dentro do timeout, depois uma resposta lenta demais
foreach (int seconds in (int[])[1, 3])
{
    Console.WriteLine($"--- response in {seconds} s expected");
    try
    {
        Console.WriteLine(await client.GetStringAsync($"slow?seconds={seconds}"));
    }
    catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
    {
        Console.WriteLine($"{ex.GetType().Name} : {ex.Message}");
    }
}

// 4 - uma requisição cancelada pelo programa após meio segundo
Console.WriteLine("--- cancellation after 0.5 s");
using (var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(0.5)))
{
    try
    {
        Console.WriteLine(await client.GetStringAsync("slow?seconds=1", cancellation.Token));
    }
    catch (TaskCanceledException ex) when (cancellation.IsCancellationRequested)
    {
        Console.WriteLine($"Request cancelled ({ex.GetType().Name})");
    }
}

// 5 - quatro requisições simultâneas com o mesmo cliente
Console.WriteLine("--- four simultaneous requests of one second each");
var stopwatch = Stopwatch.StartNew();
string[] responses = await Task.WhenAll(
    Enumerable.Range(1, 4).Select(_ => client.GetStringAsync("slow?seconds=1")));
foreach (string response in responses)
{
    Console.WriteLine(response);
}
Console.WriteLine($"Total duration: {stopwatch.Elapsed.TotalSeconds:F1} s");

Resultados:

> dotnet run internet-15.cs
--- three successive requests
Hello trial1!
Hello trial2!
Hello trial3!
--- response in 1 s expected
Response obtained after 1 s
--- response in 3 s expected
TaskCanceledException : The request was canceled due to the configured HttpClient.Timeout of 2 seconds elapsing.
--- cancellation after 0.5 s
Request cancelled (TaskCanceledException)
--- four simultaneous requests of one second each
Response obtained after 1 s
Response obtained after 1 s
Response obtained after 1 s
Response obtained after 1 s
Total duration: 1.0 s

Comentários:

  • Linha 8: uma única instância de [HttpClient] é usada por todo o programa. Essa é a regra: um objeto [HttpClient] gerencia um pool de conexões e as reutiliza de uma requisição para a seguinte; ele foi projetado para ter vida longa e pode ser usado por várias tarefas simultaneamente. Criar um [HttpClient] para cada requisição, dentro de um [using], é um erro clássico: cada instância abre suas próprias conexões, que o sistema mantém em reserva por algum tempo depois de fechadas (estado TIME_WAIT do TCP); um programa que faz muitas requisições acaba esgotando as portas disponíveis. Incluímos [using] nos programas anteriores porque eles faziam apenas algumas requisições antes de terminar;
  • linha 11: cada requisição deve receber uma resposta em no máximo 2 segundos;
  • linhas 16–18: três requisições sucessivas. Veremos no log do servidor que elas usaram a mesma conexão (TCP);
  • linhas 22–29: uma resposta que chega em 1 segundo, seguida de uma resposta que levaria 3 segundos: após 2 segundos, a requisição é abandonada e uma [TaskCanceledException] é lançada (linha 9 dos resultados). A expressão [(int[])[1, 3]] atribui um tipo à expressão de coleção, que não tem um por si só;
  • linhas 37–45: um cancelamento iniciado pelo programa. Todos os métodos de [HttpClient] aceitam um token de cancelamento, assim como os métodos assíncronos discutidos no Capítulo 9. Aqui, o token é cancelado automaticamente após meio segundo (construtor [CancellationTokenSource(TimeSpan)]); em um aplicativo interativo, ele seria cancelado por um botão [Cancel] ou por Ctrl-C. A exceção é novamente uma [TaskCanceledException]; é o filtro [when (cancellation.IsCancellationRequested)] que distingue entre cancelamento e timeout;
  • Linhas 51–58: quatro requisições lançadas simultaneamente no mesmo cliente e depois processadas em conjunto por [Task.WhenAll] (Capítulo 9). Cada requisição levou um segundo para ser processada; o total levou um segundo (linha 17): as requisições foram processadas em paralelo.

O log do servidor [internet-10.cs] mostra todas as requisições recebidas desde o início desta seção:

> dotnet run internet-10.cs
Web server started on http://localhost:27210
GET /hello?name=Serge HTTP/1.1 (client port 45988) -> 200
GET /headers HTTP/1.1 (client port 45988) -> 200
GET /headers HTTP/1.1 (client port 45988) -> 200
GET / HTTP/1.1 (client port 45988) -> 200
GET /unknown HTTP/1.1 (client port 45988) -> 404
GET / HTTP/1.1 (client port 45996) -> 200
GET /old HTTP/1.1 (client port 46006) -> 302
GET /hello?name=visitor HTTP/1.1 (client port 46006) -> 200
GET /unknown HTTP/1.1 (client port 46018) -> 404
HEAD /loop HTTP/1.1 (client port 56222) -> 302
HEAD /loop HTTP/1.1 (client port 56222) -> 302
HEAD /loop HTTP/1.1 (client port 56222) -> 302
HEAD /loop HTTP/1.1 (client port 56222) -> 302
HEAD /error HTTP/1.1 (client port 56230) -> 500
GET /hello?name=Jean%20%26%20Marie HTTP/1.1 (client port 56262) -> 200
POST /form HTTP/1.1 (client port 56262) -> 200
POST /text HTTP/1.1 (client port 56262) -> 200
GET /api/persons HTTP/1.1 (client port 39124) -> 200
GET /api/persons/2 HTTP/1.1 (client port 39124) -> 200
POST /api/persons HTTP/1.1 (client port 39124) -> 201
GET /api/persons/99 HTTP/1.1 (client port 39124) -> 404
GET /hello?name=trial1 HTTP/1.1 (client port 39138) -> 200
GET /hello?name=trial2 HTTP/1.1 (client port 39138) -> 200
GET /hello?name=trial3 HTTP/1.1 (client port 39138) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 39138) -> 200
GET /slow?seconds=3 HTTP/1.1 (client port 39138) -> abandoned by the client
GET /slow?seconds=1 HTTP/1.1 (client port 39140) -> abandoned by the client
GET /slow?seconds=1 HTTP/1.1 (client port 39156) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 39168) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 39172) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 39170) -> 200
  • linhas 3–7: as cinco requisições de [internet-11.cs] chegaram pela mesma conexão (mesma porta do cliente): o cliente a manteve aberta entre as requisições;
  • linhas 9–10: a requisição redirecionada de [internet-12.cs] e a requisição ao novo endereço, feita automaticamente pela mesma conexão;
  • linhas 12–15: a requisição inicial e os três redirecionamentos que a seguiram antes de a conexão ser fechada;
  • Linhas 24–28: as requisições sucessivas de [internet-15.cs] usaram todas a mesma conexão. A requisição que demorou demais foi abandonada pelo cliente (linha 28): [HttpClient] fechou a conexão, e o servidor viu seu token [RequestAborted] ser revogado;
  • linha 29: a requisição cancelada pelo programa precisou abrir uma nova conexão, já que a anterior havia sido fechada;
  • as quatro últimas linhas: as quatro requisições simultâneas usaram quatro conexões diferentes, abertas especificamente para isso. No HTTP/1.1, uma conexão transporta apenas uma requisição por vez; o HTTP/2 permitiria enviar todas elas por uma única conexão.

Um programa que permanece ativo por muito tempo (um servidor, um serviço do sistema) deve levar em conta um último ponto: um único [HttpClient] mantém suas conexões indefinidamente e, portanto, não detecta mudanças nos endereços IP dos servidores consultados, que o DNS revelaria. Para resolver isso, define-se um tempo de vida máximo das conexões por meio da propriedade [PooledConnectionLifetime] do handler [SocketsHttpHandler] (por exemplo, dois minutos). Em aplicativos baseados no .NET Generic Host ([Microsoft.Extensions.Hosting]) e no ASP.NET Core, os objetos [HttpClient] são obtidos, em vez disso, por meio da interface [IHttpClientFactory]: declarada com [services.AddHttpClient()] (pacote [Microsoft.Extensions.Http]), essa fábrica fornece clientes configurados (endereço base, cabeçalhos, timeout) e gerencia por conta própria seus handlers e tempos de vida. O leitor a encontrará na documentação do ASP.NET Core.

12.7.3. Aplicação: um cliente proxy para um serviço web de tradução

Vamos demonstrar agora como [HttpClient] permite usar recursos da web, mesmo quando esses recursos não foram concebidos para uso por um programa.

12.7.3.1. A aplicação

O curso de 2008 usava o site de tradução [trans.voila.fr]. Os usuários digitavam um texto, escolhiam o sentido da tradução (“francês para inglês” etc.) em uma lista suspensa, clicavam em um botão e recebiam uma página HTML contendo a tradução. O curso criava uma classe [TranslationService] que realizava a mesma tarefa por programação: ela construía a URL da requisição, a enviava ao site e extraía a tradução da página HTML recebida por meio de uma expressão regular. Uma interface gráfica Windows Forms se apoiava nessa classe; chama-se isso de cliente “proxy”: a classe [TranslationService] atua como substituta do site e o oculta do usuário.

Esse site não existe mais, e nossa máquina de teste não tem acesso à Internet. Mantemos o conceito substituindo o site por um pequeno site local que o imita: ele tem o mesmo formulário (uma caixa de texto, uma lista suspensa de sentidos de tradução escritos como no site de 2008) e exibe a tradução no mesmo lugar de sua página. Suas “traduções” são feitas palavra por palavra com pequenos dicionários: o que nos interessa é a técnica do cliente, não a qualidade da tradução. A interface gráfica é substituída por um programa de teste de console, como o do curso de 2008. A arquitetura é a seguinte:

Image

12.7.3.2. O site de tradução

O programa [internet-16.cs] é o seguinte:

#:sdk Microsoft.NET.Sdk.Web
using System.Net;
using System.Text;
using System.Text.RegularExpressions;

// um pequeno site de "tradução" palavra por palavra, que imita o site consultado pelo curso de 2008
// chamada: dotnet run internet-16.cs [-- port]
int port = args.Length == 1 && int.TryParse(args[0], out int p) ? p : 27220;

// os sentidos de tradução: código -> (rótulo, dicionário)
var translationDirections = new Dictionary<string, (string Label, Dictionary<string, string> Words)>
{
    ["fe"] = ("French &rarr; English", new()
    {
        ["ce"] = "this", ["chien"] = "dog", ["est"] = "is", ["perdu"] = "lost", ["malade"] = "sick",
        ["l'"] = "the ", ["été"] = "summer", ["sera"] = "will be", ["chaud"] = "hot",
    }),
    ["ef"] = ("English &rarr; French", new()
    {
        ["my"] = "mon", ["tailor"] = "tailleur", ["is"] = "est", ["rich"] = "riche",
        ["this"] = "ce", ["dog"] = "chien", ["lost"] = "perdu",
    }),
    ["fs"] = ("French &rarr; Spanish", new()
    {
        ["ce"] = "este", ["chien"] = "perro", ["est"] = "está", ["perdu"] = "perdido",
        ["l'"] = "el ", ["été"] = "verano", ["sera"] = "será", ["chaud"] = "caliente",
    }),
};

var builder = WebApplication.CreateBuilder(args);
builder.Logging.SetMinimumLevel(LogLevel.Warning);
var app = builder.Build();

// acompanhamento das requisições no console
app.Use(async (context, next) =>
{
    await next(context);
    var request = context.Request;
    Console.WriteLine($"{request.Method} {request.Path}{request.QueryString} -> {context.Response.StatusCode}");
});

// a página de tradução: o formulário, seguido da tradução se um texto foi fornecido
app.MapGet("/translation", (string? direction, string? text) =>
{
    var page = new StringBuilder();
    page.Append("""
        <!DOCTYPE html>
        <html lang="en">
        <head><meta charset="utf-8"><title>Translator of the C# course</title></head>
        <body>
        <h1>Translation of texts</h1>
        <form action="/translation" method="get">
        <textarea name="text" rows="4" cols="60"></textarea>
        <select name="direction">

        """);
    // a lista dos sentidos de tradução, escrita como em 2008: tags <option> não fechadas
    foreach ((string code, (string label, _)) in translationDirections)
    {
        page.Append($"    <option value='{code}'>{label}\n");
    }
    page.Append("""
        </select>
        <input type="submit" value="Translate">
        </form>

        """);
    // a tradução, se houver um texto a traduzir
    if (!string.IsNullOrWhiteSpace(text))
    {
        if (direction is not null && translationDirections.TryGetValue(direction, out var translator))
        {
            // tradução palavra por palavra; uma palavra desconhecida é deixada como está
            string translation = Regex.Replace(text.Trim().ToLower(), @"\w+'?",
                word => translator.Words.GetValueOrDefault(word.Value, word.Value));
            page.Append($"<strong>Translated text: </strong><div class=\"txtTrans\">{WebUtility.HtmlEncode(translation)}</div>\n");
        }
        else
        {
            page.Append("<p>Unknown translation direction</p>\n");
        }
    }
    page.Append("</body>\n</html>\n");
    return Results.Content(page.ToString(), "text/html; charset=utf-8");
});

Console.WriteLine($"Translation service started on http://localhost:{port}/translation");
app.Run($"http://127.0.0.1:{port}");

Comentários:

  • Linhas 11–26: os três sentidos de tradução propostos, com seus códigos ([fe] para francês → inglês, como no site de 2008), seus rótulos e seus dicionários. Os rótulos contêm entidades HTML ([&rarr;] para [→]), exatamente como os do site original;
  • linha 43: a página única do site, [/translation], pode receber dois parâmetros: o sentido da tradução [direction] e o texto [text];
  • linhas 58–60: a lista suspensa. Como no site de 2008, as tags [<option>] não são fechadas: o HTML dos sites reais nem sempre é muito limpo, e nosso cliente terá de contornar isso;
  • linhas 74–75: a tradução palavra por palavra. A expressão regular [\w+'?] corresponde a uma palavra, possivelmente seguida de um apóstrofo ([l'], [d']); cada palavra é substituída por sua tradução, ou mantida como está se for desconhecida;
  • linha 76: a tradução é colocada dentro de uma tag [<div class="txtTrans">], como no site de 2008. Ela é codificada com [WebUtility.HtmlEncode]: os caracteres que têm um significado em HTML ([<], [&]…) e, com esse método, as letras acentuadas são substituídos por entidades;
  • Linha 80: um sentido de tradução desconhecido resulta em uma página sem tradução.

Eis a página gerada com [curl] para a tradução de [l'été sera chaud] para o espanhol; observe a codificação do texto na URL:

> curl "http://localhost:27220/translation?direction=fs&text=l%27%C3%A9t%C3%A9%20sera%20chaud"
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Translator of the C# course</title></head>
<body>
<h1>Translation of texts</h1>
<form action="/translation" method="get">
<textarea name="text" rows="4" cols="60"></textarea>
<select name="direction">
    <option value='fe'>French &rarr; English
    <option value='ef'>English &rarr; French
    <option value='fs'>French &rarr; Spanish
</select>
<input type="submit" value="Translate">
</form>
<strong>Translated text: </strong><div class="txtTrans">el verano ser&#225; caliente</div>
</body>
</html>

Para escrever o cliente, precisamos, como em 2008:

  • saber o que o site espera: uma requisição [GET /translation?direction=code&text=encoded text]. Em um site real, isso pode ser descoberto olhando a URL exibida pelo navegador após uma tradução, ou o atributo [action] do formulário;
  • saber onde, nas páginas recebidas, está a informação que nos interessa: os sentidos de tradução estão nas tags [<option value='code'>label] da lista suspensa (linha 10 da página acima), e a tradução está na tag [<div class="txtTrans">] (linha 16). Isso pode ser descoberto exibindo o código-fonte da página no navegador.

Duas expressões regulares (Capítulo 5) permitem extrair essas informações:

  • [<option[^>]*value='(\w+)'>([^<\r\n]+)]: uma tag [<option], seguida de caracteres diferentes de [>], [value='], o código (primeiro grupo), [>] e, depois, o rótulo — isto é, os caracteres que seguem até o próximo [<] ou o fim da linha (segundo grupo);
  • [<div class="txtTrans">(.*?)</div>]: a tradução é o texto (primeiro grupo) entre a tag de abertura e a primeira tag [</div>] que a segue. O quantificador [*?] é “preguiçoso” (lazy): ele consome o menor número possível de caracteres.

12.7.3.3. O cliente TranslationService

O curso de 2008 dividia o cliente em dois projetos: uma biblioteca para a classe [TranslationService] e sua interface, e um aplicativo Windows Forms para a interface gráfica, configurado pelo Spring.NET. Para simplificar, reunimos a interface [ITranslationService], sua implementação [TranslationService], a exceção [TranslationException], e o programa de teste em um único arquivo de aplicativo. O programa [internet-17.cs] é o seguinte:

using System.Net;
using System.Text.RegularExpressions;

// cliente "proxy" de um serviço web de tradução: a classe TranslationService
// oculta do programa o diálogo HTTP e a análise das páginas HTML do site de tradução
// chamada: dotnet run internet-17.cs [-- siteUrl]   (por padrão http://localhost:27220/)

string siteUrl = args.Length == 1 ? args[0] : "http://localhost:27220/";
using var client = new HttpClient { BaseAddress = new Uri(siteUrl), Timeout = TimeSpan.FromSeconds(10) };
try
{
    // criação do serviço de tradução: ele consulta o site para conhecer os idiomas traduzidos
    ITranslationService service = await TranslationService.CreateAsync(client);
    Console.WriteLine("Translation directions offered by the site:");
    foreach ((string code, string label) in service.TranslatedLanguages)
    {
        Console.WriteLine($"  {code} : {label}");
    }
    // algumas traduções
    (string Text, string Direction)[] trials =
    [
        ("ce chien est perdu", "fe"),
        ("l'été sera chaud", "fs"),
        ("my tailor is rich", "ef"),
        ("xx", "ef"),
        ("", "fe"),
        ("bonjour", "fx"),
    ];
    foreach ((string text, string direction) in trials)
    {
        try
        {
            string translation = await service.TranslateAsync(text, direction);
            Console.WriteLine($"Translation [{service.TranslatedLanguages[direction]}] of [{text}]: [{translation}]");
        }
        catch (TranslationException e)
        {
            Console.WriteLine($"The following error with code {e.Code} occurred: {e.Message}");
        }
    }
}
catch (TranslationException e)
{
    Console.WriteLine($"The following error with code {e.Code} occurred: {e.Message}");
    if (e.InnerException is Exception cause)
    {
        Console.WriteLine($"Cause: {cause.GetType().Name} : {cause.Message}");
    }
}

// --------------------------------------------------------------------
// a interface apresentada ao programa
interface ITranslationService
{
    // os sentidos de tradução: código -> rótulo, por exemplo fe -> French → English
    IReadOnlyDictionary<string, string> TranslatedLanguages { get; }
    // tradução de um texto no sentido dado pelo seu código
    Task<string> TranslateAsync(string text, string direction);
}

// a exceção específica do serviço de tradução
class TranslationException : Exception
{
    public int Code { get; init; }
    public TranslationException(string message) : base(message) { }
    public TranslationException(string message, Exception inner) : base(message, inner) { }
}

// a implementação: um cliente HTTP do site de tradução
partial class TranslationService : ITranslationService
{
    // o cliente HTTP, fornecido pelo programa
    private readonly HttpClient client;
    public IReadOnlyDictionary<string, string> TranslatedLanguages { get; }

    // construtor privado: passamos pelo método de fábrica CreateAsync
    private TranslationService(HttpClient client, Dictionary<string, string> languages)
    {
        this.client = client;
        TranslatedLanguages = languages;
    }

    // as opções <option value='fe'>French &rarr; English do formulário
    [GeneratedRegex(@"<option[^>]*value='(\w+)'>([^<\r\n]+)")]
    private static partial Regex OptionRegex();

    // a tradução: <div class="txtTrans">...</div>
    [GeneratedRegex("""<div class="txtTrans">(.*?)</div>""")]
    private static partial Regex TranslationRegex();

    // criação do serviço: os sentidos de tradução são lidos do formulário do site
    public static async Task<TranslationService> CreateAsync(HttpClient client)
    {
        string page;
        try
        {
            page = await client.GetStringAsync("translation");
        }
        catch (Exception e) when (e is HttpRequestException or TaskCanceledException)
        {
            throw new TranslationException("The translation site is unreachable", e) { Code = 11 };
        }
        var languages = new Dictionary<string, string>();
        foreach (Match option in OptionRegex().Matches(page))
        {
            // as entidades HTML (&rarr;...) são decodificadas
            languages[option.Groups[1].Value] = WebUtility.HtmlDecode(option.Groups[2].Value.Trim());
        }
        if (languages.Count == 0)
        {
            throw new TranslationException("The site gives no translation direction") { Code = 13 };
        }
        return new TranslationService(client, languages);
    }

    // tradução
    public async Task<string> TranslateAsync(string text, string direction)
    {
        // a tradução solicitada é possível?
        if (!TranslatedLanguages.ContainsKey(direction))
        {
            throw new TranslationException($"The translation direction [{direction}] is not recognized") { Code = 10 };
        }
        // a URL a solicitar: o texto deve ser codificado
        string url = $"translation?direction={direction}&text={Uri.EscapeDataString(text)}";
        try
        {
            // esperamos apenas os cabeçalhos da resposta: o documento será lido progressivamente
            using HttpResponseMessage response = await client.GetAsync(url, HttpCompletionOption.ResponseHeadersRead);
            response.EnsureSuccessStatusCode();
            using var reader = new StreamReader(await response.Content.ReadAsStreamAsync());
            // procuramos a linha da tradução linha a linha e paramos assim que a encontramos
            while (await reader.ReadLineAsync() is string line)
            {
                Match result = TranslationRegex().Match(line);
                if (result.Success)
                {
                    return WebUtility.HtmlDecode(result.Groups[1].Value.Trim());
                }
            }
        }
        catch (Exception e) when (e is HttpRequestException or TaskCanceledException or IOException)
        {
            throw new TranslationException("Error encountered during the translation", e) { Code = 11 };
        }
        // a página não continha uma tradução
        throw new TranslationException("The server did not send back a translation") { Code = 12 };
    }
}

Comecemos pela interface e pela exceção:

  • linhas 53–58: a interface apresentada ao programa. A propriedade [TranslatedLanguages] é o dicionário dos sentidos de tradução aceitos pelo site, formado por entradas da forma [fe] → [French → English]; o método [TranslateAsync] traduz o texto [text] no sentido de código [direction]. Em 2008, o método era síncrono; agora ele é assíncrono, como os métodos de [HttpClient] que ele utiliza;
  • linhas 62–66: a exceção específica do serviço, com um código de erro, inspirada em [TaxException] (Capítulo 6).

A classe [TranslationService]:

  • linha 70: a classe é parcial ([partial]) porque o código de suas expressões regulares é gerado em tempo de compilação (atributo [GeneratedRegex], Capítulo 5);
  • linha 73: o serviço não cria seu próprio [HttpClient]; ele o recebe do programa, que determina sua configuração (endereço base, timeout) e seu tempo de vida;
  • linha 77: o construtor é privado. O serviço só pode ser criado depois de consultar o site, o que é uma operação assíncrona; porém, um construtor não pode ser assíncrono. Por isso, usa-se um método de construção estático, [CreateAsync];
  • linhas 84–89: as duas expressões regulares apresentadas acima. A primeira é um literal de cadeia verbatim [@"..."] (sem sequências de escape), a segunda um literal de cadeia bruto (raw) [""" ... """] (C# 11), que permite escrever as aspas de [class="txtTrans"] sem duplicá-las;
  • linhas 92–113: criação do serviço. O curso de 2008 guardava a lista de chaves de tradução no arquivo de configuração do Spring. Nós a lemos do próprio site, o que garante que esteja atualizada:
    • linha 97: solicitamos a página do formulário, sem nenhum parâmetro;
    • linha 99: um erro de comunicação é encapsulado em uma [TranslationException] com o código 11;
    • linhas 104–107: cada tag [<option>] encontrada pela expressão regular fornece um código (grupo 1) e um rótulo (grupo 2). [WebUtility.HtmlDecode] substitui as entidades HTML pelos caracteres que elas representam: [French &rarr; English] torna-se [French → English];
  • linhas 117–147: a tradução:
    • linhas 120–122: verifica-se se o sentido de tradução solicitado existe. O código de 2008 continha um erro aqui: [String.Format] era chamado sem o valor a ser inserido na mensagem; a interpolação de cadeias torna esse tipo de erro impossível;
    • Linha 125: a URL da requisição, na qual o texto é codificado;
    • Linha 129: [GetAsync] retorna a resposta assim que seus cabeçalhos chegam, sem esperar o documento. O curso de 2008 preferia [HttpWebRequest] a [WebClient] para que a página pudesse ser lida linha a linha e a leitura parasse assim que a tradução fosse encontrada; a opção [ResponseHeadersRead] permite fazer o mesmo com [HttpClient];
    • linhas 131–138: o documento é lido à medida que chega, linha a linha, e a tradução é procurada em cada linha. Assim que é encontrada, é retornada, decodificada; as instruções [using] fecham o fluxo e liberam a resposta, e o restante da página nunca é lido;
    • linha 142: um erro de comunicação lança uma exceção de código 11;
    • linha 147: se a página tiver sido lida por inteiro sem que se encontre uma tradução, uma exceção de código 12 é lançada.

O programa de teste:

  • linha 8: o endereço do site pode ser passado como argumento;
  • linha 9: o cliente HTTP da aplicação;
  • linha 13: criação do serviço. O programa passa então a interagir com o serviço somente por meio de sua interface [ITranslationService];
  • linhas 20–27: os casos de teste do curso de 2008, mais dois casos de erro: um texto vazio e um sentido de tradução desconhecido. O array é um array de tuplas nomeadas (C# 7);
  • linha 29: cada tupla é desconstruída em duas variáveis.

Resultados, com o site [internet-16.cs] iniciado em outra janela:

> dotnet run internet-17.cs
Translation directions offered by the site:
  fe : French → English
  ef : English → French
  fs : French → Spanish
Translation [French → English] of [ce chien est perdu]: [this dog is lost]
Translation [French → Spanish] of [l'été sera chaud]: [el verano será caliente]
Translation [English → French] of [my tailor is rich]: [mon tailleur est riche]
Translation [English → French] of [xx]: [xx]
The following error with code 12 occurred: The server did not send back a translation
The following error with code 10 occurred: The translation direction [fx] is not recognized
  • linhas 3–5: os sentidos de tradução foram lidos do formulário do site, e as entidades HTML foram decodificadas;
  • linha 9: uma palavra desconhecida é reproduzida como está, exatamente como fazia o site de 2008;
  • linha 10: para um texto vazio, o site devolveu seu formulário sem tradução;
  • linha 11: a tradução [fx] foi rejeitada pelo serviço sem consultar o site.

Se o site estiver indisponível:

1
2
3
> dotnet run internet-17.cs -- http://localhost:27299/
The following error with code 11 occurred: The translation site is unreachable
Cause: HttpRequestException : Connection refused (localhost:27299)

Do lado do site, vemos a requisição de [curl] mostrada acima, seguida das enviadas pelo cliente: a primeira para o formulário, as seguintes para as traduções (a requisição [fx], rejeitada pelo serviço, não gerou nenhuma requisição):

1
2
3
4
5
6
7
8
9
> dotnet run internet-16.cs
Translation service started on http://localhost:27220/translation
GET /translation?direction=fs&text=l%27%C3%A9t%C3%A9%20sera%20chaud -> 200
GET /translation -> 200
GET /translation?direction=fe&text=ce%20chien%20est%20perdu -> 200
GET /translation?direction=fs&text=l%27%C3%A9t%C3%A9%20sera%20chaud -> 200
GET /translation?direction=ef&text=my%20tailor%20is%20rich -> 200
GET /translation?direction=ef&text=xx -> 200
GET /translation?direction=fe&text= -> 200

12.7.3.4. Conclusão

Esta aplicação demonstrou que [HttpClient] nos permite aproveitar recursos da web. A técnica é sempre a mesma:

  • determinar qual URL consultar. Em geral, ela é pré-configurada;
  • consultá-la;
  • encontrar o que procuramos na resposta do servidor por meio de expressões regulares.

Essa técnica, hoje conhecida como “web scraping”, é frágil: com o tempo, a URL consultada ou a estrutura da página podem mudar, e a expressão regular que antes encontrava o resultado pode deixar de funcionar. É uma boa ideia guardar essas informações em um arquivo de configuração, mas isso nem sempre basta; além disso, os termos de uso de muitos sites a proíbem. Uma análise robusta de uma página HTML seria, na verdade, mais bem feita com uma biblioteca especializada (AngleSharp, HtmlAgilityPack) do que com expressões regulares. No próximo capítulo, veremos que existem recursos mais estáveis na Web, concebidos para uso por programas: os serviços web. Os serviços de tradução atuais, por exemplo, oferecem todos uma interface desse tipo, que aceita e retorna JSON.

12.7.4. Um cliente SMTP com a classe SmtpClient

Um cliente SMTP é um cliente de um servidor SMTP — um servidor de envio de e-mails — cujo protocolo descrevemos na Parte 1. A classe [SmtpClient] do namespace [System.Net.Mail] encapsula as exigências desse tipo de cliente: o desenvolvedor não precisa conhecer os detalhes do protocolo SMTP nem os do formato de mensagem MIME. Ela é acompanhada das classes [MailMessage] (uma mensagem), [MailAddress] (um endereço de e-mail) e [Attachment] (um anexo).

A classe [SmtpClient] ainda existe no .NET 10 e não foi declarada obsoleta, mas sua documentação afirma que a Microsoft não a recomenda para novos desenvolvimentos: ela não oferece suporte a protocolos de autenticação modernos (OAuth 2.0, cada vez mais exigido pelos grandes provedores de e-mail) e não receberá mais atualizações. A documentação recomenda a biblioteca de código aberto MailKit (o pacote NuGet [MailKit]), que também permite ler e-mails em POP3 e IMAP. Como esse pacote não está disponível no ambiente do curso, apresentaremos [SmtpClient], cujos princípios básicos (uma mensagem, endereços, anexos e um cliente que a envia) são idênticos aos do MailKit.

O curso de 2008 apresentava [SmtpClient] em um aplicativo Windows Forms que enviava o e-mail para a porta 25 de um servidor SMTP real, depois de pedir ao usuário que desativasse a proteção do antivírus. Faremos algo mais simples e seguro: o e-mail será enviado a um pequeno servidor SMTP de teste escrito em C# e executado na máquina local, que exibirá tudo o que receber e não encaminhará nada. Para uso real, existem servidores de teste completos, como o Mailpit ou o smtp4dev, que também oferecem uma interface web para consultar as mensagens recebidas.

12.7.4.1. Um servidor SMTP de teste

Nosso servidor SMTP segue a estrutura do servidor de eco da Parte 1: um laço assíncrono que espera clientes, uma tarefa por cliente e um token de cancelamento acionado por Ctrl-C. O serviço prestado a cada cliente é o diálogo SMTP mínimo apresentado na Parte 1. O programa [internet-18.cs] é o seguinte:

using System.Net;
using System.Net.Sockets;
using System.Text;

// servidor SMTP de teste: ele executa o diálogo SMTP mínimo e exibe as mensagens recebidas,
// sem nunca entregá-las a seus destinatários
// chamada: dotnet run internet-18.cs [-- port]   (porta 27225 por padrão); pare com Ctrl-C
int port = args.Length == 1 && int.TryParse(args[0], out int p) ? p : 27225;

// Ctrl-C cancela o token: o servidor para de forma limpa
using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) =>
{
    e.Cancel = true;
    cancellation.Cancel();
};

// o servidor só aceita clientes da máquina local
var listener = new TcpListener(IPAddress.Loopback, port);
var services = new List<Task>();
int clientNumber = 0;
try
{
    listener.Start();
    Console.WriteLine($"Test SMTP server started on {listener.LocalEndpoint}");
    while (true)
    {
        TcpClient client = await listener.AcceptTcpClientAsync(cancellation.Token);
        services.Add(ServeAsync(client, clientNumber++, cancellation.Token));
        services.RemoveAll(service => service.IsCompleted);
    }
}
catch (OperationCanceledException)
{
    Console.WriteLine("Server stop requested");
}
finally
{
    listener.Stop();
}
await Task.WhenAll(services);

// --------------------------------------------------------------------
// o diálogo SMTP com um cliente: C: linhas recebidas do cliente, S: linhas enviadas pelo servidor
static async Task ServeAsync(TcpClient client, int clientNumber, CancellationToken token)
{
    Console.WriteLine($"--- start of the dialog with client {clientNumber} ({client.Client.RemoteEndPoint})");
    try
    {
        using (client)
        {
            NetworkStream stream = client.GetStream();
            using var reader = new StreamReader(stream, Encoding.UTF8);
            // o SMTP exige fins de linha \r\n
            await using var writer = new StreamWriter(stream, new UTF8Encoding(false)) { AutoFlush = true, NewLine = "\r\n" };

            // envio de uma linha de resposta, também exibida no console
            async Task ReplyAsync(string response)
            {
                Console.WriteLine($"S: {response}");
                await writer.WriteLineAsync(response);
            }

            // o envelope da mensagem atual: remetente e destinatários
            string? sender = null;
            List<string> recipients = [];
            // mensagem de boas-vindas
            await ReplyAsync("220 smtp.test ESMTP test server of the C# course");
            while (await reader.ReadLineAsync(token) is string command)
            {
                Console.WriteLine($"C: {command}");
                // o verbo: os quatro primeiros caracteres, sem diferenciar maiúsculas de minúsculas
                string verb = command.Length >= 4 ? command[..4].ToUpperInvariant() : command;
                switch (verb)
                {
                    case "EHLO":
                        // resposta de várias linhas: 250-... e depois 250 ...
                        await ReplyAsync("250-smtp.test hello");
                        await ReplyAsync("250-SIZE 10485760");
                        await ReplyAsync("250 8BITMIME");
                        break;
                    case "HELO":
                        await ReplyAsync("250 smtp.test hello");
                        break;
                    case "MAIL":
                        // MAIL FROM:<address>
                        sender = command[(command.IndexOf(':') + 1)..].Trim();
                        recipients.Clear();
                        await ReplyAsync("250 2.1.0 Ok");
                        break;
                    case "RCPT":
                        // RCPT TO:<address>
                        recipients.Add(command[(command.IndexOf(':') + 1)..].Trim());
                        await ReplyAsync("250 2.1.5 Ok");
                        break;
                    case "DATA" when sender is null || recipients.Count == 0:
                        await ReplyAsync("503 5.5.1 Give the sender and the recipients first");
                        break;
                    case "DATA":
                        await ReplyAsync("354 End data with <CR><LF>.<CR><LF>");
                        // a mensagem: todas as linhas até uma linha reduzida a um ponto
                        int nbLines = 0;
                        while (await reader.ReadLineAsync(token) is string line && line != ".")
                        {
                            Console.WriteLine($"C: {line}");
                            nbLines++;
                        }
                        Console.WriteLine("C: .");
                        Console.WriteLine($"[message from {sender} to {string.Join(", ", recipients)}: {nbLines} lines]");
                        await ReplyAsync("250 2.0.0 Ok: message accepted");
                        sender = null;
                        recipients.Clear();
                        break;
                    case "RSET":
                        sender = null;
                        recipients.Clear();
                        await ReplyAsync("250 2.0.0 Ok");
                        break;
                    case "NOOP":
                        await ReplyAsync("250 2.0.0 Ok");
                        break;
                    case "QUIT":
                        await ReplyAsync("221 2.0.0 Goodbye");
                        return;
                    default:
                        await ReplyAsync("502 5.5.2 Command not recognized");
                        break;
                }
            }
        }
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine($"Dialog with client {clientNumber} interrupted by the server stop");
    }
    catch (IOException ex)
    {
        Console.WriteLine($"The following error occurred with client {clientNumber}: {ex.Message}");
    }
    finally
    {
        Console.WriteLine($"--- end of the dialog with client {clientNumber}");
    }
}

Comentaremos apenas o que é novo em relação ao servidor de eco:

  • Linha 19: o servidor escuta apenas no endereço de loopback: somente programas da mesma máquina podem se conectar a ele;
  • linha 55: o SMTP exige finais de linha \r\n, qualquer que seja o sistema;
  • linhas 58–61: uma função local (C# 7) que envia uma linha de resposta ao cliente e a exibe no console, precedida de [S:]. As linhas recebidas do cliente são exibidas precedidas de [C:], como nos diálogos de exemplo da Parte 1;
  • linhas 65–66: o cabeçalho da mensagem atual: o remetente identificado por [MAIL FROM] e os destinatários identificados por [RCPT TO];
  • linha 68: a mensagem de boas-vindas: no SMTP, o servidor fala primeiro;
  • linha 73: o verbo do comando é formado pelos seus quatro primeiros caracteres ([EHLO], [MAIL], [RCPT]…), cuja caixa (maiúsculas ou minúsculas) é desconhecida;
  • Linhas 76–80: a resposta a [EHLO] é composta de várias linhas. Nelas, o servidor especifica suas capacidades: o tamanho máximo da mensagem ([SIZE]) e o suporte a caracteres codificados em 8 bits ([8BITMIME]);
  • linha 96: uma cláusula [case] pode ser complementada por uma condição [when]: o comando [DATA] é rejeitado se o remetente ou os destinatários não tiverem sido especificados;
  • linhas 99–110: a própria mensagem. O servidor convida o cliente a enviá-la (código 354), depois lê e exibe todas as linhas até uma linha reduzida a um único ponto, e confirma o recebimento (código 250);
  • linhas 122–124: o cliente terminou; o servidor responde e fecha a conexão, saindo do método;
  • linha 126: qualquer outro comando é rejeitado.

Este servidor não faz muitas verificações e não oferece suporte às extensões [STARTTLS] e [AUTH] : ele basta para observar o que [SmtpClient] envia.

12.7.4.2. O cliente SMTP

O programa [internet-19.cs] solicita pelo teclado os elementos do e-mail que o aplicativo gráfico de 2008 fazia o usuário informar em seu formulário e depois os envia ao servidor SMTP especificado como argumento:

using System.Net.Mail;
using System.Net.Mime;
using System.Text;

// envio de um e-mail com a classe SmtpClient
// chamada: dotnet run internet-19.cs -- smtpServer port
// os anexos são procurados na pasta atual

const string syntax = "Syntax: dotnet run internet-19.cs -- smtpServer port";
if (args.Length != 2 || !int.TryParse(args[1], out int port) || port is < 1 or > 65535)
{
    Console.WriteLine(syntax);
    return;
}
string server = args[0];

// entrada dos elementos do e-mail
string sender = Input("Sender");
string recipients = Input("Recipients (separated by commas)");
string copies = Input("Copy to (Cc)");
string blindCopies = Input("Blind copy to (Bcc)");
string subject = Input("Subject");
string attachments = Input("Attachments (separated by commas)");
// o texto: várias linhas, terminadas por uma linha vazia
Console.WriteLine("Text of the message (ended by an empty line):");
var text = new StringBuilder();
while (Console.ReadLine() is string line && line != "")
{
    text.AppendLine(line);
}

try
{
    // a mensagem
    using var message = new MailMessage
    {
        From = new MailAddress(sender),
        Subject = subject,
        Body = text.ToString(),
        // o texto é codificado em UTF-8 e transportado como está (8 bits)
        BodyEncoding = Encoding.UTF8,
        BodyTransferEncoding = TransferEncoding.EightBit,
    };
    // os endereços: Add aceita uma lista de endereços separados por vírgulas
    message.To.Add(recipients);
    if (copies != "")
    {
        message.CC.Add(copies);
    }
    if (blindCopies != "")
    {
        message.Bcc.Add(blindCopies);
    }
    // os anexos, designados pelo seu caminho
    foreach (string file in attachments.Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries))
    {
        message.Attachments.Add(new Attachment(file));
    }

    // o cliente SMTP: ele conhece o protocolo SMTP e o formato MIME das mensagens
    using var client = new SmtpClient(server, port);
    await client.SendMailAsync(message);

    // resumo do envio
    Console.WriteLine("Sending successful...");
    Console.WriteLine($"Subject: {message.Subject}");
    Console.WriteLine($"Recipients: {message.To}");
    Console.WriteLine($"Cc: {message.CC}");
    Console.WriteLine($"Bcc: {message.Bcc}");
    Console.WriteLine($"Attachments: {string.Join(", ", message.Attachments.Select(attachment => attachment.Name))}");
}
catch (Exception ex) when (ex is FormatException or SmtpException or IOException)
{
    Console.WriteLine($"The following error occurred: {ex.GetType().Name} : {ex.Message}");
    if (ex.InnerException is Exception cause)
    {
        Console.WriteLine($"Cause: {cause.GetType().Name} : {cause.Message}");
    }
}

// entrada de uma linha no teclado
static string Input(string label)
{
    Console.Write($"{label}: ");
    return Console.ReadLine()?.Trim() ?? "";
}

Comentários:

  • linhas 18–23: entrada dos elementos do e-mail, usando a função local [Input];
  • linhas 26–29: o texto da mensagem, em várias linhas, terminado por uma linha em branco;
  • linhas 35–42: a mensagem, criada com um inicializador de objeto:
    • [From]: o remetente, um objeto [MailAddress]. O construtor de [MailAddress] verifica o formato do endereço e lança uma [FormatException] se ele estiver incorreto;
    • [Subject], [Body]: o assunto e o corpo da mensagem;
    • [BodyEncoding], [BodyTransferEncoding]: o texto é codificado em UTF-8 e transmitido como está, em 8 bits (o servidor indicou que aceita esse formato). Sem essas duas propriedades, [SmtpClient] escolheria sua própria codificação (base64 ou quoted-printable), o que dificultaria a leitura do texto quando exibido pelo servidor;
  • Linhas 45–52: os destinatários, os do campo “Cc” (Carbon Copy, cópia) e os do campo “Bcc” (Blind Carbon Copy, cópia oculta). Os destinatários em “Bcc” recebem a mensagem, mas os demais destinatários não sabem disso. O método [Add] das coleções [To], [CC], e [Bcc] aceita uma lista de endereços separados por vírgulas; a versão de 2008 analisava a lista por conta própria com uma expressão regular;
  • linhas 55–57: os anexos, identificados pelo caminho do arquivo. Um caminho relativo é relativo ao diretório atual; em nossos testes, o arquivo [attachment.txt] fica no diretório [12-internet], a partir do qual o programa é iniciado;
  • linha 61: o cliente SMTP, com o nome do servidor e a porta. Para um servidor real, especificaríamos também [EnableSsl = true] (criptografia por [STARTTLS]) e as credenciais de conexão, [Credentials = new NetworkCredential("username", "password")];
  • linha 62: envio assíncrono da mensagem. O curso de 2008 usava o método síncrono [Send];
  • linhas 65–70: um resumo da transmissão;
  • Linha 72: um endereço inválido provoca um erro [FormatException]; um problema de envio provoca um erro [SmtpException]; um anexo não encontrado provoca um erro [FileNotFoundException], derivada de [IOException].

O servidor SMTP de teste é iniciado em uma janela de comando na porta 27225. Em outra janela, uma mensagem é enviada a dois destinatários, com um destinatário em cópia, um em cópia oculta e um anexo:

> dotnet run internet-19.cs -- localhost 27225
Sender: alice@example.org
Recipients (separated by commas): bob@example.com, carole@example.com
Copy to (Cc): david@example.com
Blind copy to (Bcc): eve@example.com
Subject: Minutes of the meeting at the café
Attachments (separated by commas): attachment.txt
Text of the message (ended by an empty line):
Hello,
here are the minutes of the meeting at the café.
Best regards,
Alice

Sending successful...
Subject: Minutes of the meeting at the café
Recipients: bob@example.com, carole@example.com
Cc: david@example.com
Bcc: eve@example.com
Attachments: attachment.txt

O arquivo [attachment.txt] contém duas linhas de texto. Eis o que o servidor exibiu:

> dotnet run internet-18.cs
Test SMTP server started on 127.0.0.1:27225
--- start of the dialog with client 0 (127.0.0.1:53546)
S: 220 smtp.test ESMTP test server of the C# course
C: EHLO vm
S: 250-smtp.test hello
S: 250-SIZE 10485760
S: 250 8BITMIME
C: MAIL FROM:<alice@example.org>
S: 250 2.1.0 Ok
C: RCPT TO:<bob@example.com>
S: 250 2.1.5 Ok
C: RCPT TO:<carole@example.com>
S: 250 2.1.5 Ok
C: RCPT TO:<eve@example.com>
S: 250 2.1.5 Ok
C: RCPT TO:<david@example.com>
S: 250 2.1.5 Ok
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: MIME-Version: 1.0
C: From: alice@example.org
C: To: bob@example.com, carole@example.com
C: Cc: david@example.com
C: Date: 3 Oct 2026 12:20:36 +0200
C: Subject: =?utf-8?B?TWludXRlcyBvZiB0aGUgbWVldGluZyBhdCB0aGUgY2Fmw6k=?=
C: Content-Type: multipart/mixed;
C:  boundary=--boundary_0_40431766-5e35-4c3f-a18f-31531f8834df
C: 
C: 
C: ----boundary_0_40431766-5e35-4c3f-a18f-31531f8834df
C: Content-Type: text/plain; charset=utf-8
C: Content-Transfer-Encoding: 8bit
C: 
C: Hello,
C: here are the minutes of the meeting at the café.
C: Best regards,
C: Alice
C: 
C: ----boundary_0_40431766-5e35-4c3f-a18f-31531f8834df
C: Content-Type: application/octet-stream; name=attachment.txt
C: Content-Transfer-Encoding: base64
C: Content-Disposition: attachment
C: 
C: VGhpcyBpcyB0aGUgYXR0YWNobWVudCBvZiB0aGUgdGVzdCBtYWlsLgpJdCBjb250YWlu
C: cyB0d28gbGluZXMuCg==
C: ----boundary_0_40431766-5e35-4c3f-a18f-31531f8834df--
C: 
C: 
C: .
[message from <alice@example.org> to <bob@example.com>, <carole@example.com>, <eve@example.com>, <david@example.com>: 29 lines]
S: 250 2.0.0 Ok: message accepted
C: QUIT
S: 221 2.0.0 Goodbye
--- end of the dialog with client 0
Server stop requested

Comentários:

  • linha 5: [SmtpClient] se apresenta com o nome da máquina;
  • linhas 9–17: o envelope da mensagem: o remetente, seguido de todos os destinatários, inclusive o destinatário em cópia oculta (BCC) ([eve@example.com]). O envelope determina a quem a mensagem é entregue;
  • linhas 21–28: os cabeçalhos da mensagem, que compõem o que os destinatários verão. Eles incluem os destinatários [To] e [Cc], mas não o destinatário em cópia oculta: é assim que a cópia oculta permanece escondida. O assunto contém um caractere acentuado; como os cabeçalhos só podem conter caracteres ASCII, ele foi codificado segundo o padrão RFC 2047: [=?utf-8?B?...?=] significa “texto UTF-8 codificado em Base64”;
  • linha 27: a mensagem está no formato MIME (Multipurpose Internet Mail Extensions, RFC 2045 e seguintes): ela é composta de várias partes, separadas por uma linha delimitadora ([boundary]) escolhida aleatoriamente por [SmtpClient];
  • linhas 32–38: a primeira parte, o texto da mensagem, em UTF-8 de 8 bits: ela é legível como está;
  • linhas 41–46: a segunda parte, o anexo, codificado em Base64. O Base64 codifica bytes arbitrários usando 64 caracteres do conjunto ASCII; o servidor de e-mail do destinatário não precisa conhecer a natureza do anexo;
  • linha 50: o fim da mensagem;
  • linha 51: nosso servidor recebeu uma mensagem para quatro destinatários;
  • linhas 53–54: [SmtpClient] encerra a troca;
  • linha 56: o servidor foi interrompido com Ctrl-C após os testes.

Um endereço inválido é rejeitado antes de qualquer mensagem ser enviada:

> dotnet run internet-19.cs -- localhost 27225
Sender: alice@example.org
Recipients (separated by commas): bob.example.com
Copy to (Cc): 
Blind copy to (Bcc): 
Subject: test
Attachments (separated by commas): 
Text of the message (ended by an empty line):
text

The following error occurred: FormatException : The specified string is not in the form required for an e-mail address.

Se o servidor SMTP estiver indisponível, uma [SmtpException] é lançada; sua exceção interna indica a causa:

> dotnet run internet-19.cs -- localhost 27299
Sender: alice@example.org
Recipients (separated by commas): bob@example.com
Copy to (Cc): 
Blind copy to (Bcc): 
Subject: test
Attachments (separated by commas): 
Text of the message (ended by an empty line):
text

The following error occurred: SmtpException : Failure sending mail.
Cause: SocketException : Connection refused

12.8. Um cliente TCP assíncrono genérico

O curso de 2008 dedicava aqui uma seção inteira a um cliente TCP assíncrono genérico, com uma interface gráfica Windows Forms: um campo para o nome e a porta do servidor, um [Connect] / [Disconnect] botão, uma caixa de texto para digitar as linhas a enviar e duas listas exibindo os eventos da conexão e a comunicação com o servidor. As interfaces gráficas deixaram de fazer parte deste curso, e este exemplo perdeu a maior parte de sua relevância: seu objetivo era demonstrar a programação assíncrona, que passou por uma transformação completa desde 2008.

O cliente de 2008 trabalhava diretamente com um objeto [Socket] e usava o modelo assíncrono da época, chamado APM (Asynchronous Programming Model): cada operação era dividida em um método [BeginXxx], que iniciava a operação e devolvia o controle imediatamente, e um método [EndXxx], chamado dentro de um método de callback executado por uma thread do pool ao final da operação. A conexão era escrita assim:

// início da conexão: o método connected será chamado de volta ao fim da operação
client.BeginConnect(Dns.GetHostEntry(serverName).AddressList[0], port, connected, client);
...
// o método de callback
private void connected(IAsyncResult result)
{
    Socket client = result.AsyncState as Socket;
    // fim da operação: lança uma exceção se a conexão falhou
    client.EndConnect(result);
    // início da leitura assíncrona dos dados enviados pelo servidor
    client.BeginReceive(data, 0, bufferSize, SocketFlags.None, read, client);
}

O método de callback [read] da operação de recepção tinha, por sua vez, de chamar [BeginReceive] para ler o restante dos dados, reconstruir as linhas a partir dos blocos de bytes recebidos (já que uma linha podia ser dividida entre dois blocos) e, como era executado em uma thread do pool, chamar o método [Invoke] do formulário para atualizar a interface gráfica. O código era extenso, e a lógica do diálogo ficava espalhada por vários métodos.

O modelo APM foi substituído pelo modelo baseado em tarefas (TAP, Task-based Asynchronous Pattern, introduzido com o .NET 4 em 2010) e pelas palavras-chave [async] / [await] (C# 5, 2012), apresentadas no Capítulo 9. O cliente TCP genérico da primeira parte ([internet-06.cs]) já é um cliente assíncrono: [ConnectAsync] substitui o par [BeginConnect] / [EndConnect]; uma tarefa de recepção que chama [ReadLineAsync] em um laço substitui a cadeia de callbacks de [BeginReceive]; e [StreamReader] se encarrega de reconstruir as linhas. O código se lê na ordem em que é executado, como um código síncrono. Em um aplicativo gráfico atual (WPF, WinUI, .NET MAUI), [await] também retoma a execução na thread da interface, eliminando a necessidade de chamadas a [Invoke].

A conclusão do curso de 2008 continua válida: a assincronia traz pouco benefício a um cliente com uma única conexão, além de uma interface que continua responsiva; ela é, no entanto, essencial para um servidor. Um servidor que atende seus clientes com operações bloqueantes prende uma thread por cliente; com operações assíncronas, bastam algumas threads para atender um grande número de clientes. É isso que faz o servidor do aplicativo de exemplo a seguir.

12.9. Aplicativo de exemplo, versão 8: servidor de cálculo de imposto

12.9.1. A arquitetura da nova versão

Vamos retomar o aplicativo de cálculo de imposto. Na versão 5 (Capítulo 6), ele consistia em três camadas, cada uma em sua própria biblioteca: [dao] (as faixas de imposto), [business] (o cálculo) e [ui] (o diálogo de console), montadas por injeção de dependência; as versões 6 e 7 substituíram a camada [dao] por acesso a banco de dados. O curso de 2008 partia da versão 7 (dados em um banco de dados, interface gráfica); nós partimos da versão 5, que é mais simples de executar: a nova versão funcionaria da mesma forma com a camada [dao] das versões 6 e 7.

Vamos distribuir essa arquitetura por duas máquinas:

Image

  • Uma máquina [server] hospeda as camadas [business] e [dao] da versão 5. Uma camada [server] é construída para permitir que clientes da rede consultem o serviço de cálculo de imposto por meio de um protocolo TCP baseado em texto;
  • uma máquina [client] hospeda a camada [ui] da versão 5. Uma nova camada [business], que atua como cliente do servidor (TCP), permite ao cliente consultar o serviço de cálculo de imposto.

A arquitetura muda de forma significativa: a versão 5 era um aplicativo monousuário; a versão 8 se torna um aplicativo cliente/servidor, e o servidor poderá atender vários clientes simultaneamente. No entanto, escreveremos apenas duas novas classes, [TaxServer] e [TaxBusinessTcp], e dois programas principais: todo o resto é reutilizado sem modificação.

A solução [TaxV8] consiste em dois projetos de console que referenciam os projetos da versão 5:

12-internet/TaxV8/
  TaxV8.slnx
  Tax.Server/
    Tax.Server.csproj          references to Tax.Dao and Tax.Business (V5)
    appsettings.json           configuration of the [dao] layer and of the server
    Program.cs                 integration of the layers, launch of the server
    TaxServer.cs               the [server] layer
  Tax.Client/
    Tax.Client.csproj          references to Tax.Business and Tax.Ui (V5)
    TaxBusinessTcp.cs          the [business] layer of the client: a TCP client
    Program.cs                 integration of the layers, dialog

12.9.2. O protocolo de comunicação

Mantemos o protocolo do servidor de 2008. Uma vez conectado o cliente, o servidor lhe envia uma mensagem de boas-vindas e depois aceita os comandos a seguir, um por linha, sem diferenciar maiúsculas de minúsculas:

Comando
Resposta do servidor
help
uma lista dos comandos aceitos, em quatro linhas
tax married nbChildren annualSalary
o imposto de uma pessoa casada (married vale [y]) ou de uma pessoa não casada ([n]) com [nbChildren] filhos e um salário anual de [annualSalary] euros, por exemplo, [4282] em resposta a [tax y 2 60000]; ou uma mensagem de erro, em uma linha
goodbye
a mensagem [Goodbye...]; o servidor então fecha a conexão

Qualquer outro comando recebe a resposta [Command not recognized. Use the help command.]

12.9.3. O servidor de cálculo de imposto

12.9.3.1. O projeto

O arquivo [Tax.Server.csproj] é o seguinte:

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </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>

  <ItemGroup>
    <!-- contêiner de injeção de dependência e leitura de um arquivo de configuração JSON -->
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.12" />
  </ItemGroup>

  <ItemGroup>
    <!-- o arquivo de configuração é copiado para junto do executável -->
    <None Update="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>
  • Linhas 12–13: as camadas [dao] e [business] da versão 5 são referenciadas por seus projetos. Os arquivos de dados [TaxData.txt] e [TaxData.json] do projeto [Tax.Dao] são copiados para a pasta de saída do servidor;
  • linhas 18–19: o contêiner de injeção de dependência e a leitura de um arquivo de configuração JSON, como na versão 5;
  • linha 24: o arquivo de configuração é copiado para junto do executável.

O arquivo de configuração [appsettings.json]:

{
  "Dao": {
    "Implementation": "FileTax",
    "File": "TaxData.txt"
  },
  "Server": {
    "Port": 27200,
    "Echo": true
  }
}
  • Linhas 2–4: a configuração da camada [dao], idêntica à da versão 5: as faixas de imposto são lidas do arquivo de texto [TaxData.txt];
  • Linhas 6–8: a porta de escuta do servidor e o eco do diálogo com os clientes no log do servidor. O servidor de 2008 tinha um console de administração (comandos [start port], [stop], [echo start], [echo stop], [status], [quit]); optamos por um arquivo de configuração e pelo encerramento via Ctrl-C, que são mais simples e mais condizentes com o funcionamento dos servidores modernos.

12.9.3.2. O programa principal

O arquivo [Program.cs] do servidor é o seguinte:

using Dao;
using Entities;
using Business;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Server;

// o servidor TCP de cálculo de imposto: configuração, integração das camadas, execução
TaxServer server;
try
{
    // leitura da configuração, ao lado do executável
    IConfiguration config = new ConfigurationBuilder()
        .SetBasePath(AppContext.BaseDirectory)
        .AddJsonFile("appsettings.json", optional: false)
        .Build();
    string implementation = config["Dao:Implementation"] ?? "HardwiredTax";
    string file = config["Dao:File"] ?? "";
    int port = int.TryParse(config["Server:Port"], out int p) ? p : 27200;
    bool echo = bool.TryParse(config["Server:Echo"], out bool e) && e;

    // registro das camadas no contêiner
    var services = new ServiceCollection();
    // a camada [dao]: a implementação é escolhida pela configuração (como na versão 5)
    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] da versão 5
    services.AddSingleton<ITaxBusiness, TaxBusiness>();
    // a camada [server]: o contêiner lhe passará a camada [business] e suas opções
    services.AddSingleton(new ServerOptions(port, echo));
    services.AddSingleton<TaxServer>();

    // criação do servidor e, portanto, das camadas [business] e [dao]
    ServiceProvider provider = services.BuildServiceProvider();
    server = provider.GetRequiredService<TaxServer>();
}
catch (Exception ex)
{
    // exibição da cadeia de exceções e parada
    Console.WriteLine("The following error occurred during the initialization of the server:");
    for (Exception? cause = ex; cause != null; cause = cause.InnerException)
    {
        Console.WriteLine($"{cause.GetType().Name} : {cause.Message}");
    }
    return 1;
}

// Ctrl-C cancela o token: o servidor para de forma limpa
using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) =>
{
    e.Cancel = true;
    cancellation.Cancel();
};
// execução do servidor até a parada solicitada
await server.RunAsync(cancellation.Token);
return 0;

Este é claramente o programa principal da versão 5:

  • linhas 13–20: leitura da configuração. Os valores são cadeias de caracteres: a porta e o eco são convertidos com [TryParse], com valores padrão fornecidos;
  • linhas 25–33: as camadas [dao] e [business] são armazenadas no contêiner exatamente como na versão 5;
  • linhas 35–36: o novo recurso. As opções do servidor (porta, eco) são armazenadas como um objeto já construído, seguido da própria camada [server]. O construtor de [TaxServer] espera um [ITaxBusiness] e um [ServerOptions]: o contêiner os fornecerá;
  • Linha 40: a criação do servidor provoca a criação da camada [business], que por sua vez provoca a criação da camada [dao]; é nesse momento que o arquivo [TaxData.txt] é lido. Um erro (arquivo ausente, malformado) é exibido e o programa termina (linhas 42–50);
  • linhas 54–58: Ctrl-C cancela o token [cancellation], como no servidor de eco;
  • linha 61: o servidor fica em execução até que o token seja cancelado.

12.9.3.3. A camada [server]

A classe [TaxServer] é a seguinte:

using System.Net;
using System.Net.Sockets;
using Business;

namespace Server;

// as opções do servidor: porta de escuta e eco do diálogo no log
public record ServerOptions(int Port, bool Echo);

// a camada [server]: ela torna a camada [business] acessível por meio de um protocolo TCP de linhas de texto
public class TaxServer(ITaxBusiness business, ServerOptions options)
{
    // as respostas fixas do protocolo
    private const string Welcome = "Welcome to the tax calculation server";
    private const string Help = "Accepted commands\n1-help\n2-tax married(Y/N) nbChildren annualSalary\n3-goodbye";
    private const string Goodbye = "Goodbye...";
    private const string IncorrectCommand = "Command not recognized. Use the help command.";
    private const string IncorrectCalculation = "Incorrect calculation command. Use the help command.";

    // execução do servidor até que o token seja cancelado
    public async Task RunAsync(CancellationToken token)
    {
        var listener = new TcpListener(IPAddress.Any, options.Port);
        // as tarefas de serviço em andamento
        var services = new List<Task>();
        int clientNumber = 0;
        try
        {
            listener.Start();
            Log($"Tax calculation server started on port {options.Port}");
            while (true)
            {
                // espera por um cliente
                TcpClient client = await listener.AcceptTcpClientAsync(token);
                // ele é atendido por uma tarefa que não aguardamos: voltamos a esperar o próximo cliente
                services.Add(ServeAsync(client, clientNumber++, token));
                services.RemoveAll(service => service.IsCompleted);
            }
        }
        catch (OperationCanceledException)
        {
            Log("Server stop requested");
        }
        catch (SocketException ex)
        {
            Log($"The following error occurred on the server: {ex.SocketErrorCode} ({ex.Message})");
        }
        finally
        {
            listener.Stop();
        }
        // esperamos o fim dos serviços em andamento
        await Task.WhenAll(services);
        Log("Server stopped");
    }

    // o serviço prestado a um cliente
    private async Task ServeAsync(TcpClient client, int clientNumber, CancellationToken token)
    {
        Log($"Start of service to client {clientNumber} ({client.Client.RemoteEndPoint})");
        try
        {
            using (client)
            {
                NetworkStream stream = client.GetStream();
                using var reader = new StreamReader(stream);
                await using var writer = new StreamWriter(stream) { AutoFlush = true };

                // envio de uma resposta ao cliente, com possível eco no log
                async Task WriteAsync(string response)
                {
                    if (options.Echo)
                    {
                        Log($"---> client {clientNumber} : {response}");
                    }
                    await writer.WriteLineAsync(response);
                }

                // mensagem de boas-vindas
                await WriteAsync(Welcome);
                // laço de leitura da requisição / escrita da resposta, até o comando de despedida
                while (await reader.ReadLineAsync(token) is string request)
                {
                    if (options.Echo)
                    {
                        Log($"<--- client {clientNumber} : {request}");
                    }
                    // a requisição dividida em campos
                    string[] fields = request.Trim().ToLower().Split(' ', StringSplitOptions.RemoveEmptyEntries);
                    if (fields is ["goodbye"])
                    {
                        await WriteAsync(Goodbye);
                        break;
                    }
                    // a resposta conforme o comando
                    string response = fields switch
                    {
                        ["help"] => Help,
                        ["tax", ..] => CalculateTax(fields),
                        _ => IncorrectCommand,
                    };
                    await WriteAsync(response);
                }
            }
        }
        catch (OperationCanceledException)
        {
            Log($"Service to client {clientNumber} interrupted by the server stop");
        }
        catch (IOException ex)
        {
            Log($"The following error occurred while serving client {clientNumber}: {ex.Message}");
        }
        finally
        {
            Log($"End of service to client {clientNumber}");
        }
    }

    // o comando tax married nbChildren annualSalary: retorna o imposto ou uma mensagem de erro
    private string CalculateTax(string[] fields)
    {
        // são necessários 4 campos: tax, y ou n, dois inteiros
        if (fields is not [_, "y" or "n", var children, var salary]
            || !int.TryParse(children, out int nbChildren)
            || !int.TryParse(salary, out int annualSalary))
        {
            return IncorrectCalculation;
        }
        try
        {
            // o cálculo é entregue à camada [business]
            return business.CalculateTax(fields[1] == "y", nbChildren, annualSalary).ToString();
        }
        catch (Exception ex)
        {
            // a mensagem da exceção, em uma única linha: o protocolo é feito de linhas de texto
            return ex.Message.ReplaceLineEndings(" ");
        }
    }

    // o log do servidor: cada linha recebe um carimbo de data e hora
    private static void Log(string message) => Console.WriteLine($"{DateTime.Now:HH:mm:ss} {message}");
}
  • linha 8: as opções do servidor, um record posicional (C# 9);
  • linha 11: a classe recebe a camada [business] e suas opções por meio de seu construtor primário (C# 12). Ela conhece apenas a interface [ITaxBusiness] da camada [business] e não sabe nada sobre a camada [dao];
  • linhas 14–18: as respostas fixas do protocolo. A resposta ao comando [help] contém \n: ela será recebida pelo cliente como quatro linhas, como em 2008;
  • linhas 21–54: o laço de espera por clientes. É igual ao do servidor de eco da primeira parte: cada cliente é atendido por uma tarefa assíncrona que não é bloqueada (linha 36), o cancelamento do token encerra a espera de um cliente (linha 40) e o servidor aguarda a conclusão dos atendimentos em andamento antes de encerrar (linha 53). O servidor de 2008 atribuía cada cliente a uma thread de um pool limitado a 10 threads, que permanecia bloqueada durante todo o atendimento; aqui, nenhuma thread fica retida por um cliente que demora a responder;
  • linhas 58–116: o serviço prestado a um cliente:
    • linhas 70–76: uma função local que envia uma resposta ao cliente e também a grava no log, se o log estiver ativado;
    • linha 80: assim que o cliente se conecta, o servidor lhe envia uma mensagem de boas-vindas;
    • linha 82: o laço de leitura de comandos, que termina se o cliente fechar a conexão ou se o servidor for encerrado;
    • linha 89: o comando, convertido para minúsculas, é decomposto em campos. O curso de 2008 usava [Regex.Split] com o padrão [\s+]; a opção [RemoveEmptyEntries] de [Split] remove, da mesma forma, os campos vazios causados por vários espaços consecutivos;
    • linha 90: um padrão de lista (C# 11): o comando consiste somente na palavra [goodbye]. O servidor responde e sai do laço: a conexão é fechada ao sair do bloco [using (client)];
    • linhas 96–100: uma expressão [switch] com padrões de lista seleciona a resposta: [["help"]] reconhece o comando [help] isolado, enquanto [["tax", ..]] reconhece um comando que começa com [tax], seguido de qualquer número de campos (padrão de fatia [..]). O servidor de 2008 fechava a conexão ao receber uma linha vazia; agora ele recebe a resposta [Command not recognized];
  • Linhas 121–138: cálculo do imposto:
    • Linhas 124–128: um único padrão de lista verifica que o comando tem quatro campos, que o segundo campo é [y] ou [n], e atribui os dois últimos campos às variáveis [children] e [salary]; em seguida, verifica que são números inteiros. O código de 2008 realizava essas verificações em quatro testes sucessivos;
    • linha 133: o cálculo é solicitado à camada [business]. Uma única instância de [TaxBusiness] atende a todos os clientes, potencialmente de forma simultânea, a partir de threads diferentes: isso é possível porque essa classe não modifica nenhum dado depois de construída (seu array de faixas de imposto é somente leitura);
    • linha 138: se a camada [business] lançar uma exceção (por exemplo, devido a um número negativo de filhos), sua mensagem é devolvida ao cliente. Essa mensagem pode conter quebras de linha: elas são substituídas por espaços, já que o protocolo exige uma resposta de uma única linha;
  • linha 143: o log do servidor, exibido no console: cada linha é precedida da hora, o que permite ver a sequência dos atendimentos concorrentes. [Console.WriteLine] pode ser chamado sem nenhuma precaução especial a partir de várias threads: suas gravações não interferem umas nas outras.

12.9.4. O cliente do servidor de cálculo do imposto

O curso de 2008 usava a interface gráfica da versão 7; nós usamos a interface de console da versão 5, a classe [Ui.Dialog], sem modificá-la.

12.9.4.1. A camada [business] do cliente

A camada [ui] se comunica com uma camada [business], da qual conhece apenas a interface [ITaxBusiness]:

1
2
3
4
5
6
7
namespace Business;

// a interface da camada [business]
public interface ITaxBusiness
{
    int CalculateTax(bool married, int nbChildren, int salary);
}

Basta, portanto, fornecer-lhe outra implementação dessa interface que, em vez de calcular o imposto, o solicita ao servidor. É a classe [TaxBusinessTcp]:

using System.Net.Sockets;
using Entities;
using Business;

namespace Client;

// a camada [business] do cliente: ela implementa ITaxBusiness delegando o cálculo ao servidor TCP
public class TaxBusinessTcp : ITaxBusiness, IDisposable
{
    // a conexão com o servidor, aberta durante toda a vida do objeto
    private readonly TcpClient client;
    private readonly StreamReader reader;
    private readonly StreamWriter writer;

    // conexão com o servidor (machine, port)
    public TaxBusinessTcp(string machine, int port)
    {
        try
        {
            client = new TcpClient(machine, port);
            NetworkStream stream = client.GetStream();
            reader = new StreamReader(stream);
            writer = new StreamWriter(stream) { AutoFlush = true };
            // o servidor fala primeiro: lemos (e ignoramos) sua mensagem de boas-vindas
            ReadResponse();
        }
        catch (Exception e) when (e is SocketException or IOException)
        {
            throw new TaxException($"Unable to connect to the server ({machine}, {port})", e) { Code = 21 };
        }
    }

    // cálculo do imposto: uma requisição, uma resposta
    public int CalculateTax(bool married, int nbChildren, int salary)
    {
        string response;
        try
        {
            writer.WriteLine($"tax {(married ? "y" : "n")} {nbChildren} {salary}");
            response = ReadResponse();
        }
        catch (IOException e)
        {
            throw new TaxException("Error communicating with the server", e) { Code = 22 };
        }
        // o servidor retorna o imposto ou uma mensagem de erro
        return int.TryParse(response, out int tax)
            ? tax
            : throw new TaxException($"The server answered: {response}") { Code = 23 };
    }

    // leitura de uma linha de resposta; null significa que o servidor fechou a conexão
    private string ReadResponse() =>
        reader.ReadLine() ?? throw new TaxException("The server has closed the connection") { Code = 24 };

    // fim da conexão: nos despedimos do servidor, se ele ainda estiver lá
    public void Dispose()
    {
        try
        {
            writer.WriteLine("goodbye");
            reader.ReadLine();
        }
        catch (IOException)
        {
            // a conexão já foi cortada: não há mais nada a fazer
        }
        client.Dispose();
    }
}
  • Linha 8: a classe implementa [ITaxBusiness]. Ela também implementa [IDisposable]: mantém uma conexão de rede, que precisa ser fechada;
  • linhas 11–13: a conexão com o servidor e seus fluxos de leitura e escrita. A classe de 2008 abria uma nova conexão a cada cálculo; nós abrimos uma única conexão, usada para todos os cálculos de uma sessão: isso é mais eficiente, e o servidor enxerga um cliente por sessão de usuário;
  • linhas 16–29: o construtor se conecta ao servidor e lê sua mensagem de boas-vindas (linha 25). Um erro de conexão é encapsulado em uma [TaxException], a exceção da aplicação;
  • linhas 34–49: o cálculo do imposto. O comando [tax y 2 60000] é enviado ao servidor (linha 39) e sua resposta é lida. Se a resposta for um inteiro, esse é o valor do imposto; caso contrário, trata-se de uma mensagem de erro do servidor, que é devolvida em uma [TaxException] (linha 49). O código de 2008 convertia diretamente a resposta em inteiro e pedia ao leitor que o melhorasse: uma mensagem de erro do servidor causava uma exceção de conversão que mascarava a verdadeira causa do erro;
  • linha 53: [ReadLine] retorna [null] quando o servidor fechou a conexão; uma [TaxException] é então lançada;
  • Linhas 57–68: encerramento da conexão. O cliente se despede do servidor com o comando [goodbye] e, em seguida, fecha a conexão. Se o servidor já tiver encerrado a conexão, a [IOException] resultante é ignorada.

Isso levanta uma questão: por que essa classe usa os métodos síncronos [TcpClient(machine, port)], [ReadLine], e [WriteLine], quando o resto deste capítulo usa suas versões assíncronas? Porque a interface [ITaxBusiness] da versão 5 é síncrona: [CalculateTax] retorna um [int], e não um [Task<int>], e a camada [ui] a chama sem [await]. Para usar [ReadLineAsync], seria necessário aguardar seu resultado de forma bloqueante ([ReadLineAsync().Result]), o que o Capítulo 9 desaconselhou, ou tornar a interface assíncrona e, assim, modificar as camadas [business] e [ui] da versão 5. Para um programa de console que atende apenas um usuário, os métodos síncronos são perfeitamente adequados: a thread principal não tem nada a fazer além de esperar a resposta. A assincronia é essencial no lado do servidor, que precisa atender a muitos clientes, e não no lado do cliente. Quando escrevermos novas camadas no próximo capítulo, vamos dotá-las de interfaces assíncronas.

12.9.4.2. O programa principal do cliente

O projeto [Tax.Client.csproj] referencia as camadas [business] e [ui] da versão 5:

<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>
    <!-- contêiner de injeção de dependência -->
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
  </ItemGroup>

</Project>

O projeto [Tax.Ui] é uma aplicação de console: um projeto pode referenciar outro projeto executável para usar suas classes públicas, neste caso, [Ui.Dialog]. O arquivo [Program.cs] é o seguinte:

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

// o cliente console do servidor de cálculo de imposto
// chamada: dotnet run [-- machine port]   (por padrão: localhost 27200)
string machine = args.Length > 0 ? args[0] : "localhost";
int port = args.Length > 1 && int.TryParse(args[1], out int p) ? p : 27200;

// a camada [business] agora é um cliente TCP do servidor de cálculo de imposto
var services = new ServiceCollection();
services.AddSingleton<ITaxBusiness>(_ => new TaxBusinessTcp(machine, port));
// o contêiner libera (Dispose) os objetos que criou: a conexão será fechada no fim do programa
using ServiceProvider provider = services.BuildServiceProvider();
try
{
    ITaxBusiness business = provider.GetRequiredService<ITaxBusiness>();
    Console.WriteLine($"Connected to the tax calculation server ({machine}, {port})");
    // a camada [ui] da versão 5, inalterada
    Dialog.Run(business);
}
catch (TaxException e)
{
    Dialog.DisplayError(e);
    return 1;
}
return 0;
  • linhas 9–10: a máquina e a porta do servidor, passadas como argumentos, com valores padrão;
  • linha 14: a camada [business] registrada no contêiner agora é [TaxBusinessTcp]. Como seu construtor espera dois parâmetros que o contêiner não conhece, uma função de criação é fornecida para ela;
  • linha 16: o contêiner é declarado com [using]. Quando ele é liberado ao final do programa, libera por sua vez os objetos [IDisposable] que criou: o método [Dispose] de [TaxBusinessTcp] será chamado e a conexão será fechada corretamente;
  • linha 19: criação da camada [business], ou seja, da conexão com o servidor;
  • linha 22: o diálogo da versão 5, inalterado. A camada [ui] não sabe que o imposto é calculado por um servidor remoto;
  • Linhas 24–27: um erro de conexão ou de comunicação é exibido pelo método [DisplayError] da versão 5.

12.9.5. Execuções

O servidor é iniciado em uma janela de comando a partir da pasta [Tax.Server]. Em outra janela, o cliente é iniciado a partir da pasta [Tax.Client]:

> dotnet run
Connected to the tax calculation server (localhost, 27200)
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: x 2 60000
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect Married argument: type y or n
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y two 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: y 2
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

O diálogo é exatamente o mesmo da versão 5: inclui os valores de validação (4282 e 2959 para uma pessoa casada com 2 ou 3 filhos e salário de 60.000 euros, 11519 para uma pessoa solteira sem filhos) e as mesmas mensagens de erro para entradas incorretas. Essas mensagens são geradas pela camada [ui] do cliente, que valida a entrada antes de solicitar o cálculo: entradas incorretas nunca chegam ao servidor.

Vamos agora iniciar dois clientes, A e B, em duas janelas, com B começando enquanto A ainda está conectado. Cada um realiza dois cálculos. Na janela do cliente A:

1
2
3
4
5
6
7
> dotnet run
Connected to the tax calculation server (localhost, 27200)
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: n 2 40000
Tax=2854 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

Na janela do cliente B:

1
2
3
4
5
6
7
> dotnet run
Connected to the tax calculation server (localhost, 27200)
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: 

Para ver as respostas do servidor a comandos incorretos, é necessário um cliente que envie os comandos exatamente como são digitados: o cliente TCP genérico da primeira parte serve perfeitamente. O servidor fala primeiro, algo que esse cliente sabe tratar:

> dotnet run internet-06.cs -- localhost 27200
<-- Welcome to the tax calculation server
Type your commands (bye to stop):
help
<-- Accepted commands
<-- 1-help
<-- 2-tax married(Y/N) nbChildren annualSalary
<-- 3-goodbye
tax y 2 60000
<-- 4282
TAX N 0 60000
<-- 11519
tax x 2 60000
<-- Incorrect calculation command. Use the help command.
tax y 2
<-- Incorrect calculation command. Use the help command.
tax y -2 60000
<-- nbChildren ('-2') must be a non-negative value. (Parameter 'nbChildren') Actual value was -2.
calculation
<-- Command not recognized. Use the help command.
goodbye
<-- Goodbye...
[the server has closed the connection]
  • linha 2: a mensagem de boas-vindas, que chegou antes mesmo do prompt do cliente;
  • linhas 5–8: a resposta ao comando [help], ocupando quatro linhas;
  • linha 11: a caixa (maiúsculas/minúsculas) do comando é ignorada;
  • linhas 13–15: dois comandos de cálculo malformados;
  • linha 18: o comando está bem formado, mas a camada [business] rejeita um número negativo de filhos; a mensagem da exceção (em inglês: ela vem do .NET) foi devolvida em uma única linha;
  • linha 20: um comando desconhecido;
  • linhas 21–23: após o comando [goodbye], o servidor fechou a conexão.

Em seguida, o servidor é encerrado com Ctrl-C enquanto um último cliente ainda está conectado. Esse cliente fez um primeiro cálculo antes do encerramento e enviou sua segunda solicitação depois:

1
2
3
4
5
6
7
8
9
> dotnet run
Connected to the tax calculation server (localhost, 27200)
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
Exception chain:
----------------------------------------
Entities.TaxException: The server has closed the connection
----------------------------------------

A leitura da resposta resultou em [null]: a camada [business] lançou uma [TaxException], que o programa principal exibiu. Uma vez parado o servidor, um novo cliente não consegue mais se conectar:

1
2
3
4
5
6
7
> dotnet run
Exception chain:
----------------------------------------
Entities.TaxException: Unable to connect to the server (localhost, 27200)
----------------------------------------
System.Net.Sockets.SocketException: Connection refused 127.0.0.1:27200
----------------------------------------

Por fim, eis o log do servidor para todos esses testes:

> dotnet run
12:21:33 Tax calculation server started on port 27200
12:21:37 Start of service to client 0 (127.0.0.1:51654)
12:21:37 ---> client 0 : Welcome to the tax calculation server
12:21:38 <--- client 0 : tax y 2 60000
12:21:38 ---> client 0 : 4282
12:21:39 <--- client 0 : tax y 3 60000
12:21:39 ---> client 0 : 2959
12:21:40 <--- client 0 : tax n 0 60000
12:21:40 ---> client 0 : 11519
12:21:43 <--- client 0 : goodbye
12:21:43 ---> client 0 : Goodbye...
12:21:43 End of service to client 0
12:21:47 Start of service to client 1 (127.0.0.1:56532)
12:21:47 ---> client 1 : Welcome to the tax calculation server
12:21:50 Start of service to client 2 (127.0.0.1:56536)
12:21:50 ---> client 2 : Welcome to the tax calculation server
12:21:50 <--- client 1 : tax y 2 60000
12:21:50 ---> client 1 : 4282
12:21:53 <--- client 2 : tax y 3 60000
12:21:53 ---> client 2 : 2959
12:21:53 <--- client 1 : tax n 2 40000
12:21:53 ---> client 1 : 2854
12:21:56 <--- client 2 : tax n 0 60000
12:21:56 ---> client 2 : 11519
12:21:56 <--- client 1 : goodbye
12:21:56 ---> client 1 : Goodbye...
12:21:56 End of service to client 1
12:21:59 <--- client 2 : goodbye
12:21:59 ---> client 2 : Goodbye...
12:21:59 End of service to client 2
12:22:01 Start of service to client 3 (127.0.0.1:52256)
12:22:01 ---> client 3 : Welcome to the tax calculation server
12:22:02 <--- client 3 : help
12:22:02 ---> client 3 : Accepted commands
1-help
2-tax married(Y/N) nbChildren annualSalary
3-goodbye
12:22:03 <--- client 3 : tax y 2 60000
12:22:03 ---> client 3 : 4282
12:22:04 <--- client 3 : TAX N 0 60000
12:22:04 ---> client 3 : 11519
12:22:05 <--- client 3 : tax x 2 60000
12:22:05 ---> client 3 : Incorrect calculation command. Use the help command.
12:22:06 <--- client 3 : tax y 2
12:22:06 ---> client 3 : Incorrect calculation command. Use the help command.
12:22:07 <--- client 3 : tax y -2 60000
12:22:07 ---> client 3 : nbChildren ('-2') must be a non-negative value. (Parameter 'nbChildren') Actual value was -2.
12:22:08 <--- client 3 : calculation
12:22:08 ---> client 3 : Command not recognized. Use the help command.
12:22:09 <--- client 3 : goodbye
12:22:09 ---> client 3 : Goodbye...
12:22:09 End of service to client 3
12:22:12 Start of service to client 4 (127.0.0.1:52306)
12:22:12 ---> client 4 : Welcome to the tax calculation server
12:22:17 <--- client 4 : tax y 2 60000
12:22:17 ---> client 4 : 4282
12:22:17 Server stop requested
12:22:17 Service to client 4 interrupted by the server stop
12:22:17 End of service to client 4
12:22:17 Server stopped
  • Linhas 3–13: o cliente da primeira execução. Com a saída de eco, vemos todos os comandos recebidos e todas as respostas enviadas. Observe o comando [goodbye] (linha 11), enviado pelo método [Dispose] de [TaxBusinessTcp] quando o usuário terminou: a sessão foi encerrada corretamente;
  • linhas 14–31: os clientes A (cliente 1) e B (cliente 2). O cliente 2 chegou (linha 16) enquanto o cliente 1 ainda estava sendo atendido, e suas solicitações foram processadas alternadamente, conforme chegavam: o servidor de fato atende a vários clientes simultaneamente;
  • linhas 32–53: a sessão do cliente TCP genérico;
  • Linhas 54–61: o último cliente, que estava sendo atendido no momento do encerramento. Ctrl-C cancelou o token; as duas operações que o aguardavam, a leitura de um comando do cliente 4 e a espera por um novo cliente, terminaram com uma [OperationCanceledException], em uma ordem que depende do escalonamento das threads. O servidor aguardou o término do atendimento em andamento antes de encerrar.

12.9.6. Conclusão

Mais uma vez, conseguimos reutilizar código existente sem modificá-lo: as camadas [dao] e [business] da versão 5 no lado do servidor e a camada [ui] no lado do cliente. Isso foi possível graças ao uso sistemático de interfaces e de injeção de dependência: para implantar a aplicação em duas máquinas, bastou acrescentar uma camada [server] sobre a camada [business] e fornecer à camada [ui] uma implementação diferente de [ITaxBusiness]. Se a versão 1 tivesse reunido o cálculo do imposto e a interação com o usuário no mesmo programa, nada disso seria reutilizável. Observe que a camada [ui] não sabe que um servidor remoto calcula o valor do imposto.

Nosso protocolo próprio tem, porém, suas limitações: precisamos escrever o servidor, gerenciar as conexões, analisar os comandos, converter as respostas, e um cliente escrito em outra linguagem precisaria conhecer esse protocolo específico. A versão 9, no próximo capítulo, substituirá o servidor TCP por um serviço web: o protocolo será o HTTP, os dados serão trocados em JSON e o cliente usará [HttpClient].

12.10. Conclusão

Este capítulo apresentou a programação para a Internet com .NET, partindo dos fundamentos até chegar a classes de alto nível:

  • a primeira parte revisou o funcionamento dos protocolos da Internet (IP, TCP, UDP, DNS) e dos protocolos de aplicação baseados em texto (HTTP, SMTP, POP, FTP) e, em seguida, apresentou as classes [IPAddress] e [Dns], bem como as classes [TcpClient] e [TcpListener], usadas de forma assíncrona. Com elas, escrevemos servidores que atendem a vários clientes simultaneamente, clientes TCP genéricos e um cliente web que se comunicava em HTTP “manualmente”;
  • a segunda parte apresentou classes especializadas em um protocolo. Para o HTTP, a classe [HttpClient] substitui as obsoletas [WebClient] e [WebRequest]: ela realiza em uma única instrução o que nosso cliente TCP fazia em cinquenta linhas; trata redirecionamentos, formulários, JSON, timeouts e cancelamento, e foi concebida para ser reutilizada entre requisições. Para o SMTP, a classe [SmtpClient] continua utilizável, embora a biblioteca MailKit seja preferida para novos desenvolvimentos;
  • a aplicação de exemplo tornou-se uma aplicação cliente/servidor, sem nenhuma alteração em suas camadas existentes.

Os princípios da programação assíncrona vistos no Capítulo 9 encontraram aqui sua principal aplicação: um servidor assíncrono atende a um grande número de clientes com algumas poucas threads, e um cliente assíncrono aguarda as respostas da rede sem bloquear uma thread. No entanto, escrever um servidor TCP e inventar o próprio protocolo continua sendo exceção: a maioria das aplicações distribuídas hoje se comunica por HTTP, usando serviços web que trocam dados em JSON. Esse é o assunto do próximo capítulo.