Skip to content

12. Web 编程

12.1. 概述

12.1.1. Internet 协议

这里我们介绍 Internet 通信协议,也称为 TCP/IP 协议簇(Transmission Control Protocol / Internet Protocol,传输控制协议/网际协议),以其中两个主要协议命名。在着手开发分布式应用程序之前,读者最好对网络的工作方式——尤其是 TCP/IP 协议——有一个总体的了解。2008 年的课程收录了一段翻译自 Novell 的《Lan Workplace for DOS》管理指南(20 世纪 90 年代初)的节选。我们保留了其结构和精神,但做了更新:2026 年的 Internet 已不再与 1990 年的完全一样。

创建异构计算机网络的总体构想源自美国 DARPA(Defense Advanced Research Projects Agency,国防高级研究计划局)开展的研究。DARPA 开发了称为 TCP/IP 的协议簇,使异构机器之间能够相互通信。这些协议在名为 ARPAnet 的网络上进行了测试,该网络后来发展成为 Internet(ARPAnet 于 1983 年 1 月 1 日采用 TCP/IP)。TCP/IP 协议定义了与网络架构和所用硬件无关的传输与接收格式及规则。

DARPA 设计、由 TCP/IP 协议管理的网络是分组交换网络。这种网络以称为分组(packet)的小块传输信息。因此,如果一台计算机传输一个大文件,它会被拆分成小块在网络上发送,并在目的地重新组装。TCP/IP 定义了这些分组的格式,其中尤其包括:

  • 分组的源;
  • 其目的地;
  • 其长度;
  • 其类型。

Internet 协议在称为 RFC(Request for Comments,征求意见稿)的公开文档中描述,这些文档由 IETF(Internet Engineering Task Force,互联网工程任务组)发布,可在www.rfc-editor.org上获取。在本章中我们将引用其中一些文档。

12.1.2. OSI 模型

TCP/IP 协议总体上遵循由 ISO(International Organization for Standardization,国际标准化组织)定义的、称为 OSI(Open Systems Interconnection Reference Model,开放系统互连参考模型)的开放网络模型。该模型描述了一种理想的网络,其中机器之间的通信可以用一个七层模型来表示:

Image

每一层从其下一层获得服务,并向其上一层提供自己的服务。假设位于不同机器上的两个应用程序 A 和 B 想要通信:它们在应用层进行通信。它们不需要了解网络工作方式的所有细节:每个应用程序把它想传输的信息交给其下一层,即表示层。因此,应用程序只需知道与表示层交互的规则。信息一旦进入表示层,就按照其他规则传递给会话层,依此类推,直到信息到达物理介质并被物理地传输到目标机器。在那里,它将经历与在发送机器上所经历过程相反的过程。

在每一层,负责发送信息的发送方进程会按照称为该层协议的某些规则,将信息发送给另一台机器上属于同一层的接收方进程。实际的通信自上而下穿过机器 A 的各层,经过物理网络,然后自下而上穿过机器 B 的各层;然而,每一层都认为自己是在与另一台机器上的对应层直接通信。

各层的作用如下:

层
作用
物理层
确保比特在物理介质(铜缆、光纤、无线电波)上的传输。此层的关键问题包括将信息编码为信号以及传输方式。
数据链路层
对物理层的物理特性进行抽象。将信息划分为帧,检测(有时还纠正)传输错误,并管理对共享介质的访问。
网络层
管理在网络上发送的信息必须经过的路径。这称为路由:确定信息到达目的地所必须走的路线。
传输层
实现两个应用程序之间的通信,而之前的各层只允许机器之间通信。该层提供的一项服务是多路复用:传输层使用单一的网络链路(机器到机器)来传输属于多个应用程序的数据。
会话层
提供使应用程序能够在远程机器上打开并维持工作会话的服务。
表示层
规范不同机器之间数据的表示方式。机器 A 的数据在通过网络发送之前,会由机器 A 的表示层按照标准格式进行“格式化”。到达目标机器 B 的表示层后——该层根据标准格式识别这些数据——数据会被重新格式化,以便机器 B 上的应用程序能够识别。
应用层
这一层包含通常贴近用户的应用程序,例如电子邮件、Web 或文件传输。

12.1.3. TCP/IP 模型

OSI 模型是一个从未按原样实现的参考模型。已成为标准的 TCP/IP 协议簇只分为四层:

Image

会话层和表示层在 TCP/IP 中并不作为独立的层存在:必要时,它们的功能由应用程序自身或由中间协议(如 TLS,对数据交换进行加密,插在 TCP 与应用程序之间)来完成。

网络接入层

在局域网中,当今占主导地位的技术是用于有线连接的以太网和用于无线连接的 Wi-Fi(IEEE 802.11 标准)。2008 年的课程还涉及令牌环(Token Ring),这是一种如今已不再使用的技术。

以太网(Ethernet)是一种分组交换局域网技术的名称,由 Xerox 于 20 世纪 70 年代初发明,1980 年由 Xerox、Intel 和 Digital Equipment 标准化,后来由 IEEE 标准化(标准 802.3)。最初的以太网由一根同轴电缆构成,所有机器都连接在这根电缆上(总线拓扑),数据速率为每秒 10 兆比特:

Image

这是一种广播网络:发送机器在电缆上发送包含目标机器地址的信息;所有连接的机器都会收到,只有预定的接收者会保留它。由于多台机器可能同时决定发送,因此必须检测冲突:这就是载波侦听多路访问/冲突检测(Carrier Sense Multiple Access/Collision Detect,CSMA/CD)方法。每个发送者在发送前先监听电缆(CSMA),并在发送期间验证电缆上经过的内容确实是自己所发送的;如果不是,则发生了冲突(CD):各方都停止发送,并在随机延迟后重试。

现代以太网已有很大演进:设备通过双绞线或光纤电缆连接到交换机,交换机将每个帧路由到接收者对应的端口。连接是全双工的(同时发送和接收):不再有任何冲突,CSMA/CD 已经过时。典型数据速率为每秒 1 到 10 吉比特,在数据中心则要高得多。

没有改变的是 48 位寻址:每块网卡都有一个地址,称为物理地址或 MAC(Media Access Control,介质访问控制)地址,通常写成六个十六进制字节(例如[00:1A:2B:3C:4D:5E])。它由制造商嵌入网卡,但——与 2008 年课程中所述相反——可以通过软件修改:当前的操作系统甚至在 Wi-Fi 网络上使用随机 MAC 地址,以防止设备在不同网络之间被跟踪。

Internet 层(网络层)

这一层中有以下协议:

协议
作用
IP(Internet Protocol,网际协议)
在两个网络节点之间传送分组,版本为 4(IPv4)或 6(IPv6)
ICMP(Internet Control Message Protocol,互联网控制报文协议)
促进一台机器上的 IP 协议程序与另一台机器上的 IP 协议程序之间的通信。因此它是在 IP 协议内部交换控制报文的协议
ARP(Address Resolution Protocol,地址解析协议)
将机器的 IP 地址映射到该机器的物理地址(在 IPv6 中,这一作用由 NDP 协议,即邻居发现协议,来完成)

2008 年的课程还提到了 RARP(Reverse Address Resolution Protocol,反向地址解析协议),它执行相反的映射。它早已被 DHCP 取代而弃用,我们将在后面讨论 DHCP。

传输层

这一层包含以下协议:

协议
作用
TCP(Transmission Control Protocol,传输控制协议)
确保两个应用程序之间信息的可靠、有序传递
UDP(User Datagram Protocol,用户数据报协议)
提供两个应用程序之间不可靠的信息传递

QUIC(2021)协议是 HTTP/3 的基础,它是构建在 UDP 之上的可靠、加密的传输协议。

应用层

这里有各种协议,稍后我们将详细介绍:

协议
作用
HTTP、HTTPS(HyperText Transfer Protocol,超文本传输协议)
Web 协议:客户端(浏览器、应用程序)向 Web 服务器请求资源。HTTPS 是使用 TLS 加密的 HTTP
DNS(Domain Name System,域名系统)
将机器名转换为 IP 地址
SMTP(Simple Mail Transfer Protocol,简单邮件传输协议)
用于发送电子邮件
POP3、IMAP
用于读取存储在服务器上的电子邮件
SSH(Secure Shell,安全外壳)
允许您连接到远程机器并使用加密方式在其上执行命令。它取代了功能相同但不加密的 TELNET
FTP(File Transfer Protocol,文件传输协议)、SFTP
用于文件传输
DHCP(Dynamic Host Configuration Protocol,动态主机配置协议)
使机器能够自动获取其 IP 地址和网络配置

12.1.4. Internet 协议如何工作

在 TCP/IP 环境中开发的应用程序通常会使用该环境中的多个协议。应用程序与协议的最高层通信。该层把信息传递给其下一层,依此类推,直到到达物理介质。在那里,信息被物理地传送到接收机器,并在接收机器上再次经过相同的各层——这次是相反的顺序——直到到达作为所发送信息预定接收者的应用程序。下图显示了信息的路径:

Image

我们来看一个例子:一个应用程序使用 TCP 向另一台机器发送文件。

  • 应用程序向传输层交付一个待传输的字节序列;
  • 传输层将该字节序列划分为 TCP 段,并在每个段的开头添加一个头部,其中除其他内容外,还包含源端口号和目标端口号以及序列号。这些段被传递给由 IP 协议管理的网络层;
  • IP 层创建一个封装所收到 TCP 段的分组。它在该分组的头部写入源机器和目标机器的 IP 地址。它还确定分组应当送达的机器(目标机器本身或路由器)的物理地址。整个分组被传递给网络接入层,即将机器连接到物理网络的网卡;
  • 在那里,IP 分组又被封装进物理帧,并通过介质发送给其接收者;
  • 在目标机器上,网络接入层执行相反的过程:它从物理帧中解封装出 IP 分组,并将其传递给 IP 层;
  • IP 层验证该分组是否有效:它计算其头部的校验和,该校验和必须与分组头部中的值一致。如果不一致,则丢弃该分组;
  • 如果认为分组有效,IP 层会解封装其中包含的 TCP 段,并将其向上传递给传输层;
  • TCP 层同样会验证该段的校验和。如果正确,它向源机器发送确认;否则忽略该段(源机器将重新发送);
  • 利用序列号,TCP 层将各段重新排列成正确的顺序;
  • TCP 层剩下要做的就是将各段的数据部分传送给由目标端口号标识的目标应用程序。

12.1.5. Internet 上的寻址问题

网络节点可以是计算机、打印机、电话、联网设备——实际上是任何能够使用 TCP/IP 协议通信的东西。每个节点都有一个物理地址,其格式取决于网络类型。在以太网或 Wi-Fi 网络中,物理地址使用 6 个字节编码。

节点的 Internet 地址(IP)是逻辑地址:它与所用的硬件和网络无关。在 IPv4 中,它是一个 4 字节的地址,既标识一个网络,也标识该网络上的一个节点。它通常表示为四个数字——四个字节的值——以句点分隔。例如,在 2008 年,昂热(Angers)理学院名为“Lagaffe”的机器的地址是 193.49.144.1,名为“Liny”的机器的地址是 193.49.144.9。由此可以推断,本地网络地址是 193.49.144.0,该网络上最多可以有 254 个节点。

由于 IP 地址与物理网络无关,网络 A 上的计算机可以与网络 B 上的计算机通信,而无需关心后者所处的网络类型:只需知道其 IP 地址即可。每个网络上的 IP 协议负责 IP 地址与物理地址之间的双向转换。

所有公网 IP 地址都必须是唯一的。它们的分配遵循层级结构:IANA(Internet Assigned Numbers Authority,互联网号码分配机构)将地址块分发给五个区域注册机构,其中包括负责欧洲的 RIPE NCC,再由它们转分配给运营商和大型组织。这些实体再将地址分配给其客户。获得 193.49.144.0 至 193.49.144.255 地址块的网络的管理员,可以按自己的意愿分配 193.49.144.1 至 193.49.144.254 之间的地址。2008 年的课程指出,在法国由 INRIA 负责分配地址;这种情况早已不复存在。

12.1.5.1. IP 地址类别与 CIDR 表示法

IPv4 地址是一个由 4 个字节组成的序列,写作 I1.I2.I3.I4,它实际上包含两部分信息:

  • 网络地址(最高有效位);
  • 该网络内节点的地址(最低有效位)。

最初,这两个字段的大小由第一个字节的值决定。IP 地址被分为三个主要类别:

类别
第一个字节
网络 / 节点
网络和节点的数量
A
1 到 126(最高位为 0)
R1.N1.N2.N3:1 字节网络(7 个有效位),3 字节节点
126 个网络,每个网络 2²⁴ - 2 个节点(约 1600 万)
B
128 到 191(最高两位为 10)
R1.R2.N1.N2:2 字节网络(14 个有效位),2 字节节点
2¹⁴ = 16,384 个网络,每个网络 2¹⁶ - 2 = 65,534 个节点
C
192 到 223(最高三位为 110)
R1.R2.R3.N1:3 字节网络(21 个有效位),1 字节节点
2²¹ 个网络(约 200 万),每个网络 254 个节点

由于 Lagaffe 机器的地址是 193.49.144.1,其最高有效字节是 193,二进制为 11000001:该网络是 C 类网络。

这种分类被证明过于僵化:一个拥有 300 台机器的组织必须使用 B 类网络,浪费了 65,000 多个地址。自 1993 年(RFC 1518 和 1519)起,这些类别已被无类别路由(CIDR,Classless Inter-Domain Routing,无类别域间路由)所取代。网络部分与主机部分之间的边界可以设在任意一位上;它通过斜杠后面的网络前缀长度来表示:

  • 193.49.144.0/24:前 24 位表示网络,后 8 位表示节点。该网络包含 193.49.144.0 至 193.49.144.255 的地址;
  • 10.0.0.0/8:一个拥有 2²⁴ 个地址的网络;
  • 192.168.1.0/26:一个拥有 2⁶ = 64 个地址的网络,范围从 192.168.1.0 到 192.168.1.63。

子网掩码的旧表示法仍在使用,它表达的是同样的意思:/24 前缀对应掩码 255.255.255.0。“A、B、C 类”这些术语仍在日常使用,但已不再对应任何实际机制。

12.1.5.2. 保留地址、私有地址与 NAT

某些地址有特定用途:

  • 主机部分全为 0 的地址指代网络本身:193.49.144.0 是 193.49.144.0/24 网络的地址;
  • 主机部分全为 1 的地址是广播地址:193.49.144.255 指代 193.49.144.0/24 网络上的所有主机。因此这两个地址不能分配给节点:一个有 256 个地址的 /24 网络只提供 254 个可用地址;
  • 地址 127.0.0.0/8,实际上是 127.0.0.1,是环回地址:机器用它们来指代自身而无需经过网络。名称[localhost] 与它们相关联;
  • 地址块 10.0.0.0/8、172.16.0.0/12 和 192.168.0.0/16(RFC 1918)保留给私有网络:它们可以在公司或家庭内部自由使用,但不会在 Internet 上路由;
  • 地址块 192.0.2.0/24、198.51.100.0/24 和 203.0.113.0/24(RFC 5737)保留用于文档和示例。

IPv4 地址的数量(2³²,略多于 40 亿)不足以满足所有联网机器的需要。IANA 的中央地址池于 2011 年耗尽,RIPE NCC 的地址池于 2019 年耗尽。这种短缺通过网络地址转换(NAT,Network Address Translation)得以规避:家庭中的设备拥有私有地址(如 192.168.1.x),将它们连接到 Internet 的路由器把它们“转换”为自己唯一的公网地址。长远的解决方案是 IPv6。

12.1.5.3. IPv6 地址

IPv6(1998 年的 RFC 2460,现为 RFC 8200)使用 128 位编码地址,提供 2¹²⁸ 个可能的地址——约 3.4 × 10³⁸——因此不再需要担心短缺。IPv6 地址写成由冒号分隔的八组、每组四个十六进制数字:

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

