HttpClient Classe

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

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

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

Comentários

A instância da classe HttpClient atua como uma sessão para enviar solicitações HTTP.The HttpClient class instance acts as a session to send HTTP requests. Uma instância de HttpClient é 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 instância de HttpClient usa seu próprio pool de conexões, isolando suas solicitações de solicitações executadas por outras instâncias de HttpClient.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 clientes HTTP mais específicos.The HttpClient also acts as a base class for more specific HTTP clients. Um exemplo seria um FacebookHttpClient que fornece métodos adicionais específicos para um serviço Web do 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 aceite HttpMessageHandler para configurar qualquer processamento de pré ou pós-solicitação.Instead, use a constructor overload that accepts HttpMessageHandler to configure any pre- or post-request processing instead.

Por padrão, em .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 especificando um canal diferente em uma das sobrecargas de construtor que levam uma instância de HttpMessageHandler 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 forem necessários recursos como autenticação ou cache, WebRequestHandler poderá ser usado para definir as configurações e a instância poderá ser passada 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 do construtor usando um parâmetro HttpMessageHandler.The returned handler can be passed to one of the constructor overloads taking a HttpMessageHandler parameter.

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

Os métodos a seguir 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

a HttpClient deve ser instanciada uma vez e reutilizada durante toda a vida útil de um aplicativo.HttpClient is intended to be instantiated once and re-used throughout the life of an application. A instanciação de uma classe HttpClient para cada solicitação irá esgotar o número de soquetes disponíveis sob 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. Veja abaixo um exemplo que usa HttpClient corretamente.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

O HttpClient é uma API de alto nível que encapsula a funcionalidade de nível inferior disponível em cada plataforma em que é executada.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 melhor transporte disponível:On each platform, HttpClient tries to use the best available transport:

Host/tempo de execuçãoHost/Runtime EndBackend
Windows/.NET FrameworkWindows/.NET Framework HttpWebRequest
Windows/monoWindows/Mono HttpWebRequest
Windows/UWPWindows/UWP WinHttpHandler nativo do Windows (compatível com HTTP 2,0)Windows native WinHttpHandler (HTTP 2.0 capable)
Windows/.NET Core 1.0-2.0Windows/.NET Core 1.0-2.0 WinHttpHandler nativo do Windows (compatível com HTTP 2,0)Windows native WinHttpHandler (HTTP 2.0 capable)
Android/XamarinAndroid/Xamarin Selecionado no momento da compilação.Selected at build-time. Pode usar o HttpWebRequest ou ser configurado para usar o HttpURLConnection nativo do AndroidCan either use HttpWebRequest or be configured to use Android's native HttpURLConnection
iOS, tvOS, watchOS/XamariniOS, tvOS, watchOS/Xamarin Selecionado no momento da compilação.Selected at build-time. Pode usar o HttpWebRequest ou ser configurado para usar o NSUrlSession da Apple (compatível com http 2,0)Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/XamarinmacOS/Xamarin Selecionado no momento da compilação.Selected at build-time. Pode usar o HttpWebRequest ou ser configurado para usar o NSUrlSession da Apple (compatível com 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 transporte HTTP baseado em libcurl(compatível com 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 transporte HTTP baseado em libcurl(compatível com HTTP 2,0)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 Construtor HttpClient que usa uma 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

A partir do .NET Core 2,1, a classe System.Net.Http.SocketsHttpHandler em vez de HttpClientHandler fornece a implementação usada por classes de rede HTTP de nível superior, 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 várias 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, o que simplifica a implantação e a manutenção.The elimination of platform dependencies, which simplifies deployment and servicing. Por exemplo, libcurl não é mais uma dependência do .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ê poderá configurar seu aplicativo para usar o System.Net.Http.HttpClientHandler mais antigo, em vez 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 método AppContext.SetSwitch 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 a opção System.Net.Http.UseSocketsHttpHandler no arquivo de configuração . 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
      }
    }
    
  • Definindo uma variável de ambiente chamada DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER e definindo-a 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()

Inicializa uma nova instância da classe HttpClient usando um HttpClientHandler que é descartado quando essa instância é descartada.Initializes a new instance of the HttpClient class using a HttpClientHandler that is disposed when this instance is disposed.

HttpClient(HttpMessageHandler)

Inicializa uma nova instância da classe HttpClient com o manipulador especificado.Initializes a new instance of the HttpClient class with the specified handler. O manipulador é descartado quando essa instância é descartada.The handler is disposed when this instance is disposed.

HttpClient(HttpMessageHandler, Boolean)

Inicializa uma nova instância da classe HttpClient com o manipulador fornecido e especifica se esse manipulador deverá ser descartado quando essa instância for descartada.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.

Propriedades

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.

DefaultProxy

Obtém ou define o proxy HTTP global.Gets or sets the global Http proxy.

DefaultRequestHeaders

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

DefaultRequestVersion

Obtém ou define a versão HTTP padrão usada em solicitações posteriores feitas por essa instância de HttpClient.Gets or sets the default HTTP version used on subsequent requests made by this HttpClient instance.

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

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()

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

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)

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)

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)

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()

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.

(Herdado de HttpMessageInvoker)
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)

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

(Herdado de Object)
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)

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)

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)

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)

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)

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)

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)

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)

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)

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()

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

(Herdado de Object)
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)

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)

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)

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()

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

(Herdado de Object)
MemberwiseClone()

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

(Herdado de Object)
PatchAsync(String, HttpContent)

Envia uma solicitação PATCH a um URI designado como uma cadeia de caracteres, como uma operação assíncrona.Sends a PATCH request to a Uri designated as a string as an asynchronous operation.

PatchAsync(String, HttpContent, CancellationToken)

Envia uma solicitação PATCH com um token de cancelamento a um URI representado como uma cadeia de caracteres, como uma operação assíncrona.Sends a PATCH request with a cancellation token to a Uri represented as a string as an asynchronous operation.

PatchAsync(Uri, HttpContent)

Envia uma solicitação PATCH como uma operação assíncrona.Sends a PATCH request as an asynchronous operation.

PatchAsync(Uri, HttpContent, CancellationToken)

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

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)

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)

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)

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)

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)

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)

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)

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)

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

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)

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

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

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

ToString()

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

(Herdado de Object)

Aplica-se a

Veja também