HttpClient 类
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
提供一个类，用于从 URI 标识的资源发送 HTTP 请求和接收 HTTP 响应。
public ref class HttpClient : System::Net::Http::HttpMessageInvokerpublic class HttpClient : System.Net.Http.HttpMessageInvokertype HttpClient = class
inherit HttpMessageInvokerPublic Class HttpClient
Inherits HttpMessageInvoker- 继承
示例
// HttpClient is intended to be instantiated once per application, rather than per-use. See Remarks.
static readonly HttpClient client = new HttpClient();
static async Task Main()
{
// Call asynchronous network methods in a try/catch block to handle exceptions.
try
{
using HttpResponseMessage response = await client.GetAsync("http://www.contoso.com/");
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();
// Above three lines can be replaced with new helper method below
// string responseBody = await client.GetStringAsync(uri);
Console.WriteLine(responseBody);
}
catch (HttpRequestException e)
{
Console.WriteLine("\nException Caught!");
Console.WriteLine("Message :{0} ", e.Message);
}
}
open System.Net.Http
// HttpClient is intended to be instantiated once per application, rather than per-use. See Remarks.
let client = new HttpClient()
let main =
task {
// Call asynchronous network methods in a try/catch block to handle exceptions.
try
use! response = client.GetAsync "http://www.contoso.com/"
response.EnsureSuccessStatusCode() |> ignore
let! responseBody = response.Content.ReadAsStringAsync()
// Above three lines can be replaced with new helper method below
// let! responseBody = client.GetStringAsync uri
printfn $"{responseBody}"
with
| :? HttpRequestException as e ->
printfn "\nException Caught!"
printfn $"Message :{e.Message} "
}
main.Wait()
' HttpClient is intended to be instantiated once per application, rather than per-use. See Remarks.
Shared ReadOnly client As HttpClient = New HttpClient()
Private Shared Async Function Main() As Task
' Call asynchronous network methods in a try/catch block to handle exceptions.
Try
Using response As HttpResponseMessage = Await client.GetAsync("http://www.contoso.com/")
response.EnsureSuccessStatusCode()
Dim responseBody As String = Await response.Content.ReadAsStringAsync()
' Above three lines can be replaced with new helper method below
' Dim responseBody As String = Await client.GetStringAsync(uri)
Console.WriteLine(responseBody)
End Using
Catch e As HttpRequestException
Console.WriteLine(Environment.NewLine & "Exception Caught!")
Console.WriteLine("Message :{0} ", e.Message)
End Try
End Function
前面的代码示例使用 async Task Main() 入口点。 该功能需要 C# 7.1 或更高版本。
注解
类 HttpClient 实例充当发送 HTTP 请求的会话。 HttpClient实例是应用于该实例执行的所有请求的设置的集合。 此外，每个实例都 HttpClient 使用自己的连接池，将其请求与其他 HttpClient 实例执行的请求隔离开来。
实例化
HttpClient 旨在实例化一次，并在应用程序的整个生命周期内重复使用。 在 .NET Core 和 .NET 5+ 中，HttpClient 将连接池在处理程序实例内，并在多个请求之间重复使用连接。 如果为每个请求实例化 HttpClient 类，则重负载下可用的套接字数将耗尽。 这种耗尽将导致 SocketException 错误。
可以通过传入“处理程序”（如 HttpClientHandler (）或 SocketsHttpHandler .NET Core 2.1 或更高版本) 作为构造函数的一部分来配置其他选项。 提交请求后，处理程序上的连接属性无法更改，因此创建新的 HttpClient 实例的一个原因是需要更改连接属性。 如果不同的请求需要不同的设置，这还可能导致应用程序具有多个 HttpClient 实例，其中每个实例都进行了适当的配置，然后在相关客户端上发出请求。
HttpClient 仅在创建连接时解析 DNS 条目。 它不跟踪 DNS 服务器指定的任何生存时间 (TTL)。 如果 DNS 条目定期更改（这可能在某些容器方案中发生），客户端将不遵循这些更新。 若要解决此问题，可以通过设置 SocketsHttpHandler.PooledConnectionLifetime 属性来限制连接的生存期，以便在替换连接时要求执行 DNS 查找。
public class GoodController : ApiController
{
private static readonly HttpClient httpClient;
static GoodController()
{
var socketsHandler = new SocketsHttpHandler
{
PooledConnectionLifetime = TimeSpan.FromMinutes(2)
};
httpClient = new HttpClient(socketsHandler);
}
}
作为仅创建一个 HttpClient 实例的替代方法，还可以使用 IHttpClientFactory 来管理 HttpClient 实例。 有关详细信息，请参阅 HttpClient 使用准则。
派生
还 HttpClient 充当更具体的 HTTP 客户端的基类。 例如，FacebookHttpClient 提供特定于 Facebook Web 服务的其他方法 (例如， GetFriends) 方法。 派生类不应重写 类上的虚拟方法。 请改用接受 HttpMessageHandler 的构造函数重载来配置任何请求前或请求后处理。
传输
HttpClient是一个高级 API，用于包装运行它的每个平台上可用的较低级别的功能。
在每个平台上， HttpClient 尝试使用最佳可用传输：
| 主机/运行时 | 后端 |
|---|---|
| Windows/.NET Framework | HttpWebRequest |
| Windows/Mono | HttpWebRequest |
| Windows/UWP | 支持 Windows 本机 WinHttpHandler (HTTP 2.0 的) |
| Windows/.NET Core 1.0-2.0 | 支持 Windows 本机 WinHttpHandler (HTTP 2.0 的) |
| Android/Xamarin | 在生成时选择。 HttpWebRequest可以使用 或 配置为使用 Android 的本机HttpURLConnection |
| iOS、tvOS、watchOS/Xamarin | 在生成时选择。 HttpWebRequest可以使用 或 配置为使用 Apple NSUrlSession 的 (HTTP 2.0 支持) |
| macOS/Xamarin | 在生成时选择。 HttpWebRequest可以使用 或 配置为使用 Apple NSUrlSession 的 (HTTP 2.0 支持) |
| macOS/Mono | HttpWebRequest |
| macOS/.NET Core 1.0-2.0 | libcurl基于 的 HTTP 传输 (支持 HTTP 2.0 的) |
| Linux/Mono | HttpWebRequest |
| Linux/.NET Core 1.0-2.0 | libcurl基于 的 HTTP 传输 (支持 HTTP 2.0 的) |
| .NET Core 2.1 及更高版本 | System.Net.Http.SocketsHttpHandler |
用户还可以通过调用HttpClient采用 HttpMessageHandler的构造函数来配置 HttpClient 特定的传输。
&.NET Framework Mono
默认情况下，在 .NET Framework 和 Mono 上， HttpWebRequest 用于向服务器发送请求。 可以通过使用 参数在其中一个构造函数重载 HttpMessageHandler 中指定不同的处理程序来修改此行为。 如果需要身份验证或缓存等功能，可以使用 WebRequestHandler 来配置设置，并将 实例传递给构造函数。 返回的处理程序可以传递给具有 HttpMessageHandler 参数的构造函数重载。
.NET Core
从 .NET Core 2.1 开始， System.Net.Http.SocketsHttpHandler 类而不是 HttpClientHandler 提供更高级别的 HTTP 网络类（如 HttpClient）使用的实现。 使用 SocketsHttpHandler 提供了许多优点：
- 对照以前的实现，可以看到显著的性能改进。
- 消除平台依赖项，简化了部署和服务。 例如，
libcurl不再是 .NET Core for macOS 和 .NET Core for Linux 的依赖项。 - 跨所有 .NET 平台的一致行为。
如果不需要此更改，可以在 Windows 上通过引用其 NuGet 包并将其手动传递给 HttpClient 的构造函数来继续使用WinHttpHandler。
使用运行时配置选项配置行为
的行为的某些方面 HttpClient可通过 运行时配置选项进行自定义。 但是，这些开关的行为因 .NET 版本而异。 例如，在 .NET Core 2.1 - 3.1 中，可以配置是否 SocketsHttpHandler 默认使用 ，但从 .NET 5.0 开始，该选项不再可用。
连接池
HttpClient 尽可能池 HTTP 连接，并将其用于多个请求。 这具有显著的性能优势，尤其是对于 HTTPS 请求，因为连接握手只执行一次。
可以在 上配置连接池属性， HttpClientHandler 也可以在 SocketsHttpHandler 构造期间传入连接池属性，包括 MaxConnectionsPerServer、 PooledConnectionIdleTimeout和 PooledConnectionLifetime。
释放 HttpClient 实例会关闭打开的连接并取消所有挂起的请求。
注意
如果同时向同一服务器发送 HTTP/1.1 请求，则可以创建新连接。 即使重复使用实例 HttpClient ，如果请求速率较高，或者存在任何防火墙限制，也可能因为默认 TCP 清理计时器而耗尽可用套接字。 若要限制并发连接数，可以设置 MaxConnectionsPerServer 属性。 默认情况下，并发 HTTP/1.1 连接数不受限制。
缓冲和请求生存期
默认情况下，HttpClient 方法 (，但 GetStreamAsync) 缓冲来自服务器的响应，在返回异步结果之前将所有响应正文读取到内存中。 这些请求将继续，直到发生以下情况之一：
- 成功 Task<TResult> 并返回结果。
- 达到 Timeout ，在这种情况下， Task<TResult> 将取消 。
- 将 CancellationToken 触发传递给某些方法重载的 。
- 调用 CancelPendingRequests()。
- HttpClient 已释放。
可以使用某些方法重载上可用的 参数更改 HttpCompletionOption 每个请求的缓冲行为。 此参数可用于指定 在仅读取响应标头后，还是在 Task<TResult> 读取和缓冲响应内容后，应将 视为已完成。
如果命名空间中使用 HttpClientSystem.Net.Http 和相关类的应用打算下载 (50 兆字节或更多) 的大量数据，则应用应流式传输这些下载内容，而不使用默认缓冲。 如果使用默认缓冲，客户端内存使用量将变得非常大，这可能会导致性能大幅下降。
线程安全
以下方法是线程安全的：
- CancelPendingRequests
- DeleteAsync
- GetAsync
- GetByteArrayAsync
- GetStreamAsync
- GetStringAsync
- PostAsync
- PutAsync
- SendAsync
代理
默认情况下，HttpClient 根据平台从环境变量或用户/系统设置读取代理配置。 可以通过按优先级顺序将 WebProxy 或 IWebProxy 传递给 来更改此行为：
- 在 Proxy HttpClient 构造过程中传入的 HttpClientHandler 上的 属性
- 静态 DefaultProxy 属性 (影响所有实例)
可以使用 禁用代理 UseProxy。 Windows 用户的默认配置是尝试使用网络发现来检测代理，这可能会很慢。 对于已知不需要代理的高吞吐量应用程序，应禁用代理。
仅应在使用 HttpClient 发出第一个请求之前更改代理设置 (（如 Credentials) ）。 首次使用 HttpClient 后所做的更改可能不会反映在后续请求中。
超时
可以使用 Timeout 为来自 HttpClient 实例的所有 HTTP 请求设置默认超时。 超时仅适用于导致启动请求/响应的 xxxAsync 方法。 如果达到超时， Task<TResult> 则取消该请求的 。
如果在构造 HttpClient 对象时传入 实例，则可以设置一 SocketsHttpHandler 些额外的超时：
| 属性 | 说明 |
|---|---|
| ConnectTimeout | 指定在请求要求创建新的 TCP 连接时使用的超时。 如果发生超时，请求 Task<TResult> 将被取消。 |
| PooledConnectionLifetime | 指定用于连接池中每个连接的超时。 如果连接处于空闲状态，则连接会立即关闭;否则，连接在当前请求结束时关闭。 |
| PooledConnectionIdleTimeout | 如果连接池中的连接长时间处于空闲状态，则连接将关闭。 |
| Expect100ContinueTimeout | 如果请求具有“Expect： 100-continue”标头，则会延迟发送内容，直到超时或收到“100-continue”响应。 |
HttpClient 仅在创建连接时解析 DNS 条目。 它不跟踪 DNS 服务器指定的任何生存时间 (TTL)。 如果 DNS 条目定期更改（在某些容器方案中可能发生），则可以使用 PooledConnectionLifetime 来限制连接的生存期，以便在替换连接时需要 DNS 查找。
构造函数
| HttpClient() |
使用释放此实例时释放的 HttpClientHandler 初始化 HttpClient 类的新实例。 |
| HttpClient(HttpMessageHandler) |
使用指定的处理程序初始化 HttpClient 类的新实例。 处理程序在释放此实例时被释放。 |
| HttpClient(HttpMessageHandler, Boolean) |
使用提供的处理程序初始化 HttpClient 类的新实例，并指定在释放此实例时是否应释放该处理程序。 |
属性
| BaseAddress |
获取或设置发送请求时使用的 Internet 资源的统一资源标识符 (URI) 的基址。 |
| DefaultProxy |
获取或设置全局 HTTP 代理。 |
| DefaultRequestHeaders |
获取与每个请求一起发送的标题。 |
| DefaultRequestVersion |
获取或设置对此 HttpClient 实例发出的后续请求使用的默认 HTTP 版本。 |
| DefaultVersionPolicy |
获取或设置便捷方法中隐式创建的请求的默认版本策略，例如 GetAsync(String) 和 PostAsync(String, HttpContent)。 |
| MaxResponseContentBufferSize |
获取或设置读取响应内容时要缓冲的最大字节数。 |
| Timeout |
获取或设置请求超时前等待的时间跨度。 |