HttpClient Класс

Определение

Предоставляет базовый класс для отправки HTTP-запросов и получения HTTP-ответов от ресурса с заданным URI.Provides a base class for sending HTTP requests and receiving HTTP responses from a resource identified by a URI.

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);
  }
}
' 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().The preceding code example uses an async Task Main() entry point. Для этого компонента C# требуется 7,1 или более поздняя версия.That feature requires C# 7.1 or later.

Комментарии

Экземпляр класса HttpClient выступает в качестве сеанса для отправки HTTP-запросов.The HttpClient class instance acts as a session to send HTTP requests. HttpClient экземпляр — это коллекция параметров, применяемых ко всем запросам, выполняемым этим экземпляром.An HttpClient instance is a collection of settings applied to all requests executed by that instance. Кроме того, каждый экземпляр HttpClient использует собственный пул соединений, изолируя его запросы от запросов, выполняемых другими экземплярами HttpClient.In addition, every HttpClient instance uses its own connection pool, isolating its requests from requests executed by other HttpClient instances.

HttpClient также выступает в качестве базового класса для более конкретных HTTP-клиентов.The HttpClient also acts as a base class for more specific HTTP clients. Примером может быть Фацебукхттпклиент, предоставляющий дополнительные методы, характерные для веб-службы Facebook (например, метод «друзья»).An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Производные классы не должны переопределять виртуальные методы класса.Derived classes should not override the virtual methods on the class. Вместо этого используйте перегрузку конструктора, которая принимает HttpMessageHandler для настройки обработки, выполняемой до или после запроса.Instead, use a constructor overload that accepts HttpMessageHandler to configure any pre- or post-request processing instead.

По умолчанию в .NET Framework и Mono HttpWebRequest используется для отправки запросов на сервер.By default on .NET Framework and Mono, HttpWebRequest is used to send requests to the server. Это поведение можно изменить, указав другой канал в одной из перегрузок конструктора, принимающих экземпляр HttpMessageHandler в качестве параметра.This behavior can be modified by specifying a different channel in one of the constructor overloads taking a HttpMessageHandler instance as parameter. Если требуются такие функции, как проверка подлинности или кэширование, WebRequestHandler можно использовать для настройки параметров, и экземпляр можно передать в конструктор.If features like authentication or caching are required, WebRequestHandler can be used to configure settings and the instance can be passed to the constructor. Возвращаемый обработчик может быть передан в одну из перегрузок конструктора, принимающих параметр HttpMessageHandler.The returned handler can be passed to one of the constructor overloads taking a HttpMessageHandler parameter.

Если приложение, использующее HttpClient и связанные классы в пространстве имен System.Net.Http, планирует загружать большие объемы данных (50 МБ или более), приложение должно выполнять потоковую передачу этих файлов и не использовать буферизацию по умолчанию.If an app using HttpClient and related classes in the System.Net.Http namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. Если используется буферизация по умолчанию, использование памяти клиента будет очень большим, что может привести к значительному снижению производительности.If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance.

Следующие методы являются потокобезопасными:The following methods are thread safe:

  1. CancelPendingRequests

  2. DeleteAsync

  3. GetAsync

  4. GetByteArrayAsync

  5. GetStreamAsync

  6. GetStringAsync

  7. PostAsync

  8. PutAsync

  9. SendAsync

HttpClient предназначено для однократного создания и повторного использования в течение всего жизненного цикла приложения.HttpClient is intended to be instantiated once and re-used throughout the life of an application. При создании экземпляра класса HttpClient для каждого запроса будет исчерпано количество сокетов, доступных при высоких нагрузках.Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. Это приведет к ошибкам SocketException.This will result in SocketException errors. Ниже приведен пример, использующий HttpClient правильно.Below is an example using HttpClient correctly.

public class GoodController : ApiController
{
    private static readonly HttpClient HttpClient;

    static GoodController()
    {
        HttpClient = new HttpClient();
    }
}
  Public Class GoodController
    Inherits ApiController  
   
    Private Shared ReadOnly HttpClient As HttpClient  
  
    Shared Sub New()  
        HttpClient = New HttpClient()
    End Sub
End Class