每组中的前导零可以省略,并且一段连续的全零组可以用[::]替换。因此前面的地址可以写成[2001:db8::8a2e:0:370:7334]。环回地址相当于 127.0.0.1,为[::1]。在 URL 中,IPv6 地址放在方括号中,以避免其冒号与端口前面的冒号混淆:[http://[::1]:8080/]。

IPv6 带来了进一步的简化:分组头部长度固定,默认内置自动地址配置,也不再需要 NAT 地址转换。它的采用较为缓慢,但如今 Internet 流量中有相当大且不断增长的一部分通过 IPv6 传输(例如 Google 公布了通过 IPv6 访问它的用户比例),法国的主要 ISP 也向其用户提供 IPv6。两个版本并存:大多数机器同时拥有 IPv4 和 IPv6 地址(称为“双栈”),程序必须能够同时处理这两种地址。

12.1.5.4. IP 地址与物理地址之间转换的协议

我们已经看到,当数据从一台机器传输到另一台机器时,经过 IP 层会被封装成分组。这些分组具有如下形式:

Image

因此,IP 分组包含源机器和目标机器的 IP 地址。当这个分组被传递给负责在物理网络上发送它的层时,会添加额外的信息,以构成最终将在网络上发送的物理帧。例如,以太网上帧的格式如下:

Image

前 8 个字节(前导码)用于同步;在最常见的以太网帧形式中,数据前面的 2 字节字段指示所承载的协议类型(IPv4、IPv6、ARP……),而不是分组长度。在最终的帧中,有源机器和目标机器的物理地址(在实际的帧中,目标地址位于源地址之前,与图中所示顺序相反)。它们是如何获得的呢?

发送机器知道它想要通信的机器的 IP 地址,通过 ARP 协议(Address Resolution Protocol,地址解析协议)获得该机器的物理地址:

  • 它发送一种特殊类型的分组,称为 ARP 分组,其中包含要查询物理地址的那台机器的 IP 地址。该分组还包含它自己的 IP 地址及物理地址;
  • 该分组被发送给本地网络上的所有节点(广播);
  • 这些节点识别出该分组的特殊性质。在分组中认出自己 IP 地址的节点,会把自己的物理地址发送给发送者作为响应。它之所以能够这样做,是因为它在分组中找到了发送者的 IP 地址和物理地址;
  • 于是发送者收到了它所查询的物理地址。它将其存储在缓存中,以便之后需要向同一接收者发送其他分组时使用。

在 IPv6 中,相同的服务由 NDP 协议(Neighbor Discovery Protocol,邻居发现协议)提供,它依赖于 ICMPv6 报文。

问题依然存在:机器如何知道自己的 IP 地址?可以在机器上的配置文件中指定——这仍然是服务器的标准做法。然而,当管理员需要重新组织网络时,逐台修改每台机器的配置文件既繁琐又容易出错。2008 年的课程介绍了 RARP 协议,机器通过它根据自己的物理地址向服务器请求其 IP 地址。它已被 DHCP(Dynamic Host Configuration Protocol,动态主机配置协议,RFC 2131)取代:启动时,机器在网络上广播一个请求;服务器(例如家用路由器或企业中的专用服务器)为它分配一个有限期限(租约)的地址,同时分配其余配置:网络前缀、路由器地址和 DNS 服务器地址。管理员这时只需配置 DHCP 服务器。在 IPv6 中,设备还可以根据路由器通告的前缀构造自己的地址(SLAAC 自动配置)。

12.1.6. Internet 的网络层,即 IP 层

IP 协议定义了分组必须采用的格式,以及在发送或接收时必须如何处理它们。这种特定类型的分组称为 IP 数据报。我们之前已经讨论过它:

Image

重点在于,除了要传输的数据之外,IP 数据报还包含源机器和目标机器的 IP 地址。这样,目标机器就知道是谁在给它发送消息。

与长度由其所经过的网络的物理特性决定的网络帧不同,IP 数据报的长度由软件设定,因此在不同的物理网络上都是相同的。我们已经看到,从网络层向下到物理层时,IP 数据报被封装在物理帧中。

物理帧从一个节点传到下一个节点,朝着目的地前进,而目的地可能与发送机器不在同一个物理网络上。因此,IP 分组可能在连接两个不同类型网络的节点处被相继封装进不同的物理帧中。IP 分组也可能太大而无法封装进一个物理帧(以太网帧的有效载荷限制为 1,500 字节)。在 IPv4 中,出现这个问题的节点会把 IP 分组拆分成片段,这些片段只会在最终目的地重新组装。在 IPv6 中,路由器不再对分组进行分片:由发送方确定沿途路径所接受的最大尺寸,并相应地调整其分组的大小。

12.1.6.1. 路由

路由是将 IP 分组导向其目的地的方法。有两种方法:直接路由和间接路由。

直接路由

直接路由是指在同一网络内将 IP 分组直接从发送者传输到接收者:

  • 发送 IP 数据报的机器拥有接收者的 IP 地址;
  • 它通过 ARP 协议获得接收者的物理地址,如果已经获得过该地址,则从其缓存中获取;
  • 它将分组通过网络发送到该物理地址。

间接路由

间接路由是指将 IP 分组传输到位于发送者所属网络之外的另一个网络上的目的地。在这种情况下,源机器和目标机器 IP 地址的“网络”部分不同;源机器通过将目标地址与自己的网络前缀进行比较来检测这一点。然后它把分组发送给一个称为路由器的特殊节点,路由器将本地网络与其他网络连接起来,其 IP 地址为源机器所知(这称为默认网关,通常由 DHCP 提供)。路由器至少连接两个网络,并在每个网络中都有一个 IP 地址:

Image

在上面的示例中:

  • 1 号网络的地址为 193.49.144.0/24,2 号网络的地址为 193.49.145.0/24;
  • 在 1 号网络中,路由器的地址为 193.49.144.6,在 2 号网络中,其地址为 193.49.145.3。

路由器的作用是取出它收到的 IP 分组——包含在来自 1 号网络的物理帧中——并将其放入可以在 2 号网络上传输的物理帧中。如果分组的目标 IP 地址在 2 号网络上,路由器会直接将分组发送给它;否则,它会将分组发送给连接 2 号网络与 3 号网络的另一个路由器,依此类推。Internet 路由器不断交换关于它们可到达网络的信息(运营商之间使用 BGP 等路由协议),以构建其路由表。

12.1.6.2. 错误与控制报文

同样位于网络层——因此与 IP 协议处于同一层次——的是 ICMP 协议(Internet Control Message Protocol,互联网控制报文协议)。它用于发送有关网络内部运行情况的报文:节点不可达、分组经过了太多路由器等。ICMP 报文被封装在 IP 分组中在网络上发送。各个节点的 IP 层根据收到的 ICMP 报文采取相应的措施。因此,应用程序自身永远看不到这些与网络相关的问题。[ping]命令(发送 ICMP“回显请求”报文并等待“回显应答”报文)以及[traceroute] / [tracert] (显示所经过的路由器)都基于 ICMP。

12.1.7. 传输层:UDP 和 TCP 协议

12.1.7.1. UDP 协议:User Datagram Protocol

UDP 协议实现两点之间不可靠的数据交换;也就是说,既不保证分组成功送达目的地,也不保证分组到达的顺序。应用程序如果愿意,可以自己处理这些问题——例如,在发送一条消息后等待确认,再发送下一条。

到目前为止,在网络层面我们讨论的是机器的 IP 地址。然而,在同一台机器上,不同的进程可以同时共存,并且它们都可以相互通信。因此,发送消息时,不仅必须指定目标机器的 IP 地址,还必须指定目标进程的“名称”。这个名称实际上是一个 16 位的数字(从 1 到 65,535),称为端口号。某些编号保留给标准应用程序:DNS 使用端口 53,HTTP 使用 80,HTTPS 使用 443,SMTP 使用 25,等等。1024 以下的端口称为“知名端口”;在 Linux 下,要在其中某个端口上开启服务,需要特殊权限。本章的示例使用 27100–27199 和 27200–27299 范围内的端口。

由 UDP 协议处理的分组称为数据报。它们具有如下形式:

Image

这些数据报被封装在 IP 分组中,然后再封装在物理帧中。当速度比可靠性更重要,或者应用程序自行处理分组丢失时,会使用 UDP:DNS(一问一答)、实时音视频流、在线游戏,以及 HTTP/3 的 QUIC 协议。

12.1.7.2. TCP 协议:Transmission Control Protocol

对于安全可靠的通信,UDP 协议是不够的:应用程序开发人员必须自己创建一个协议来确保分组被正确送达。TCP 协议避免了这些问题。它的特点如下:

  • 希望传输数据的进程首先与将接收其即将传输信息的进程建立连接。该连接通过三个段的交换(SYN、SYN-ACK、ACK:“三次握手”)建立在发送机器的某个端口与接收机器的某个端口之间。这样就在两个端口之间创建了一条虚电路,它将专门保留给建立连接的这两个进程;
  • 所有由源进程传输的字节都按其传输的顺序到达目的地,而 UDP 协议无法保证这一点,因为分组可能走不同的路径;
  • 传输的信息是连续的:它是字节流。发送进程按自己的节奏发送信息。这些信息不一定会被立即发送:TCP 协议可能会等到有足够的数据再发送。数据被放入称为 TCP 段的结构中。该段填满后,被传输到 IP 层,在那里封装成 IP 分组。对程序员的一个重要影响是:一次性发送的一“行”可能分成几块到达,而几行也可能一起到达。应用程序需要自己识别其消息的边界(我们将为此使用行尾字符);
  • TCP 协议发送的每个段都有编号。接收方的 TCP 协议会验证它是否按顺序接收到各个段。对于每个正确接收的段,它会向发送方发送确认;
  • 如果在一定时间后,发送某个段的 TCP 协议没有收到确认,它就会重传该段,从而确保信息传递服务的质量;
  • 在两个通信进程之间建立的虚电路是全双工的:信息可以同时在两个方向上传输。因此,即使源进程仍在继续发送信息,目标进程也可以发送确认。这使得,例如,源端的 TCP 协议可以在不等待确认的情况下发送多个段。如果在一定时间后它发现没有收到某个特定的第 n 号段的确认,它将从该处开始重新传输各段;
  • TCP 还会调节其数据速率,以避免使接收方过载(流量控制)或使网络过载(拥塞控制)。

12.1.8. 应用层

在 UDP 和 TCP 协议之上是各种标准协议:

TELNET 和 SSH

TELNET 允许机器 A 上的用户连接到机器 B(通常称为主机),就好像他们有一个连接到该机器的终端一样。TELNET 基于 TCP。它的数据交换,包括密码,都以明文传输:它已被 SSH(Secure Shell,安全外壳)取代,SSH 以加密方式提供相同的服务,还用于安全文件传输(SFTP、SCP)和创建隧道。截至 2008 年,[telnet]客户端程序仍是“手动”与 TCP 服务器通信的便捷工具:我们将看到如何替代它。

FTP(File Transfer Protocol,文件传输协议)

该协议用于在两台远程机器之间交换文件,以及执行创建目录等文件操作。它基于 TCP 协议。与 TELNET 一样,它以明文传输密码;它正在被 SFTP 和 HTTPS 逐步取代。

TFTP(Trivial File Transfer Protocol,简单文件传输协议)

该协议是 FTP 的简化变体。它基于 UDP 协议。它仍用于通过网络引导机器。

DNS(Domain Name System,域名系统)

当用户想要与远程机器交换信息时,必须知道该机器的 IP 地址。用名称来指代机器比用 IP 地址方便得多。这就引出了名称唯一性的问题:相互连接的机器数以十亿计。人们可能会设想由一个中央机构来分配名称,但那样会非常繁琐。对名称的控制权已按域进行了分散。每个域由一个组织管理,该组织在其域内可以完全自由地选择名称。因此,法国的机器通常属于域[fr],由 AFNIC 管理(在 1997 年 AFNIC 成立之前由 INRIA 管理)。为了进一步简化,控制权被分散得更远:在[fr]域内创建各个域。例如,昂热大学(University of Angers)拥有[univ-angers.fr]域;管理该域的部门可以完全自由地为大学网络上的计算机命名并创建子域。

机器的完整名称(FQDN,Fully Qualified Domain Name,完全限定域名)指明它所属的域的层级结构,从最具体到最一般:[www.univ-angers.fr]。在一个域内,通常可以使用相对名称,系统会自动将其补全。

因此,应用程序可以通过名称来指代机器。但最终,仍然需要获得该机器的 IP 地址。假设您想从机器 A 与机器 B 通信:

  • 机器 A 首先检查本地映射文件(Linux 和 macOS 上为[/etc/hosts] ,Windows 上为[C:\Windows\System32\drivers\etc\hosts] ),然后检查其缓存;
  • 否则,它会查询 DNS 服务器,其地址列在它的配置中(通常由 DHCP 提供)。它发送一个包含所查找机器名称的 DNS 请求。如果被查询的服务器知道答案或已将其缓存,就把对应的 IP 地址返回给机器 A。否则,它会依次——从根服务器开始——查询负责域[fr]、然后是[univ-angers.fr]的服务器,依此类推,直到获得答案,然后该答案会被逐级转发回机器 A。

DNS 域将各种类型的记录与名称关联起来:A(IPv4 地址)、AAAA(IPv6 地址)、CNAME(指向另一个名称的别名)、MX(域的邮件服务器)等。

HTTP 和 HTTPS(HyperText Transfer Protocol,超文本传输协议)

这是 Web 协议,也是当今使用最广泛的协议:不仅被浏览器使用,也被交换数据的应用程序使用(下一章讨论的 Web 服务)。我们将对其进行详细研究。HTTPS 是通过 TLS(Transport Layer Security,传输层安全)加密的连接传输的 HTTP;这现在已是 Web 的标准形式。

SMTP、POP3 和 IMAP

SMTP 用于发送电子邮件,而 POP3 和 IMAP 用于读取存储在服务器上的电子邮件。我们也将讨论这些协议。

XDR、RPC、NFS

2008 年的课程还介绍了 Sun Microsystems 定义的三个协议:XDR(eXternal Data Representation,外部数据表示),它规定了一种标准的、与机器无关的数据表示;RPC(Remote Procedure Call,远程过程调用),一种基于 XDR 的远程过程调用协议;NFS(Network File System,网络文件系统),它允许一台机器“看到”另一台机器的文件系统,并基于 RPC。NFS 在 Unix 世界中仍在使用。远程过程调用的概念被众多后继技术所采用;如今这些技术包括 REST Web 服务(基于 HTTP)和 gRPC(基于 HTTP/2)。

12.1.9. 结论

在这篇导论中,我们介绍了 Internet 协议的一些主要特性。若要更深入地探索这一领域,读者可以参阅 Douglas Comer 的经典著作《Internetworking with TCP/IP, Volume 1》(Pearson,第 6 版)——其早期版本已有法文译本——以及本章中引用的 RFC。对于 HTTP,Mozilla 位于developer.mozilla.org/en-US/docs/Web/HTTP的文档是极好的入门资料。

12.2. 用于 IP 地址管理的 .NET 类

Internet 上的机器由 IP 地址标识,IP 地址可以采用两种形式:

  • IPv4:编码为 32 位,用形如 "I1.I2.I3.I4" 的字符串表示,其中 In 是 0 到 255 之间的数字;
  • IPv6:编码为 128 位,用由冒号分隔的八组十六进制数字组成的字符串表示,例如 "2001:db8::8a2e:370:7334"。2008 年的课程声明不会使用 IPv6 地址;如今这已不可能:我们的程序将接受 IPv6 地址。

机器也可以由名称标识。这个名称不是必需的,因为应用程序最终总是使用机器的 IP 地址。名称的存在是为了方便用户:让浏览器访问 URL [https://learn.microsoft.com] 比访问由该站点某个 IP 地址构成的 URL 更容易,顺便说一句,该 IP 地址会随发出请求的位置而变化。

一台机器可以有多个 IP 地址:一个环回地址、其所连接的每个网络各一个地址,以及 IPv4 和 IPv6 地址。

在 .NET 中,IP 地址可以用两种方式表示:

  • 作为字符串 "I1.I2.I3.I4" 或 "2001:db8::1";
  • 作为类型[IPAddress] (命名空间[System.Net])的对象。

IPAddress 类

类[IPAddress] 的方法 M、属性 P 和静态字段 F 中包括以下内容:

成员
类型
作用
AddressFamily AddressFamily
P
IP 地址的族。类型[AddressFamily] (命名空间[System.Net.Sockets])是一个枚举,目前它的两个值是[AddressFamily.InterNetwork](IPv4)和[AddressFamily.InterNetworkV6] (IPv6)
static IPAddress Any
F
IPv4 地址 0.0.0.0。当服务与此地址关联时,它接受来自本机所有 IPv4 地址上的客户端
static IPAddress Loopback
F
环回地址 127.0.0.1。与此地址关联的服务只接受与其位于同一台机器上的客户端
static IPAddress Broadcast
F
广播地址 255.255.255.255([IPAddress.None] 的值与之相同)
static IPAddress IPv6Any, IPv6Loopback
F
IPv6 中分别对应于[Any] (::)和[Loopback] (::1)的地址
static IPAddress Parse(string ipString)
M
将 IPv4 或 IPv6 字符串转换为[IPAddress]对象;如果该字符串不是 IP 地址,则抛出[FormatException]
static bool TryParse(string ipString, out IPAddress address)
M
同上,但返回[false] 而不是抛出异常
static bool IsLoopback(IPAddress address)
M
如果地址是环回地址(127.x.y.z 或 ::1),则返回[true]
byte[] GetAddressBytes()
M
返回地址的字节(IPv4 为 4 个,IPv6 为 16 个)
string ToString()
M
返回地址的标准文本形式

另外两个类型是对[IPAddress]的补充:

  • [IPEndPoint] 表示连接点:一个 IP 地址和一个端口号。其属性[Address] 和[Port] 提供这两部分信息;静态方法[IPEndPoint.Parse] 解析诸如 "127.0.0.1:27100" 或 "[::1]:27100" 这样的字符串;
  • [IPNetwork] (自 .NET 8 起)表示 CIDR 表示法的网络,例如 193.49.144.0/24。其方法[Contains] 用于判断某个地址是否属于该网络。

程序[internet-01.cs] 演示了这三个类型:

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

// IPAddress、IPEndPoint 和 IPNetwork 类

// IPv4 和 IPv6 地址,正确或不正确的
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:如果字符串不是 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 会抛出异常
try
{
    IPAddress.Parse("256.1.1.1");
}
catch (FormatException ex)
{
    Console.WriteLine($"Parse(\"256.1.1.1\"): {ex.GetType().Name} : {ex.Message}");
}

// 几个预定义的地址
Console.WriteLine($"Any={IPAddress.Any}, Loopback={IPAddress.Loopback}, Broadcast={IPAddress.Broadcast}");
Console.WriteLine($"IPv6Any={IPAddress.IPv6Any}, IPv6Loopback={IPAddress.IPv6Loopback}");

// 端点 = IP 地址 + 端口
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})");

// CIDR 表示法的网络:网络地址 / 前缀长度
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))}");
}

结果:

> 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

说明:

  • 第 7 行:使用集合表达式初始化待解析的字符串数组;
  • 第 12 行:如果字符串是 IPv4 或 IPv6 地址,[TryParse] 返回[true] ,并将得到的[IPAddress] 对象赋给变量[address]。可空类型[IPAddress?] 表明解析失败时,该变量被设置为[null] ;
  • 第 14 行:属性[AddressFamily] 用于区分 IP 的两个版本;
  • 第 15 行:[GetAddressBytes] 返回地址的字节,[Convert.ToHexString] 以十六进制显示它们。可以看到(结果的第 2 行)193.49.144.1 由四个字节 C1、31、90、01 组成,并且(第 5 行)::1 由 15 个零字节后跟一个值为 1 的字节组成;
  • 结果的第 4 行:出人意料。字符串 "192.168.1" 被接受并转换为 192.168.0.1。[TryParse] 确实接受 IPv4 地址的历史缩写形式(此时最后一个数字占据所有剩余的字节)。因此,要验证某个输入是完整的 IPv4 地址,还必须检查它是否包含四个数字;
  • 第 6 行:IPv6 地址以其标准化的紧凑形式重新显示。前缀 2001:db8::/32 与 IPv4 中的 192.0.2.0/24 一样,保留用于文档;
  • 第 27–31 行:对于字符串“256.1.1.1”(256 无法放入一个字节),[IPAddress.Parse] 会产生[FormatException] 。与整个课程一样,异常消息是英文的(.NET 不提供法文翻译);
  • 第 41 行:[IPEndPoint]对象将一个地址和一个端口关联起来。它的显示(结果的第 12 行)形式为 地址:端口;在 IPv6 中(第 13 行),地址用方括号括起来;
  • 第 47 行:CIDR 表示法的网络。结果的第 14–15 行显示 193.49.144.1 属于 193.49.144.0/24 网络,而 193.49.145.3(我们图中路由器在其第二个网络上的地址)不属于该网络。这正是机器在选择直接路由还是间接路由时所做的测试。

Dns 类

IP 地址与主机名之间的映射由 DNS 处理。[Dns]类(命名空间[System.Net])的静态方法允许您查询它:

方法
作用
Task<IPHostEntry> GetHostEntryAsync(string hostNameOrAddress)
根据字符串形式的机器名或 IP 地址返回[IPHostEntry]对象。如果找不到该机器,则抛出[SocketException]
Task<IPHostEntry> GetHostEntryAsync(IPAddress address)
同上,但根据[IPAddress]对象
Task<IPAddress[]> GetHostAddressesAsync(string hostNameOrAddress)
仅返回该机器上的 IP 地址
string GetHostName()
返回运行该程序的机器的名称

这些异步方法中的每一个都有同步版本([GetHostEntry]、[GetHostAddresses]),2008 年的课程使用的就是同步版本。DNS 请求可能需要几十毫秒,如果服务器没有响应甚至可能需要几秒:正如我们在异步编程一章中所见,最好不要在等待时阻塞线程。

[IPHostEntry]对象封装了 IP 地址、别名和机器名:

属性
类型
作用
IPAddress[] AddressList
P
机器的 IP 地址数组
string[] Aliases
P
系统已知的该机器的其他名称(通常为空)
string HostName
P
机器的主名称

程序[internet-02.cs] 显示其所在机器的名称,然后以交互方式列出机器名与 IP 地址之间的映射:

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

// 显示本机的名称
// 然后以交互方式给出网络中各机器的信息
// 机器由名称或 IP 地址标识

// 本机
Console.WriteLine($"Local machine = {Dns.GetHostName()}");

// 交互式问答
while (true)
{
    // 输入所查找机器的名称或 IP 地址
    Console.Write("Machine looked for (nothing to stop): ");
    string machine = (Console.ReadLine() ?? "").Trim().ToLower();
    // 完成了吗?
    if (machine == "")
    {
        break;
    }
    try
    {
        // (异步)查询 DNS
        IPHostEntry entry = await Dns.GetHostEntryAsync(machine);
        // 机器的名称
        Console.WriteLine($"Machine: {entry.HostName}");
        // 它的 IP 地址
        Console.WriteLine($"IP addresses: {string.Join(", ", entry.AddressList.Select(ip => ip.ToString()))}");
        // 它可能的别名
        if (entry.Aliases.Length != 0)
        {
            Console.WriteLine($"Aliases: {string.Join(", ", entry.Aliases)}");
        }
    }
    catch (SocketException ex)
    {
        // 未找到该机器
        Console.WriteLine($"Unable to find the machine [{machine}]: {ex.SocketErrorCode} ({ex.Message})");
    }
}

结果:

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

说明:

  • 第 9 行:本地机器的名称。我们的测试机器是一台名为[vm]的 Linux 虚拟机;对读者来说,这当然是他们自己计算机的名称;
  • 第 25 行:异步 DNS 查询。如果名称(或地址)未知,则抛出 [SocketException];其属性[SocketErrorCode] (第 39 行)以枚举形式给出错误的性质,比消息更容易测试;
  • 第 29 行:机器的 IP 地址由[string.Join]合并为一个字符串,合并之前先由[Select] (LINQ)转换为字符串。

这些结果值得做几点说明。它们取决于机器的配置:不要期望在您自己的系统上得到完全相同的结果。

  • 第 4 行:名称[localhost] 对应于环回地址 127.0.0.1。在启用了 IPv6 的机器上,还会得到 ::1;
  • 第 8 行:该机器的名称对应两个地址:环回地址和其网络接口的地址。在名为 PC、连接到路由器的 Windows 机器上,通常会得到一个形如 192.168.x.y 的私有地址以及一个或多个 IPv6 地址;
  • 第 9 行:给定一个 IP 地址,[GetHostEntryAsync] 会执行“反向”查找,并返回与该地址关联的名称;
  • 第 13 行:对 ::1 的反向查找失败,因为我们测试机器上的文件[/etc/hosts] 没有把任何名称与该地址关联,而且那里没有启用 IPv6 接口。在 Windows 上,则会返回机器名;
  • 第 15 行:名称[xx] 未知。这里的异常消息来自 Linux 系统库;在 Windows 上会有所不同,但在两种情况下,[SocketErrorCode] 都等于[HostNotFound] 。

在连接到 Internet 的机器上,您还可以查询公共名称,例如[learn.microsoft.com]。通常,这会返回一个与所请求名称不同的主名称(该站点由内容分发网络提供服务,所请求的名称是一个 DNS 别名),以及随请求的位置和时间而变化的地址。我们不再列出该结果,因为我们的测试机器没有 Internet 访问权限。

12.3. Web 编程基础

12.3.1. 总体概述

考虑两台远程机器 A 和 B 之间的通信:

Image

当机器 A 上的应用程序 AppA 想要通过 Internet 与机器 B 上的应用程序 AppB 通信时,它必须知道几件事:

  • 机器 B 的 IP 地址或名称;
  • 应用程序 AppB 使用的端口号。这是因为机器 B 上可能运行着许多在 Internet 上工作的应用程序。当它从网络接收到信息时,必须知道该信息是发给哪个应用程序的。机器 B 上的应用程序通过称为通信端口的接口访问网络。目标端口号包含在机器 B 收到的段中,以便将其递交给正确的应用程序;
  • 机器 B 理解的通信协议。在我们的学习中,我们将只使用 TCP/IP 协议;
  • 应用程序 AppB 所支持的通信协议。事实上,机器 A 和 B 将相互“交谈”。它们所说的内容将被封装在 TCP/IP 协议中。然而,当链条末端的应用程序 AppB 收到应用程序 AppA 发送的信息时,它必须能够解释这些信息。这类似于两个人 A 和 B 通过电话交谈的情形:他们的谈话通过电话传送,但如果 A 说法语而 B 听不懂这种语言,A 和 B 就无法进行有意义的对话。因此,通信的两个应用程序必须就它们所使用的通信类型达成一致。例如,与 Web 服务器通信不同于与邮件服务器通信:这两种服务不接受相同的命令。它们有不同的通信协议。

12.3.2. TCP 协议的特性

在这里,我们只关注使用 TCP 传输协议的网络通信。让我们回顾一下它对程序员而言的主要特性:

  • 首先在客户端机器上的一个端口与服务器机器上的一个端口之间建立连接。它由四项信息标识:客户端的 IP 地址和端口,以及服务器的 IP 地址和端口;
  • 该连接承载两个字节流,每个方向一个(全双工)。字节按其传输的顺序到达,没有丢失,也没有重复;
  • TCP 不识别消息的概念:由应用程序的通信协议来界定请求和响应(通过换行、指定长度、关闭连接等);
  • 双方中的一方关闭连接;另一方在读到读取流的末尾时检测到这一点。

12.3.3. 客户端-服务器关系

Internet 上的通信往往是不对称的:机器 A 发起到机器 B 的连接,以请求服务。它指明希望与机器 B 的服务 SB1 建立连接。机器 B 接受或拒绝该请求。如果接受,机器 A 就可以向服务 SB1 发送其请求。这些请求必须遵守服务 SB1 所理解的通信协议。这样,在被称为客户端机器的机器 A 与被称为服务器机器的机器 B 之间就建立了请求-响应对话。双方中的一方将关闭连接。

12.3.4. 客户端架构

请求服务器应用程序服务的网络程序,其架构如下:

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. 服务器架构

提供服务的程序,其架构如下:

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

服务器程序处理客户端的初始连接请求与其后的服务请求的方式不同。监听程序本身不提供服务:如果它提供服务,那么在服务进行期间它就不再监听连接请求,其他客户端就得不到服务。因此它采用不同的做法:一旦在监听端口上收到并接受连接请求,服务器就创建一个任务,负责通过刚刚建立的服务连接提供客户端所请求的服务。这使得可以同时为多个客户端服务:

Image

2008 年的课程声称服务连接在服务器端使用另一个随机选择的端口。这是不正确的:所有服务连接都使用服务器的监听端口;它们通过客户端的地址和端口相互区分,这些是不同的。我们将在回显服务器的输出中看到这一点。

服务任务将具有如下结构:

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. 探索 Internet 通信协议

12.4.1. 简介

当客户端连接到服务器时,二者之间就建立了对话。这种对话的性质构成了所谓服务器的通信协议。最常见的 Internet 协议包括:

  • HTTP:HyperText Transfer Protocol,与 Web 服务器(HTTP 服务器)通信的协议;
  • SMTP:简单邮件传输协议(Simple Mail Transfer Protocol),用于与邮件发送服务器(SMTP 服务器)通信的协议;
  • POP:邮局协议(Post Office Protocol),用于与邮件存储服务器(POP 服务器)通信的协议。它用于获取收到的邮件,而不是发送邮件。IMAP 的用途与之相同;
  • FTP:文件传输协议(File Transfer Protocol),用于与文件存储服务器(FTP 服务器)通信的协议。

