HttpClient 类

定义

提供一个类,用于发送 HTTP 请求并从 URI 标识的资源接收 HTTP 响应。

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

示例

// 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	
  {
     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
            let! 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
        Dim 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)
    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 支持 HTTP 2.0 的本机 (Windows) WinHttpHandler
Windows/.NET Core 1.0-2.0 支持 HTTP 2.0 的本机 (Windows) WinHttpHandler
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不再依赖于适用于 macOS 的 .NET Core 和适用于 Linux 的 .NET Core。
  • 在所有 .NET 平台上的一致行为。

如果此更改不可取,Windows可以通过引用其NuGet包并将其手动传递给 HttpClient 的构造函数WinHttpHandler继续使用。

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

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

连接池

HttpClient 尽可能池 HTTP 连接,并将它们用于多个请求。 这可以具有显著的性能优势,尤其是对于 HTTPS 请求,因为连接握手仅完成一次。

连接池属性可以在构造期间配置 HttpClientHandlerSocketsHttpHandler 传入,包括 MaxConnectionsPerServerPooledConnectionIdleTimeoutPooledConnectionLifetime

释放 HttpClient 实例会关闭打开的连接并取消任何挂起的请求。

备注

如果将 HTTP/1.1 请求并发发送到同一服务器,则可以创建新连接。 即使重复使用 HttpClient 实例,如果请求速率很高,或者存在任何防火墙限制,由于默认 TCP 清理计时器,可能会耗尽可用套接字。 若要限制并发连接数,可以设置属性 MaxConnectionsPerServer 。 默认情况下,并发 HTTP/1.1 连接数不受限制。

缓冲和请求生存期

默认情况下,HttpClient 方法 (,) GetStreamAsync 缓冲来自服务器的响应,在返回异步结果之前将所有响应正文读取到内存中。 这些请求将继续,直到发生以下情况之一:

可以使用某些方法重载上可用的参数,根据 HttpCompletionOption 每个请求更改缓冲行为。 此参数可用于指定在仅读取响应标头后或读取和缓冲响应内容后是否 Task<TResult> 应被视为完成。

如果命名空间中使用System.Net.Http和相关类的应用HttpClient打算下载大量数据, (50 兆字节或更多) ,则应用应流式传输这些下载,而不使用默认缓冲。 如果使用默认缓冲,则客户端内存使用率将非常大,这可能会导致性能大幅降低。

线程安全

以下方法是线程安全的:

代理

默认情况下,HttpClient 根据平台从环境变量或用户/系统设置读取代理配置。 可以通过按优先级顺序传递 WebProxyIWebProxy 传递给此行为:

  • Proxy HttpClientHandler 在 HttpClient 构造过程中传入的属性
  • DefaultProxy静态属性 (会影响所有实例)

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

超时

可用于 Timeout 为来自 HttpClient 实例的所有 HTTP 请求设置默认超时。 超时仅适用于导致启动请求/响应的 xxxAsync 方法。 如果达到超时,则会 Task<TResult> 取消该请求。

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

属性 说明
ConnectTimeout 指定在请求需要创建新的 TCP 连接时使用的超时。 如果发生超时,将取消请求 Task<TResult>
PooledConnectionLifetime 指定要用于连接池中每个连接的超时值。 如果连接处于空闲状态,则连接会立即关闭;否则,连接在当前请求结束时关闭。
PooledConnectionIdleTimeout 如果连接池中的连接长时间处于空闲状态,则连接将关闭。
Expect100ContinueTimeout 如果请求具有“预期: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

获取或设置请求超时前等待的时间跨度。

方法

CancelPendingRequests()

取消该实例所有挂起的请求。

DeleteAsync(String)

以异步操作将 DELETE 请求发送给指定 URI。

DeleteAsync(String, CancellationToken)

用以异步操作的取消标记发送 DELETE 请求到指定的 URI。

DeleteAsync(Uri)

以异步操作将 DELETE 请求发送给指定 URI。

DeleteAsync(Uri, CancellationToken)

用以异步操作的取消标记发送 DELETE 请求到指定的 URI。

Dispose()

释放由 HttpMessageInvoker 使用的非托管资源和托管资源。

(继承自 HttpMessageInvoker)
Dispose(Boolean)

释放由 HttpClient 使用的非托管资源,并可根据需要释放托管资源。

Equals(Object)

确定指定对象是否等于当前对象。

(继承自 Object)
GetAsync(String)

以异步操作将 GET 请求发送给指定 URI。

GetAsync(String, CancellationToken)

用以异步操作的取消标记发送 GET 请求到指定的 URI。

GetAsync(String, HttpCompletionOption)

用以异步操作的 HTTP 完成选项发送 GET 请求到指定的 URI。

