HttpClient HttpClient HttpClient HttpClient Class

Definição

Fornece uma classe base para enviar solicitações HTTP e receber respostas HTTP de um recurso identificado por um 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
Herança

Exemplos

static async Task Main()
{
   // Create a New HttpClient object and dispose it when done, so the app doesn't leak resources
   using (HttpClient client = new HttpClient())
   {
      // 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);
      }
   }
}

O exemplo de código anterior usa um async Task Main() ponto de entrada.The preceding code example uses an async Task Main() entry point. Esse recurso requer o c# 7.1 ou posterior.That feature requires C# 7.1 or later.

Comentários

O HttpClient instância da classe atua como uma sessão para enviar solicitações HTTP.The HttpClient class instance acts as a session to send HTTP requests. Um HttpClient instância é uma coleção de configurações aplicadas a todas as solicitações executadas por essa instância.An HttpClient instance is a collection of settings applied to all requests executed by that instance. Além disso, cada HttpClient instância usa seu próprio pool de conexão, isolar suas solicitações de solicitações executadas por outros HttpClient instâncias.In addition, every HttpClient instance uses its own connection pool, isolating its requests from requests executed by other HttpClient instances.

O HttpClient também atua como uma classe base para os clientes HTTP mais específicos.The HttpClient also acts as a base class for more specific HTTP clients. Um exemplo seria um FacebookHttpClient fornecendo métodos adicionais específicos a um serviço web de Facebook (um método GetFriends, por exemplo).An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Classes derivadas não devem substituir os métodos virtuais na classe.Derived classes should not override the virtual methods on the class. Em vez disso, use uma sobrecarga de construtor que aceita HttpMessageHandler para configurar qualquer script pré ou pós-solicitação de processamento em vez disso.Instead, use a constructor overload that accepts HttpMessageHandler to configure any pre- or post-request processing instead.

Por padrão no .NET Framework e Mono, HttpWebRequest é usado para enviar solicitações ao servidor.By default on .NET Framework and Mono, HttpWebRequest is used to send requests to the server. Esse comportamento pode ser modificado com a especificação de um canal diferente em uma das sobrecargas de construtor levando um HttpMessageHandler instância como parâmetro.This behavior can be modified by specifying a different channel in one of the constructor overloads taking a HttpMessageHandler instance as parameter. Se recursos como autenticação ou armazenamento em cache forem necessários, WebRequestHandler pode ser usado para definir as configurações e instância podem ser passados para o construtor.If features like authentication or caching are required, WebRequestHandler can be used to configure settings and the instance can be passed to the constructor. O manipulador retornado pode ser passado para uma das sobrecargas de construtor levando um HttpMessageHandler parâmetro.The returned handler can be passed to one of the constructor overloads taking a HttpMessageHandler parameter.

Se um aplicativo usando HttpClient e classes relacionadas no System.Net.Http namespace pretende baixar grandes quantidades de dados (50 megabytes ou mais), em seguida, o aplicativo deve transmitir esses downloads e não usar o armazenamento em buffer padrão.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. Se o armazenamento em buffer padrão é usado o uso de memória do cliente obterá muito grande, possivelmente resultando em substancialmente o desempenho reduzido.If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance.

Os seguintes métodos são thread-safe: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 destina-se a ser instanciado uma vez e reutilizadas em toda a vida útil de um aplicativo.HttpClient is intended to be instantiated once and re-used throughout the life of an application. Criando uma instância de uma classe HttpClient para cada solicitação irá esgotar o número de soquetes disponíveis com cargas pesadas.Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. Isso resultará em erros SocketException.This will result in SocketException errors. Abaixo está um exemplo usando HttpClient corretamente.Below is an example using HttpClient correctly.

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

    static GoodController()
    {
        HttpClient = new HttpClient();
    }
}

O HttpClient é uma API de alto nível que encapsula a funcionalidade de baixo nível disponível em cada plataforma, onde ele é executado.The HttpClient is a high-level API that wraps the lower-level functionality available on each platform where it runs.