这些协议在其历史版本中的特点是基于文本:客户端和服务器交换以两个字符 \r\n(回车、换行)结尾的文本行。如果有一个客户端能够:

  • 与 TCP 服务器建立连接;
  • 在控制台上显示服务器发送的文本行;
  • 向服务器发送用户在键盘上键入的文本行,

那么只要我们知道该协议的规则,就可以使用基于文本的协议与 TCP 服务器通信。

程序 [telnet] 过去在 Unix 和 Windows 机器上都有提供,就是这样一种客户端;2008 年的课程使用的是 PuTTY 工具,并将其配置为原始连接模式。[telnet] 客户端在 Windows 上已不再默认安装,而且大多数公共服务器也不再接受未加密的通信。我们将采用不同的做法:

  • 对于 HTTP,我们将使用 [curl] 工具(Windows 10 和 11 以及 Linux 上均默认提供),它会显示交换的详细信息,随后再使用本章稍后编写的通用 TCP 客户端。在 Windows 的 PowerShell 中,[curl] 是命令 [Invoke-WebRequest] 的别名:必须键入 [curl.exe];
  • 由于我们无法访问真实的服务器,因此我们将查询一个自己编写、运行在本地机器上的小型 Web 服务器;
  • 对于 SMTP、POP 和 FTP,我们将给出符合定义这些协议的 RFC 的示例对话。

12.4.2. 测试用 Web 服务器

我们的测试 Web 服务器是一个名为“最小 API(Minimal API)”的单文件 ASP.NET Core 应用程序。ASP.NET Core 是 .NET 的 Web 开发框架,我们将在下一章中学习。目前不必详细理解这个程序,只需知道它输出什么即可。[internet-03.cs] 程序如下:

#:sdk Microsoft.NET.Sdk.Web

// 一个小型本地 Web 服务器,用作我们 HTTP 客户端的目标
// 调用: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);
// 不输出 ASP.NET 日志(仅警告):我们自己编写日志
builder.Logging.SetMinimumLevel(LogLevel.Warning);
var app = builder.Build();

// 控制台跟踪:每个请求及其响应的状态码
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}");
});

// 这些 URL 接受 GET 和 HEAD 方法
string[] getHead = ["GET", "HEAD"];

// 主页:一个 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"));

// 由 URL 的参数构建的文本文档
app.MapMethods("/hello", getHead, (string? name) => $"Hello {name ?? "unknown"}!");

// 临时重定向(302)到一个相对地址
app.MapMethods("/old", getHead, () => Results.Redirect("/hello?name=visitor"));

// 永久重定向(301)到一个绝对地址
app.MapMethods("/moved", getHead, () => Results.Redirect($"http://localhost:{port}/", permanent: true));

// 一个循环指向自身的重定向
app.MapMethods("/loop", getHead, () => Results.Redirect("/loop"));

// 任何其他 URL 都得到 404 Not Found 响应(默认行为)
Console.WriteLine($"Web server started on http://localhost:{port}");
app.Run($"http://127.0.0.1:{port}");