HttpClient представляет собой высокоуровневый интерфейс API, который упаковывает функциональные возможности нижнего уровня, доступные на каждой платформе, где она выполняется.The HttpClient is a high-level API that wraps the lower-level functionality available on each platform where it runs.

На каждой платформе HttpClient пытается использовать оптимальный доступный транспорт:On each platform, HttpClient tries to use the best available transport:

Узел/Среда выполненияHost/Runtime ФоновBackend
Windows/. NET FrameworkWindows/.NET Framework HttpWebRequest
Windows/MonoWindows/Mono HttpWebRequest
Windows/UWPWindows/UWP Машинный WinHttpHandler Windows (поддерживается HTTP 2,0)Windows native WinHttpHandler (HTTP 2.0 capable)
Windows/. NET Core 1.0 — 2.0Windows/.NET Core 1.0-2.0 Машинный WinHttpHandler Windows (поддерживается HTTP 2,0)Windows native WinHttpHandler (HTTP 2.0 capable)
Android или XamarinAndroid/Xamarin Выбирается во время сборки.Selected at build-time. Можно использовать HttpWebRequest или настроить для использования собственного HttpURLConnection AndroidCan either use HttpWebRequest or be configured to use Android's native HttpURLConnection
iOS, tvOS, watchOS/XamariniOS, tvOS, watchOS/Xamarin Выбирается во время сборки.Selected at build-time. Можно использовать HttpWebRequest или настроить для использования NSUrlSession Apple (с поддержкой HTTP 2,0).Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/XamarinmacOS/Xamarin Выбирается во время сборки.Selected at build-time. Можно использовать HttpWebRequest или настроить для использования NSUrlSession Apple (с поддержкой HTTP 2,0).Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/MonomacOS/Mono HttpWebRequest
macOS/. NET Core 1.0 — 2.0macOS/.NET Core 1.0-2.0 HTTP-транспорт на основе libcurl(поддерживается HTTP 2,0)libcurl-based HTTP transport (HTTP 2.0 capable)
Linux/MonoLinux/Mono HttpWebRequest
Linux/. NET Core 1.0 — 2.0Linux/.NET Core 1.0-2.0 HTTP-транспорт на основе libcurl(поддерживается HTTP 2,0)libcurl-based HTTP transport (HTTP 2.0 capable)
.NET Core 2,1 и более поздние версии.NET Core 2.1 and later System.Net.Http.SocketsHttpHandler

Пользователи также могут настроить конкретный транспорт для HttpClient, вызвав конструктор HttpClient, который принимает HttpMessageHandler.Users can also configure a specific transport for HttpClient by invoking the HttpClient constructor that takes an HttpMessageHandler.

HttpClient и .NET CoreHttpClient and .NET Core

Начиная с .NET Core 2,1 класс System.Net.Http.SocketsHttpHandler, а не HttpClientHandler предоставляет реализацию, используемую сетевыми классами HTTP более высокого уровня, такими как HttpClient.Starting with .NET Core 2.1, the System.Net.Http.SocketsHttpHandler class instead of HttpClientHandler provides the implementation used by higher-level HTTP networking classes such as HttpClient. Использование SocketsHttpHandler предлагает ряд преимуществ.The use of SocketsHttpHandler offers a number of advantages:

  • Значительное улучшение производительности по сравнению с предыдущей реализацией.A significant performance improvement when compared with the previous implementation.

  • Исключение зависимостей платформы, которое упрощает развертывание и обслуживание.The elimination of platform dependencies, which simplifies deployment and servicing. Например, libcurl больше не является зависимостью от .NET Core для macOS и .NET Core для Linux.For example, libcurl is no longer a dependency on .NET Core for macOS and .NET Core for Linux.

  • Согласованное поведение на всех платформах .NET.Consistent behavior across all .NET platforms.

