HttpClient 类

定义

public ref class HttpClient : System::Net::Http::HttpMessageInvoker

public class HttpClient : System.Net.Http.HttpMessageInvoker

type HttpClient = class
    inherit HttpMessageInvoker

Public Class HttpClient
Inherits HttpMessageInvoker

继承

Object

HttpMessageInvoker

HttpClient

示例

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

注解

类 HttpClient 实例充当发送 HTTP 请求的会话。 HttpClient实例是应用于该实例执行的所有请求的设置集合。 此外，每个 HttpClient 实例都使用自己的连接池，将请求与其他实例执行 HttpClient 的请求隔离开来。

Instancing

HttpClient 旨在实例化一次，并在应用程序的整个生命周期内重复使用。 在 .NET Core 和 .NET 5+ 中，HttpClient 在处理程序实例内池化连接，并在多个请求之间重用连接。 如果为每个请求实例化一个 HttpClient 类，在高负载下可用的套接字数将会耗尽。 如果耗尽，将导致 SocketException 错误。

可以在构造函数中传入一个“处理程序”，例如 HttpClientHandler（或在 .NET Core 2.1 或更高版本中使用 SocketsHttpHandler），以配置其他选项。 提交请求后，无法更改处理程序上的连接属性，因此，如果需要更改连接属性，则创建新 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 的构造函数重载来配置任何预请求或请求后处理。

Transports

HttpClient这是一个高级 API，用于包装其运行的每个平台上可用的较低级别功能。

在每个平台上， HttpClient 尝试使用最佳可用传输：

用户还可以通过调用接受 HttpClient 的 HttpClient 构造函数为 HttpMessageHandler 配置特定传输。

.NET Framework 和 Mono

默认情况下，在 .NET Framework 和 Mono 上， HttpWebRequest 用于将请求发送到服务器。 可以通过使用 HttpMessageHandler 参数在构造函数重载之一中指定不同的处理程序来修改此行为。 如果需要身份验证或缓存等功能，则可以用于 WebRequestHandler 配置设置，实例可以传递给构造函数。 返回的处理程序可以传递给具有 HttpMessageHandler 参数的构造函数重载。

.NET 核心

从 .NET Core 2.1 开始， System.Net.Http.SocketsHttpHandler 该类而不是 HttpClientHandler 提供更高级别的 HTTP 网络类（例如 HttpClient）使用的实现。 使用 SocketsHttpHandler 提供了许多优势：

• 对照以前的实现，可以看到显著的性能改进。
• 消除平台依赖项，从而简化了部署和服务。 例如， libcurl 不再依赖于适用于 macOS 的 .NET Core 和适用于 Linux 的 .NET Core。
• 在所有 .NET 平台中一致的行为。

如果你认为此更改不可取，可以在 Windows 上通过引用WinHttpHandler并手动将其传递给HttpClient 的构造函数来继续使用。

使用运行时配置选项配置行为

某些方面 HttpClient的行为可通过 运行时配置选项进行自定义。 但是，这些开关的行为因 .NET 版本而异。 例如，在 .NET Core 2.1 - 3.1 中，可以配置是否 SocketsHttpHandler 默认使用，但从 .NET 5 开始，该选项不再可用。

连接池

HttpClient 尽可能使用连接池管理 HTTP 连接，并将它们用于多个请求。 这可以具有明显的性能优势，尤其是对于 HTTPS 请求，因为连接握手过程仅执行一次。

可以在构造过程中传入的 HttpClientHandler 或 SocketsHttpHandler 上配置连接池属性，包括 MaxConnectionsPerServer、PooledConnectionIdleTimeout 和 PooledConnectionLifetime。

销毁 HttpClient 实例会关闭已建立的连接并取消任何挂起的请求。

缓冲和请求生存期

默认情况下， 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 构建过程中传入 HttpClientHandler 的 HttpClient 属性
• DefaultProxy静态属性（影响所有实例）

可以使用 UseProxy 禁用代理。 Windows 用户的默认配置是尝试并使用网络发现来检测代理，这可能很慢。 对于已知不需要代理的高吞吐量应用程序，应禁用代理。

只有在使用Credentials第一个请求之前，才应更改代理设置（例如HttpClient）。 首次使用 HttpClient 后所做的更改可能不会反映在后续请求中。

Timeouts

你可以使用 Timeout 为 HttpClient 实例中的所有 HTTP 请求设置默认超时。 超时仅适用于导致启动请求/响应的 xxxAsync 方法。 如果达到超时，针对该请求的 Task<TResult> 将被取消。

在构造SocketsHttpHandler对象时，如果传入一个HttpClient实例，可以设置一些额外的超时时间。

HttpClient 仅在创建连接时解析 DNS 条目。 它不会跟踪由 DNS 服务器指定的任何生存时间 (TTL) 时长。 如果 DNS 条目频繁更改，这可能发生在某些容器场景中，你可以使用 PooledConnectionLifetime 来限制连接的生存期，这样在替换连接时就需要重新进行 DNS 查找。

另请参阅

• HttpClient 的使用准则
• HttpClient 示例