说明:

  • 第 1 行:该指令指定单文件应用程序使用 ASP.NET Core 的 SDK Web 版本([Microsoft.NET.Sdk.Web]),而不是通常的 SDK 控制台版本。ASP.NET Core 的命名空间([Microsoft.AspNetCore.Builder]、[Microsoft.AspNetCore.Http]……)随后便成为默认 [using] 的一部分;
  • 第 5 行:监听端口,默认为 27110;
  • 第 13–18 行:每个处理过的请求都会连同响应状态码一起显示在控制台上;
  • 第 25 行:URL [/] 返回一个小型 HTML 文档。文档文本使用原始字符串字面量 [""" ... """] (C# 11)编写,这样就无需对引号进行转义;
  • 第 35 行:URL [/hello?name=xx] 返回文本 [Hello xx!]。lambda 的 [name] 参数会自动用 URL 的 [name] 参数填充;
  • 第 38 行:URL [/old] 会触发临时重定向(状态码 302),指向相对地址 [/hello?name=visitor];
  • 第 41 行:URL [/moved] 会触发永久重定向(状态码 301),指向绝对地址 [http://localhost:27110/];
  • 第 44 行:URL [/loop] 重定向到它自身:盲目跟随重定向的客户端将永远不会停止;
  • 任何其他 URL 都会收到 404 响应(找不到页面);
  • 第 48 行:服务器监听环回地址 127.0.0.1:只有本机才能访问它。

服务器在命令窗口中启动。它显示:

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

第 3–4 行是在下一段所述的测试期间出现的。按 Ctrl-C 可停止服务器。

12.4.3. HTTP 协议(HyperText Transfer Protocol,超文本传输协议)

服务器运行期间,我们在第二个命令窗口中使用 [curl] 工具请求站点 [http://localhost:27110] 的根 [/]。其 [-v] (详细)选项会显示完整的 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

说明:

  • 以 [*] 开头的行包含来自 [curl] 的信息;以 [>] 开头的行是发送给服务器的;以 [<] 开头的行是从服务器接收到的;其余的行构成接收到的文档;
  • 第 2–6 行:[curl] 获取了 [localhost] 的地址(IPv6 为 ::1,IPv4 为 127.0.0.1),并连接到地址 127.0.0.1 的 27110 端口;
  • 第 7–10 行:客户端的请求。它由一个采用 [method URL version] 语法的第一行(这里使用 [GET] 方法,通过 HTTP/1.1 请求文档 [/],即站点的根)、随后的 [Name: value] 形式的 HTTP 标头,以及结尾的一个空行组成;
  • 第 8 行:[Host] 标头指明被查询的机器和端口;它在 HTTP/1.1 中是必需的,因为同一台服务器可能托管多个站点;
  • 第 9 行:客户端软件的标识符;
  • 第 10 行:客户端接受的文档类型,此处为所有类型;
  • 第 12–16 行:响应标头,同样以一个空行结尾;
  • 第 12 行:状态行,语法为 [version code message]。代码 200 表示找到了所请求的文档;
  • 第 13 行:文档大小(以字节为单位)。这告诉客户端文档在哪里结束;
  • 第 14 行:文档类型(HTML 文档)及其编码(UTF-8);
  • 第 15 行:服务器的日期和时间,始终采用协调世界时(GMT);
  • 第 16 行:提供 Web 服务的软件,此处为 Kestrel,即 ASP.NET Core 的 Web 服务器。在 2008 年的课程中,它是带有 PHP 4 的 Apache 1.3 服务器;
  • 第 18–22 行:服务器发送的文档;
  • 第 23 行:在 HTTP/1.1 中,响应之后连接默认保持打开(“keep-alive”模式),以便处理其他请求;[curl] 会让它保持打开,并在自身终止时将其关闭。

现在我们来请求一个不存在的文档:

> 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
  • 第 7 行:我们请求了一个不存在的文档;
  • 第 12 行:服务器以 404 状态码作出响应,表示未找到所请求的文档;
  • 第 13 行:发送的文档为空。默认情况下,Kestrel 不会在 404 响应中附带任何文档;2008 年查询的 Apache 服务器则会发送一个简短的说明性 HTML 页面。收到不带文档的 404 响应时,浏览器会显示它自己的错误页面。

状态码分为五类:1xx(信息)、2xx(成功,200 OK)、3xx(重定向,301 和 302,我们稍后会讲到)、4xx(客户端错误:404 Not Found、401 Unauthorized、403 Forbidden……)、5xx(服务器错误:500 Internal Server Error……)。

浏览器的做法与 [curl] 相同:它发送 HTTP 请求,接收标头和文档,然后显示文档。浏览器开发者工具(F12 键,“网络”选项卡)可以查看交换的标头。

关于 HTTP 的现状,有几点说明:

  • HTTPS 现已成为标准:浏览器会将使用普通 HTTP 的站点标记为“不安全”。使用 HTTPS 时,HTTP 对话之前会先进行 TLS 协商,此后的所有内容都经过加密。因此,已无法再用简单的 TCP 客户端与 HTTPS 服务器“手动”通信。不过,仍然可以用 [curl] 观察对话,它会执行 TLS 握手,然后以明文 显示标头。仅作说明(由于我们的测试机器无法访问互联网,这里不再给出结果),命令将是 [curl -v https://learn.microsoft.com/];
  • HTTP/1.1(现为 RFC 9112)是一种基于文本的协议,也是我们所学习的协议。HTTP/2(2015 年,现为 RFC 9113)保留了相同的方法、标头和状态码,但以压缩的二进制格式传输它们,并在单个 TCP 连接上同时发送多个请求。HTTP/3(2022 年,RFC 9114)做的是同样的事情,但基于 QUIC,因而基于 UDP。浏览器和服务器会自动选择双方共有的最新版本;不带任何特定选项的 [curl] 对 [http://] URL 使用 HTTP/1.1。

12.4.4. SMTP 协议(Simple Mail Transfer Protocol)

SMTP 服务器之间通过 25 端口交换电子邮件。发送邮件的电子邮件客户端在完成身份验证后,会将邮件提交给其提供商的 SMTP 服务器,使用 587 端口(提交端口,通过 [STARTTLS] 命令切换到加密模式)或 465 端口(从一开始就是加密连接)。互联网服务提供商通常会阻止其用户路由器向 25 端口发起出站连接,以限制被感染机器发送的垃圾邮件:2008 年课程中展示的未加密对话,如今已无法在个人计算机上进行。

下面是一段符合 RFC 5321 的典型 SMTP 对话,仅作说明。这不是真实的执行过程:以 [C:] 为前缀的行由客户端发送,以 [S:] 为前缀的行由服务器发送,域名 [example.org] 和 [example.com] 是专为示例保留的:

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
  • 第 1 行:来自服务器的欢迎消息。服务器的每个响应都以三位数字代码开头:2xx 表示成功,3xx 表示“请继续”,4xx 和 5xx 表示错误;
  • 第 2 行:客户端表明身份。命令 [EHLO] 取代了 2008 年课程中的命令 [HELO] :它要求服务器列出其支持的扩展;
  • 第 3–6 行:服务器的响应,占多行。代码后面的连字符表示响应还会继续;最后一行则是空格。这里服务器声明它接受最大 10 MB 的邮件、支持加密模式并接受 8 位字符;
  • 第 7 行:发件人的地址;
  • 第 9 行:收件人的地址(对于多个收件人,该命令可以重复);
  • 第 11 行:客户端宣告要发送邮件;
  • 第 12 行:服务器提示客户端发送邮件,并提醒它如何结束;
  • 第 13–19 行:邮件,由标头([From]、[To]、[Subject]……)、一个空行和正文组成,并以只含一个句点的行结束;
  • 第 20 行:服务器接受了该邮件并将其放入队列;
  • 第 21–22 行:客户端表示已完成;服务器关闭连接。

12.4.5. POP 协议(Post Office Protocol)

POP3 服务器工作在 110 端口,或使用 TLS 加密连接的 995 端口——由于密码会在对话中传输,这是目前大多数提供商唯一提供的选项。下面是一段符合 RFC 1939 的典型 POP3 对话,采用与上一段相同的约定来呈现:

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.
  • 第 1 行:来自服务器的欢迎消息。POP3 的响应以 [+OK] (成功)或 [-ERR] (错误)开头;
  • 第 2 行:客户端提供其用户名,即它用于读取电子邮件的名称;
  • 第 4 行:客户端的密码(此处已隐藏);
  • 第 6 行:客户端请求其电子邮件的列表;
  • 第 7–10 行:客户端邮箱中的邮件列表,格式为 [message number, size in bytes],以只含一个句点的行结束;
  • 第 11 行:请求 2 号邮件;
  • 第 12–23 行:2 号邮件,包含其标头、一个空行和正文,同样以句点结束;
  • 第 24–25 行:客户端表示已完成;服务器关闭连接。

POP3 旨在将电子邮件下载到用户的计算机上。如今它面临来自 IMAP(143 端口,或使用 TLS 的 993 端口;RFC 9051)的强劲竞争,IMAP 会把邮件保留在服务器上,并允许从多台设备以及通过基于 Web 的电子邮件客户端查看和整理邮件。

12.4.6. FTP 协议(File Transfer Protocol)

FTP 协议(RFC 959)比前面介绍的协议更复杂:对话(命令及其响应)通过与服务器 21 端口建立的控制连接进行,而每个文件或文件列表的传输则使用专门为此打开的第二个连接。下面是控制连接上的一段典型对话:

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.
  • 第 2 行:匿名连接,公共下载服务器提供这种方式;
  • 第 8 行:客户端要求服务器为数据连接打开一个端口。服务器(第 9 行)回复说,它正在 40312 端口等待该连接;
  • 第 10 行:客户端请求文件 [readme.txt]。文件通过数据连接到达,而控制连接则收到响应 150(传输开始)和 226(传输结束)。

2008 年的课程建议在 FileZilla 客户端的日志中监视这些命令,这现在仍然可行。不过,FTP 正在逐渐过时:它以明文传输密码,由于第二个连接而难以与防火墙配合工作,并且浏览器自 2021 年起已不再支持它(Chrome 88、Firefox 90)。最好使用 SFTP(通过 SSH 进行的文件传输),以及通过 HTTPS 进行的简单下载。

12.5. Web 编程中的 .NET 类

12.5.1. 选择合适的类

.NET 提供了各种用于网络编程的类:

Image

  • [Socket] 类最接近网络层,可对网络连接进行精细管理。英文术语“socket”原指电源插座,其含义后来被扩展为指软件网络套接字。在 A、B 两台机器之间的 TCP/IP 通信中,由两个套接字相互通信。应用程序可以直接使用套接字:上面的应用程序 A 就是这种情况。套接字既可以是客户端套接字,也可以是服务器套接字;
  • 如果希望在比 [Socket] 类更高的层次上工作,可以使用 [TcpClient] 类创建(TCP)客户端,并使用 [TcpListener] 类 创建(TCP)服务器(上面的应用程序 B)。这两个类替应用程序处理套接字的技术细节,为其提供更简单的网络通信视图。[UdpClient] 类在 UDP 方面发挥相同的作用;
  • .NET 还提供专用于特定协议的类。如今最重要的是 [HttpClient](上面的应用程序 C),它管理 1.1、2 和 3 版本的 HTTP 协议,包括 HTTPS 的 TLS 加密。2008 年的课程讲授了 [WebClient] 和 [WebRequest] 这两个类,它们现已过时,被 [HttpClient] 取代(我们将在本章第二部分回到这一点),还讲授了用于发送邮件的 [SmtpClient] 类,该类虽未被声明为过时,但微软已不再推荐在新开发中使用。

值得注意的是,[Socket] 类本身就足以处理所有 TCP/IP 通信,但我们将主要使用更高层的类,以简化应用程序的开发。

12.5.2. TcpClient 类

[TcpClient] 类(命名空间 [System.Net.Sockets])在大多数情况下是创建 TCP 服务客户端的合适类。在其构造函数(C)、方法(M)和属性(P)中,包含以下成员:

成员
类型
作用
TcpClient()
C
创建一个尚未连接的客户端
Task ConnectAsync(string machine, int port), ValueTask ConnectAsync(string machine, int port, CancellationToken token)
M
(异步)与机器 [machine] 的 [port] 端口上运行的服务建立 TCP 连接。例如 [await client.ConnectAsync("localhost", 27110)]。还有接受 [IPAddress] 或 [IPEndPoint] 的重载。如果连接失败,则抛出 [SocketException]
NetworkStream GetStream()
M
获取到服务器的读写流。该流用于客户端与服务器之间的通信
Socket Client
P
客户端用来与服务器通信的套接字。其属性 [LocalEndPoint] 和 [RemoteEndPoint] 表示连接的两端
bool Connected
P
如果连接已建立(且未被客户端关闭),则为 true
void Close(), void Dispose()
M
关闭连接。套接字和 [NetworkStream] 流也会随之关闭

2008 年的课程使用 [TcpClient(string machine, int port)] 构造函数,它以阻塞方式连接:执行它的线程在整个连接建立期间都会被阻塞,如果远程机器没有响应,这可能长达几十秒。我们将使用 [ConnectAsync]。

[NetworkStream] 类表示客户端与服务器之间的网络流。它派生自 [Stream] 类,因此提供了读写字节的 [ReadAsync] 和 [WriteAsync] 方法。许多客户端/服务器应用程序交换的是文本行。因此,使用文件一章中介绍过的 [StreamReader] 和 [StreamWriter] 对象在网络流中读写这些行会很方便:

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

[AutoFlush = true] 属性表示对 [writer] 的每次写入都会立即通过网络传输,而无需等待 [StreamWriter] 的内部缓冲区填满。这一点很重要。通常,当客户端向其对端发送一行文本时,它期待得到响应。如果这一行一直留在发送机器的缓冲区中而没有发出,那么这个响应将永远不会到来。如果没有 [AutoFlush],则必须在写完一个完整的请求后显式调用 [FlushAsync] 。

要向服务器发送一行文本,请这样写:

await writer.WriteLineAsync("some text");

并读取服务器的响应:

        string? response = await reader.ReadLineAsync();

当对端关闭了连接并且其发送的所有内容都已读取完毕时,[ReadLineAsync] 返回 [null] :这标志着流的结束。

有一点值得注意:行结束符。[WriteLineAsync] 使用 [StreamWriter] 的 [NewLine] 属性值来结束一行,该属性默认为 [Environment.NewLine],即在 Windows 上为 \r\n,而在 Linux 和 macOS 上仅为 \n。互联网协议(HTTP、SMTP、POP、FTP)要求使用 \r\n。有些服务器(如 Kestrel)能容忍单个 \n,而另一些则不能;因此,使用这些协议之一的可移植程序必须设置 [NewLine = "\r\n"]。读取时,[ReadLineAsync] 同时接受 \r\n 和 \n。

现在我们已具备编写 TCP 客户端基本架构的要素,客户端与服务器之间采用如下基本通信协议:

  • 客户端发送一个包含在单独一行中的请求;
  • 服务器发送一个包含在单独一行中的响应。
try
{
    // 连接到服务
    using var client = new TcpClient();
    await client.ConnectAsync(server, port);
    // 网络流,读取流和写入流
    await using NetworkStream stream = client.GetStream();
    using var reader = new StreamReader(stream);
    await using var writer = new StreamWriter(stream) { AutoFlush = true };
    // 请求 - 响应循环
    while (true)
    {
        // 准备请求
        string request = ...;
        // 向服务器发送请求
        await writer.WriteLineAsync(request);
        // 读取服务器的响应
        string? response = await reader.ReadLineAsync();
        // 处理响应
        ...
    }
}
catch (SocketException ex)
{
    // 无法连接
    ...
}
catch (IOException ex)
{
    // 交互过程中出错
    ...
}
  • 第 4 行:创建客户端。[using] 声明(C# 8)确保无论发生什么,退出包含它的代码块时连接都会被关闭。2008 年的课程嵌套了四个 [using (...) { ... }] 语句;而 [using] 声明避免了这种嵌套;
  • 第 5 行:异步连接到服务;
  • 第 7 行:获取网络流。[await using](C# 8)通过调用对象的 [DisposeAsync] 方法([Dispose] 的异步版本)来释放对象:释放 [StreamWriter] 确实可能触发最后一次向网络的写入;
  • 第 8–9 行:在网络流上创建读取流和写入流;
  • 第 11–19 行:客户端请求/服务器响应的循环;
  • 第 16 行:客户端向服务器发送其请求;
  • 第 18 行:客户端等待服务器的响应。当以 \n 结尾的一行到达时,或者在服务器关闭连接而使流结束时,这一等待就会结束。等待期间,不会阻塞任何线程;
  • 第 23–28 行:[SocketException] 表示连接失败(机器未知、所请求的端口上没有服务等),而 [IOException] 表示通信过程中出现错误(连接丢失等)。

12.5.3. TcpListener 类

[TcpListener] 类在大多数情况下是创建 TCP 服务的合适类。在其构造函数(C)、方法(M)和属性(P)中,包含以下成员:

成员
类型
作用
TcpListener(IPAddress address, int port)
C
创建一个 TCP 服务,在地址 [address] 的 [port] 端口(称为监听端口)上监听客户端请求。使用 [IPAddress.Any] 时,服务监听本机所有 IPv4 地址;使用 [IPAddress.Loopback] 时,则只监听环回地址
static TcpListener Create(int port)
M
创建一个同时在机器所有地址的 IPv4 和 IPv6 上监听的服务
void Start()
M
开始监听客户端请求
Task<TcpClient> AcceptTcpClientAsync(), ValueTask<TcpClient> AcceptTcpClientAsync(CancellationToken token)
M
(异步)等待客户端请求并接受它。返回与该客户端已打开的服务连接在服务器端相关联的 [TcpClient] 对象
void Stop()
M
停止监听客户端请求
EndPoint LocalEndpoint
P
监听地址和端口
Socket Server
P
服务器的监听套接字

2008 年课程中使用的 [TcpListener(int port)] 构造函数已被声明为过时:必须指定监听地址,或使用 [TcpListener.Create]。

使用“一行请求、一行响应”协议与其客户端通信的 TCP 服务器,其基本结构可以如下:

// 监听服务,监听本机的所有网络接口
var listener = new TcpListener(IPAddress.Any, port);
listener.Start();
// 等待客户端的循环
while (true)
{
    // 等待一个客户端
    TcpClient client = await listener.AcceptTcpClientAsync();
    // 该客户端由另一个任务服务,我们不等待它
    _ = ServeAsync(client);
    // 下一个客户端
}

// 为客户端提供的服务
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 };
            // 读取请求 / 写入响应的循环
            while (await reader.ReadLineAsync() is string request)
            {
                // 准备响应
                string response = ...;
                // 向客户端发送响应
                await writer.WriteLineAsync(response);
            }
        }
    }
    catch (IOException ex)
    {
        // 错误
        ...
    }
}
  • 第 2 行:为给定的端口和给定的 IP 地址创建监听服务。一台机器至少有两个 IP 地址:环回地址 127.0.0.1,以及它在所连接网络上的地址。如果连接到多个网络,它还可能有其他地址。[IPAddress.Any] 指的是机器所有的 IPv4 地址;
  • 第 3 行:监听服务启动。它之前已经创建,但尚未开始监听。监听意味着等待来自客户端的连接请求;
  • 第 5–11 行:等待客户端并启动其服务的循环,对每个新客户端重复执行;
  • 第 8 行:接受一个客户端的请求。[AcceptTcpClientAsync] 返回一个名为 [TcpClient] 的服务实例:
    • 客户端使用它自己的 [TcpClient] 实例发出请求,我们称之为 [TcpClientRequest];
    • 服务器使用 [AcceptTcpClientAsync] 接受该请求,它会创建一个服务器端的 [TcpClient] 实例,我们称之为 [TcpClientService]。这时就有了一个已打开的 TCP 连接,其两端的实例是 [TcpClientRequest] ↔ [TcpClientService] ;
    • 随后进行的客户端/服务器通信都发生在这个连接上,监听服务不再参与;
  • 第 10 行:为了让服务器能同时处理多个客户端,服务由一个异步任务提供。服务器不等待它(没有 [await]),而是立即返回去等待下一个客户端。[ServeAsync] 返回的任务被赋给弃元变量 [_],向读者(和编译器)表明其结果被有意忽略;
  • 第 15 行:为客户端提供服务的方法。它接收实例 [TcpClient] 作为参数,该实例已与要服务的客户端建立连接;
  • 第 25 行:这里的代码与前面讨论的基本 TCP 客户端类似。当 [ReadLineAsync] 返回 [null](即客户端已关闭连接)时,循环停止。模式 [is string request] 检查读取到的值不是 [null] ,并将其赋给变量 [request];
  • 第 34 行:必须在 [ServeAsync] 中捕获异常:由于没有人在等待该任务,未捕获的异常将不会被察觉。

12.5.4. 每个客户端一个线程,还是每个客户端一个任务?

2008 年课程中的服务器把每个客户端分配给线程池中的一个线程([ThreadPool.QueueUserWorkItem]),该线程执行阻塞式的读写:只要客户端在思考,它的线程就一直阻塞在 [ReadLine] 中。每个线程都会消耗内存(约 1 MB 的保留栈)和处理器时间,因为系统必须在它们之间切换。对于几十个客户端,这不是问题;而面对成千上万的并发连接(真实服务器的常见场景),服务器就会崩溃。事实上,该课程把线程池限制为 10 个线程:第十一个客户端必须等待前十个中的某一个断开连接。

使用异步方法([AcceptTcpClientAsync]、[ReadLineAsync]、[WriteLineAsync])时,不发送任何内容的客户端不会占用任何线程:它的任务被挂起,只有在数据到达时,该任务的其余部分才会由线程池中的某个线程执行。因此,只需少量线程就足以服务成千上万的客户端。现代服务器正是这样工作的,尤其是 ASP.NET Core 的 Web 服务器 Kestrel。异步编程一章中介绍的原则在这里完全适用:从头到尾使用 [async] / [await] ,并使用 [CancellationToken] 来干净地终止正在进行的操作。

12.6. TCP 客户端和服务器示例

本节的程序是 [12-internet] 文件夹中的单文件应用程序。服务器和客户端在同一台机器上的不同命令窗口中启动;所用端口形如 271xx。

12.6.1. 回显服务器

我们将编写一个回显服务器,在命令窗口中通过以下命令启动:

dotnet run internet-04.cs -- port

服务器在作为参数传入的端口上运行。它只是把客户端发送的每一行用方括号括起来后发回给客户端。程序 [internet-04.cs] 如下:

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

// 回显服务器:把每个客户端发来的行原样发回给它
// 调用:dotnet run internet-04.cs,后接两个连字符和端口 port

const string syntax = "Syntax: dotnet run internet-04.cs -- port";
// 需要一个参数:1 到 65535 之间的端口
if (args.Length != 1 || !int.TryParse(args[0], out int port) || port is < 1 or > 65535)
{
    Console.WriteLine(syntax);
    return;
}

// Ctrl-C 取消令牌:服务器干净地停止
using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) =>
{
    // 我们阻止进程被突然终止
    e.Cancel = true;
    cancellation.Cancel();
};

// 监听服务,监听本机的所有网络接口
var listener = new TcpListener(IPAddress.Any, port);
// 正在进行的服务任务
var services = new List<Task>();
int clientNumber = 0;
try
{
    // 我们启动它
    listener.Start();
    Console.WriteLine($"Echo server started on {listener.LocalEndpoint}");
    // 等待客户端的循环 - 由 Ctrl-C 停止
    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");
}
catch (SocketException ex)
{
    Console.WriteLine($"The following error occurred on the server: {ex.SocketErrorCode} ({ex.Message})");
}
finally
{
    // 监听结束
    listener.Stop();
}
// 离开之前,我们等待正在进行的服务结束
await Task.WhenAll(services);

// --------------------------------------------------------------------
// 为客户端提供的服务
static async Task ServeAsync(TcpClient client, int clientNumber, CancellationToken token)
{
    Console.WriteLine($"Start of service to client {clientNumber} ({client.Client.RemoteEndPoint})");
    try
    {
        // 离开代码块时,连接和网络流会被释放
        using (client)
        {
            await using NetworkStream stream = client.GetStream();
            using var reader = new StreamReader(stream);
            await using var writer = new StreamWriter(stream) { AutoFlush = true };
            // 读取请求 / 写入响应的循环
            // 客户端关闭连接时,ReadLineAsync 返回 null
            while (await reader.ReadLineAsync(token) is string request)
            {
                Console.WriteLine($"<--- client {clientNumber} : {request}");
                // 把请求回显给客户端,放在方括号之间
                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}");
    }
}

回显服务器的结构符合前面所述的 TCP 服务器基本架构,并有一些补充:

  • 第 9 行:端口必须是 1 到 65,535 之间的整数。组合关系模式 [is < 1 or > 65535] (C# 9)简洁地表达了这一条件;
  • 第 16–21 行:关闭服务器。2008 年的服务器是被 Ctrl-C 突然终止的:进程终止时并未关闭连接。这里,事件 [Console.CancelKeyPress] 由 Ctrl-C 触发。其处理程序阻止进程立即终止(第 20 行),并取消令牌 [cancellation] (第 21 行);
  • 第 38 行:对客户端的等待接收取消令牌。令牌被取消时,等待以 [OperationCanceledException] 结束,该异常在第 45 行被拦截;
  • 第 40–42 行:每个客户端由一个任务提供服务,循环不会等待这些任务。这些任务保存在一个列表中,已完成的任务会在结束时从中移除;
  • 第 56 行:监听结束,通过 [finally] 在所有情况下都会执行;
  • 第 59 行:退出之前,我们等待当前的服务结束。由于它们收到了相同的取消令牌,因此会很快终止。

“客户端服务”部分:

  • 第 65 行:客户端的地址和端口;
  • 第 76 行:读取客户端的请求。如果服务器关闭,取消令牌会中断等待。当客户端关闭连接时,[ReadLineAsync] 返回 [null] :随后循环和服务停止;
  • 第 80 行:请求被用方括号括起来后返回给客户端;
  • 第 85–89 行:处理服务器关闭以及客户端终止连接的情况;
  • 第 95 行:无论原因如何,[finally] 都会发出服务结束的信号。

要看到服务器运行,我们需要一个客户端。2008 年的课程使用 PuTTY;我们将在下一节编写自己的客户端,并在之后展示结果。

12.6.2. 回显服务器的客户端

现在我们为上一个服务器编写一个客户端。它的调用方式如下:

dotnet run internet-05.cs -- machine port

它连接到机器 [machine] 的 [port] 端口,然后把通过键盘输入的文本发送给服务器,服务器再把它回显回来。程序 [internet-05.cs] 如下:

using System.Net.Sockets;

// 回显客户端:把键盘键入的行发送给服务器
// 并显示服务器的回答
// 调用: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
{
    // (异步)连接到服务
    using var client = new TcpClient();
    await client.ConnectAsync(server, port);
    Console.WriteLine($"Connected to the server {client.Client.RemoteEndPoint} from {client.Client.LocalEndPoint}");
    // 连接上的读取流和写入流
    await using NetworkStream stream = client.GetStream();
    using var reader = new StreamReader(stream);
    // AutoFlush:每写入一行就立即发送到网络上
    await using var writer = new StreamWriter(stream) { AutoFlush = true };
    // 请求 - 响应循环
    while (true)
    {
        // 请求来自键盘
        Console.Write("Request (bye to stop): ");
        string? request = Console.ReadLine();
        // 完成了吗?
        if (request is null || request.Trim().Equals("bye", StringComparison.OrdinalIgnoreCase))
        {
            break;
        }
        // 我们把请求发送给服务器
        await writer.WriteLineAsync(request);
        // 我们等待它的响应
        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}");
}

该客户端的结构符合为 TCP 客户端提出的基本架构:

  • 第 19 行:异步连接到服务器;
  • 第 20 行:显示连接的两端:[RemoteEndPoint] (服务器)和 [LocalEndPoint] (客户端)。客户端的端口由系统选择;
  • 第 25 行:写入的每一行都会立即发送;
  • 第 31 行:请求通过键盘键入。如果标准输入已关闭(Linux 上为 Ctrl-D,Windows 上为 Ctrl-Z 后按 Enter),[Console.ReadLine] 返回 [null] ;
  • 第 33 行:与 [bye] 的比较不区分大小写;
  • 第 38 行:请求被发送给服务器;
  • 第 40–43 行:等待响应;[null] 表示服务器已关闭连接;
  • 第 49–53 行:连接和交换错误。

以下是在如下配置下得到的结果:

  • 服务器在命令窗口中运行于 27100 端口;
  • 在同一台机器上,两个客户端 A 和 B 在另外两个窗口中运行;客户端 B 启动时,客户端 A 仍在与服务器通信。

在客户端 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

客户端 A 发送了三行,它们都被回显回来,然后键入 [bye]:它关闭了连接,没有再向服务器发送任何内容。

在客户端 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

客户端 B 发送了两行,然后在键入第三行之前,服务器被 Ctrl-C 终止。[line3B] 这一行是在已被服务器关闭的连接上发送的:读取响应(第 8 行)返回 [null]。

在服务器窗口中:

> 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
  • 第 2 行:服务器在 27100 端口上监听本机所有的 IPv4 地址(0.0.0.0);
  • 第 3–6 行:两个客户端都来自同一台机器(127.0.0.1),使用由系统选择的不同端口。这些端口区分了两个连接,两者都终止于服务器的 27100 端口;
  • 第 6 行:客户端 1(B)正在被服务,而客户端 0(A)仍在被服务:服务器确实在同时服务多个客户端;
  • 第 11 行:服务器检测到客户端 A 关闭了连接;
  • 第 16–18 行:在服务器窗口中按下了 Ctrl-C。对新客户端的等待被取消,随后对客户端 1(它正在等待一行)的服务被同一个取消令牌中断。服务器正常关闭。

最后,来看看尝试连接到没有服务监听的端口时会发生什么:

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

[ConnectAsync] 抛出了 [SocketException] ,代码为 [ConnectionRefused]:机器作出了响应,但 27199 端口上没有程序在监听。该消息来自操作系统;在 Windows 上则有所不同。

12.6.3. 通用 TCP 客户端

我们将编写一个通用 TCP 客户端,其启动方式如下:

dotnet run internet-06.cs -- machine port

它的功能类似于 [telnet] 和 PuTTY 客户端:可以与任何基于文本的 TCP 服务器通信。

在上一个应用程序中,通信协议是已知的:客户端发送一行,服务器回复一行。每种服务都有自己特定的协议,因此还可能出现以下情况:

  • 客户端必须发送多行文本后才会收到响应(HTTP 请求);
  • 服务器的响应可能由多行文本组成(SMTP 服务器的 [EHLO] 响应,HTML 文档);
  • 服务器可能先开口(SMTP 和 POP 服务器的欢迎消息)。

因此,“向服务器发送一行 / 接收服务器发送的一行”这一循环并不总是适用。为了处理比回显协议更复杂的协议,通用 TCP 客户端并行执行两项任务:

  • 主程序读取键盘上键入的文本行并将其发送给服务器;
  • 另有一个任务专门读取服务器发送的文本行。一收到文本行,它就把它显示在控制台上。直到连接关闭,它才会停止。

2008 年的课程把读取服务器响应的任务交给线程池中的一个线程。程序 [internet-06.cs] 如下:

using System.Net.Sockets;

// 通用 TCP 客户端
// - 连接到服务(机器、端口)
// - 把键盘键入的每一行发送给服务器
// - 一个独立的任务持续显示服务器发来的行
// 调用: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];

// 连接到服务
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();
// 发送的行以 \r\n 结尾,这是 HTTP、SMTP、POP、FTP 等协议所要求的
var writer = new StreamWriter(stream) { AutoFlush = true, NewLine = "\r\n" };

// 读取服务器各行的工作交给一个并行运行的任务
Task reception = ReceiveAsync(new StreamReader(stream));

// 读取键盘命令的工作在主程序中完成
Console.WriteLine("Type your commands (bye to stop):");
try
{
    while (true)
    {
        // Console.ReadLine 是阻塞的:我们在池任务中执行它
        Task<string?> input = Task.Run(Console.ReadLine);
        // 我们等待键盘键入的一行,或者接收结束
        if (await Task.WhenAny(input, reception) == reception)
        {
            // 服务器已关闭连接:没必要再等待输入
            Console.WriteLine("[the server has closed the connection]");
            break;
        }
        string? command = await input;
        // 完成了吗?
        if (command is null || command.Trim().Equals("bye", StringComparison.OrdinalIgnoreCase))
        {
            break;
        }
        // 我们把命令发送给服务器
        await writer.WriteLineAsync(command);
    }
}
catch (IOException ex)
{
    Console.WriteLine($"The following error occurred while writing: {ex.Message}");
}
// 我们关闭连接:如果接收任务尚未结束,它将随之结束
client.Close();
await reception;

// --------------------------------------------------------------------
// 显示服务器发来的行,直到连接关闭
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)
    {
        // 读取期间连接被关闭:任务结束
    }
}
  • 第 21 行:客户端连接到服务器;
  • 第 31 行:发送的行以 \r\n 结尾,这是我们想要探究的协议所要求的;
  • 第 34 行:读取服务器发送的行被委托给异步方法 [ReceiveAsync]。我们不会立即等待它:任务 [reception] 与主程序并行运行;
  • 第 40–58 行:键盘输入并向服务器发送数据的循环;
  • 第 43 行:键盘输入没有真正的异步方式。因此,具有阻塞性的 [Console.ReadLine] 在线程池的一个任务中执行;
  • 第 45 行:[Task.WhenAny] 返回两个任务中最先完成的那个:要么是从键盘输入一行,要么是接收,后者在服务器关闭连接时结束。在后一种情况下,无需等待用户键入任何内容:循环退出。相比之下,2008 年的客户端会等待用户键入 [bye];
  • 第 51 行:在键盘上键入的行;
  • 第 58 行:将其发送给服务器;
  • 第 66–67 行:关闭连接,然后程序等待接收任务结束,如果它仍在读取,则它也会随之结束。程序终止时,任何正在进行的键盘输入都会被丢弃;
  • 第 71–82 行:接收任务执行的方法。它显示收到的每一行,前面加上 [<--],直到流结束。如果客户端在读取进行期间关闭连接,当前的读取操作会以异常结束,该异常会被捕获:[when] 筛选器(C# 6)只捕获两种预期的异常类型。

现在我们可以手动向在另一个窗口中运行的测试 Web 服务器发送 HTTP 请求。前面带有 [<--] 的行是服务器发送的;其余的是手动键入的:

> 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]
  • 第 3–5 行:在键盘上键入的请求:我们请求文档 [/hello?name=Serge]。标头 [Connection: close] 指示服务器在发送完响应后关闭连接;
  • 随后的空行结束请求。它触发服务器的响应;
  • 第 7 行:找到了文档;
  • 第 8 行:服务器宣告它将在发送完响应后关闭连接;
  • 第 9 行:这次文档是纯文本;
  • 第 12 行:服务器没有指定文档的大小([Content-Length]);它分块发送,每块前面带有以十六进制表示的大小;
  • 第 14–16 行:一个 0x0c = 12 字节的块,文本为 [Hello Serge!],后面是一个大小为零的块,标志着文档的结束;
  • 第 18 行:按照请求,服务器关闭了连接。客户端检测到这一点并自行关闭。

我们去掉 [Connection: close] 标头再试一次,请求站点的根:

> 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
  • 第 7 行:文档连同其大小(169 字节)一起被宣告。因此客户端知道它在哪里结束;
  • 第 16 行:文档已完整接收,但服务器没有关闭连接:在 HTTP/1.1 中,连接默认保持打开以处理其他请求。服务器在等待新的请求;这时用户键入 [bye] 来关闭连接。

当服务器不可用时,连接失败:

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

读者可以将这个通用 TCP 客户端用于回显服务器;如果有接受未加密连接的 SMTP 或 POP3 服务器(例如本地安装的测试服务器),也可以用它重现上面展示的示例对话。

12.6.4. 通用 TCP 服务器

现在我们来关注一个服务器:

  • 它在屏幕上显示其客户端发送的行;
  • 它把用户在键盘上键入的文本行作为响应发回。因此,用户扮演服务器的角色。

该程序在命令窗口中通过 [dotnet run internet-07.cs -- port] 启动,其中 [port] 是客户端必须连接的端口。对客户端的服务由两个处理过程提供:

  • 主程序:
    • 依次处理客户端,而不是并行处理。由于控制台无法被两个客户端同时使用,我们的服务器一次只处理一个客户端。在此期间连接的客户端,其连接由系统建立,但必须等待程序接受它们;
    • 读取用户在键盘上键入的行并将其发送给客户端。用户通过命令 [bye] 表示要关闭与客户端的连接;
  • 另有一个任务专门用于读取客户端发送的文本行。

除非用户在键盘上按 Ctrl-C,否则服务器永不停止。

程序 [internet-07.cs] 如下:

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

// 通用 TCP 服务器
// - 显示客户端发来的行
// - 把用户在键盘键入的行作为响应发送给客户端
// 客户端依次被服务(只有一个控制台)
// 调用: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;
}

// 监听服务
var listener = new TcpListener(IPAddress.Any, port);
listener.Start();
Console.WriteLine($"Generic server started on {listener.LocalEndpoint}");

// 正在进行的键盘输入(它可能比某个客户端的连接存活得更久)
Task<string?>? input = null;
// 服务循环 - 服务器由 Ctrl-C 停止
while (true)
{
    // 等待一个客户端
    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" };
    // 一个独立的任务显示客户端发来的行
    Task reception = ReceiveAsync(new StreamReader(stream));
    // 读取键盘上响应的工作在主程序中完成
    Console.WriteLine("Type your responses (bye to close the connection with the client):");
    try
    {
        while (true)
        {
            // 如果没有正在进行的键盘输入,我们就启动一个
            input ??= Task.Run(Console.ReadLine);
            // 我们等待键盘键入的一行,或者客户端离开
            if (await Task.WhenAny(input, reception) == reception)
            {
                // 正在进行的输入将服务于下一个客户端
                Console.WriteLine("[the client has closed the connection]");
                break;
            }
            string? response = await input;
            input = null;
            // 键盘输入结束(Ctrl-D、Ctrl-Z):服务器停止
            if (response is null)
            {
                listener.Stop();
                return;
            }
            // 与该客户端的连接结束了吗?
            if (response.Trim().Equals("bye", StringComparison.OrdinalIgnoreCase))
            {
                Console.WriteLine("[connection closed by the server]");
                break;
            }
            // 我们把响应发送给客户端
            await writer.WriteLineAsync(response);
        }
    }
    catch (IOException ex)
    {
        Console.WriteLine($"The following error occurred while writing: {ex.Message}");
    }
    // 我们关闭与该客户端的连接
    client.Close();
    await reception;
}

// --------------------------------------------------------------------
// 显示客户端发来的行,直到连接关闭
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)
    {
        // 读取期间连接被关闭:任务结束
    }
}
  • 第 18–19 行:创建并启动监听服务。它监听机器所有的网络接口;
  • 第 23 行:当前的键盘输入。它在客户端循环之外声明,原因见下文;
  • 第 25 行:等待客户端的无限循环。用户通过按 Ctrl-C 来停止服务器;
  • 第 29 行:等待客户端。客户端到达时,由 [AcceptTcpClientAsync] 返回的 [TcpClient] 实例表示与该客户端已打开连接的服务器端。[using] 声明会在每次循环迭代结束时释放它;
  • 第 34 行:读取客户端发送的行由一个单独的任务处理,与通用客户端相同;
  • 第 39–65 行:通过键盘输入要发送给客户端的响应的循环;
  • 第 42 行:[??=] 运算符(C# 8)仅在当前没有正在进行的输入时才发起新的输入。事实上,当客户端关闭连接时(第 44 行),程序会直接转到下一个客户端而不等待输入,为上一个客户端发起的键盘输入仍在进行:它将被下一个客户端使用。如果再发起第二个输入,就会导致两个输入处理过程争抢同一批按键;
  • 第 53 行:如果标准输入已关闭,服务器停止;
  • 第 59 行:命令 [bye] 关闭与当前客户端的连接;
  • 第 65 行:键入的行被发送给客户端;
  • 第 73–74 行:关闭连接并等待读取操作结束;
  • 第 79–90 行:持续在控制台上显示客户端所发送文本行的方法。这与我们在通用 TCP 客户端中看到的类似。

2008 年的课程用这个服务器来模拟被浏览器查询的 Web 服务器。我们也这样做,只是用 [curl] 代替浏览器。通用服务器运行在 27101 端口上。在另一个窗口中,我们让 [curl] 请求 URL [http://localhost:27101/example.html]。[curl] 随后连接到 [localhost] 机器的 27101 端口,并请求文档 [/example.html]。下面是服务器窗口:

> 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...
  • 第 4 行:有一个客户端到达;
  • 第 5–8 行:我们看到 [curl] 发送的 HTTP 请求,以一个空行结束。浏览器会发送更多的标头(支持的语言和格式、压缩、Cookie 等):读者可以用浏览器请求同一个 URL 来测试这一点;
  • 第 10–17 行:这里,键盘前的用户就是真正的服务器,他手动构造响应。他只写最基本的内容:一个状态行、三个标头、一个空行和 HTML 文档。他没有指定文档大小([Content-Length]),而是表明在发送之后会关闭连接([Connection: close])。这就足够了:当客户端看到连接关闭时,就知道响应已经完整;
  • 第 19 行:用户键入了 [bye]:服务器关闭与客户端的连接;
  • 第 20 行:服务器等待新的客户端。我们用 Ctrl-C 将其停止。

下面是 [curl] 显示的内容:

> 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

[curl] 收到的正是在服务器窗口中键入的内容(第 12–18 行),并检测到连接已关闭(第 19 行)。浏览器则会显示收到的 HTML 页面,标签页中的标题为 [Generic server] 。

12.6.5. Web 客户端

在上一个示例中,我们看到了 [curl] 发送的 HTTP 标头。我们将编写一个 Web 客户端,它以 URL 为参数,并在屏幕上显示服务器发送给它的全部内容。我们假设服务器支持 HTTP/1.1 协议。我们的客户端将发送如下请求:

1
2
3
4
GET /document HTTP/1.1
Host: machine:port
User-Agent: web-client-csharp-course
Connection: close
  • 第一行指明所需的文档;
  • 标头 [Host] 标识被查询的服务器;
  • 标头 [User-Agent] 标识我们的客户端;
  • 标头 [Connection] 表示我们希望服务器在响应我们之后关闭连接:我们将读取其响应直到流结束;
  • 空行表示请求结束。

如果把第一行中的 [GET] 替换为 [HEAD],服务器就只会发给我们其响应中的 HTTP 标头,而不会发送文档。

我们的 Web 客户端的调用方式如下:[dotnet run internet-08.cs -- URL command],其中 [URL] 是所需的 URL,[command] 是 关键字 [GET] 或 [HEAD] 之一。程序 [internet-08.cs] 如下:

using System.Net.Sockets;

// Web 客户端:用"手工"编写的 HTTP/1.1 请求请求一个 URL
// 并显示服务器返回的全部内容(HTTP 头和文档)
// 调用: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;
}

// 检查 URL:它必须是绝对 URL 并使用 http 协议
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;
}