Если это изменение нежелательно, можно настроить приложение так, чтобы оно использовало более старую System.Net.Http.HttpClientHandler, а не несколько способов.If this change is undesirable, you can configure your application to use the older System.Net.Http.HttpClientHandler instead in a number of ways:

  • Вызвав метод AppContext.SetSwitch следующим образом:By calling the AppContext.SetSwitch method as follows:

    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
    
    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False)
    
  • Определив параметр System.Net.Http.UseSocketsHttpHandler в файле конфигурации . netcore. runtimeconfig. JSON :By defining the System.Net.Http.UseSocketsHttpHandler switch in the .netcore.runtimeconfig.json configuration file:

    "runtimeOptions": {
      "configProperties": {
          "System.Net.Http.UseSocketsHttpHandler": false
      }
    }
    
  • Определив переменную среды с именем DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER и задав для нее значение false или 0.By defining an environment variable named DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER and setting it to either false or 0.

Конструкторы

HttpClient()

Инициализирует новый экземпляр класса HttpClient, используя HttpClientHandler, который удаляется при удалении этого экземпляра.Initializes a new instance of the HttpClient class using a HttpClientHandler that is disposed when this instance is disposed.

HttpClient(HttpMessageHandler)

Инициализирует новый экземпляр класса HttpClient с указанным обработчиком.Initializes a new instance of the HttpClient class with the specified handler. Обработчик удаляется при удалении этого экземпляра.The handler is disposed when this instance is disposed.

HttpClient(HttpMessageHandler, Boolean)

Инициализирует новый экземпляр класса HttpClient с предоставленным обработчиком и указывает, должен ли этот обработчик удаляться при удалении этого экземпляра.Initializes a new instance of the HttpClient class with the provided handler, and specifies whether that handler should be disposed when this instance is disposed.

Свойства

BaseAddress

Получает или задает базовый адрес универсального кода ресурса (URI) интернет-ресурса, используемого при отправке запросов.Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests.

DefaultProxy

Возвращает или устанавливает глобальный прокси-сервер HTTP.Gets or sets the global Http proxy.

DefaultRequestHeaders

Получает заголовки для отправки в каждом запросе.Gets the headers which should be sent with each request.

DefaultRequestVersion

Возвращает или задает версию HTTP по умолчанию, используемую в последующих запросах, выполняемых этим экземпляром HttpClient.Gets or sets the default HTTP version used on subsequent requests made by this HttpClient instance.

MaxResponseContentBufferSize

Получает или задает максимальное количество байтов, помещаемых в буфер при чтении содержимого ответа.Gets or sets the maximum number of bytes to buffer when reading the response content.

Timeout

Возвращает или задает время ожидания для выполнения запроса.Gets or sets the timespan to wait before the request times out.

Методы

CancelPendingRequests()

Отмена всех ожидающих запросов к данному экземпляру.Cancel all pending requests on this instance.

DeleteAsync(String)

Отправка запроса DELETE согласно указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(String, CancellationToken)

Отправка запроса DELETE к указанному URI с токеном отмены в качестве асинхронной операции.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

DeleteAsync(Uri)

Отправка запроса DELETE согласно указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(Uri, CancellationToken)

Отправка запроса DELETE к указанному URI с токеном отмены в качестве асинхронной операции.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

Dispose()

Освобождает неуправляемые ресурсы и удаляет управляемые ресурсы, используемые объектом HttpMessageInvoker.Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageInvoker.

(Унаследовано от HttpMessageInvoker)
Dispose(Boolean)

Освобождает неуправляемые ресурсы, используемые объектом HttpClient, и опционально удаляет управляемые ресурсы.Releases the unmanaged resources used by the HttpClient and optionally disposes of the managed resources.

Equals(Object)

Определяет, равен ли указанный объект текущему объекту.Determines whether the specified object is equal to the current object.

(Унаследовано от Object)
GetAsync(String)

Отправка запроса GET согласно указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(String, CancellationToken)

Отправка запроса DELETE указанному универсальному коду ресурса (URI) с токеном отмены в качестве асинхронной операции.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(String, HttpCompletionOption)

Отправка запроса GET указанному универсальному коду ресурса (URI) с параметром "выполнение HTTP" в качестве асинхронной операции.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(String, HttpCompletionOption, CancellationToken)

Отправка запроса GET к указанному универсальному коду ресурса (URI) с параметром "выполнение HTTP" и токеном отмены в качестве асинхронной операции.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetAsync(Uri)

Отправка запроса GET согласно указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(Uri, CancellationToken)

Отправка запроса DELETE указанному универсальному коду ресурса (URI) с токеном отмены в качестве асинхронной операции.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption)

