HttpClient Klasa

Definicja

Stanowi klasę bazową do wysyłania żądań HTTP i odbierania odpowiedzi HTTP z zasobu zidentyfikowanego z użyciem identyfikatora 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
Dziedziczenie

Przykłady

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

Poprzedni przykład kodu używa async Task Main() punktu wejścia.The preceding code example uses an async Task Main() entry point. Ta funkcja wymaga C# 7,1 lub nowszej.That feature requires C# 7.1 or later.

Uwagi

Wystąpienie klasy HttpClient pełni rolę sesji wysyłania żądań HTTP.The HttpClient class instance acts as a session to send HTTP requests. Wystąpienie HttpClient jest kolekcją ustawień zastosowanych do wszystkich żądań wykonywanych przez to wystąpienie.An HttpClient instance is a collection of settings applied to all requests executed by that instance. Ponadto każde wystąpienie HttpClient używa własnej puli połączeń, izolując jej żądania od żądań wykonywanych przez inne wystąpienia HttpClient.In addition, every HttpClient instance uses its own connection pool, isolating its requests from requests executed by other HttpClient instances.

HttpClient działa również jako klasa bazowa dla bardziej szczegółowych klientów HTTP.The HttpClient also acts as a base class for more specific HTTP clients. Przykładem może być FacebookHttpClient z dodatkowymi metodami specyficznymi dla usługi sieci Web w serwisie Facebook (na przykład Metoda getfriends).An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Klasy pochodne nie powinny przesłaniać metod wirtualnych w klasie.Derived classes should not override the virtual methods on the class. Zamiast tego należy użyć przeciążenia konstruktora, które akceptuje HttpMessageHandler w celu skonfigurowania dowolnego przetwarzania przed lub po żądaniu.Instead, use a constructor overload that accepts HttpMessageHandler to configure any pre- or post-request processing instead.

Domyślnie na .NET Framework i mono HttpWebRequest jest używany do wysyłania żądań do serwera.By default on .NET Framework and Mono, HttpWebRequest is used to send requests to the server. To zachowanie można zmodyfikować, określając inny kanał w jednym z przeciążeń konstruktora, pobierając wystąpienie HttpMessageHandler jako parametr.This behavior can be modified by specifying a different channel in one of the constructor overloads taking a HttpMessageHandler instance as parameter. Jeśli wymagane są funkcje, takie jak uwierzytelnianie lub buforowanie, WebRequestHandler może służyć do konfigurowania ustawień, a wystąpienie może być przesyłane do konstruktora.If features like authentication or caching are required, WebRequestHandler can be used to configure settings and the instance can be passed to the constructor. Zwracaną procedurę obsługi można przesłać do jednego z przeciążeń konstruktora pobierającego parametr HttpMessageHandler.The returned handler can be passed to one of the constructor overloads taking a HttpMessageHandler parameter.

Jeśli aplikacja używająca HttpClient i powiązanych klas w przestrzeni nazw System.Net.Http zamierza pobrać duże ilości danych (50 megabajtów lub więcej), aplikacja powinna przesyłać strumieniowo te pliki do pobrania i nie używać domyślnego buforowania.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. Jeśli domyślne buforowanie jest używane, użycie pamięci przez klienta będzie bardzo duże, co może znacznie zmniejszyć wydajność.If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance.

Następujące metody są bezpieczne dla wątków: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 jest przeznaczony do tworzenia wystąpień i ponownego wykorzystania przez cały czas życia aplikacji.HttpClient is intended to be instantiated once and re-used throughout the life of an application. Utworzenie wystąpienia klasy HttpClient dla każdego żądania spowoduje wyczerpanie liczby gniazd dostępnych w ramach dużych obciążeń.Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. Spowoduje to błędy Gniazdaexception.This will result in SocketException errors. Poniżej przedstawiono przykład użycia HttpClient prawidłowo.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 to interfejs API wysokiego poziomu, który otacza funkcje niższego poziomu dostępne na każdej platformie, na której działa.The HttpClient is a high-level API that wraps the lower-level functionality available on each platform where it runs.

Na każdej platformie HttpClient próbuje użyć najlepszego dostępnego transportu:On each platform, HttpClient tries to use the best available transport:

Host/środowisko uruchomienioweHost/Runtime DanychBackend
Windows/.NET FrameworkWindows/.NET Framework HttpWebRequest
Windows/MonoWindows/Mono HttpWebRequest
Windows/UWPWindows/UWP WinHttpHandler natywny systemu Windows (obsługa protokołu HTTP 2,0)Windows native WinHttpHandler (HTTP 2.0 capable)
Windows/. NET Core 1.0-2.0Windows/.NET Core 1.0-2.0 WinHttpHandler natywny systemu Windows (obsługa protokołu HTTP 2,0)Windows native WinHttpHandler (HTTP 2.0 capable)
Android/XamarinAndroid/Xamarin Wybrane w czasie kompilacji.Selected at build-time. Można użyć HttpWebRequest lub skonfigurować do korzystania z natywnego HttpURLConnection systemu AndroidCan either use HttpWebRequest or be configured to use Android's native HttpURLConnection
iOS, systemu tvOS, systemu watchOS/XamariniOS, tvOS, watchOS/Xamarin Wybrane w czasie kompilacji.Selected at build-time. Może użyć HttpWebRequest lub skonfigurować do korzystania z NSUrlSession firmy Apple (z obsługą protokołu HTTP 2,0)Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/XamarinmacOS/Xamarin Wybrane w czasie kompilacji.Selected at build-time. Może użyć HttpWebRequest lub skonfigurować do korzystania z NSUrlSession firmy Apple (z obsługą protokołu 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 transport HTTP oparty na libcurl(obsługujący protokół 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 transport HTTP oparty na libcurl(obsługujący protokół HTTP 2,0)libcurl-based HTTP transport (HTTP 2.0 capable)
.NET Core 2,1 i nowsze.NET Core 2.1 and later System.Net.Http.SocketsHttpHandler

Użytkownicy mogą również konfigurować określony transport dla HttpClient przez wywoływanie konstruktora HttpClient, który pobiera HttpMessageHandler.Users can also configure a specific transport for HttpClient by invoking the HttpClient constructor that takes an HttpMessageHandler.

HttpClient i .NET CoreHttpClient and .NET Core

Począwszy od platformy .NET Core 2,1, Klasa System.Net.Http.SocketsHttpHandler, a nie HttpClientHandler zapewnia implementację używaną przez klasy sieci HTTP wyższego poziomu, takie jak 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. Korzystanie z SocketsHttpHandler oferuje wiele korzyści:The use of SocketsHttpHandler offers a number of advantages:

  • Znaczący wzrost wydajności w porównaniu z poprzednią implementacją.A significant performance improvement when compared with the previous implementation.

  • Eliminacja zależności platformy, która upraszcza wdrażanie i obsługę.The elimination of platform dependencies, which simplifies deployment and servicing. Na przykład libcurl nie jest już zależność od platformy .NET Core dla macOS i .NET Core dla systemu Linux.For example, libcurl is no longer a dependency on .NET Core for macOS and .NET Core for Linux.

  • Spójne zachowanie na wszystkich platformach .NET.Consistent behavior across all .NET platforms.

Jeśli ta zmiana jest niepożądana, można skonfigurować aplikację tak, aby korzystała ze starszej System.Net.Http.HttpClientHandler zamiast tego na wiele sposobów:If this change is undesirable, you can configure your application to use the older System.Net.Http.HttpClientHandler instead in a number of ways:

  • Wywołując metodę AppContext.SetSwitch w następujący sposób:By calling the AppContext.SetSwitch method as follows:

    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
    
    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False)
    
  • Przez zdefiniowanie przełącznika System.Net.Http.UseSocketsHttpHandler w pliku konfiguracji . servicecore. runtimeconfig. JSON :By defining the System.Net.Http.UseSocketsHttpHandler switch in the .netcore.runtimeconfig.json configuration file:

    "runtimeOptions": {
      "configProperties": {
          "System.Net.Http.UseSocketsHttpHandler": false
      }
    }
    
  • Zdefiniowanie zmiennej środowiskowej o nazwie DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER i ustawienie jej na false lub 0.By defining an environment variable named DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER and setting it to either false or 0.

Konstruktory

HttpClient()

Inicjuje nowe wystąpienie klasy HttpClient przy użyciu HttpClientHandler, który jest usuwany, gdy to wystąpienie zostanie usunięte.Initializes a new instance of the HttpClient class using a HttpClientHandler that is disposed when this instance is disposed.

HttpClient(HttpMessageHandler)

Inicjuje nowe wystąpienie klasy HttpClient z określonym programem obsługi.Initializes a new instance of the HttpClient class with the specified handler. Procedura obsługi jest usuwana, gdy to wystąpienie zostanie usunięte.The handler is disposed when this instance is disposed.

HttpClient(HttpMessageHandler, Boolean)

Inicjuje nowe wystąpienie klasy HttpClient przy użyciu podanej procedury obsługi i określa, czy ta procedura obsługi powinna zostać usunięta, gdy to wystąpienie zostanie usunięte.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.

Właściwości

BaseAddress

Pobiera lub ustawia podstawowy identyfikator URI zasobu internetowego używanego podczas wysyłania żądań.Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests.

DefaultProxy

Pobiera lub ustawia globalny serwer proxy HTTP.Gets or sets the global Http proxy.

DefaultRequestHeaders

Pobiera nagłówki, które powinny być wysyłane z każdym żądaniem.Gets the headers which should be sent with each request.

DefaultRequestVersion

Pobiera lub ustawia domyślną wersję protokołu HTTP używaną w kolejnych żądaniach wykonywanych przez to wystąpienie HttpClient.Gets or sets the default HTTP version used on subsequent requests made by this HttpClient instance.

MaxResponseContentBufferSize

Pobiera lub ustawia maksymalną liczbę bajtów do zbuforowania podczas odczytywania zawartości odpowiedzi.Gets or sets the maximum number of bytes to buffer when reading the response content.

Timeout

Pobiera lub ustawia obiekt TimeSpan, który ma czekać przed upływem limitu czasu żądania.Gets or sets the timespan to wait before the request times out.

Metody

CancelPendingRequests()

Anuluje wszystkie oczekujące żądania dla tego wystąpienia.Cancel all pending requests on this instance.

DeleteAsync(String)

Wyślij żądanie USUŃ do określonego identyfikatora Uri jako operację asynchroniczną.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(String, CancellationToken)

Wyślij żądanie usunięcia do określonego identyfikatora URI z tokenem anulowania jako operacji asynchronicznej.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

DeleteAsync(Uri)

Wyślij żądanie USUŃ do określonego identyfikatora Uri jako operację asynchroniczną.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(Uri, CancellationToken)

Wyślij żądanie usunięcia do określonego identyfikatora URI z tokenem anulowania jako operacji asynchronicznej.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

Dispose()

Zwalnia zasoby niezarządzane i usuwa zasoby zarządzane używane przez HttpMessageInvokerprogram.Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageInvoker.

(Odziedziczone po HttpMessageInvoker)
Dispose(Boolean)

Zwalnia zasoby niezarządzane używane przez program HttpClient i opcjonalnie usuwa zarządzane zasoby.Releases the unmanaged resources used by the HttpClient and optionally disposes of the managed resources.

Equals(Object)

Określa, czy określony obiekt jest równy bieżącemu obiektowi.Determines whether the specified object is equal to the current object.

(Odziedziczone po Object)
GetAsync(String)

Wyślij żądanie POBIERZ do określonego identyfikatora Uri jako operację asynchroniczną.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(String, CancellationToken)

Wyślij żądanie GET do określonego identyfikatora URI z tokenem anulowania jako operacji asynchronicznej.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(String, HttpCompletionOption)

Wyślij żądanie GET do określonego identyfikatora URI z opcją zakończenia HTTP jako operacją asynchroniczną.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(String, HttpCompletionOption, CancellationToken)

Wyślij żądanie GET do określonego identyfikatora URI z opcją zakończenia HTTP i tokenem anulowania jako operacją asynchroniczną.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetAsync(Uri)

Wyślij żądanie POBIERZ do określonego identyfikatora Uri jako operację asynchroniczną.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(Uri, CancellationToken)

Wyślij żądanie GET do określonego identyfikatora URI z tokenem anulowania jako operacji asynchronicznej.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption)