try
{
    // 连接到 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);
    // HTTP 要求行以 \r\n 结尾(在 Linux 下 Environment.NewLine 是 \n)
    await using var writer = new StreamWriter(stream) { NewLine = "\r\n" };
    // 请求:命令行、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();
    // 读取响应,直到服务器关闭连接
    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}");
}

这个程序的新特性是使用了 [Uri] 类(命名空间 [System])。程序接收一个 URL(统一资源定位符,Uniform Resource Locator),它是 URI(统一资源标识符,Uniform Resource Identifier)的一种特定形式,形如 [http://server:port/path?param1=val1&param2=val2]。[Uri] 类可以把这个字符串分解为各个组成部分:

  • 第 15 行:[Uri.TryCreate] 根据字符串 [args[0]] 构造一个 [Uri] 对象,如果该字符串不是有效的绝对 URI(缺少方案、服务器等),则返回 [false]。2008 年的课程在 [try/catch] 中使用构造函数 [new Uri(...)];[TryCreate] 则避免了异常。我们还要验证方案是 [http]:我们的客户端无法为 [https] 执行 TLS 协商。构造出 [Uri] 对象之后,就可以访问 URI 的各个元素。因此,如果 [uri] 对象由字符串 [http://localhost:27110/hello?name=Serge] 构造而来,则有:
    • [uri.Scheme]:http;
    • [uri.Host]:localhost;
    • [uri.Port]:27110(如果 URL 中未指定端口,则为 80,HTTPS 为 443);
    • [uri.Authority]:localhost:27110(如果是该方案的默认端口,则省略端口);
    • [uri.AbsolutePath]:/hello;
    • [uri.Query]:?name=Serge;
    • [uri.PathAndQuery]:/hello?name=Serge;
  • 第 22 行:模式 [not (... or ...)] (C# 9)检查命令是 [GET] 还是 [HEAD];
  • 第 32 行:连接到 URL 所指定的服务器;
  • 第 36 行:HTTP 要求以 \r\n 作为行结束符;
  • 第 38–42 行:HTTP 请求;
  • 第 44 行:没有使用 [AutoFlush]:请求在完整写入之后一次性发送;
  • 第 46–48 行:显示响应,直到服务器关闭连接。

我们只请求测试服务器根路径的标头:

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

我们得到了状态行和标头,后面是一个空行,但没有文档。标头 [Content-Length] 给出的是使用命令 [GET] 时文档本应具有的大小。再来看使用命令 [GET] 且文档以分块方式发送的情况:

> 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

注意命令中 URL 两边的引号:没有引号的话,某些命令解释器会赋予字符 [?] 特殊含义。文档([Hello Serge!]) 被各个块的大小框住,这一点我们已经见过。我们的客户端显示的是原始响应;而真正的 HTTP 客户端则必须根据这些块重新构造文档。

不存在的文档:

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

会发生重定向的 URL:

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
  • 第 2 行:代码 302 表示重定向;所请求的文档暂时位于另一个地址;
  • 第 7 行:这个地址由标头 [Location] 提供。这里它是相对地址:完整地址是 [http://localhost:27110/hello?name=visitor]。

我们的客户端到此为止。而浏览器则会自动请求新的地址。这正是我们的下一个客户端要做的事。

最后,对 [https] URL 的请求会被拒绝:

> 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. 能处理重定向的 Web 客户端

前面的 Web 客户端不处理其所请求 URL 可能发生的重定向。重定向状态码如下:

代码
含义
301 Moved Permanently
文档已永久移到新地址;浏览器可以保存新地址
302 Found
文档暂时位于另一个地址
303 See Other
必须使用 [GET] 方法向另一个地址请求响应(在提交表单之后使用)
307 Temporary Redirect, 308 Permanent Redirect
与 302 和 301 相同,但客户端必须使用相同的方法重新发送请求([POST] 仍为 [POST])

无论哪种情况,新地址都由 [Location] 标头提供,可以是绝对 URL,也可以是相对 URL。2008 年的客户端根据状态行中是否出现单词 [moved] 来检测重定向。这并不可靠:代码后面的消息是任意的,Kestrel 的响应是 [302 Found],不含单词 [moved]。我们依据状态码本身。

程序 [internet-09.cs] 如下:

using System.Net.Sockets;

// 跟随重定向的 Web 客户端(代码 301、302、303、307、308)
// 调用: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;
}

// 表示重定向的 HTTP 状态码
int[] redirectionCodes = [301, 302, 303, 307, 308];
// 最多跟随的重定向次数
const int maxRedirections = 3;

try
{
    // 每个被请求的 URL 迭代一次
    for (int nbRedirections = 0; ; nbRedirections++)
    {
        // 我们请求该 URL,并获取可能的重定向地址
        string? location = await RequestAsync(uri, command, redirectionCodes);
        // 没有重定向:结束
        if (location is null)
        {
            break;
        }
        // 重定向次数过多:我们放弃
        if (nbRedirections == maxRedirections)
        {
            Console.WriteLine($"<-- Giving up: more than {maxRedirections} redirections -->");
            break;
        }
        // 新的 URL:重定向地址可以是绝对地址,也可以是相对于当前 URL 的地址
        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}");
}

// --------------------------------------------------------------------
// 请求 URL [uri],显示服务器的响应
// 返回重定向地址,如果没有重定向则返回 null
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" };
    // 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();

    // 状态行,例如: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);

    // HTTP 头,直到空行
    string? location = null;
    while (await reader.ReadLineAsync() is string header && header != "")
    {
        Console.WriteLine(header);
        // HTTP 头的名称不区分大小写
        if (redirection && header.StartsWith("Location:", StringComparison.OrdinalIgnoreCase))
        {
            location = header["Location:".Length..].Trim();
        }
    }
    Console.WriteLine();
    // 可能存在的文档
    while (await reader.ReadLineAsync() is string line)
    {
        Console.WriteLine(line);
    }
    return location;
}

与上一版本相比,改动如下:

  • 第 25 行:表示重定向的状态码;
  • 第 27 行:连续重定向的最大次数。如果没有限制,配置错误的服务器可能会让我们的客户端陷入无限循环(浏览器在大约二十次重定向后就会放弃);
  • 第 32 行:以前只针对单个 URL 执行的代码,现在可以依次针对多个 URL 执行;
  • 第 35 行:[RequestAsync] 方法请求当前 URL,显示响应,并返回重定向 URL;如果没有重定向,则返回 [null] ;
  • 第 42–44 行:如果达到重定向的最大次数,则中止该过程;
  • 第 48 行:[Uri(Uri base, string relative)] 构造函数计算新的 URL。如果 [location] 是绝对地址,则原样使用;如果是相对地址,则依据当前 URL [uri] 补全。2008 年的课程通过一个测试来区分这两种情况:现在由编译器处理这件事;
  • 第 64–103 行:对某个 URL 的请求:
    • 第 80 行:读取状态行,例如 [HTTP/1.1 302 Found];
    • 第 82–84 行:提取代码(该行的第二个字段),并检查它是否属于重定向代码;
    • 第 88–94 行:读取标头直到空行。如果存在重定向,就查找标头 [Location],忽略大小写,因为 HTTP 中的标头名称不区分大小写。表达式 [header["Location:".Length..]] 使用范围(C# 8)来提取标头名称之后的内容;
    • 第 98–103 行:显示响应的其余部分,然后返回找到的重定向 URL。

我们再来看 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
  • 第 2–7 行:指向相对地址的临时重定向;
  • 第 9 行:新的 URL,由 [new Uri(uri, location)] 补全;
  • 第 11–19 行:对新 URL 的响应。文档大小为 0x0e = 14 字节,以分块方式发送。

URL [/moved] 被永久重定向到一个绝对地址:

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

URL [/loop] 重定向到它自身:

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

我们的客户端跟随了三次重定向,然后放弃(第 32 行)。使用命令 [HEAD] 时,没有发送文档。

Web 服务器日志记录了条目 [A web client] 和 [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

对于每次重定向,它都会显示触发重定向的请求,以及随后对新地址的请求(第 7–8 行),还有被中断的循环中的四个请求(第 11–14 行)。

编写基于 TCP 的 HTTP 客户端有助于理解该协议,但真正的客户端还必须处理许多其他事情:TLS 加密、分块传输、压缩、持久连接、HTTP/2 和 HTTP/3……本章的第二部分将介绍 .NET 的 [HttpClient] 类,它为我们处理了所有这些事情。

12.7. 专用于某个协议的 .NET 类

在前面的示例中,HTTP 协议是通过 TCP 客户端处理的:我们必须自己构造请求、解析状态行和标头,并跟踪重定向。我们同样可以用这种方式构建 SMTP 或 POP 客户端。.NET 提供了专用于 HTTP 和 SMTP 协议的类。这些类理解客户端与服务器之间的通信协议,使开发人员无需自己管理它。下面我们来介绍它们。

与第一部分一样,第二部分的程序也是 [12-internet] 文件夹中的单文件应用程序,依次编号([internet-10.cs] 到 [internet-19.cs])。本章末尾的示例应用程序是一个独立的解决方案 [TaxV8]。所用端口形如 272xx。

12.7.1. WebClient 和 WebRequest 类,现已过时

2008 年的课程介绍了两个系列的类:

  • 类 [WebClient],用一条指令就能请求文档(方法 [DownloadString]、[DownloadData]、[DownloadFile]、[OpenRead])或发送文档(方法 [UploadString]、[UploadValues] 用于表单……);
  • 类 [WebRequest] / [WebResponse] 及其派生类 [HttpWebRequest] / [HttpWebResponse],它们更为灵活:可以选择 HTTP 方法([GET]、[HEAD]、[POST])、添加标头,并在响应到达时读取它。

这些类在 .NET 10 中仍然存在以保持兼容,但自 .NET 6 起已被标记为已弃用。下面这个小程序使用了它们:

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/");

编译它会产生以下两条警告(我们只摘录 [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)

信息很明确:必须使用 [HttpClient] 类。该类随 .NET 4.5(2012 年)引入;它从一开始就是为异步编程而设计的(其所有网络方法都是异步的),支持 HTTP/1.1、HTTP/2 和 HTTP/3,会复用其连接,并且可以被多个任务同时使用。在当前的 .NET 中,[WebClient]、和 [WebRequest] 实际上不过是构建在 [HttpClient] 之上的外观。我们不再深入研究它们,而是转回 [HttpClient],用它来重做 2008 年课程用这两个类讲解过的示例。

12.7.2. HttpClient 类

12.7.2.1. 测试用 Web 服务器

为了演示 [HttpClient] 的功能,我们需要一个比第一部分中的服务器([internet-03.cs])功能更丰富的 Web 服务器:它必须能接受表单、交换 JSON,并能处理延迟。因此我们将编写第二个测试服务器 [internet-10.cs],与第一个一样,它是一个名为“最小 API(Minimal API)”的 ASP.NET Core 应用程序。同样,目前不必详细理解这个程序(ASP.NET Core 将在下一章讲解):只需知道每个 URL 的响应内容即可。

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

// 一个本地 Web 服务器,用作 HttpClient 客户端的目标
// 调用: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);
// 不输出 ASP.NET 日志(仅警告):我们自己编写日志
builder.Logging.SetMinimumLevel(LogLevel.Warning);
var app = builder.Build();

// 控制台跟踪:每个请求、客户端的端口和响应的状态码
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)
    {
        // 客户端在响应之前放弃了请求
        Console.WriteLine($"{start} -> abandoned by the client");
    }
});

// 查询类 URL 接受 GET 和 HEAD 方法
string[] getHead = ["GET", "HEAD"];

// 主页:一个 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"));

// 由 URL 的参数构建的文本文档
app.MapMethods("/hello", getHead, (string? name) => $"Hello {name ?? "unknown"}!");

// 服务器收到的 HTTP 头,以文本形式发回给客户端
app.MapMethods("/headers", getHead, (HttpRequest request) =>
    string.Join("\n", request.Headers.Select(header => $"{header.Key}: {header.Value}")));

// 临时重定向(302)到一个相对地址
app.MapMethods("/old", getHead, () => Results.Redirect("/hello?name=visitor"));

// 一个循环指向自身的重定向
app.MapMethods("/loop", getHead, () => Results.Redirect("/loop"));

// 服务器错误(500 Internal Server Error)
app.MapMethods("/error", getHead, () => Results.StatusCode(500));

// 一个需要较长时间才响应的回答
app.MapGet("/slow", async (int seconds, CancellationToken token) =>
{
    await Task.Delay(TimeSpan.FromSeconds(seconds), token);
    return $"Response obtained after {seconds} s";
});

// 通过 POST 发送的表单:我们描述所收到的内容
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}";
});

// 通过 POST 发送的任意文本:我们把它转为大写后发回
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()}";
});

// 一个小型人员"数据库",以 JSON 格式交换
List<Person> persons = [new(1, "Dupont", 42), new(2, "Durand", 35)];
Lock padlock = new();

// 人员列表
app.MapGet("/api/persons", () =>
{
    lock (padlock)
    {
        return persons.ToList();
    }
});

// 按编号指定的一个人员,如果不存在则返回 404
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();
    }
});

// 添加一个人员:服务器给它分配一个编号并回答 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);
    }
});

// 任何其他 URL 都得到 404 Not Found 响应(默认行为)
Console.WriteLine($"Web server started on http://localhost:{port}");
app.Run($"http://127.0.0.1:{port}");

// 一个人
record Person(int Id, string Name, int Age);

说明:

  • 第 2 行:单文件应用程序默认配置为本机编译(AOT),这会禁用基于反射的序列化(JSON)。与第 5 章一样,我们重新启用它:服务器就能自动把其对象转换为 JSON;
  • 第 14–27 行:每个请求都会连同客户端的端口和响应状态码一起记录到控制台。借助客户端的端口,我们可以判断两个请求是否使用了同一个 TCP 连接。如果客户端在收到响应之前中止请求,Kestrel 会撤销令牌 [RequestAborted],而当前操作会以 [OperationCanceledException] 结束:我们也会显示这一点;
  • 第 35 行:URL [/] 返回一个小型 HTML 文档;
  • 第 45 行:URL [/hello?name=xx] 生成文本 [Hello xx!];
  • 第 48 行:URL [/headers] 以文本形式把客户端请求中的 HTTP 标头返回给客户端。这让我们能看到 [HttpClient] 发送了什么。2008 年的课程为此使用通用 TCP 服务器,而键盘前的用户随后必须让它作出响应;
  • 第 52–55 行:一个指向 [/hello?name=visitor] 的临时重定向,以及一个循环回到自身的重定向,与第一部分的服务器相同;
  • 第 58 行:一个 500 响应(内部服务器错误);
  • 第 61 行:URL [/slow?seconds=n] 要等 n 秒过去之后才会响应。如果客户端中止请求,令牌 [token] 就会被取消:等待随即中断;
  • 第 68 行:URL [/form] 接收 通过 [POST] 方法发送的表单,并描述它收到了什么;
  • 第 76 行:URL [/text] 通过 [POST] 接收任意文本,并以大写形式返回;
  • 第 84–114 行:一个小型“数据集”,由若干人员组成,以 JSON 格式交换。[GET /api/persons] 返回人员列表;[GET /api/persons/n] 返回编号为 n 的人员(或返回 404 响应);[POST /api/persons] 添加客户端发送的人员,为其分配编号,并以状态码 201(Created)响应。由于多个请求可能由不同线程同时处理,该列表由锁 [Lock] (第 8 章)保护;
  • 第 123 行:类型 [Person],一个记录([record]);
  • 第 120 行:服务器在环回地址的 27210 端口上监听。

服务器在命令窗口中启动,并在本节的整个测试过程中一直留在那里。它收到的请求将在本节末尾展示。

12.7.2.2. 下载文档:GetStringAsync

使用 [HttpClient] 获取文档最简单的方式是使用下列方法之一:

方法
作用
Task<string> GetStringAsync(string url)
使用 [GET] 方法请求 URL [url],并将接收到的文档作为字符串返回
Task<byte[]> GetByteArrayAsync(string url)
同上,但文档以字节数组形式返回(例如图像)
Task<Stream> GetStreamAsync(string url)
同上,但文档以流的形式返回,可在其到达时读取(例如大文件)

以上每个方法还有一个带 [Uri] 类型参数的版本,以及一个带附加 [CancellationToken] 类型参数的版本。如果服务器以错误代码响应,这些方法会抛出 [HttpRequestException] 。

程序 [internet-11.cs] 如下:

// HttpClient 入门:把文档下载为字符串
// 测试服务器 [internet-10.cs] 必须在端口 27210 上运行

// 一个 HTTP 客户端,以及它所请求的相对 URL 的基地址
using var client = new HttpClient { BaseAddress = new Uri("http://localhost:27210/") };

// 1 - 一个文本文档
string text = await client.GetStringAsync("hello?name=Serge");
Console.WriteLine($"Document received: {text}");

// 2 - HttpClient 发送的 HTTP 头,即服务器收到的样子
Console.WriteLine("--- headers sent by default");
Console.WriteLine(await client.GetStringAsync("headers"));

// 3 - 我们给此客户端的所有请求添加 HTTP 头
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 - 一个 HTML 文档,以字节数组形式获取
byte[] bytes = await client.GetByteArrayAsync("/");
Console.WriteLine($"--- the home page is {bytes.Length} bytes long");

// 5 - 一个不存在的文档
try
{
    await client.GetStringAsync("unknown");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"--- {ex.GetType().Name} : {ex.Message}");
    Console.WriteLine($"Status code: {(int?)ex.StatusCode} ({ex.StatusCode})");
}

结果([internet-10.cs] 服务器已在另一个窗口中启动):

> 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)

说明:

  • 第 5 行:创建客户端。[BaseAddress] 属性设置了此后所用相对 URL 值所依附的地址:因此 [hello?name=Serge] 指的是 [http://localhost:27210/hello?name=Serge]。基地址末尾的斜杠很重要:没有它,路径的最后一段会被相对 URL 取代;
  • 第 8 行:一条指令就足以获取文档。[HttpClient] 构建了请求、建立了连接、解析了响应,并重构了以分块方式发送的文档([Transfer-Encoding: chunked]),而第一部分的 TCP 客户端是原样显示它的;
  • 第 13 行:从结果的第 3 行可以看到,[HttpClient] 默认只发送必需的标头 [Host]。2008 年版的 [WebClient] 还会添加 [Connection: Keep-Alive];这在 HTTP/1.1 中是不必要的,因为连接默认会保持。此外也没有 [User-Agent] 标头:有些公共服务器会拒绝缺少该标头的请求;
  • 第 16–17 行:[DefaultRequestHeaders] 集合包含添加到该客户端所有请求中的标头。常见标头有带类型的属性,例如 [UserAgent];其他标头按名称添加,例如使用 [Add]。结果的第 7–8 行表明服务器确实收到了它们;
  • 第 22 行:文档以字节形式接收。注意 URL [/]: 以斜杠开头的相对 URL 表示相对于基地址的站点根;
  • 第 26–33 行:一个不存在的文档。[GetStringAsync] 抛出 [HttpRequestException] ,其属性 [StatusCode](类型为 [HttpStatusCode?],.NET 5)返回收到的状态码。2008 年的课程在这种情况下收到的是 [WebException]。

12.7.2.3. 请求和响应:HttpRequestMessage 和 HttpResponseMessage

[GetXxxAsync] 方法只返回文档。要管理请求(方法、标头)或检查响应(状态、标头),请使用 [HttpRequestMessage] 和 [HttpResponseMessage] 类:

成员
作用
new HttpRequestMessage(HttpMethod method, Uri url)
一个请求。[HttpMethod] 为以下方法提供了静态属性:[HttpMethod.Get]、[HttpMethod.Head]、[HttpMethod.Post]……
HttpRequestMessage.Headers, Content
请求标头,以及可能发送的文档(方法 [POST])
Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
[HttpClient] 方法,发送请求并返回响应。[GetAsync(url)] 是 [GET] 请求的快捷方式
HttpResponseMessage.StatusCode, ReasonPhrase, Version
状态行:代码(枚举 [HttpStatusCode])、消息和 HTTP 版本
HttpResponseMessage.IsSuccessStatusCode
如果状态码在 200 到 299 之间,则为 true
HttpResponseMessage.EnsureSuccessStatusCode()
如果状态码不在 200 到 299 之间,则抛出 [HttpRequestException]
HttpResponseMessage.Headers
响应本身的标头([Date]、[Server]、[Location]……)
HttpResponseMessage.Content
接收到的文档([HttpContent]):它自己的标头([Content.Headers]:[Content-Type]、[Content-Length]……)以及用于读取它的方法 [ReadAsStringAsync]、[ReadAsByteArrayAsync]、[ReadAsStreamAsync]
HttpResponseMessage.RequestMessage
响应所对应的请求:发生重定向时,这是最后发送的那个请求

我们将使用这些类来实现第一部分的 Web 客户端([internet-08.cs]、[internet-09.cs]),它通过一个 URL 和 [GET] 或 [HEAD] 方法来调用。2008 年的课程用 [HttpWebRequest] / [HttpWebResponse] 类做了同样的事。程序 [internet-12.cs] 如下:

using System.Net.Http.Headers;

// 基于 HttpClient 的 Web 客户端:显示收到的状态、HTTP 头和文档
// 调用: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;
}
// URL 必须是绝对的 http 或 https URL
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;
}
// HTTP 方法
string command = args[1].ToUpper();
if (command is not ("GET" or "HEAD"))
{
    Console.WriteLine(syntax);
    return;
}

