【微软技术栈】C#.NET 使用 HttpClient 类发出 HTTP 请求

本文内容

1. 创建 HttpClient
2. 发出 HTTP 请求
3. 处理 HTTP 响应
4. HTTP 错误处理
5. HTTP 代理

本文介绍如何使用 HttpClient 类发出 HTTP 请求和处理响应。

 重要

所有示例 HTTP 请求都以下面 URL 之一为目标：

• https://jsonplaceholder.typicode.com：用于测试和原型设计的免费虚设 API。
• https://www.example.com：此域用于文档中的说明性示例。

HTTP 终结点通常返回 JavaScript 对象表示法 (JSON) 数据，但并不总是如此。 为方便起见，可选的 System.Net.Http.Json NuGet 包为使用 System.Text.Json 执行自动序列化和反序列化的 HttpClient 和 HttpContent 提供多个扩展方法。 下面的示例提醒人们注意这些扩展的可用位置。

1、创建 HttpClient

下面的大多数示例都重复使用同一 HttpClient 实例，因此只需配置一次。 要创建 HttpClient，请使用 HttpClient 类构造函数。 

// HttpClient lifecycle management best practices:
// https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use
private static HttpClient sharedClient = new()
{
    BaseAddress = new Uri("https://jsonplaceholder.typicode.com"),
};

前面的代码：

• 实例化新的 HttpClient 实例作为 static 变量。 根据准则，建议在应用程序的生命周期内重复使用 HttpClient 实例。
• 将 HttpClient.BaseAddress 设置为 "https://jsonplaceholder.typicode.com"。

发出后续请求时，此 HttpClient 实例将使用基址。 若要应用其他配置，请考虑：

• 设置 HttpClient.DefaultRequestHeaders。
• 应用非默认 HttpClient.Timeout。
• 指定 HttpClient.DefaultRequestVersion。

 提示

或者，可使用工厂模式方法创建 HttpClient 实例，该方法允许配置任意数量的客户端并将它们用作依赖关系注入服务。 

2、发出 HTTP 请求

要发出 HTTP 请求，请调用以下任一 API：

HTTP 方法	API
GET	HttpClient.GetAsync
GET	HttpClient.GetByteArrayAsync
GET	HttpClient.GetStreamAsync
GET	HttpClient.GetStringAsync
POST	HttpClient.PostAsync
PUT	HttpClient.PutAsync
PATCH	HttpClient.PatchAsync
DELETE	HttpClient.DeleteAsync
†USER SPECIFIED	HttpClient.SendAsync

†USER SPECIFIED 请求指示 SendAsync 方法接受任何有效的 HttpMethod。

 警告

发出 HTTP 请求被视为是与网络 I/O 相关的工作。 虽然有同步 HttpClient.Send 方法，但建议改用异步 API，除非有充分的理由不这样做。

2.1 HTTP 内容

HttpContent 类型用于表示 HTTP 实体正文和相应的内容标头。 对于需要正文的 HTTP 方法（或请求方法）POST、PUT 和 PATCH，可使用 HttpContent 类来指定请求的正文。 大多数示例演示如何使用 JSON 有效负载准备 StringContent 子类，但还有针对其他内容 (MIME) 类型的其他子类。

• ByteArrayContent：提供基于字节数组的 HTTP 内容。
• FormUrlEncodedContent：为使用 "application/x-www-form-urlencoded" MIME 类型编码的名称/值元组提供 HTTP 内容。
• JsonContent：提供基于 JSON 的 HTTP 内容。
• MultipartContent：提供使用 "multipart/*" MIME 类型规范进行序列化的 HttpContent 对象的集合。
• MultipartFormDataContent：为使用 "multipart/form-data" MIME 类型进行编码的内容提供容器。
• ReadOnlyMemoryContent：提供基于 ReadOnlyMemory<T> 的 HTTP 内容。
• StreamContent：提供基于流的 HTTP 内容。
• StringContent：提供基于字符串的 HTTP 内容。

HttpContent 类还用于表示 HttpResponseMessage 的响应正文，可通过