Wyślij żądanie GET do określonego identyfikatora URI z opcją zakończenia HTTP jako operacją asynchroniczną.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption, CancellationToken)

Wyślij żądanie GET do określonego identyfikatora URI z opcją zakończenia HTTP i tokenem anulowania jako operacją asynchroniczną.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetByteArrayAsync(String)

Wysyła żądanie GET do określonego identyfikatora URI i zwraca treść odpowiedzi jako tablicę bajtów w operacji asynchronicznej.Sends a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetByteArrayAsync(Uri)

Wyślij żądanie POBIERZ do określonego identyfikatora Uri i zwróć treść odpowiedzi jako tablicę bajtów w operacji asynchronicznej.Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetHashCode()

Służy jako domyślna funkcja skrótu.Serves as the default hash function.

(Odziedziczone po Object)
GetStreamAsync(String)

Wyślij żądanie POBIERZ do określonego identyfikatora Uri i zwróć treść odpowiedzi jako strumień w operacji asynchronicznej.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStreamAsync(Uri)

Wyślij żądanie POBIERZ do określonego identyfikatora Uri i zwróć treść odpowiedzi jako strumień w operacji asynchronicznej.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStringAsync(String)

Wyślij żądanie POBIERZ do określonego identyfikatora Uri i zwróć treść odpowiedzi jako ciąg w operacji asynchronicznej.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetStringAsync(Uri)