GetAsync(String, HttpCompletionOption, CancellationToken)

用以异步操作的 HTTP 完成选项和取消标记发送 GET 请求到指定的 URI。

GetAsync(Uri)

以异步操作将 GET 请求发送给指定 URI。

GetAsync(Uri, CancellationToken)

用以异步操作的取消标记发送 GET 请求到指定的 URI。

GetAsync(Uri, HttpCompletionOption)

用以异步操作的 HTTP 完成选项发送 GET 请求到指定的 URI。

GetAsync(Uri, HttpCompletionOption, CancellationToken)

用以异步操作的 HTTP 完成选项和取消标记发送 GET 请求到指定的 URI。

GetByteArrayAsync(String)

将 GET 请求发送到指定 URI 并在异步操作中以字节数组的形式返回响应正文。

GetByteArrayAsync(String, CancellationToken)

将 GET 请求发送到指定 URI 并在异步操作中以字节数组的形式返回响应正文。

GetByteArrayAsync(Uri)

将 GET 请求发送到指定 URI 并在异步操作中以字节数组的形式返回响应正文。

GetByteArrayAsync(Uri, CancellationToken)

将 GET 请求发送到指定 URI 并在异步操作中以字节数组的形式返回响应正文。

GetHashCode()

作为默认哈希函数。

(继承自 Object)
GetStreamAsync(String)

将 GET 请求发送到指定 URI 并在异步操作中以流的形式返回响应正文。

GetStreamAsync(String, CancellationToken)

将 GET 请求发送到指定 URI 并在异步操作中以流的形式返回响应正文。

GetStreamAsync(Uri)

将 GET 请求发送到指定 URI 并在异步操作中以流的形式返回响应正文。

GetStreamAsync(Uri, CancellationToken)

将 GET 请求发送到指定 URI 并在异步操作中以流的形式返回响应正文。

GetStringAsync(String)

将 GET 请求发送到指定 URI 并在异步操作中以字符串的形式返回响应正文。

GetStringAsync(String, CancellationToken)

将 GET 请求发送到指定 URI 并在异步操作中以字符串的形式返回响应正文。

GetStringAsync(Uri)

将 GET 请求发送到指定 URI 并在异步操作中以字符串的形式返回响应正文。

GetStringAsync(Uri, CancellationToken)

将 GET 请求发送到指定 URI 并在异步操作中以字符串的形式返回响应正文。

GetType()

获取当前实例的 Type

(继承自 Object)
MemberwiseClone()

创建当前 Object 的浅表副本。

(继承自 Object)
PatchAsync(String, HttpContent)

以异步操作方式将 PATCH 请求发送到指定为字符串的 URI。

PatchAsync(String, HttpContent, CancellationToken)

以异步操作方式将带有取消令牌的 PATCH 请求发送到表示为字符串的 URI。

PatchAsync(Uri, HttpContent)

以异步操作方式发送 PATCH 请求。

PatchAsync(Uri, HttpContent, CancellationToken)

以异步操作方式发送带有取消令牌的 PATCH 请求。

PostAsync(String, HttpContent)

以异步操作将 POST 请求发送给指定 URI。

PostAsync(String, HttpContent, CancellationToken)

用以异步操作的取消标记发送 POST 请求。

PostAsync(Uri, HttpContent)

以异步操作将 POST 请求发送给指定 URI。

PostAsync(Uri, HttpContent, CancellationToken)

用以异步操作的取消标记发送 POST 请求。

PutAsync(String, HttpContent)

以异步操作将 PUT 请求发送给指定 URI。

PutAsync(String, HttpContent, CancellationToken)

用以异步操作的取消标记发送 PUT 请求。

PutAsync(Uri, HttpContent)

以异步操作将 PUT 请求发送给指定 URI。

PutAsync(Uri, HttpContent, CancellationToken)

用以异步操作的取消标记发送 PUT 请求。

Send(HttpRequestMessage)

发送带有指定请求的 HTTP 请求。

Send(HttpRequestMessage, CancellationToken)

发送带有指定请求和取消标记的 HTTP 请求。

Send(HttpRequestMessage, CancellationToken)

发送带有指定请求和取消标记的 HTTP 请求。

(继承自 HttpMessageInvoker)
Send(HttpRequestMessage, HttpCompletionOption)

发送 HTTP 请求。

Send(HttpRequestMessage, HttpCompletionOption, CancellationToken)

发送带有指定请求、完成选项和取消标记的 HTTP 请求。

SendAsync(HttpRequestMessage)

以异步操作发送 HTTP 请求。

SendAsync(HttpRequestMessage, CancellationToken)

以异步操作发送 HTTP 请求。

SendAsync(HttpRequestMessage, HttpCompletionOption)

以异步操作发送 HTTP 请求。

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

