HttpClient Classe

Definizione

Fornisce una classe di base per l'invio di richieste HTTP e la ricezione di risposte HTTP da una risorsa identificata da un 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
Ereditarietà

Esempi

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

Nell'esempio di codice precedente viene usato un punto di ingresso async Task Main().The preceding code example uses an async Task Main() entry point. Questa funzionalità richiede C# 7,1 o versione successiva.That feature requires C# 7.1 or later.

Commenti

L'istanza della classe HttpClient funge da sessione per l'invio di richieste HTTP.The HttpClient class instance acts as a session to send HTTP requests. Un'istanza di HttpClient è una raccolta di impostazioni applicate a tutte le richieste eseguite da tale istanza.An HttpClient instance is a collection of settings applied to all requests executed by that instance. Ogni HttpClient istanza usa inoltre il proprio pool di connessioni, isolando le richieste dalle richieste eseguite da altre istanze di HttpClient.In addition, every HttpClient instance uses its own connection pool, isolating its requests from requests executed by other HttpClient instances.

Il HttpClient funge anche da classe di base per client HTTP più specifici.The HttpClient also acts as a base class for more specific HTTP clients. Un esempio è costituito da un FacebookHttpClient che fornisce metodi aggiuntivi specifici per un servizio Web Facebook (ad esempio, un metodo GetFriends).An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Le classi derivate non devono eseguire l'override dei metodi virtuali della classe.Derived classes should not override the virtual methods on the class. In alternativa, usare un overload del costruttore che accetti HttpMessageHandler per configurare eventuali elaborazioni pre-o post-richiesta.Instead, use a constructor overload that accepts HttpMessageHandler to configure any pre- or post-request processing instead.

Per impostazione predefinita, in .NET Framework e mono HttpWebRequest viene usato per inviare richieste al server.By default on .NET Framework and Mono, HttpWebRequest is used to send requests to the server. Questo comportamento può essere modificato specificando un canale diverso in uno degli overload del costruttore che accetta un'istanza di HttpMessageHandler come parametro.This behavior can be modified by specifying a different channel in one of the constructor overloads taking a HttpMessageHandler instance as parameter. Se sono necessarie funzionalità come l'autenticazione o la memorizzazione nella cache, è possibile usare WebRequestHandler per configurare le impostazioni e l'istanza può essere passata al costruttore.If features like authentication or caching are required, WebRequestHandler can be used to configure settings and the instance can be passed to the constructor. Il gestore restituito può essere passato a uno degli overload del costruttore che accettano un parametro HttpMessageHandler.The returned handler can be passed to one of the constructor overloads taking a HttpMessageHandler parameter.

Se un'app che usa HttpClient e le classi correlate nello spazio dei nomi System.Net.Http intende scaricare grandi quantità di dati (50 megabyte o più), l'app deve trasmettere tali download senza usare la memorizzazione nel buffer predefinita.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 viene utilizzata la memorizzazione nel buffer predefinita, l'utilizzo della memoria del client otterrà dimensioni molto elevate, causando potenzialmente una riduzione sostanziale delle prestazioni.If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance.

I metodi seguenti sono 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 deve essere creata un'istanza una volta e riutilizzata per tutta la durata di un'applicazione.HttpClient is intended to be instantiated once and re-used throughout the life of an application. Se si crea un'istanza di una classe HttpClient per ogni richiesta, viene esaurito il numero di socket disponibili in presenza di carichi elevati.Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. Questa operazione comporterà errori di SocketException.This will result in SocketException errors. Di seguito è riportato un esempio di utilizzo corretto di 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

Il HttpClient è un'API di alto livello che include la funzionalità di livello inferiore disponibile in ogni piattaforma in cui è in esecuzione.The HttpClient is a high-level API that wraps the lower-level functionality available on each platform where it runs.

In ogni piattaforma HttpClient prova a usare il trasporto migliore disponibile:On each platform, HttpClient tries to use the best available transport:

Host/runtimeHost/Runtime Back-endBackend
Windows/.NET FrameworkWindows/.NET Framework HttpWebRequest
Windows/MonoWindows/Mono HttpWebRequest
Windows/UWPWindows/UWP WinHttpHandler nativo di Windows (in grado di supportare 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 di Windows (in grado di supportare HTTP 2,0)Windows native WinHttpHandler (HTTP 2.0 capable)
Android/NovellAndroid/Xamarin Selezionato in fase di compilazione.Selected at build-time. Può usare HttpWebRequest o essere configurato per usare HttpURLConnection nativo di AndroidCan either use HttpWebRequest or be configured to use Android's native HttpURLConnection
iOS, tvOS, watchos/NovelliOS, tvOS, watchOS/Xamarin Selezionato in fase di compilazione.Selected at build-time. Può usare HttpWebRequest o essere configurato per l'uso di Apple NSUrlSession (http 2,0 capable)Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/XamarinmacOS/Xamarin Selezionato in fase di compilazione.Selected at build-time. Può usare HttpWebRequest o essere configurato per l'uso di Apple NSUrlSession (http 2,0 capable)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 trasporto HTTP basato su libcurl(in grado di supportare 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 trasporto HTTP basato su libcurl(in grado di supportare HTTP 2,0)libcurl-based HTTP transport (HTTP 2.0 capable)
.NET Core 2,1 e versioni successive.NET Core 2.1 and later System.Net.Http.SocketsHttpHandler

Gli utenti possono anche configurare un trasporto specifico per HttpClient richiamando il costruttore di HttpClient che accetta un 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 partire da .NET Core 2,1, la classe System.Net.Http.SocketsHttpHandler anziché HttpClientHandler fornisce l'implementazione utilizzata dalle classi di rete HTTP di livello superiore, ad esempio 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. L'uso di SocketsHttpHandler offre diversi vantaggi:The use of SocketsHttpHandler offers a number of advantages:

  • Miglioramento significativo delle prestazioni rispetto all'implementazione precedente.A significant performance improvement when compared with the previous implementation.

  • Eliminazione delle dipendenze della piattaforma, che semplifica la distribuzione e la manutenzione.The elimination of platform dependencies, which simplifies deployment and servicing. Ad esempio, libcurl non è più una dipendenza da .NET Core per macOS e .NET Core per Linux.For example, libcurl is no longer a dependency on .NET Core for macOS and .NET Core for Linux.

  • Comportamento coerente in tutte le piattaforme .NET.Consistent behavior across all .NET platforms.

Se questa modifica è indesiderata, è possibile configurare l'applicazione in modo che usi i System.Net.Http.HttpClientHandler precedenti in diversi modi:If this change is undesirable, you can configure your application to use the older System.Net.Http.HttpClientHandler instead in a number of ways:

  • Chiamando il metodo AppContext.SetSwitch come segue:By calling the AppContext.SetSwitch method as follows:

    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
    
    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False)
    
  • Definendo l'opzione System.Net.Http.UseSocketsHttpHandler nel file di configurazione . 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
      }
    }
    
  • Definendo una variabile di ambiente denominata DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER e impostandola su false o 0.By defining an environment variable named DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER and setting it to either false or 0.

Costruttori

HttpClient()

Inizializza una nuova istanza della classe HttpClient con HttpClientHandler che viene eliminato quando viene eliminata l'istanza.Initializes a new instance of the HttpClient class using a HttpClientHandler that is disposed when this instance is disposed.

HttpClient(HttpMessageHandler)

Inizializza una nuova istanza della classe HttpClient con il gestore specificato.Initializes a new instance of the HttpClient class with the specified handler. Il gestore viene eliminato quando viene eliminata l'istanza.The handler is disposed when this instance is disposed.

HttpClient(HttpMessageHandler, Boolean)

Inizializza una nuova istanza della classe HttpClient con il gestore specificato e stabilisce se il gestore deve essere eliminato quando viene eliminata l'istanza.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.

Proprietà

BaseAddress

Ottiene o imposta l'indirizzo di base dell'URI (Uniform Resource Identifier) della risorsa Internet utilizzata durante l'invio delle richieste.Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests.

DefaultProxy

Ottiene o imposta il proxy HTTP globale.Gets or sets the global Http proxy.

DefaultRequestHeaders

Ottiene le intestazioni che devono essere inviate con ciascuna richiesta.Gets the headers which should be sent with each request.

DefaultRequestVersion

Ottiene o imposta la versione HTTP predefinita usata per le richieste successive effettuate da questa istanza di HttpClient.Gets or sets the default HTTP version used on subsequent requests made by this HttpClient instance.

MaxResponseContentBufferSize

Ottiene o imposta il numero massimo di byte da memorizzare nel buffer durante la lettura del contenuto della risposta.Gets or sets the maximum number of bytes to buffer when reading the response content.

Timeout

Ottiene o imposta l'intervallo di tempo da attendere prima che si verifichi il timeout della richiesta.Gets or sets the timespan to wait before the request times out.

Metodi

CancelPendingRequests()

Annulla tutte le richieste in sospeso in questa istanza.Cancel all pending requests on this instance.

DeleteAsync(String)

Inviare una richiesta DELETE all'URI specificato come operazione asincrona.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(String, CancellationToken)

Inviare una richiesta DELETE all'URI specificato con un token di annullamento come operazione asincrona.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

DeleteAsync(Uri)

Inviare una richiesta DELETE all'URI specificato come operazione asincrona.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(Uri, CancellationToken)

Inviare una richiesta DELETE all'URI specificato con un token di annullamento come operazione asincrona.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

Dispose()

Rilascia le risorse non gestite ed elimina le risorse gestite utilizzate dall'oggetto HttpMessageInvoker.Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageInvoker.

(Ereditato da HttpMessageInvoker)
Dispose(Boolean)

Rilascia le risorse non gestite usate da HttpClient e, facoltativamente, elimina le risorse gestite.Releases the unmanaged resources used by the HttpClient and optionally disposes of the managed resources.