Wyślij żądanie POBIERZ do określonego identyfikatora Uri i zwróć treść odpowiedzi jako ciąg w operacji asynchronicznej.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetType()

Pobiera Type bieżącego wystąpienia.Gets the Type of the current instance.

(Odziedziczone po Object)
MemberwiseClone()

Tworzy skróconą kopię bieżącego Object.Creates a shallow copy of the current Object.

(Odziedziczone po Object)
PatchAsync(String, HttpContent)

Wysyła żądanie PATCH do identyfikatora URI wyznaczoną jako ciąg jako operację asynchroniczną.Sends a PATCH request to a Uri designated as a string as an asynchronous operation.

PatchAsync(String, HttpContent, CancellationToken)

Wysyła żądanie PATCH z tokenem anulowania do identyfikatora URI reprezentowanego jako ciąg w postaci operacji asynchronicznej.Sends a PATCH request with a cancellation token to a Uri represented as a string as an asynchronous operation.

PatchAsync(Uri, HttpContent)

Wysyła żądanie PATCH jako operację asynchroniczną.Sends a PATCH request as an asynchronous operation.

PatchAsync(Uri, HttpContent, CancellationToken)

Wysyła żądanie PATCH z tokenem anulowania jako operacji asynchronicznej.Sends a PATCH request with a cancellation token as an asynchronous operation.

PostAsync(String, HttpContent)

Wyślij żądanie WYŚLIJ do określonego identyfikatora Uri jako operację asynchroniczną.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(String, HttpContent, CancellationToken)

Wyślij żądanie POST z tokenem anulowania jako operacji asynchronicznej.Send a POST request with a cancellation token as an asynchronous operation.

PostAsync(Uri, HttpContent)

Wyślij żądanie WYŚLIJ do określonego identyfikatora Uri jako operację asynchroniczną.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(Uri, HttpContent, CancellationToken)

Wyślij żądanie POST z tokenem anulowania jako operacji asynchronicznej.Send a POST request with a cancellation token as an asynchronous operation.

PutAsync(String, HttpContent)

Wyślij żądanie UMIEŚĆ do określonego identyfikatora Uri jako operację asynchroniczną.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(String, HttpContent, CancellationToken)

Wyślij żądanie PUT z tokenem anulowania jako operacji asynchronicznej.Send a PUT request with a cancellation token as an asynchronous operation.

PutAsync(Uri, HttpContent)

Wyślij żądanie UMIEŚĆ do określonego identyfikatora Uri jako operację asynchroniczną.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(Uri, HttpContent, CancellationToken)

Wyślij żądanie PUT z tokenem anulowania jako operacji asynchronicznej.Send a PUT request with a cancellation token as an asynchronous operation.

SendAsync(HttpRequestMessage)

Wyślij żądanie HTTP jako operację asynchroniczną.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, CancellationToken)

Wyślij żądanie HTTP jako operację asynchroniczną.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption)

Wyślij żądanie HTTP jako operację asynchroniczną.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

Wyślij żądanie HTTP jako operację asynchroniczną.Send an HTTP request as an asynchronous operation.

ToString()

Zwraca ciąg, który reprezentuje bieżący obiekt.Returns a string that represents the current object.

(Odziedziczone po Object)

Dotyczy

Zobacz też