以异步操作发送 HTTP 请求。

ToString()

返回表示当前对象的字符串。

(继承自 Object)

扩展方法

GetFromJsonAsync(HttpClient, String, Type, JsonSerializerOptions, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync(HttpClient, String, Type, JsonSerializerContext, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync(HttpClient, String, Type, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync(HttpClient, Uri, Type, JsonSerializerOptions, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync(HttpClient, Uri, Type, JsonSerializerContext, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync(HttpClient, Uri, Type, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync<TValue>(HttpClient, String, JsonSerializerOptions, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync<TValue>(HttpClient, String, JsonTypeInfo<TValue>, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync<TValue>(HttpClient, String, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync<TValue>(HttpClient, Uri, JsonSerializerOptions, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync<TValue>(HttpClient, Uri, JsonTypeInfo<TValue>, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

GetFromJsonAsync<TValue>(HttpClient, Uri, CancellationToken)

将 GET 请求发送到指定 URI,并在异步操作中以 JSON 形式返回反序列化响应正文生成的值。

PatchAsJsonAsync<TValue>(HttpClient, String, TValue, JsonSerializerOptions, CancellationToken)

将 PATCH 请求发送到指定的 URI,其中包含 value 在请求正文中序列化为 JSON 的 URI。

PatchAsJsonAsync<TValue>(HttpClient, String, TValue, JsonTypeInfo<TValue>, CancellationToken)

将 PATCH 请求发送到指定的 URI,其中包含 value 在请求正文中序列化为 JSON 的 URI。

PatchAsJsonAsync<TValue>(HttpClient, String, TValue, CancellationToken)

将 PATCH 请求发送到指定的 URI,其中包含在 value 请求正文中序列化为 JSON 的 URI。

PatchAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonSerializerOptions, CancellationToken)

将 PATCH 请求发送到指定的 URI,其中包含 value 在请求正文中序列化为 JSON 的 URI。

PatchAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonTypeInfo<TValue>, CancellationToken)

将 PATCH 请求发送到指定的 URI,其中包含 value 在请求正文中序列化为 JSON 的 URI。

PatchAsJsonAsync<TValue>(HttpClient, Uri, TValue, CancellationToken)

将 PATCH 请求发送到指定的 URI,其中包含 value 在请求正文中序列化为 JSON 的 URI。

PostAsJsonAsync<TValue>(HttpClient, String, TValue, JsonSerializerOptions, CancellationToken)

将 POST 请求发送到指定 URI,该 URI 包含请求正文中序列化为 JSON 的 value

PostAsJsonAsync<TValue>(HttpClient, String, TValue, JsonTypeInfo<TValue>, CancellationToken)

将 POST 请求发送到指定 URI,该 URI 包含请求正文中序列化为 JSON 的 value

PostAsJsonAsync<TValue>(HttpClient, String, TValue, CancellationToken)

将 POST 请求发送到指定 URI,该 URI 包含请求正文中序列化为 JSON 的 value

PostAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonSerializerOptions, CancellationToken)

将 POST 请求发送到指定 URI,该 URI 包含请求正文中序列化为 JSON 的 value

PostAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonTypeInfo<TValue>, CancellationToken)

将 POST 请求发送到指定 URI,该 URI 包含请求正文中序列化为 JSON 的 value

PostAsJsonAsync<TValue>(HttpClient, Uri, TValue, CancellationToken)

将 POST 请求发送到指定 URI,该 URI 包含请求正文中序列化为 JSON 的 value

PutAsJsonAsync<TValue>(HttpClient, String, TValue, JsonSerializerOptions, CancellationToken)

将 PUT 请求发送到指定 URI,该 URI 包含在请求正文中序列化为 JSON 的 value

PutAsJsonAsync<TValue>(HttpClient, String, TValue, JsonTypeInfo<TValue>, CancellationToken)

将 PUT 请求发送到指定 URI,该 URI 包含在请求正文中序列化为 JSON 的 value

PutAsJsonAsync<TValue>(HttpClient, String, TValue, CancellationToken)

将 PUT 请求发送到指定 URI,该 URI 包含在请求正文中序列化为 JSON 的 value

PutAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonSerializerOptions, CancellationToken)

将 PUT 请求发送到指定 URI,该 URI 包含在请求正文中序列化为 JSON 的 value

PutAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonTypeInfo<TValue>, CancellationToken)

将 PUT 请求发送到指定 URI,该 URI 包含在请求正文中序列化为 JSON 的 value

PutAsJsonAsync<TValue>(HttpClient, Uri, TValue, CancellationToken)

将 PUT 请求发送到指定 URI,该 URI 包含在请求正文中序列化为 JSON 的 value

适用于

另请参阅