Em cada plataforma, HttpClient tenta usar o transporte melhor:On each platform, HttpClient tries to use the best available transport:

Host/RuntimeHost/Runtime BackendBackend
Windows/.NET FrameworkWindows/.NET Framework HttpWebRequest
Windows/MonoWindows/Mono HttpWebRequest
Windows/UWPWindows/UWP Windows nativo WinHttpHandler (HTTP 2.0 compatível com)Windows native WinHttpHandler (HTTP 2.0 capable)
Windows/.NET Core 1.0-2.0Windows/.NET Core 1.0-2.0 Windows nativo WinHttpHandler (HTTP 2.0 compatível com)Windows native WinHttpHandler (HTTP 2.0 capable)
Android/XamarinAndroid/Xamarin Selecionada no momento da compilação.Selected at build-time. Pode usar HttpWebRequest ou ser configurado para usar nativa do Android HttpURLConnectionCan either use HttpWebRequest or be configured to use Android's native HttpURLConnection
iOS, tvOS, watchOS/XamariniOS, tvOS, watchOS/Xamarin Selecionada no momento da compilação.Selected at build-time. Pode usar HttpWebRequest ou ser configurado para usar da Apple NSUrlSession (HTTP 2.0 compatível com)Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/XamarinmacOS/Xamarin Selecionada no momento da compilação.Selected at build-time. Pode usar HttpWebRequest ou ser configurado para usar da Apple NSUrlSession (HTTP 2.0 compatível com)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 libcurl-com base em transporte HTTP (HTTP 2.0 compatível com)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 libcurl-com base em transporte HTTP (HTTP 2.0 compatível com)libcurl-based HTTP transport (HTTP 2.0 capable)
.NET core 2.1 e posterior.NET Core 2.1 and later System.Net.Http.SocketsHttpHandler

Os usuários também podem configurar um transporte específico para HttpClient invocando o HttpClient construtor que usa um HttpMessageHandler.Users can also configure a specific transport for HttpClient by invoking the HttpClient constructor that takes an HttpMessageHandler.

HttpClient e .NET CoreHttpClient and .NET Core

Começando com o .NET Core 2.1, o System.Net.Http.SocketsHttpHandler classe, em vez de HttpClientHandler fornece a implementação usada pelas classes de rede HTTP nível mais altos, como 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. O uso de SocketsHttpHandler oferece uma série de vantagens:The use of SocketsHttpHandler offers a number of advantages:

  • Uma melhoria de desempenho significativa quando comparada com a implementação anterior.A significant performance improvement when compared with the previous implementation.

  • A eliminação de dependências de plataforma, que simplifica a implantação e manutenção.The elimination of platform dependencies, which simplifies deployment and servicing. Por exemplo, libcurl não é mais uma dependência no .NET Core para macOS e .NET Core para Linux.For example, libcurl is no longer a dependency on .NET Core for macOS and .NET Core for Linux.

  • Comportamento consistente em todas as plataformas .NET.Consistent behavior across all .NET platforms.

Se essa alteração for indesejável, você pode configurar seu aplicativo para usar o antigo System.Net.Http.HttpClientHandler em vez disso, de várias maneiras:If this change is undesirable, you can configure your application to use the older System.Net.Http.HttpClientHandler instead in a number of ways:

  • Chamando o AppContext.SetSwitch método da seguinte maneira:By calling the AppContext.SetSwitch method as follows:

    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
    
    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False)
    
  • Definindo o System.Net.Http.UseSocketsHttpHandler de inserção a . netcore.runtimeconfig.json arquivo de configuração:By defining the System.Net.Http.UseSocketsHttpHandler switch in the .netcore.runtimeconfig.json configuration file:

    "runtimeOptions": {
      "configProperties": {
          "System.Net.Http.UseSocketsHttpHandler": false
      }
    }
    
  • Definindo uma variável de ambiente denominada DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER e defini-la como false ou 0.By defining an environment variable named DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER and setting it to either false or 0.