Equals(Object)

Determina se l'oggetto specificato è uguale all'oggetto corrente.Determines whether the specified object is equal to the current object.

(Ereditato da Object)
GetAsync(String)

Inviare una richiesta GET all'URI specificato come operazione asincrona.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(String, CancellationToken)

Inviare una richiesta GET all'URI specificato con un token di annullamento come operazione asincrona.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(String, HttpCompletionOption)

Inviare una richiesta GET all'URI specificato con un'opzione di completamento HTTP come operazione asincrona.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(String, HttpCompletionOption, CancellationToken)

Inviare una richiesta GET all'URI specificato con un'opzione di completamento HTTP e un token di annullamento come operazione asincrona.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetAsync(Uri)

Inviare una richiesta GET all'URI specificato come operazione asincrona.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(Uri, CancellationToken)

Inviare una richiesta GET all'URI specificato con un token di annullamento come operazione asincrona.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption)

Inviare una richiesta GET all'URI specificato con un'opzione di completamento HTTP come operazione asincrona.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption, CancellationToken)

Inviare una richiesta GET all'URI specificato con un'opzione di completamento HTTP e un token di annullamento come operazione asincrona.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetByteArrayAsync(String)

Invia una richiesta GET all'URI specificato e restituisce il corpo della risposta come matrice di byte in un'operazione asincrona.Sends a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetByteArrayAsync(Uri)

Inviare una richiesta GET all'URI specificato e restituire il corpo della risposta come matrice di byte in un'operazione asincrona.Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetHashCode()

Funge da funzione hash predefinita.Serves as the default hash function.

(Ereditato da Object)
GetStreamAsync(String)

Inviare una richiesta GET all'URI specificato e restituisce il corpo della risposta come flusso in un'operazione asincrona.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStreamAsync(Uri)

Inviare una richiesta GET all'URI specificato e restituisce il corpo della risposta come flusso in un'operazione asincrona.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStringAsync(String)

Inviare una richiesta GET all'URI specificato e restituisce il corpo della risposta come stringa in un'operazione asincrona.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetStringAsync(Uri)

Inviare una richiesta GET all'URI specificato e restituisce il corpo della risposta come stringa in un'operazione asincrona.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetType()

Ottiene l'oggetto Type dell'istanza corrente.Gets the Type of the current instance.

(Ereditato da Object)
MemberwiseClone()

Crea una copia superficiale dell'oggetto Object corrente.Creates a shallow copy of the current Object.

(Ereditato da Object)
PatchAsync(String, HttpContent)

Invia una richiesta PATCH come operazione asincrona a un URI designato come stringa.Sends a PATCH request to a Uri designated as a string as an asynchronous operation.

PatchAsync(String, HttpContent, CancellationToken)

Invia una richiesta PATCH con un token di annullamento come operazione asincrona a un URI rappresentato come stringa.Sends a PATCH request with a cancellation token to a Uri represented as a string as an asynchronous operation.

PatchAsync(Uri, HttpContent)

Invia una richiesta PATCH come operazione asincrona.Sends a PATCH request as an asynchronous operation.

PatchAsync(Uri, HttpContent, CancellationToken)

Invia una richiesta PATCH con un token di annullamento come operazione asincrona.Sends a PATCH request with a cancellation token as an asynchronous operation.

PostAsync(String, HttpContent)

Inviare una richiesta POST all'URI specificato come operazione asincrona.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(String, HttpContent, CancellationToken)

Inviare una richiesta POST con un token di annullamento come operazione asincrona.Send a POST request with a cancellation token as an asynchronous operation.

PostAsync(Uri, HttpContent)

Inviare una richiesta POST all'URI specificato come operazione asincrona.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(Uri, HttpContent, CancellationToken)

Inviare una richiesta POST con un token di annullamento come operazione asincrona.Send a POST request with a cancellation token as an asynchronous operation.

PutAsync(String, HttpContent)

Inviare una richiesta PUT all'URI specificato come operazione asincrona.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(String, HttpContent, CancellationToken)

Inviare una richiesta PUT con un token di annullamento come operazione asincrona.Send a PUT request with a cancellation token as an asynchronous operation.

PutAsync(Uri, HttpContent)

Inviare una richiesta PUT all'URI specificato come operazione asincrona.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(Uri, HttpContent, CancellationToken)

Inviare una richiesta PUT con un token di annullamento come operazione asincrona.Send a PUT request with a cancellation token as an asynchronous operation.

SendAsync(HttpRequestMessage)

Inviare una richiesta HTTP come operazione asincrona.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, CancellationToken)

Inviare una richiesta HTTP come operazione asincrona.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption)

Inviare una richiesta HTTP come operazione asincrona.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

Inviare una richiesta HTTP come operazione asincrona.Send an HTTP request as an asynchronous operation.

ToString()

Restituisce una stringa che rappresenta l'oggetto corrente.Returns a string that represents the current object.

(Ereditato da Object)

Si applica a

Vedi anche