// 负责网络工作的处理程序:最多跟随 3 次重定向
var handler = new SocketsHttpHandler { MaxAutomaticRedirections = 3 };
// HTTP 客户端:最多 10 秒内必须得到响应
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(10) };
try
{
    // 请求:方法、URL、HTTP 头
    using var request = new HttpRequestMessage(new HttpMethod(command), uri);
    request.Headers.UserAgent.ParseAdd("csharp-course-client/1.0");
    // 我们发送它并等待响应
    using HttpResponseMessage response = await client.SendAsync(request);
    // 状态行
    Console.WriteLine($"The server {response.RequestMessage?.RequestUri} answered: "
        + $"HTTP/{response.Version} {(int)response.StatusCode} {response.ReasonPhrase}");
    // 响应的 HTTP 头,然后是文档的 HTTP 头
    Console.WriteLine("--- headers");
    DisplayHeaders(response.Headers);
    DisplayHeaders(response.Content.Headers);
    // 200-299 范围之外的状态码会抛出 HttpRequestException
    response.EnsureSuccessStatusCode();
    // 文档
    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");
}

// 显示一组 HTTP 头:一个名称可以有多个值
static void DisplayHeaders(HttpHeaders headers)
{
    foreach ((string name, IEnumerable<string> values) in headers)
    {
        Console.WriteLine($"{name}: {string.Join(", ", values)}");
    }
}

说明:

  • 第 13 行:与 [internet-08.cs] 中一样,系统会验证 URL 是否有效。这次接受方案 [https] :[HttpClient] 能够执行 TLS 协商;
  • 第 27 行:[HttpClient] 把网络处理委托给一个处理程序,默认是为它创建的 [SocketsHttpHandler] 对象。我们自己创建它,以便设置它的一个属性:[MaxAutomaticRedirections] 把跟随的重定向次数限制为 3(默认为 50)。该处理程序还管理连接池、Cookie([UseCookies])、解压缩([AutomaticDecompression])以及代理([Proxy]);
  • 第 29 行:[Timeout] 属性设置接收响应的最长时间(默认为 100 秒);
  • 第 33–34 行:请求,包含所请求的方法和一个专属于该请求的 [User-Agent] 标头。2008 年的课程没有想出如何用 [HEAD] 请求配合 [WebClient] 使用:而用 [HttpRequestMessage],只需选择方法即可;
  • 第 36 行:发送请求;一旦收到响应的标头(默认还包括其文档),响应就可用了。[HttpResponseMessage] 是 [IDisposable]:[using] 声明会释放其资源;
  • 第 38–39 行:状态行。[response.RequestMessage.RequestUri] 是最后一次请求的 URL:发生重定向时,它与所请求的 URL 不同;
  • 第 42–43 行:[HttpClient] 把标头组织成两个集合:响应本身的标头,以及描述文档的标头;
  • 第 45 行:如果状态码不表示成功,则抛出 [HttpRequestException];
  • 第 48 行:文档作为字符串读取。接收到的字节使用 [Content-Type] ([charset=utf-8])标头所指定的字符集进行解码;
  • 第 50 行:从 .NET 8 开始,异常的 [HttpRequestError] 属性以枚举的形式指示错误的性质:[ConnectionError]、[NameResolutionError]、[SecureConnectionError]……对于错误状态码,它被设置为 [Unknown];
  • 第 54 行:由于历史原因,超时会导致 [TaskCanceledException],其内部异常是 [TimeoutException];[when] 筛选器会检查这一点;
  • 第 60–64 行:一个标头名称可以有多个值;[HttpHeaders] 集合的每个元素都是一个(名称,值)对,在 [foreach] 中进行解析。

我们来请求站点的根:

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

我们看到的信息,正是之前使用 TCP 客户端自己分析响应时得到的:状态行、响应标头 [Date] 和 [Server],以及文档标头 [Content-Length] 和 [Content-Type]。

被重定向的 URL:

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!

重定向被自动处理:收到的响应是 URL [/hello?name=visitor] 的响应(第 2 行)。我们与第一部分比较一下:客户端 [internet-09.cs] 必须读取状态行、提取代码、查找标头 [Location]、计算新的 URL,然后重新开始,并在最多三次重定向的循环中进行。这里,这一切都由处理程序 [SocketsHttpHandler] 处理。以分块方式发送的文档(第 6 行)已被重构。要自己处理重定向,只需在处理程序上设置 [AllowAutoRedirect = false] :这时 302 响应会被原样返回。

不存在的文档:

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).

404 代码包含在响应中,连同其标头。抛出异常的是 [EnsureSuccessStatusCode]。在 2008 年的课程中,使用 [HttpWebRequest] 时,会直接得到一个 [WebException],必须从异常中取回 响应;而使用 [HttpClient] 时,只有 [GetStringAsync]、[GetByteArrayAsync]、和 [GetStreamAsync] 这几个方法会针对错误代码抛出异常;[SendAsync] 和 [GetAsync] 则返回响应,由程序自行决定。

会重定向到自身的 URL [/loop]:

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).

三次重定向之后,处理程序放弃并返回最后收到的响应,即一个 302 响应。由于它不在 200–299 范围内,[EnsureSuccessStatusCode] 会抛出异常。

服务器错误:

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).

没有服务器监听的端口:

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

属性 [HttpRequestError] 等于 [ConnectionError]:无法连接到服务器。最后,把 [https] URL 发送给我们的服务器,而它只会说明文的 HTTP:

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

TLS 协商失败了([SecureConnectionError])。在联网的机器上,像 [https://learn.microsoft.com/] 这样的 URL 请求,通常会根据服务器的能力,以 HTTP/2 或 HTTP/3 提供服务。

关于代理的最后一点说明。2008 年的课程用了一段篇幅讲 HTTP 代理,即企业网络中的工作站访问 Web 时必须经过的机器。默认情况下,[HttpClient] 使用系统配置的代理(Windows 设置,Linux 上的环境变量 [HTTP_PROXY] 和 [HTTPS_PROXY] ,以及 macOS)。可以使用处理程序的 [Proxy] 属性指定另一个代理,[new SocketsHttpHandler { Proxy = new WebProxy("proxy.example.org:3128") }],或者通过 [UseProxy = false] 完全不使用代理。

12.7.2.4. 向服务器发送数据:GET 和 POST

客户端可以通过两种方式向服务器发送信息:

  • 使用 [GET] 方法,信息是 URL 的一部分:[/document?param1=value1&param2=value2];
  • 使用 [POST] 方法,信息构成附加在请求上的文档,位于结束标头的空行之后。[Content-Type] 标头指明其格式。对于 HTML 表单,文档的格式与 URL 的参数部分相同:[param1=value1&param2=value2],类型为 [application/x-www-form-urlencoded]。

在这两种情况下,值都必须经过编码:某些字符(空格、[&]、[=]、[?]、带重音的字母等)不能原样出现在 URL 或表单中。2008 年的课程为此使用 [HttpUtility.UrlEncode] 方法;如今,对于要放入 URL 的值,我们使用 [Uri.EscapeDataString],而表单则由 [FormUrlEncodedContent] 类自身进行编码。

发送数据的 [HttpClient] 方法有 [PostAsync]、[PutAsync] 和 [PatchAsync]。它们接收一个 URL 和要发送的文档,即派生自 [HttpContent] 的对象:

类
所发送的文档
FormUrlEncodedContent
一个表单,由(名称,值)对的集合构造而成
StringContent
文本,附带其编码和类型([text/plain]、[application/json]……)
ByteArrayContent, StreamContent
任意字节、流(例如文件)
MultipartFormDataContent
包含文件的表单([multipart/form-data])
JsonContent
转换为 JSON 的对象(命名空间 [System.Net.Http.Json])

程序 [internet-13.cs] 如下:

using System.Text;

// 向服务器发送数据:URL 参数(GET)、表单和文本(POST)
// 测试服务器 [internet-10.cs] 必须在端口 27210 上运行

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

// 1 - GET:参数是 URL 的一部分;必须在其中进行编码
string name = "Jean & Marie";
string url = $"hello?name={Uri.EscapeDataString(name)}";
Console.WriteLine($"--- GET {url}");
Console.WriteLine(await client.GetStringAsync(url));

// 2 - 表单的 POST:参数构成发送给服务器的文档
var form = new FormUrlEncodedContent(
[
    new("name", "Jean & Marie"),
    new("age", "42"),
    new("city", "Angers"),
]);
// 将要发送的文档
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 任意文本,并带上其类型
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());
}

结果:

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

说明:

  • 第 9–10 行:值 [Jean & Marie] 被放入 URL 中。如果不编码,字符 [&] 会被解释为两个参数之间的分隔符,服务器收到的参数 [name] 的值就会是 [Jean]。在结果的第 2 行中,我们看到空格变成了 [%20] ,字符 [&] 变成了 [%26]:这是该字符的十六进制代码,前面加上 [%];
  • 第 15–19 行:表单由一组键值对 [KeyValuePair<string, string>] 构造而成;由于每个元素的类型是已知的,只需写 [new(...)] 即可;
  • 第 22 行:为了验证这一点,我们读取将要发送的文档:在结果的第 4 行中,可以看到格式 [name=value&name=value]。在表单中,空格被编码为 [+];
  • 第 23 行:表单使用 [POST] 方法发送到 URL [/form]。服务器指出(第 5–6 行),它收到了类型为 [application/x-www-form-urlencoded] 的文档,并已从中提取并解码了三个字段;
  • 第 30 行:文本,以 UTF-8 编码,类型为 [text/plain]。服务器将其以大写形式返回(第 9 行)。

注意 [using (...) { ... }] 块:这里不能使用 [using] 声明,因为同一个代码块中有两个 [response] 变量。2008 年课程中提到的 [GET] 与 [POST] 之间的区别依然成立:浏览器会在地址栏中显示 [GET] 请求的参数,而不会显示 [POST] 请求的参数;此外,[GET] 请求只应用于获取信息,而 [POST] 请求则用于发送信息或修改服务器的状态。

12.7.2.5. 以 JSON 格式交换对象

目前,应用程序交换的大部分数据都采用第 5 章介绍的 JSON 格式。[System.Net.Http.Json] 命名空间为 [HttpClient] 和 [HttpContent] 添加了扩展方法,它们只用一条语句就能完成 HTTP 请求,以及使用 [System.Text.Json] 在对象与 JSON 之间的转换:

方法
作用
Task<T?> GetFromJsonAsync<T>(string url)
通过 [GET] 获取该 URL,并将收到的 JSON 文档转换为类型为 [T] 的对象
Task<HttpResponseMessage> PostAsJsonAsync<T>(string url, T object)
通过 [POST] 发送转换为 JSON 的对象(类型为 [application/json]),并返回响应。[PutAsJsonAsync] 对 [PUT] 方法执行相同的操作
Task<T?> ReadFromJsonAsync<T>()
[HttpContent] 的方法:将响应中的 JSON 文档转换为类型为 [T] 的对象

程序 [internet-14.cs] 如下:

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

// 与 Web 服务器以 JSON 格式交换对象
// 测试服务器 [internet-10.cs] 必须在端口 27210 上运行

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

// 1 - 人员列表:JSON 文档被直接转换为对象
List<Person>? persons = await client.GetFromJsonAsync<List<Person>>("api/persons");
Console.WriteLine("--- list of persons");
foreach (Person person in persons ?? [])
{
    Console.WriteLine(person);
}

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

// 3 - 添加一个人员:对象以 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}");
    // 收到的 JSON 文档,先是原始形式,然后是对象形式
    Console.WriteLine($"JSON received: {await response.Content.ReadAsStringAsync()}");
    Person? created = await response.Content.ReadFromJsonAsync<Person>();
    Console.WriteLine($"Person created: {created}");
}

// 4 - 一个不存在的人员
try
{
    await client.GetFromJsonAsync<Person>("api/persons/99");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"--- person no. 99: {ex.GetType().Name} : {ex.Message}");
}

// 一个人员:与服务器端的类型相同
record Person(int Id, string Name, int Age);

结果:

> 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).

说明:

  • 第 1 行:与服务器一样,我们重新启用基于反射的 JSON 序列化。另一种方案是第 6 章在第 5 版的 [dao] 层中讨论过的、在编译时生成的序列化上下文([JsonSerializerContext]):上述每个方法都有一个接受它的重载;
  • 第 10 行:人员列表。服务器发送的 JSON 文档 [[{"id":1,"name":"Dupont","age":42},...]] 被直接转换为 [Person] 对象的列表。结果的类型为 [List<Person>?]:JSON 文档可能是 [null];
  • 第 12 行:如果是这样,则遍历一个空列表;
  • 第 18 行:单个人员;
  • 第 23 行:对象 [martin] 被转换为 JSON 并发送给服务器。服务器以状态码 201(Created)和标头 [Location] 响应,该标头提供新资源的 URL(结果的第 7 行);
  • 第 28 行:收到的 JSON 文档:遵循 Web 惯例,属性名采用“camelCase”格式([id]、[name]、[age])。[System.Net.Http.Json] 的方法 使用选项 [JsonSerializerDefaults.Web],通过这些选项完成与 C# 属性 [Id]、[Name] 和 [Age] 之间的转换;
  • 第 29 行:同一个文档,转换为对象。注意,该文档可能被读取了两次:[HttpClient] 把它保存在内存中,因为发出请求时没有使用 [HttpCompletionOption.ResponseHeadersRead] 选项,我们稍后会讨论该选项;
  • 第 34–40 行:与 [GetStringAsync] 一样,如果状态码表示错误,[GetFromJsonAsync] 会抛出 [HttpRequestException] 。

我们将在下一章回到这些方法,届时税款计算服务器将成为一个 JSON Web 服务。

12.7.2.6. 超时、取消与客户端复用

程序 [internet-15.cs] 说明了在实际应用程序中使用 [HttpClient] 的三个重要要点:

using System.Diagnostics;

// HttpClient 的超时、取消和复用
// 测试服务器 [internet-10.cs] 必须在端口 27210 上运行

// 1 - 整个应用程序只使用一个 HttpClient 实例
//     每个请求的超时为 2 秒
var client = new HttpClient
{
    BaseAddress = new Uri("http://localhost:27210/"),
    Timeout = TimeSpan.FromSeconds(2),
};

// 2 - 连续请求:复用同一个 TCP 连接
Console.WriteLine("--- three successive requests");
for (int i = 1; i <= 3; i++)
{
    Console.WriteLine(await client.GetStringAsync($"hello?name=trial{i}"));
}

// 3 - 先是在超时内得到的响应,然后是太慢的响应
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 - 程序在半秒后取消的请求
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 - 用同一个客户端同时发出四个请求
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");

结果:

> 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

说明:

  • 第 8 行:整个程序只使用一个 [HttpClient] 实例。这是规则:[HttpClient] 对象管理一个连接池,并在一次查询到下一次查询之间复用这些连接;它被设计为长期运行,并且可以被多个任务同时使用。为每个请求创建一个 [HttpClient],并将其置于 [using] 中,是一个典型的错误:每个实例都会打开自己的连接,而系统在这些连接关闭之后还会将它们保留一段时间(TCP 的 TIME_WAIT 状态);发出大量查询的程序最终会耗尽可用端口。我们在前面的程序中包含了 [using] ,是因为它们在终止之前只发出了少量请求;
  • 第 11 行:每个请求最多必须在 2 秒内收到响应;
  • 第 16–18 行:三个连续的请求。我们将在服务器日志中看到它们使用了同一个(TCP)连接;
  • 第 22–29 行:一个在 1 秒内到达的响应,接着是一个需要 3 秒的响应:2 秒之后,请求被放弃,并抛出 [TaskCanceledException](结果的第 9 行)。表达式 [(int[])[1, 3]] 为集合表达式指定了类型,因为集合表达式自身没有类型;
  • 第 37–45 行:由程序发起的取消。[HttpClient] 的所有方法 都接受取消令牌,就像第 9 章讨论的异步方法一样。这里,令牌在半秒后自动取消(构造函数 [CancellationTokenSource(TimeSpan)]);在交互式应用程序中,它会由 [Cancel] 按钮或 Ctrl-C 来取消。异常同样是 [TaskCanceledException];区分取消与超时的是 [when (cancellation.IsCancellationRequested)] 筛选器;
  • 第 51–58 行:在同一个客户端上同时发起四个请求,然后用 [Task.WhenAll] (第 9 章)一起处理。每个请求用了一秒来处理;总共用了一秒(第 17 行):这些请求是并行处理的。

服务器 [internet-10.cs] 的日志显示了自本节开始以来收到的所有请求:

> 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
  • 第 3–7 行:来自 [internet-11.cs] 的五个请求通过同一个连接到达(同一个客户端端口):客户端在请求之间保持该连接打开;
  • 第 9–10 行:来自 [internet-12.cs] 的被重定向的请求,以及对新地址的请求,后者是通过同一个连接自动发出的;
  • 第 12–15 行:初始请求,以及随后在连接关闭之前发生的三次重定向;
  • 第 24–28 行:来自 [internet-15.cs] 的连续请求都使用同一个连接。耗时过长的请求被客户端放弃(第 28 行):[HttpClient] 关闭了连接,服务器看到其令牌 [RequestAborted] 被撤销;
  • 第 29 行:由程序取消的请求必须打开一个新连接,因为前一个连接已被关闭;
  • 最后四行:四个同时发出的请求使用了四个不同的连接,这些连接是专门为此打开的。在 HTTP/1.1 中,一个连接一次只承载一个请求;而 HTTP/2 则允许通过单个连接发送所有这些请求。

长时间保持活动的程序(服务器、系统服务)必须考虑最后一点:单个 [HttpClient] 会无限期保留其连接,因此无法察觉其所查询服务器的 IP 地址发生的变化,而这些变化是 DNS 会反映出来的。为解决这一问题,可以使用 [PooledConnectionLifetime] 属性为 [SocketsHttpHandler] 处理程序设置连接的最长生存期(例如两分钟)。在基于 .NET 通用主机([Microsoft.Extensions.Hosting])的应用程序和 ASP.NET Core 中,[HttpClient] 对象改为通过 [IHttpClientFactory] 接口获得:该工厂使用 [services.AddHttpClient()] (包 [Microsoft.Extensions.Http])声明,提供已配置的客户端(基地址、标头、超时),并自行管理它们的处理程序和生存期。读者可以在 ASP.NET Core 文档中找到它。

12.7.3. 应用:Web 翻译服务的代理客户端

现在我们来演示 [HttpClient] 如何让程序使用 Web 资源,即使这些资源并非为程序使用而设计。

12.7.3.1. 应用程序

2008 年的课程使用了翻译网站 [trans.voila.fr]。用户输入文本,从下拉列表中选择翻译方向(“法语到英语”等),点击按钮,就会收到一个包含译文的 HTML 页面。该课程创建了一个 [TranslationService] 类,以编程方式完成同样的任务:它构造请求的 URL,将其发送到该网站,并使用正则表达式从收到的 HTML 页面中提取译文。一个 Windows Forms 图形界面依托于这个类;这称为“代理”客户端:[TranslationService] 类充当该网站的替身,并将其对用户隐藏。

该网站已不复存在,而且我们的测试机器无法访问互联网。我们保留这一概念,用一个模仿它的本地小站点来取代该网站:它有相同的表单(一个文本框,以及一个按 2008 年网站那样书写的翻译方向下拉列表),并在其页面的同一位置显示译文。它的“翻译”是使用小型词典逐词完成的:我们关心的是客户端的技术,而不是翻译的质量。图形界面被控制台测试程序取代,与 2008 年课程中的一样。架构如下:

Image

12.7.3.2. 翻译站点

程序 [internet-16.cs] 如下:

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

// 一个逐词"翻译"的小型网站,模仿 2008 年课程所查询的网站
// 调用:dotnet run internet-16.cs,其后可加两个连字符和端口 port
int port = args.Length == 1 && int.TryParse(args[0], out int p) ? p : 27220;

// 翻译方向:代码 ->(标签,词典)
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();

// 请求的控制台跟踪
app.Use(async (context, next) =>
{
    await next(context);
    var request = context.Request;
    Console.WriteLine($"{request.Method} {request.Path}{request.QueryString} -> {context.Response.StatusCode}");
});