Construtores

HttpClient() HttpClient() HttpClient() HttpClient()

Inicializa uma nova instância da classe HttpClient.Initializes a new instance of the HttpClient class.

HttpClient(HttpMessageHandler) HttpClient(HttpMessageHandler) HttpClient(HttpMessageHandler) HttpClient(HttpMessageHandler)

Inicializa uma nova instância da classe HttpClient com um manipulador específico.Initializes a new instance of the HttpClient class with a specific handler.

HttpClient(HttpMessageHandler, Boolean) HttpClient(HttpMessageHandler, Boolean) HttpClient(HttpMessageHandler, Boolean) HttpClient(HttpMessageHandler, Boolean)

Inicializa uma nova instância da classe HttpClient com um manipulador específico.Initializes a new instance of the HttpClient class with a specific handler.

Propriedades

BaseAddress BaseAddress BaseAddress BaseAddress

Obtém ou define o endereço básico do URI (Uniform Resource Identifier) do recurso da Internet usado ao enviar solicitações.Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests.

DefaultRequestHeaders DefaultRequestHeaders DefaultRequestHeaders DefaultRequestHeaders

Obtém os cabeçalhos que devem ser enviados com cada solicitação.Gets the headers which should be sent with each request.

MaxResponseContentBufferSize MaxResponseContentBufferSize MaxResponseContentBufferSize MaxResponseContentBufferSize

Obtém ou define o número máximo de bytes armazenados no buffer ao ler o conteúdo da resposta.Gets or sets the maximum number of bytes to buffer when reading the response content.

Timeout Timeout Timeout Timeout

Obtém ou define o período de tempo de espera antes que a solicitação expire.Gets or sets the timespan to wait before the request times out.

Métodos

CancelPendingRequests() CancelPendingRequests() CancelPendingRequests() CancelPendingRequests()

Cancele todas as solicitações pendentes nessa instância.Cancel all pending requests on this instance.

DeleteAsync(String) DeleteAsync(String) DeleteAsync(String) DeleteAsync(String)

Envie uma solicitação DELETE para o URI especificado como uma operação assíncrona.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(String, CancellationToken) DeleteAsync(String, CancellationToken) DeleteAsync(String, CancellationToken) DeleteAsync(String, CancellationToken)

Envie uma solicitação DELETE para o URI especificado com um token de cancelamento como uma operação assíncrona.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

DeleteAsync(Uri) DeleteAsync(Uri) DeleteAsync(Uri) DeleteAsync(Uri)

Envie uma solicitação DELETE para o URI especificado como uma operação assíncrona.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(Uri, CancellationToken) DeleteAsync(Uri, CancellationToken) DeleteAsync(Uri, CancellationToken) DeleteAsync(Uri, CancellationToken)

Envie uma solicitação DELETE para o URI especificado com um token de cancelamento como uma operação assíncrona.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

Dispose() Dispose() Dispose() Dispose()

Libera os recursos não gerenciados e descarta aqueles gerenciados usados pelo HttpMessageInvoker.Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageInvoker.

(Inherited from HttpMessageInvoker)
Dispose(Boolean) Dispose(Boolean) Dispose(Boolean) Dispose(Boolean)

Libera os recursos não gerenciados usados pelo HttpClient e, opcionalmente, descarta os recursos gerenciados.Releases the unmanaged resources used by the HttpClient and optionally disposes of the managed resources.

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetAsync(String) GetAsync(String) GetAsync(String) GetAsync(String)

Envie uma solicitação GET para o URI especificado como uma operação assíncrona.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(String, CancellationToken) GetAsync(String, CancellationToken) GetAsync(String, CancellationToken) GetAsync(String, CancellationToken)