Отправка запроса GET указанному универсальному коду ресурса (URI) с параметром "выполнение HTTP" в качестве асинхронной операции.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption, CancellationToken)

Отправка запроса GET к указанному универсальному коду ресурса (URI) с параметром "выполнение HTTP" и токеном отмены в качестве асинхронной операции.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetByteArrayAsync(String)

Отправляет запрос GET согласно указанному универсальному коду ресурса (URI) и возвращает текст ответа в виде массива байтов в асинхронной операции.Sends a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetByteArrayAsync(Uri)

Отправка запроса GET согласно указанному универсальному коду ресурса (URI) и возврат текста ответа в виде массива байтов в асинхронной операции.Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetHashCode()

Служит в качестве хэш-функции по умолчанию.Serves as the default hash function.

(Унаследовано от Object)
GetStreamAsync(String)

Отправка запроса GET согласно указанному универсальному коду ресурса (URI) и возврат текста ответа в виде потока в асинхронной операции.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStreamAsync(Uri)

Отправка запроса GET согласно указанному универсальному коду ресурса (URI) и возврат текста ответа в виде потока в асинхронной операции.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStringAsync(String)

Отправка запроса GET согласно указанному универсальному коду ресурса (URI) и возврат текста ответа в виде строки в асинхронной операции.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetStringAsync(Uri)

Отправка запроса GET согласно указанному универсальному коду ресурса (URI) и возврат текста ответа в виде строки в асинхронной операции.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetType()

Возвращает объект Type для текущего экземпляра.Gets the Type of the current instance.

(Унаследовано от Object)
MemberwiseClone()

Создает неполную копию текущего объекта Object.Creates a shallow copy of the current Object.

(Унаследовано от Object)
PatchAsync(String, HttpContent)

Асинхронно отправляет запрос PATCH к универсальному коду ресурса (URI), заданному в виде строки.Sends a PATCH request to a Uri designated as a string as an asynchronous operation.

PatchAsync(String, HttpContent, CancellationToken)

Асинхронно отправляет запрос PATCH с токеном отмены к универсальному коду ресурса (URI), представленному строкой.Sends a PATCH request with a cancellation token to a Uri represented as a string as an asynchronous operation.

PatchAsync(Uri, HttpContent)

Отправляет запрос PATCH в качестве асинхронной операции.Sends a PATCH request as an asynchronous operation.

PatchAsync(Uri, HttpContent, CancellationToken)

Отправляет запрос PATCH с токеном отмены в качестве асинхронной операции.Sends a PATCH request with a cancellation token as an asynchronous operation.

PostAsync(String, HttpContent)

Отправка запроса POST по указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(String, HttpContent, CancellationToken)

Отправка запроса POST с токеном отмены в качестве асинхронной операции.Send a POST request with a cancellation token as an asynchronous operation.

PostAsync(Uri, HttpContent)

Отправка запроса POST по указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(Uri, HttpContent, CancellationToken)

Отправка запроса POST с токеном отмены в качестве асинхронной операции.Send a POST request with a cancellation token as an asynchronous operation.

PutAsync(String, HttpContent)

Отправка запроса PUT по указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(String, HttpContent, CancellationToken)

Отправка запроса PUT с токеном отмены в качестве асинхронной операции.Send a PUT request with a cancellation token as an asynchronous operation.

PutAsync(Uri, HttpContent)

Отправка запроса PUT по указанному универсальному коду ресурса (URI) в качестве асинхронной операции.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(Uri, HttpContent, CancellationToken)

Отправка запроса PUT с токеном отмены в качестве асинхронной операции.Send a PUT request with a cancellation token as an asynchronous operation.

SendAsync(HttpRequestMessage)

Отправка HTTP-запроса в качестве асинхронной операции.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, CancellationToken)

Отправка HTTP-запроса в качестве асинхронной операции.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption)

Отправка HTTP-запроса в качестве асинхронной операции.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

Отправка HTTP-запроса в качестве асинхронной операции.Send an HTTP request as an asynchronous operation.

ToString()

Возвращает строку, представляющую текущий объект.Returns a string that represents the current object.

(Унаследовано от Object)

Применяется к

Дополнительно