// 翻译页面:表单,如果提供了文本,则后接翻译结果
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">

        """);
    // 翻译方向列表,按 2008 年的写法:未闭合的 <option> 标签
    foreach ((string code, (string label, _)) in translationDirections)
    {
        page.Append($"    <option value='{code}'>{label}\n");
    }
    page.Append("""
        </select>
        <input type="submit" value="Translate">
        </form>

        """);
    // 翻译结果,如果有要翻译的文本
    if (!string.IsNullOrWhiteSpace(text))
    {
        if (direction is not null && translationDirections.TryGetValue(direction, out var translator))
        {
            // 逐词翻译;未知单词保持原样
            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}");

说明:

  • 第 11–26 行:三个提供的翻译方向,以及它们的代码([fe] 表示法语 → 英语,与 2008 年的网站相同)、标签和词典。标签中包含 HTML 实体([&rarr;] 表示 [→]),与原网站上的一样;
  • 第 43 行:站点唯一的页面 [/translation],可以接收两个参数:翻译方向 [direction] 和文本 [text];
  • 第 58–60 行:下拉列表。与 2008 年的站点一样,[<option>] 标签没有闭合:实际网站上的 HTML 并不总是很规范,我们的客户端必须绕过这个问题;
  • 第 74–75 行:逐词翻译。正则表达式 [\w+'?] 匹配一个单词,后面可以跟一个撇号([l']、[d']);每个单词被替换为其译文,如果未知则保持原样;
  • 第 76 行:译文被放在 [<div class="txtTrans">] 标签内,与 2008 年的网站一样。它使用 [WebUtility.HtmlEncode] 进行编码:在 HTML 中具有特殊含义的字符([<]、[&]……)以及(使用该方法时)带重音的字母都会被替换为实体;
  • 第 80 行:未知的翻译方向会得到一个没有译文的页面。

下面是使用 [curl] 为将 [l'été sera chaud] 翻译成西班牙语而生成的页面;请注意 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>

要编写客户端,与 2008 年一样,我们需要:

  • 知道站点期望什么:一个 [GET /translation?direction=code&text=encoded text] 请求。在真实的网站上,可以通过查看翻译之后浏览器显示的 URL,或表单的 [action] 属性来找到它;
  • 知道我们感兴趣的信息位于收到的页面中的什么位置:翻译方向位于下拉列表的 [<option value='code'>label] 标签中(上面页面的第 10 行),译文位于 [<div class="txtTrans">] 标签中(第 16 行)。可以通过在浏览器中查看页面的源代码找到它们。

可以用两个正则表达式(第 5 章)来提取这些信息:

  • [<option[^>]*value='(\w+)'>([^<\r\n]+)]:一个 [<option] 标签,后面是除 [>] 之外的字符、[value=']、代码(第一个分组)、[>],然后是标签文字,即后面直到下一个 [<] 或行尾的字符(第二个分组);
  • [<div class="txtTrans">(.*?)</div>]:译文是开始标签与随后出现的第一个 [</div>] 标签之间的文本(第一个分组)。量词 [*?] 是“惰性”的:它取尽可能少的字符。

12.7.3.3. TranslationService 客户端

2008 年的课程把客户端分成两个项目:一个包含 [TranslationService] 类及其接口的库,以及一个用于图形用户界面、由 Spring.NET 配置的 Windows Forms 应用程序。为了简洁起见,我们把 [ITranslationService] 接口、其实现 [TranslationService]、异常 [TranslationException]、以及测试程序合并到一个应用程序文件中。程序 [internet-17.cs] 如下:

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

// 翻译 Web 服务的"代理"客户端:TranslationService 类
// 向程序隐藏了 HTTP 对话和翻译网站 HTML 页面的解析
// 调用:dotnet run internet-17.cs,其后可加两个连字符和 siteUrl(默认为 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
{
    // 创建翻译服务:它查询网站以了解所支持的翻译语言
    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}");
    }
    // 几次翻译
    (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}");
    }
}

// --------------------------------------------------------------------
// 呈现给程序的接口
interface ITranslationService
{
    // 翻译方向:代码 -> 标签,例如 fe -> French → English
    IReadOnlyDictionary<string, string> TranslatedLanguages { get; }
    // 按代码给出的方向翻译一段文本
    Task<string> TranslateAsync(string text, string direction);
}

// 翻译服务特有的异常
class TranslationException : Exception
{
    public int Code { get; init; }
    public TranslationException(string message) : base(message) { }
    public TranslationException(string message, Exception inner) : base(message, inner) { }
}

// 实现:翻译网站的 HTTP 客户端
partial class TranslationService : ITranslationService
{
    // 由程序提供的 HTTP 客户端
    private readonly HttpClient client;
    public IReadOnlyDictionary<string, string> TranslatedLanguages { get; }

    // 私有构造函数:我们通过工厂方法 CreateAsync 创建
    private TranslationService(HttpClient client, Dictionary<string, string> languages)
    {
        this.client = client;
        TranslatedLanguages = languages;
    }

    // 表单中的选项 <option value='fe'>French &rarr; English
    [GeneratedRegex(@"<option[^>]*value='(\w+)'>([^<\r\n]+)")]
    private static partial Regex OptionRegex();

    // 翻译结果:<div class="txtTrans">...</div>
    [GeneratedRegex("""<div class="txtTrans">(.*?)</div>""")]
    private static partial Regex TranslationRegex();

    // 创建服务:翻译方向从网站的表单中读取
    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))
        {
            // HTML 实体(&rarr;……)被解码
            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);
    }

    // 翻译
    public async Task<string> TranslateAsync(string text, string direction)
    {
        // 请求的翻译是否可行?
        if (!TranslatedLanguages.ContainsKey(direction))
        {
            throw new TranslationException($"The translation direction [{direction}] is not recognized") { Code = 10 };
        }
        // 要请求的 URL:文本必须经过编码
        string url = $"translation?direction={direction}&text={Uri.EscapeDataString(text)}";
        try
        {
            // 我们只等待响应的 HTTP 头:文档将被逐步读取
            using HttpResponseMessage response = await client.GetAsync(url, HttpCompletionOption.ResponseHeadersRead);
            response.EnsureSuccessStatusCode();
            using var reader = new StreamReader(await response.Content.ReadAsStreamAsync());
            // 我们逐行查找翻译结果,找到后立即停止
            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 };
        }
        // 页面中不包含翻译结果
        throw new TranslationException("The server did not send back a translation") { Code = 12 };
    }
}

我们先从接口和异常开始:

  • 第 53–58 行:呈现给程序的接口。属性 [TranslatedLanguages] 是站点所接受的翻译方向的字典,其条目形如 [fe] → [French → English];方法 [TranslateAsync] 把文本 [text] 按代码为 [direction] 的方向进行翻译。2008 年时该方法是同步的;现在它是异步的,与它所使用的 [HttpClient] 的方法一样;
  • 第 62–66 行:服务专用的异常,带有错误代码,仿照 [TaxException] (第 6 章)设计。

[TranslationService] 类:

  • 第 70 行:该类是分部类([partial]),因为其正则表达式的代码是在编译时生成的(特性 [GeneratedRegex],第 5 章);
  • 第 73 行:服务不会自行创建 [HttpClient],而是从程序接收它,由程序决定其配置(基地址、超时)及其生命周期;
  • 第 77 行:构造函数是私有的。服务只能在查询网站之后创建,而这是一个异步操作;然而,构造函数不能是异步的。因此使用了静态构造方法 [CreateAsync];
  • 第 84–89 行:上面介绍的两个正则表达式。第一个是逐字字符串字面量 [@"..."] (没有转义序列),第二个是原始字符串字面量 [""" ... """](C# 11),它允许直接书写 [class="txtTrans"] 中的引号而无需将其重复书写;
  • 第 92–113 行:创建服务。2008 年的课程把翻译键列表存放在 Spring 配置文件中。我们则直接从网站本身读取,这样可以确保它是最新的:
    • 第 97 行:我们请求表单页面,不带任何参数;
    • 第 99 行:通信错误被封装为一个 [TranslationException] ,代码为 11;
    • 第 104–107 行:正则表达式找到的每个 [<option>] 标签都提供一个代码(第 1 组)和一个标签文本(第 2 组)。[WebUtility.HtmlDecode] 将 HTML 实体替换为它们所代表的字符:[French &rarr; English] 变为 [French → English];
  • 第 117–147 行:翻译:
    • 第 120–122 行:系统验证所请求的翻译方向是否存在。2008 年的代码在这里有一个错误:[String.Format] 被调用时没有提供要插入消息中的值;字符串插值使这类错误不可能发生;
    • 第 125 行:请求 URL,其中的文本已被编码;
    • 第 129 行:[GetAsync] 在响应头到达后立即返回响应,而不等待文档内容。2008 年的课程选择 [HttpWebRequest] 而不是 [WebClient] ,这样就可以逐行读取页面,并在找到翻译后立即停止;[ResponseHeadersRead] 选项使我们可以用 [HttpClient] 做到同样的事;
    • 第 131–138 行:文档在到达时被逐行读取,并在每一行中搜索翻译。一旦找到,就将其解码后返回;[using] 语句会关闭流并释放响应,页面的其余部分永远不会被读取;
    • 第 142 行:通信错误会抛出代码为 11 的异常;
    • 第 147 行:如果整个页面读完后仍未找到翻译,则抛出代码为 12 的异常。

测试程序:

  • 第 8 行:网站地址可以作为参数传入;
  • 第 9 行:应用程序的 HTTP 客户端;
  • 第 13 行:创建服务。此后程序仅通过其接口 [ITranslationService] 与服务交互;
  • 第 20–27 行:来自 2008 年课程的测试用例,外加两个错误用例:空文本和未知的翻译方向。该数组是具名元组(C# 7)的数组;
  • 第 29 行:每个元组被解构为两个变量。

结果,此时 [internet-16.cs] 网站已在另一个窗口中启动:

> 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
  • 第 3–5 行:翻译方向是从网站表单中读取的,并且 HTML 实体已被解码;
  • 第 9 行:未知单词按原样返回,与 2008 年的网站一样;
  • 第 10 行:对于空文本,网站返回了其表单而没有翻译;
  • 第 11 行:翻译 [fx] 被服务拒绝,没有查询网站。

如果网站不可用:

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)

在网站一侧,我们可以看到上面所示来自 [curl] 的请求,随后是客户端发送的请求:第一个用于获取表单,之后的用于翻译([fx] 请求被服务拒绝,因此没有产生任何请求):

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. 结论

这个应用程序表明 [HttpClient] 使我们能够利用 Web 资源。每次所用的技术都是相同的:

  • 确定要查询哪个 URL。它通常是预先配置好的;
  • 查询该 URL;
  • 使用正则表达式在服务器的响应中找到我们要查找的内容。

这种如今被称为“网页抓取”的技术是脆弱的:随着时间推移,所查询的 URL 或页面结构可能会改变,原来能找到结果的正则表达式可能不再有效。把这些信息存放在配置文件中是个好主意,但这并不总是足够;此外,许多网站的使用条款禁止这样做。事实上,对 HTML 页面进行可靠的分析,更适合使用专门的库(AngleSharp、HtmlAgilityPack)来完成,而不是使用正则表达式。在下一章中,我们将看到 Web 上有更稳定的、专为程序使用而设计的资源:Web 服务。例如,当今的翻译服务无一例外都提供这种类型的接口,它接受并返回 JSON。

12.7.4. 使用 SmtpClient 类的 SMTP 客户端

SMTP 客户端是 SMTP 服务器(即邮件发送服务器)的客户端,其协议我们已在第 1 部分中介绍过。[System.Net.Mail] 命名空间中的 [SmtpClient] 类封装了这种客户端的需求:开发人员无需了解 SMTP 协议或 MIME 消息格式的细节。与它配合使用的类有 [MailMessage] (一封邮件)、[MailAddress] (一个电子邮件地址)和 [Attachment] (一个附件)。

[SmtpClient] 类在 .NET 10 中仍然存在,也没有被声明为过时,但其文档指出,Microsoft 不建议将其用于新的开发:它不支持现代身份验证协议(OAuth 2.0,各大邮件服务商越来越多地要求使用它),并且将不再更新。文档推荐使用开源库 MailKit(即 [MailKit] NuGet 包),它还支持通过 POP3 和 IMAP 读取电子邮件。由于课程环境中没有这个包,我们将介绍 [SmtpClient],它的基本原理(一封邮件、地址、附件,以及发送邮件的客户端)与 MailKit 中的相同。

2008 年的课程在一个 Windows Forms 应用程序中介绍 [SmtpClient] ,该应用程序在要求用户关闭杀毒软件保护之后,将电子邮件发送到真实 SMTP 服务器的 25 端口。我们将把它做得更简单、更安全:电子邮件将发送到一个用 C# 编写、运行在本机上的小型 SMTP 测试服务器,它会显示收到的所有内容,并且不转发任何东西。在实际使用中,有功能完整的测试服务器,例如 Mailpit 或 smtp4dev,它们还提供用于查看已收到邮件的 Web 界面。

12.7.4.1. SMTP 测试服务器

我们的 SMTP 服务器沿用了第 1 部分中回显服务器的结构:一个等待客户端的异步循环、每个客户端一个任务,以及由 Ctrl-C 触发的取消令牌。向每个客户端提供的服务是第 1 部分中介绍的最简 SMTP 对话。程序 [internet-18.cs] 如下:

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

// 测试用 SMTP 服务器:它执行最简化的 SMTP 对话并显示收到的邮件,
// 但从不把它们投递给收件人
// 调用:dotnet run internet-18.cs,其后可加两个连字符和端口 port(默认 27225);用 Ctrl-C 停止
int port = args.Length == 1 && int.TryParse(args[0], out int p) ? p : 27225;

// Ctrl-C 取消令牌:服务器干净地停止
using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) =>
{
    e.Cancel = true;
    cancellation.Cancel();
};

// 服务器只接受来自本机的客户端
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);

// --------------------------------------------------------------------
// 与客户端的 SMTP 对话:C: 是从客户端收到的行,S: 是服务器发送的行
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);
            // SMTP 要求行以 \r\n 结尾
            await using var writer = new StreamWriter(stream, new UTF8Encoding(false)) { AutoFlush = true, NewLine = "\r\n" };

            // 发送一行响应,同时在控制台显示
            async Task ReplyAsync(string response)
            {
                Console.WriteLine($"S: {response}");
                await writer.WriteLineAsync(response);
            }

            // 当前邮件的信封:发件人和收件人
            string? sender = null;
            List<string> recipients = [];
            // 欢迎消息
            await ReplyAsync("220 smtp.test ESMTP test server of the C# course");
            while (await reader.ReadLineAsync(token) is string command)
            {
                Console.WriteLine($"C: {command}");
                // 动词:前四个字符,不区分大小写
                string verb = command.Length >= 4 ? command[..4].ToUpperInvariant() : command;
                switch (verb)
                {
                    case "EHLO":
                        // 多行响应:250-... 然后是 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>");
                        // 邮件:直到只含一个点的行为止的所有行
                        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}");
    }
}

我们只对与回显服务器相比的新内容进行说明:

  • 第 19 行:服务器只在环回地址上监听:只有同一台机器上的程序才能连接到它;
  • 第 55 行:无论系统是什么,SMTP 都要求使用 \r\n 作为行结束符;
  • 第 58–61 行:一个本地函数(C# 7),它向客户端发送一行响应,并在控制台上显示该行,前面加上 [S:]。从客户端收到的行则在前面加上 [C:] 显示,与第 1 部分中的示例对话一致;
  • 第 65–66 行:当前邮件的头部:由 [MAIL FROM] 标识的发件人,以及由 [RCPT TO] 标识的收件人;
  • 第 68 行:问候消息:在 SMTP 中,服务器先说话;
  • 第 73 行:命令动词由其前四个字符构成([EHLO]、[MAIL]、[RCPT]……),其大小写是不确定的;
  • 第 76–80 行:对 [EHLO] 的响应由多行组成。在这些行中,服务器说明其能力:最大邮件大小([SIZE])以及对 8 位编码字符的支持([8BITMIME]);
  • 第 96 行:[case] 子句后面可以补充一个 [when] 条件:如果没有指定发件人或收件人,[DATA] 命令会被拒绝;
  • 第 99–110 行:邮件本身。服务器提示客户端发送邮件(代码 354),然后读取并显示所有行,直到只含一个点号的行,并确认收到(代码 250);
  • 第 122–124 行:客户端已结束;服务器作出响应并关闭连接,退出该方法;
  • 第 126 行:任何其他命令都会被拒绝。

这个服务器不做太多检查,也不支持 [STARTTLS] 和 [AUTH] 扩展:它足以用来观察 [SmtpClient] 发送了什么。

12.7.4.2. SMTP 客户端

[internet-19.cs] 程序通过键盘提示用户输入电子邮件的各项内容(2008 年的图形应用程序曾让用户在其表单中输入这些内容),然后将它们发送到作为参数指定的 SMTP 服务器:

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

// 用 SmtpClient 类发送电子邮件
// 调用:dotnet run internet-19.cs,后接两个连字符、SMTP 服务器 smtpServer 和端口 port
// 附件在当前文件夹中查找

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

// 输入邮件的各个元素
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)");
// 正文:多行,以空行结束
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
{
    // 邮件
    using var message = new MailMessage
    {
        From = new MailAddress(sender),
        Subject = subject,
        Body = text.ToString(),
        // 文本以 UTF-8 编码并原样传输(8 位)
        BodyEncoding = Encoding.UTF8,
        BodyTransferEncoding = TransferEncoding.EightBit,
    };
    // 地址:Add 接受以逗号分隔的地址列表
    message.To.Add(recipients);
    if (copies != "")
    {
        message.CC.Add(copies);
    }
    if (blindCopies != "")
    {
        message.Bcc.Add(blindCopies);
    }
    // 附件,由其路径指定
    foreach (string file in attachments.Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries))
    {
        message.Attachments.Add(new Attachment(file));
    }

    // SMTP 客户端:它了解 SMTP 协议和邮件的 MIME 格式
    using var client = new SmtpClient(server, port);
    await client.SendMailAsync(message);

    // 发送情况摘要
    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}");
    }
}

// 从键盘输入一行
static string Input(string label)
{
    Console.Write($"{label}: ");
    return Console.ReadLine()?.Trim() ?? "";
}

说明:

  • 第 18–23 行:使用本地函数 [Input] 输入电子邮件的各项内容;
  • 第 26–29 行:邮件正文,可跨多行,以一个空行结束;
  • 第 35–42 行:邮件,使用对象初始值设定项创建:
    • [From]:发件人,一个 [MailAddress] 对象。[MailAddress] 的构造函数会检查地址格式,如果地址不正确,则抛出 [FormatException];
    • [Subject]、[Body]:邮件的主题和正文;
    • [BodyEncoding]、[BodyTransferEncoding]:文本以 UTF-8 编码,并按原样以 8 位传输(服务器表明它接受这种格式)。如果没有这两个属性,[SmtpClient] 会自行选择编码(base64 或 quoted-printable),这会使文本在服务器显示时难以阅读;
  • 第 45–52 行:收件人、“Cc”(抄送)字段中的收件人,以及“Bcc”(密送)字段中的收件人。“Bcc”字段中的收件人会收到邮件,但其他收件人并不知情。[To]、[CC] 和 [Bcc] 集合的 [Add] 方法接受以逗号分隔的地址列表;2008 年的版本是自己使用正则表达式解析该列表的;
  • 第 55–57 行:附件,由其文件路径标识。相对路径是相对于当前目录的;在我们的测试中,文件 [attachment.txt] 位于程序启动所在的 [12-internet] 目录中;
  • 第 61 行:SMTP 客户端,带有服务器名称和端口。对于真实的服务器,我们还会指定 [EnableSsl = true] (通过 [STARTTLS] 加密)以及连接凭据 [Credentials = new NetworkCredential("username", "password")];
  • 第 62 行:异步发送邮件。2008 年的课程使用的是同步方法 [Send];
  • 第 65–70 行:发送情况的摘要;
  • 第 72 行:无效地址会引发 [FormatException] 错误;发送问题会引发 [SmtpException] 错误;找不到附件会引发 [FileNotFoundException] 错误,它派生自 [IOException]。

SMTP 测试服务器在命令窗口中于 27225 端口启动。在另一个窗口中,向两个收件人发送一封邮件,其中一个收件人为抄送,一个为密送,并带有一个附件:

> 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

文件 [attachment.txt] 包含两行文本。服务器显示的内容如下:

> 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

说明:

  • 第 5 行:[SmtpClient] 连同机器名称一起出现;
  • 第 9–17 行:邮件信封:发件人,后面是所有收件人,包括密送(BCC)收件人([eve@example.com])。信封决定邮件投递给谁;
  • 第 21–28 行:邮件头,构成收件人将看到的内容。它们包含收件人 [To] 和 [Cc],但不包含密送收件人:密送就是这样保持隐藏的。主题行包含一个带重音的字符;由于邮件头只能包含 ASCII 字符,它按 RFC 2047 标准进行了编码:[=?utf-8?B?...?=] 表示“以 Base64 编码的 UTF-8 文本”;
  • 第 27 行:邮件为 MIME 格式(多用途互联网邮件扩展,RFC 2045 及后续标准):它由多个部分组成,各部分以一条分隔行([boundary])隔开,该分隔行由 [SmtpClient] 随机选择;
  • 第 32–38 行:第一部分,即邮件正文,为 8 位 UTF-8:可以直接阅读;
  • 第 41–46 行:第二部分,即附件,以 Base64 编码。Base64 使用 ASCII 字符集中的 64 个字符来编码任意字节;收件人的邮件服务器无需知道附件的性质;
  • 第 50 行:邮件结束;
  • 第 51 行:我们的服务器收到了一封发给四个收件人的邮件;
  • 第 53–54 行:[SmtpClient] 结束交互;
  • 第 56 行:测试结束后,服务器被 Ctrl-C 停止。

无效地址在发送任何邮件之前就会被拒绝:

> 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.

如果 SMTP 服务器不可用,则会抛出 [SmtpException];其内部异常指明了原因:

> 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. 通用异步 TCP 客户端

2008 年的课程在这里用了整整一节介绍一个通用的异步 TCP 客户端,它带有 Windows Forms 图形界面:一个用于输入服务器名称和端口的字段、一个 [Connect] / [Disconnect] 按钮、一个用于输入要发送的行的文本框,以及两个用于显示连接事件和服务器通信的列表。图形用户界面已不再属于本课程,这个示例也已失去了大部分意义:它的目的是演示异步编程,而自 2008 年以来异步编程已经发生了彻底的变革。

2008 年的客户端直接使用 [Socket] 对象,并采用当时的异步模型,称为 APM(异步编程模型):每个操作被分成一个 [BeginXxx] 方法,它启动操作并立即返回控制权,以及一个 [EndXxx] 方法,它在操作结束时由线程池中的线程所执行的回调方法内调用。连接是这样写的:

// 启动连接:操作结束时将回调 connected 方法
client.BeginConnect(Dns.GetHostEntry(serverName).AddressList[0], port, connected, client);
...
// 回调方法
private void connected(IAsyncResult result)
{
    Socket client = result.AsyncState as Socket;
    // 操作结束:如果连接失败则抛出异常
    client.EndConnect(result);
    // 启动对服务器所发数据的异步读取
    client.BeginReceive(data, 0, bufferSize, SocketFlags.None, read, client);
}

接收操作的 [read] 回调方法必须再次调用 [BeginReceive] 来读取其余数据,根据收到的字节块重建各行(因为一行可能被分割在两个块之间),并且由于它运行在线程池中的线程上,还必须调用窗体的 [Invoke] 方法来更新图形界面。代码冗长,对话逻辑也分散在多个方法中。

APM 模型已被基于任务的模型(TAP,基于任务的异步模式,随 2010 年的 .NET 4 引入)以及关键字 [async] / [await] (C# 5,2012 年)所取代,后者将在第 9 章中介绍。第一部分中的通用 TCP 客户端([internet-06.cs])已经是一个异步客户端:[ConnectAsync] 取代了 [BeginConnect] / [EndConnect] 这一对方法;在循环中调用 [ReadLineAsync] 的接收任务取代了 [BeginReceive] 的回调链;而 [StreamReader] 负责重建各行。代码的阅读顺序就是它的执行顺序,如同同步代码一样。在当前的图形应用程序(WPF、WinUI、.NET MAUI)中,[await] 还会在界面线程上恢复执行,从而无需再调用 [Invoke]。

2008 年课程的结论依然成立:对于只有一个连接的客户端,异步除了让界面保持响应之外,益处不大;但对服务器来说,它是必不可少的。使用阻塞操作为客户端提供服务的服务器,每个客户端都要占用一个线程;而使用异步操作,只需几个线程就足以为大量客户端提供服务。下一个示例应用程序中的服务器正是这样做的。

12.9. 示例应用程序第 8 版:税款计算服务器

12.9.1. 新版本的架构

我们将重新回到税款计算应用程序。在第 5 版(第 6 章)中,它由三个层组成,每个层位于各自的库中:[dao] (税率档次)、[business] (计算)和 [ui] (控制台对话),通过依赖注入组装;第 6 版和第 7 版用数据库访问替换了 [dao] 层。2008 年的课程从第 7 版(数据在数据库中,带图形界面)开始;我们从第 5 版开始,它运行起来更简单:新版本与第 6 版和第 7 版中的 [dao] 层配合,工作方式也完全相同。

我们将把这个架构分布到两台机器上:

Image

  • 一台 [server] 机器承载第 5 版的 [business] 层和 [dao] 层。构建一个 [server] 层,使网络上的客户端能够通过基于文本的 TCP 协议查询税款计算服务;
  • 一台 [client] 机器承载第 5 版的 [ui] 层。一个新的 [business] 层作为服务器的(TCP)客户端,使客户端能够查询税款计算服务。

架构发生了重大变化:第 5 版是单用户应用程序;第 8 版成为客户端/服务器应用程序,服务器将能够同时为多个客户端服务。不过,我们只需编写两个新类 [TaxServer] 和 [TaxBusinessTcp],以及两个主程序:其余所有内容都原样复用,无需修改。

[TaxV8] 解决方案由两个控制台项目组成,它们引用第 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. 通信协议

我们保留 2008 年的服务器协议。客户端连接后,服务器向其发送一条欢迎消息,然后接受以下命令,每行一条,不区分大小写:

命令
服务器响应
help
接受的命令列表,共四行
tax married nbChildren annualSalary
已婚者(married 为 [y])或未婚者([n]),有 [nbChildren] 个孩子、年薪为 [annualSalary] 欧元时的税款,例如,对 [tax y 2 60000] 的响应为 [4282];或者一行错误消息
goodbye
消息 [Goodbye...];随后服务器关闭连接

任何其他命令都会收到响应 [Command not recognized. Use the help command.]

12.9.3. 税款计算服务器

12.9.3.1. 项目

文件 [Tax.Server.csproj] 如下:

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

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

  <ItemGroup>
    <!-- 第 5 版的 [dao] 层和 [business] 层,原样复用 -->
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Dao/Tax.Dao.csproj" />
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Business/Tax.Business.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- 依赖注入容器与 JSON 配置文件的读取 -->
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.12" />
  </ItemGroup>

  <ItemGroup>
    <!-- 配置文件被复制到可执行文件旁边 -->
    <None Update="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>
  • 第 12–13 行:第 5 版的 [dao] 层和 [business] 层通过其项目被引用。来自 [Tax.Dao] 项目的数据文件 [TaxData.txt] 和 [TaxData.json] 被复制到服务器的输出文件夹;
  • 第 18–19 行:依赖注入容器和对 JSON 配置文件的读取,与第 5 版相同;
  • 第 24 行:配置文件被复制到可执行文件旁边。

配置文件 [appsettings.json]:

{
  "Dao": {
    "Implementation": "FileTax",
    "File": "TaxData.txt"
  },
  "Server": {
    "Port": 27200,
    "Echo": true
  }
}
  • 第 2–4 行:[dao] 层的配置,与第 5 版相同:税率档次从文本文件 [TaxData.txt] 中读取;
  • 第 6–8 行:服务器的监听端口,以及服务器日志中与客户端对话的回显。2008 年的服务器有一个管理控制台(命令 [start port]、[stop]、[echo start]、[echo stop]、[status]、[quit]);我们选择了配置文件和通过 Ctrl-C 关闭,这两者更简单,也更符合现代服务器的运作方式。

12.9.3.2. 主程序

服务器的 [Program.cs] 文件如下:

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

// TCP 税额计算服务器:配置、各层的集成、执行
TaxServer server;
try
{
    // 读取可执行文件旁边的配置
    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;

    // 在容器中注册各层
    var services = new ServiceCollection();
    // [dao] 层:实现由配置选择(与第 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")
    });
    // 第 5 版的 [business] 层
    services.AddSingleton<ITaxBusiness, TaxBusiness>();
    // [server] 层:容器会把 [business] 层及其选项传给它
    services.AddSingleton(new ServerOptions(port, echo));
    services.AddSingleton<TaxServer>();

    // 创建服务器,从而创建 [business] 层和 [dao] 层
    ServiceProvider provider = services.BuildServiceProvider();
    server = provider.GetRequiredService<TaxServer>();
}
catch (Exception ex)
{
    // 显示异常链并停止
    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 取消令牌:服务器干净地停止
using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) =>
{
    e.Cancel = true;
    cancellation.Cancel();
};
// 运行服务器,直到收到停止请求
await server.RunAsync(cancellation.Token);
return 0;

这显然就是第 5 版的主程序:

  • 第 13–20 行:读取配置。这些值是字符串:端口和回显通过 [TryParse] 转换,并提供默认值;
  • 第 25–33 行:[dao] 层和 [business] 层存放在容器中,与第 5 版完全相同;
  • 第 35–36 行:新增的功能。服务器选项(端口、回显)作为预先构建好的对象存放,随后是 [server] 层本身。[TaxServer] 的构造函数需要一个 [ITaxBusiness] 和一个 [ServerOptions]:容器会提供它们;
  • 第 40 行:创建服务器会触发 [business] 层的创建,进而触发 [dao] 层的创建;此时会读取 [TaxData.txt] 文件。如果出现错误(文件缺失、格式错误),则显示该错误并终止程序(第 42–50 行);
  • 第 54–58 行:与回显服务器一样,Ctrl-C 会取消令牌 [cancellation];
  • 第 61 行:服务器一直运行,直到令牌被取消。

12.9.3.3. [server] 层

[TaxServer] 类如下:

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

namespace Server;

// 服务器的选项:监听端口以及是否在日志中回显对话
public record ServerOptions(int Port, bool Echo);

// [server] 层:它通过文本行组成的 TCP 协议使 [business] 层可被访问
public class TaxServer(ITaxBusiness business, ServerOptions options)
{
    // 协议的固定响应
    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.";

    // 运行服务器,直到令牌被取消
    public async Task RunAsync(CancellationToken token)
    {
        var listener = new TcpListener(IPAddress.Any, options.Port);
        // 正在进行的服务任务
        var services = new List<Task>();
        int clientNumber = 0;
        try
        {
            listener.Start();
            Log($"Tax calculation server started on port {options.Port}");
            while (true)
            {
                // 等待一个客户端
                TcpClient client = await listener.AcceptTcpClientAsync(token);
                // 它由一个我们不等待的任务服务:我们回头等待下一个客户端
                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();
        }
        // 我们等待正在进行的服务结束
        await Task.WhenAll(services);
        Log("Server stopped");
    }

    // 为客户端提供的服务
    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 };

                // 向客户端发送响应,可在日志中回显
                async Task WriteAsync(string response)
                {
                    if (options.Echo)
                    {
                        Log($"---> client {clientNumber} : {response}");
                    }
                    await writer.WriteLineAsync(response);
                }

                // 欢迎消息
                await WriteAsync(Welcome);
                // 读取请求 / 写入响应的循环,直到收到告别命令
                while (await reader.ReadLineAsync(token) is string request)
                {
                    if (options.Echo)
                    {
                        Log($"<--- client {clientNumber} : {request}");
                    }
                    // 按字段拆分的请求
                    string[] fields = request.Trim().ToLower().Split(' ', StringSplitOptions.RemoveEmptyEntries);
                    if (fields is ["goodbye"])
                    {
                        await WriteAsync(Goodbye);
                        break;
                    }
                    // 根据命令给出的响应
                    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}");
        }
    }

    // 命令 tax married nbChildren annualSalary:返回税额或错误消息
    private string CalculateTax(string[] fields)
    {
        // 需要 4 个字段:tax、y 或 n、两个整数
        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
        {
            // 计算工作交给 [business] 层
            return business.CalculateTax(fields[1] == "y", nbChildren, annualSalary).ToString();
        }
        catch (Exception ex)
        {
            // 异常的消息,写在一行内:协议由文本行组成
            return ex.Message.ReplaceLineEndings(" ");
        }
    }

    // 服务器的日志:每行都带时间戳
    private static void Log(string message) => Console.WriteLine($"{DateTime.Now:HH:mm:ss} {message}");
}
  • 第 8 行:服务器选项,一个位置记录(C# 9);
  • 第 11 行:该类通过其主构造函数(C# 12)接收 [business] 层及其选项。它只了解 [business] 层的 [ITaxBusiness] 接口,对 [dao] 层一无所知;
  • 第 14–18 行:协议的固定响应。对 [help] 命令的响应包含 \n:客户端会把它作为四行收到,与 2008 年相同;
  • 第 21–54 行:等待客户端的循环。这与第一部分中的回显服务器相同:每个客户端由一个不会被阻塞的异步任务提供服务(第 36 行),取消令牌会结束对客户端的等待(第 40 行),服务器在关闭之前会等待正在进行的服务完成(第 53 行)。2008 年的服务器把每个客户端分配给一个限制为 10 个线程的线程池中的线程,该线程在服务期间一直被阻塞;而在这里,不会有线程被一个慢吞吞的客户端占住;
  • 第 58–116 行:向客户端提供的服务:
    • 第 70–76 行:一个本地函数,它向客户端发送响应,并且在启用日志时也把响应写入日志;
    • 第 80 行:客户端一连接,服务器就向其发送一条欢迎消息;
    • 第 82 行:读取命令的循环,如果客户端关闭连接或服务器被关闭,该循环就会停止;
    • 第 89 行:命令被转换为小写后解析为各个字段。2008 年的课程使用 [Regex.Split] 和 [\s+] 模式;[Split] 的 [RemoveEmptyEntries] 选项同样会移除由连续多个空格产生的空字段;
    • 第 90 行:列表模式(C# 11):命令仅由单词 [goodbye] 构成。服务器作出响应并退出循环:退出 [using (client)] 块时连接被关闭;
    • 第 96–100 行:带有列表模式的 [switch] 表达式选择响应:[["help"]] 单独匹配命令 [help],而 [["tax", ..]] 匹配以 [tax] 开头的命令,后面跟任意数量的字段(切片模式 [..])。2008 年的服务器在收到空行时会关闭连接;现在它会收到响应 [Command not recognized];
  • 第 121–138 行:计算税款:
    • 第 124–128 行:一个列表模式即可检查命令是否有四个字段、第二个字段是否为 [y] 或 [n],并把最后两个字段赋给变量 [children] 和 [salary];然后检查它们是否为整数。2008 年的代码是通过四个连续的测试来完成这些检查的;
    • 第 133 行:向 [business] 层请求计算。同一个 [TaxBusiness] 实例为所有客户端提供服务,可能是来自不同线程的同时服务:这之所以可行,是因为该类在构造之后不会修改任何数据(其税率档次数组是只读的);
    • 第 138 行:如果 [business] 层抛出异常(例如由于孩子数量为负数),其消息会返回给客户端。该消息可能包含换行符:这些换行符会被替换为空格,因为协议要求响应只占一行;
  • 第 143 行:服务器日志,显示在控制台上:每一行前面都有时间,这使我们能够看出并发服务的先后顺序。[Console.WriteLine] 可以从多个线程调用而无需任何特殊预防措施:它的写入互不干扰。

12.9.4. 税款计算服务器的客户端

2008 年的课程使用第 7 版的图形界面;我们使用第 5 版的控制台界面(即 [Ui.Dialog] 类),并且不对其进行修改。

12.9.4.1. 客户端的 [business] 层

[ui] 层与一个 [business] 层通信,它只了解后者的 [ITaxBusiness] 接口:

1
2
3
4
5
6
7
namespace Business;

// [business] 层的接口
public interface ITaxBusiness
{
    int CalculateTax(bool married, int nbChildren, int salary);
}

因此,只需为它提供该接口的另一个实现,这个实现不是自己计算税款,而是向服务器请求税款。这就是 [TaxBusinessTcp] 类:

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

namespace Client;

// 客户端的 [business] 层:它实现 ITaxBusiness,把计算委托给 TCP 服务器
public class TaxBusinessTcp : ITaxBusiness, IDisposable
{
    // 与服务器的连接,在对象的整个生命周期内保持打开
    private readonly TcpClient client;
    private readonly StreamReader reader;
    private readonly StreamWriter writer;

    // 连接到服务器(机器、端口)
    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 };
            // 服务器先发言:我们读取(并忽略)它的欢迎消息
            ReadResponse();
        }
        catch (Exception e) when (e is SocketException or IOException)
        {
            throw new TaxException($"Unable to connect to the server ({machine}, {port})", e) { Code = 21 };
        }
    }

    // 税额计算:一个请求,一个响应
    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 };
        }
        // 服务器返回税额或错误消息
        return int.TryParse(response, out int tax)
            ? tax
            : throw new TaxException($"The server answered: {response}") { Code = 23 };
    }

    // 读取一行响应;null 表示服务器已关闭连接
    private string ReadResponse() =>
        reader.ReadLine() ?? throw new TaxException("The server has closed the connection") { Code = 24 };

    // 连接结束:如果服务器还在,我们向它告别
    public void Dispose()
    {
        try
        {
            writer.WriteLine("goodbye");
            reader.ReadLine();
        }
        catch (IOException)
        {
            // 连接已断开:无事可做
        }
        client.Dispose();
    }
}
  • 第 8 行:该类实现 [ITaxBusiness]。它还实现 [IDisposable]:它维持一个必须关闭的网络连接;
  • 第 11–13 行:到服务器的连接及其读写流。2008 年的类为每次计算都打开一个新连接;我们只打开一个连接,用于一次会话中的所有计算:这样更高效,而且服务器看到的是每个用户会话对应一个客户端;
  • 第 16–29 行:构造函数连接到服务器并读取其欢迎消息(第 25 行)。连接错误被封装在 [TaxException] 中,这是应用程序异常;
  • 第 34–49 行:税款计算。命令 [tax y 2 60000] 被发送到服务器(第 39 行),并读取其响应。如果响应是整数,那就是税款金额;否则它是服务器的错误消息,并通过 [TaxException] 返回(第 49 行)。2008 年的代码直接把响应转换为整数,并要求读者加以改进:服务器的错误消息会引发转换异常,从而掩盖了错误的真正原因;
  • 第 53 行:当服务器已关闭连接时,[ReadLine] 返回 [null] ;此时会抛出 [TaxException];
  • 第 57–68 行:连接结束。客户端使用 [goodbye] 命令向服务器告别,然后关闭连接。如果服务器已经终止了连接,由此产生的 [IOException] 会被忽略。

这就引出了一个问题:为什么这个类使用同步方法 [TcpClient(machine, port)]、[ReadLine] 和 [WriteLine],而本章其余部分使用的是它们的异步版本?因为第 5 版中的 [ITaxBusiness] 接口是同步的:[CalculateTax] 返回的是 [int],而不是 [Task<int>],并且 [ui] 层调用它时不带 [await]。要使用 [ReadLineAsync],要么必须以阻塞方式等待其结果([ReadLineAsync().Result]),而第 9 章建议不要这样做;要么就得把接口改为异步的,从而修改第 5 版的 [business] 层和 [ui] 层。对于只服务一个用户的控制台程序,同步方法完全适用:主线程除了等待响应之外没有别的事可做。异步在服务器端至关重要,因为服务器必须为许多客户端服务,而在客户端则不然。在下一章编写新的层时,我们会为它们配备异步接口。

12.9.4.2. 客户端的主程序

项目 [Tax.Client.csproj] 引用第 5 版的 [business] 层和 [ui] 层:

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

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

  <ItemGroup>
    <!-- 第 5 版的 [business] 层接口和 [ui] 层 -->
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Business/Tax.Business.csproj" />
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Ui/Tax.Ui.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- 依赖注入容器 -->
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
  </ItemGroup>

</Project>

[Tax.Ui] 项目是一个控制台应用程序:一个项目可以引用另一个可执行项目以使用其公共类,在这里就是 [Ui.Dialog]。[Program.cs] 文件如下:

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

// 税额计算服务器的控制台客户端
// 调用:dotnet run,其后可加两个连字符、机器名 machine 和端口 port(默认:localhost 27200)
string machine = args.Length > 0 ? args[0] : "localhost";
int port = args.Length > 1 && int.TryParse(args[1], out int p) ? p : 27200;

// [business] 层现在是税额计算服务器的 TCP 客户端
var services = new ServiceCollection();
services.AddSingleton<ITaxBusiness>(_ => new TaxBusinessTcp(machine, port));
// 容器会释放(Dispose)它创建的对象:连接将在程序结束时关闭
using ServiceProvider provider = services.BuildServiceProvider();
try
{
    ITaxBusiness business = provider.GetRequiredService<ITaxBusiness>();
    Console.WriteLine($"Connected to the tax calculation server ({machine}, {port})");
    // 第 5 版的 [ui] 层,保持不变
    Dialog.Run(business);
}
catch (TaxException e)
{
    Dialog.DisplayError(e);
    return 1;
}
return 0;
  • 第 9–10 行:服务器的机器和端口,作为参数传入,并带有默认值;
  • 第 14 行:容器中注册的 [business] 层现在是 [TaxBusinessTcp]。由于它的构造函数需要容器不认识的两个参数,因此为它提供了一个创建函数;
  • 第 16 行:容器用 [using] 声明。当它在程序结束时被释放,它会依次释放自己创建的 [IDisposable] 对象:[TaxBusinessTcp] 的 [Dispose] 方法将被调用,连接将被正确关闭;
  • 第 19 行:创建 [business] 层,即建立到服务器的连接;
  • 第 22 行:第 5 版的对话,保持不变。[ui] 层并不知道税款是由远程服务器计算的;
  • 第 24–27 行:连接或通信错误由第 5 版的 [DisplayError] 方法显示。

12.9.5. 执行

服务器在命令窗口中从 [Tax.Server] 文件夹启动。在另一个窗口中,客户端从 [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: 

对话与第 5 版完全相同:它包含验证值(已婚且有 2 或 3 个孩子、薪水为 60,000 欧元时分别为 4282 和 2959,未婚且无孩子时为 11519),以及针对错误输入的相同错误消息。这些消息由客户端的 [ui] 层生成,该层在请求计算之前先验证输入:错误的输入永远不会到达服务器。

现在我们在两个窗口中启动两个客户端 A 和 B,B 在 A 仍处于连接状态时启动。每个客户端执行两次计算。在客户端 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: 

在客户端 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: 

要查看服务器对错误命令的响应,需要一个能够把命令按键入的原样发送出去的客户端:第一部分中的通用 TCP 客户端正好适用。服务器先说话,这个客户端可以处理这种情况:

> 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]
  • 第 2 行:欢迎消息,它甚至在客户端的提示符之前就到达了;
  • 第 5–8 行:对命令 [help] 的响应,共四行;
  • 第 11 行:命令的大小写被忽略;
  • 第 13–15 行:两个格式错误的计算命令;
  • 第 18 行:命令的格式正确,但 [business] 层拒绝了负数的孩子数量;异常消息(为英文:它来自 .NET)被放在一行中返回;
  • 第 20 行:一个未知命令;
  • 第 21–23 行:在命令 [goodbye] 之后,服务器关闭了连接。

然后在还有最后一个客户端处于连接状态时,用 Ctrl-C 终止服务器。这个客户端在终止之前执行了第一次计算,并在终止之后发送了它的第二个请求:

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

读取响应得到了 [null]:[business] 层抛出了 [TaxException],主程序将其显示出来。服务器停止后,新的客户端就无法再连接了:

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

最后,这里是所有这些测试的服务器日志:

> 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
  • 第 3–13 行:第一次运行的客户端。借助回显输出,我们可以看到收到的所有命令和发送的所有响应。请注意命令 [goodbye] (第 11 行),它是在用户结束时由 [TaxBusinessTcp] 的 [Dispose] 方法发送的:会话被正确关闭;
  • 第 14–31 行:客户端 A(客户端 1)和 B(客户端 2)。客户端 2 在客户端 1 仍在被服务时到达(第 16 行),它们的请求按到达顺序交替处理:服务器确实在同时为多个客户端服务;
  • 第 32–53 行:通用 TCP 客户端的会话;
  • 第 54–61 行:最后一个客户端,在关闭时正被服务。Ctrl-C 取消了令牌;正在等待该令牌的两个操作(读取客户端 4 的命令和等待新客户端)以 [OperationCanceledException] 结束,其先后顺序取决于线程调度。服务器等待当前服务结束后才关闭。

12.9.6. 结论

我们再一次做到了在不修改的情况下重用现有代码:服务器端第 5 版的 [dao] 层和 [business] 层,以及客户端的 [ui] 层。这得益于对接口和依赖注入的系统化使用:要把应用程序部署到两台机器上,只需在 [business] 层之上添加一个 [server] 层,并为 [ui] 层提供 [ITaxBusiness] 的另一种实现。如果第 1 版把税款计算和用户交互放在同一个程序中,这一切都将无法复用。请注意,[ui] 层并不知道税款金额是由远程服务器计算的。

不过,我们这个自制协议确实有其局限:我们必须编写服务器、管理连接、解析命令、转换响应,而且用另一种语言编写的客户端需要了解这个特定的协议。下一章中的第 9 版将用 Web 服务取代 TCP 服务器:协议将是 HTTP,数据将使用 JSON 交换,客户端将使用 [HttpClient]。

12.10. 结论

本章介绍了使用 .NET 进行互联网编程,从基础知识开始,逐步过渡到高层类:

  • 第一部分回顾了互联网协议(IP、TCP、UDP、DNS)和基于文本的应用层协议(HTTP、SMTP、POP、FTP)的工作原理,然后介绍了 [IPAddress] 和 [Dns] 类,以及 [TcpClient] 和 [TcpListener] 类,它们是以异步方式使用的。利用这些类,我们编写了能够同时为多个客户端服务的服务器、通用 TCP 客户端,以及“手动”使用 HTTP 通信的 Web 客户端;
  • 第二部分介绍了专用于某个协议的类。对于 HTTP,[HttpClient] 类取代了已过时的 [WebClient] 和 [WebRequest]:我们的 TCP 客户端过去需要五十行完成的事情,它只用一条语句就能完成;它能处理重定向、表单、JSON、超时和取消,并且旨在跨请求重复使用。对于 SMTP,[SmtpClient] 类仍然可用,不过新的开发更推荐使用 MailKit 库;
  • 示例应用程序已经变成了客户端/服务器应用程序,而其现有的各层无需任何改动。

第 9 章中讨论的异步编程原理在这里找到了它的主要应用:异步服务器用少数几个线程为大量客户端服务,异步客户端等待来自网络的响应而不会阻塞线程。然而,编写 TCP 服务器并自行发明协议依然是例外:如今大多数分布式应用程序通过 HTTP 通信,使用交换 JSON 数据的 Web 服务。这就是下一章的主题。