Envie uma solicitação GET para o URI especificado com um token de cancelamento como uma operação assíncrona.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(String, HttpCompletionOption) GetAsync(String, HttpCompletionOption) GetAsync(String, HttpCompletionOption) GetAsync(String, HttpCompletionOption)

Envie uma solicitação GET para o URI especificado com uma opção de conclusão de HTTP como uma operação assíncrona.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(String, HttpCompletionOption, CancellationToken) GetAsync(String, HttpCompletionOption, CancellationToken) GetAsync(String, HttpCompletionOption, CancellationToken) GetAsync(String, HttpCompletionOption, CancellationToken)

Envie uma solicitação GET para o URI especificado com uma opção de conclusão de HTTP e um token de cancelamento como uma operação assíncrona.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetAsync(Uri) GetAsync(Uri) GetAsync(Uri) GetAsync(Uri)

Envie uma solicitação GET para o URI especificado como uma operação assíncrona.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(Uri, CancellationToken) GetAsync(Uri, CancellationToken) GetAsync(Uri, CancellationToken) GetAsync(Uri, CancellationToken)

Envie uma solicitação GET para o URI especificado com um token de cancelamento como uma operação assíncrona.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption) GetAsync(Uri, HttpCompletionOption) GetAsync(Uri, HttpCompletionOption) GetAsync(Uri, HttpCompletionOption)

Envie uma solicitação GET para o URI especificado com uma opção de conclusão de HTTP como uma operação assíncrona.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption, CancellationToken) GetAsync(Uri, HttpCompletionOption, CancellationToken) GetAsync(Uri, HttpCompletionOption, CancellationToken) GetAsync(Uri, HttpCompletionOption, CancellationToken)

Envie uma solicitação GET para o URI especificado com uma opção de conclusão de HTTP e um token de cancelamento como uma operação assíncrona.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetByteArrayAsync(String) GetByteArrayAsync(String) GetByteArrayAsync(String) GetByteArrayAsync(String)

Envia uma solicitação GET para o Uri especificado e retorna o corpo da resposta como uma matriz de bytes em uma operação assíncrona.Sends a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetByteArrayAsync(Uri) GetByteArrayAsync(Uri) GetByteArrayAsync(Uri) GetByteArrayAsync(Uri)

Envie uma solicitação GET para o URI especificado e retorne o corpo da resposta como uma matriz de bytes em uma operação assíncrona.Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Serve como a função de hash padrão.Serves as the default hash function.

(Inherited from Object)
GetStreamAsync(String) GetStreamAsync(String) GetStreamAsync(String) GetStreamAsync(String)

Envie uma solicitação GET para o URI especificado e retorne o corpo da resposta como um fluxo em uma operação assíncrona.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStreamAsync(Uri) GetStreamAsync(Uri) GetStreamAsync(Uri) GetStreamAsync(Uri)

Envie uma solicitação GET para o URI especificado e retorne o corpo da resposta como um fluxo em uma operação assíncrona.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStringAsync(String) GetStringAsync(String) GetStringAsync(String) GetStringAsync(String)

Envie uma solicitação GET para o URI especificado e retorne o corpo da resposta como uma cadeia de caracteres em uma operação assíncrona.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetStringAsync(Uri) GetStringAsync(Uri) GetStringAsync(Uri) GetStringAsync(Uri)

Envie uma solicitação GET para o URI especificado e retorne o corpo da resposta como uma cadeia de caracteres em uma operação assíncrona.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetType() GetType() GetType() GetType()

Obtém o Type da instância atual.Gets the Type of the current instance.

(Inherited from Object)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

Cria uma cópia superficial do Object atual.Creates a shallow copy of the current Object.

(Inherited from Object)
PatchAsync(String, HttpContent) PatchAsync(String, HttpContent) PatchAsync(String, HttpContent) PatchAsync(String, HttpContent)
PatchAsync(String, HttpContent, CancellationToken) PatchAsync(String, HttpContent, CancellationToken) PatchAsync(String, HttpContent, CancellationToken) PatchAsync(String, HttpContent, CancellationToken)
PatchAsync(Uri, HttpContent) PatchAsync(Uri, HttpContent) PatchAsync(Uri, HttpContent) PatchAsync(Uri, HttpContent)
PatchAsync(Uri, HttpContent, CancellationToken) PatchAsync(Uri, HttpContent, CancellationToken) PatchAsync(Uri, HttpContent, CancellationToken) PatchAsync(Uri, HttpContent, CancellationToken)
PostAsync(String, HttpContent) PostAsync(String, HttpContent) PostAsync(String, HttpContent) PostAsync(String, HttpContent)

Envie uma solicitação POST para o URI especificado como uma operação assíncrona.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(String, HttpContent, CancellationToken) PostAsync(String, HttpContent, CancellationToken) PostAsync(String, HttpContent, CancellationToken) PostAsync(String, HttpContent, CancellationToken)

Envie uma solicitação POST com um token de cancelamento como uma operação assíncrona.Send a POST request with a cancellation token as an asynchronous operation.

PostAsync(Uri, HttpContent) PostAsync(Uri, HttpContent) PostAsync(Uri, HttpContent) PostAsync(Uri, HttpContent)

Envie uma solicitação POST para o URI especificado como uma operação assíncrona.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(Uri, HttpContent, CancellationToken) PostAsync(Uri, HttpContent, CancellationToken) PostAsync(Uri, HttpContent, CancellationToken) PostAsync(Uri, HttpContent, CancellationToken)

Envie uma solicitação POST com um token de cancelamento como uma operação assíncrona.Send a POST request with a cancellation token as an asynchronous operation.

PutAsync(String, HttpContent) PutAsync(String, HttpContent) PutAsync(String, HttpContent) PutAsync(String, HttpContent)

Envie uma solicitação PUT para o URI especificado como uma operação assíncrona.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(String, HttpContent, CancellationToken) PutAsync(String, HttpContent, CancellationToken) PutAsync(String, HttpContent, CancellationToken) PutAsync(String, HttpContent, CancellationToken)

Envie uma solicitação PUT com um token de cancelamento como uma operação assíncrona.Send a PUT request with a cancellation token as an asynchronous operation.

PutAsync(Uri, HttpContent) PutAsync(Uri, HttpContent) PutAsync(Uri, HttpContent) PutAsync(Uri, HttpContent)

Envie uma solicitação PUT para o URI especificado como uma operação assíncrona.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(Uri, HttpContent, CancellationToken) PutAsync(Uri, HttpContent, CancellationToken) PutAsync(Uri, HttpContent, CancellationToken) PutAsync(Uri, HttpContent, CancellationToken)

Envie uma solicitação PUT com um token de cancelamento como uma operação assíncrona.Send a PUT request with a cancellation token as an asynchronous operation.

SendAsync(HttpRequestMessage) SendAsync(HttpRequestMessage) SendAsync(HttpRequestMessage) SendAsync(HttpRequestMessage)

Envie uma solicitação HTTP como uma operação assíncrona.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, CancellationToken) SendAsync(HttpRequestMessage, CancellationToken) SendAsync(HttpRequestMessage, CancellationToken) SendAsync(HttpRequestMessage, CancellationToken)

Envie uma solicitação HTTP como uma operação assíncrona.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption) SendAsync(HttpRequestMessage, HttpCompletionOption) SendAsync(HttpRequestMessage, HttpCompletionOption) SendAsync(HttpRequestMessage, HttpCompletionOption)

Envie uma solicitação HTTP como uma operação assíncrona.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken) SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken) SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken) SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

Envie uma solicitação HTTP como uma operação assíncrona.Send an HTTP request as an asynchronous operation.

ToString() ToString() ToString() ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.Returns a string that represents the current object.

(Inherited from Object)

Aplica-se a

Veja também