HttpClient Klasse

Definition

Stellt eine Klasse zum Senden von HTTP-Anforderungen und Empfangen von HTTP-Antworten von einer Durch einen URI identifizierten Ressource bereit.

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
Vererbung

Beispiele

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

Im vorherigen Codebeispiel wird ein async Task Main() Einstiegspunkt verwendet. Für dieses Feature ist C# 7.1 oder höher erforderlich.

Hinweise

Die HttpClient Klasseninstanz fungiert als Sitzung zum Senden von HTTP-Anforderungen. Eine HttpClient -Instanz ist eine Sammlung von Einstellungen, die auf alle von dieser Instanz ausgeführten Anforderungen angewendet werden. Darüber hinaus verwendet jede HttpClient Instanz einen eigenen Verbindungspool, um ihre Anforderungen von Anforderungen zu isolieren, die von anderen Instanzen ausgeführt HttpClient werden.

Abgeleitete Klassen sollten die virtuellen Methoden für die Klasse nicht überschreiben. Verwenden Sie stattdessen eine Konstruktorüberladung, die HttpMessageHandler akzeptiert, um jede Verarbeitung vor oder nach der Anforderung zu konfigurieren.

Standardmäßig wird auf .NET Framework und Mono HttpWebRequest verwendet, um Anforderungen an den Server zu senden. Dieses Verhalten kann durch Angeben eines anderen Kanals in einer der Konstruktorüberladungen geändert werden, die eine HttpMessageHandler -Instanz als Parameter akzeptieren. Wenn Features wie Authentifizierung oder Zwischenspeicherung erforderlich sind, WebRequestHandler kann verwendet werden, um Einstellungen zu konfigurieren, und die Instanz kann an den Konstruktor übergeben werden. Der zurückgegebene Handler kann an eine der Konstruktorüberladungen übergeben werden, die einen HttpMessageHandler -Parameter akzeptieren.

Wenn eine App, HttpClient die und verwandte Klassen im Namespace System.Net.Http verwendet, große Datenmengen (50 Megabyte oder mehr) herunterladen möchte, sollte die App diese Downloads streamen und nicht die Standardpufferung verwenden. Wenn die Standardpufferung verwendet wird, wird die Clientarbeitsspeicherauslastung sehr groß, was zu einer erheblich geringeren Leistung führen kann.

Eigenschaften von HttpClient sollten nicht geändert werden, während ausstehende Anforderungen vorhanden sind, da sie nicht threadsicher sind.

Die folgenden Methoden sind threadsicher:

  1. CancelPendingRequests

  2. DeleteAsync

  3. GetAsync

  4. GetByteArrayAsync

  5. GetStreamAsync

  6. GetStringAsync

  7. PostAsync

  8. PutAsync

  9. SendAsync

  10. PatchAsync

HttpClient ist dafür vorgesehen, einmal instanziiert und während der gesamten Lebensdauer einer Anwendung wiederverwendet zu werden. Durch das Instanziieren einer HttpClient-Klasse für jede Anforderung wird die Anzahl der Sockets erschöpft, die bei hoher Auslastung verfügbar sind. Dies führt zu SocketException-Fehlern. Im Folgenden finden Sie ein Beispiel für die korrekte Verwendung von HttpClient.

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

Ist HttpClient eine high-level-API, die die funktionen auf niedrigerer Ebene umschließt, die auf jeder Plattform verfügbar sind, auf der sie ausgeführt wird.

Versucht auf jeder Plattform, HttpClient den besten verfügbaren Transport zu verwenden:

Host/Runtime Back-End
Windows/.NET Framework HttpWebRequest
Windows/Mono HttpWebRequest
Windows/UWP Windows nativ WinHttpHandler (HTTP 2.0-fähig)
Windows/.NET Core 1.0-2.0 Windows nativ WinHttpHandler (HTTP 2.0-fähig)
Android/Xamarin Zur Buildzeit ausgewählt. Kann entweder verwenden oder für die Verwendung des HttpWebRequest nativen Android-Geräts konfiguriert werden. HttpURLConnection
iOS, tvOS, watchOS/Xamarin Zur Buildzeit ausgewählt. Kann entweder verwenden HttpWebRequest oder für die Verwendung von Apple konfiguriert werden NSUrlSession (HTTP 2.0-fähig)
macOS/Xamarin Zur Buildzeit ausgewählt. Kann entweder verwenden HttpWebRequest oder für die Verwendung von Apple konfiguriert werden NSUrlSession (HTTP 2.0-fähig)
macOS/Mono HttpWebRequest
macOS/.NET Core 1.0-2.0 libcurl-basierter HTTP-Transport (HTTP 2.0-fähig)
Linux/Mono HttpWebRequest
Linux/.NET Core 1.0-2.0 libcurl-basierter HTTP-Transport (HTTP 2.0-fähig)
.NET Core 2.1 und höher System.Net.Http.SocketsHttpHandler

Benutzer können auch einen bestimmten Transport für konfigurieren, HttpClient indem sie den HttpClient Konstruktor aufrufen, der ein HttpMessageHandler annimmt.

HttpClient und .NET Core

Ab .NET Core 2.1 stellt die -Klasse anstelle von die Implementierung bereit, System.Net.Http.SocketsHttpHandler HttpClientHandler die von HTTP-Netzwerkklassen auf höherer Ebene wie verwendet HttpClient wird. Die Verwendung von SocketsHttpHandler bietet eine Reihe von Vorteilen:

  • Eine beträchtliche Leistungssteigerung im Vergleich zur früheren Implementierung.
  • Die Beseitigung von Plattformabhängigkeiten, was die Bereitstellung und Wartung vereinfacht. beispielsweise libcurl ist keine Abhängigkeit mehr von .NET Core für macOS und .NET Core für Linux.
  • Konsistentes Verhalten auf allen .NET-Plattformen.

Wenn diese Änderung nicht erwünscht ist, können Sie auf Windows weiterhin verwenden, indem Sie WinHttpHandler auf NuGet Paket verweisen und es manuell an HttpClient den Konstruktor von übergeben.

Konfigurieren des Verhaltens mithilfe von Laufzeitkonfigurationsoptionen

Bestimmte Aspekte des Verhaltens von HttpClient können über Laufzeitkonfigurationsoptionenangepasst werden. Das Verhalten dieser Switches unterscheidet sich jedoch durch .NET-Versionen. In .NET Core 2.1 bis 3.1 können Sie beispielsweise konfigurieren, ob SocketsHttpHandler standardmäßig verwendet wird, aber diese Option ist ab .NET 5.0 nicht mehr verfügbar.

Konstruktoren

HttpClient()

Initialisiert eine neue Instanz der HttpClient-Klasse mithilfe eines HttpClientHandler-Objekts, das bei Freigabe dieser Instanz freigegeben wird.

HttpClient(HttpMessageHandler)

Initialisiert eine neue Instanz der HttpClient-Klasse mit dem angegebenen Handler. Der Handler wird freigegeben, wenn diese Instanz freigegeben wird.

HttpClient(HttpMessageHandler, Boolean)

Initialisiert eine neue Instanz der HttpClient-Klasse mit dem bereitgestellten Handler und gibt an, ob dieser Handler freigegeben werden soll, wenn diese Instanz freigegeben wird.

Eigenschaften

BaseAddress

Ruft die Basisadresse des URI (Uniform Resource Identifier) der Internetressource ab, die verwendet wird, wenn Anforderungen gesendet werden, oder legt diese fest.

DefaultProxy

Ruft den globalen HTTP-Proxy ab oder legt diesen fest.

DefaultRequestHeaders

Ruft die Header ab, die mit jeder Anforderung gesendet werden sollen.

DefaultRequestVersion

Ruft die HTTP-Standardversion ab, die für nachfolgende Anforderungen dieser HttpClient-Klasse verwendet wird, oder legt diese fest.

DefaultVersionPolicy

Ruft die Standardversionsrichtlinie für implizit erstellte Anforderungen in Hilfsmethoden (z. B. GetAsync(String) und PostAsync(String, HttpContent)) ab oder legt sie fest.

MaxResponseContentBufferSize

Ruft beim Lesen des Antwortinhalts die maximale Anzahl zwischenzuspeichernder Bytes ab oder legt diese fest.

Timeout

Ruft die Zeitspanne ab, nach der das Zeitlimit der Anforderung überschritten ist, oder legt diese fest.

Methoden

CancelPendingRequests()

Alle ausstehenden Anforderungen für diese Instanz abbrechen.

DeleteAsync(String)

Eine DELETE-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

DeleteAsync(String, CancellationToken)

Eine DELETE-Anforderung für den angegebenen URI mit einem Abbruchtoken als asynchronen Vorgang senden.

DeleteAsync(Uri)

Eine DELETE-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

DeleteAsync(Uri, CancellationToken)

Eine DELETE-Anforderung für den angegebenen URI mit einem Abbruchtoken als asynchronen Vorgang senden.

Dispose()

Gibt die vom HttpMessageInvoker verwendeten, nicht verwalteten Ressourcen frei und verwirft die verwalteten Ressourcen.

(Geerbt von HttpMessageInvoker)
Dispose(Boolean)

Gibt die vom HttpClient verwendeten, nicht verwalteten Ressourcen frei und verwirft optional auch die verwalteten Ressourcen.

Equals(Object)

Bestimmt, ob das angegebene Objekt gleich dem aktuellen Objekt ist.

(Geerbt von Object)
GetAsync(String)

Eine GET-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

GetAsync(String, CancellationToken)

Eine GET-Anforderung für den angegebenen URI mit einem Abbruchtoken als asynchronen Vorgang senden.

GetAsync(String, HttpCompletionOption)

Eine GET-Anforderung an den angegebenen URI mit einer HTTP-Abschlussoption als asynchronen Vorgang senden.

GetAsync(String, HttpCompletionOption, CancellationToken)

Eine GET-Anforderung an den angegebenen URI mit einer HTTP-Abschlussoption und einem Abbruchtoken als asynchronen Vorgang senden.

GetAsync(Uri)

Eine GET-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

GetAsync(Uri, CancellationToken)

Eine GET-Anforderung für den angegebenen URI mit einem Abbruchtoken als asynchronen Vorgang senden.

GetAsync(Uri, HttpCompletionOption)

Eine GET-Anforderung an den angegebenen URI mit einer HTTP-Abschlussoption als asynchronen Vorgang senden.

GetAsync(Uri, HttpCompletionOption, CancellationToken)

Eine GET-Anforderung an den angegebenen URI mit einer HTTP-Abschlussoption und einem Abbruchtoken als asynchronen Vorgang senden.

GetByteArrayAsync(String)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Antworttext in einem asynchronen Vorgang als Bytearray zurück.

GetByteArrayAsync(String, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Antworttext in einem asynchronen Vorgang als Bytearray zurück.

GetByteArrayAsync(Uri)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Bytearray in einem asynchronen Vorgang zurück.

GetByteArrayAsync(Uri, CancellationToken)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Bytearray in einem asynchronen Vorgang zurück.

GetHashCode()

Fungiert als Standardhashfunktion.

(Geerbt von Object)
GetStreamAsync(String)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Datenstrom in einem asynchronen Vorgang zurück.

GetStreamAsync(String, CancellationToken)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Datenstrom in einem asynchronen Vorgang zurück.

GetStreamAsync(Uri)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Datenstrom in einem asynchronen Vorgang zurück.

GetStreamAsync(Uri, CancellationToken)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Datenstrom in einem asynchronen Vorgang zurück.

GetStringAsync(String)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Zeichenfolge in einem asynchronen Vorgang zurück.

GetStringAsync(String, CancellationToken)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Zeichenfolge in einem asynchronen Vorgang zurück.

GetStringAsync(Uri)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Zeichenfolge in einem asynchronen Vorgang zurück.

GetStringAsync(Uri, CancellationToken)

Senden Sie eine GET-Anforderung an den angegebenen URI und geben Sie den Antworttext als Zeichenfolge in einem asynchronen Vorgang zurück.

GetType()

Ruft den Type der aktuellen Instanz ab.

(Geerbt von Object)
MemberwiseClone()

Erstellt eine flache Kopie des aktuellen Object.

(Geerbt von Object)
PatchAsync(String, HttpContent)

Sendet eine PATCH-Anforderung an einen Uri, der als eine Zeichenfolge als asynchroner Vorgang festgelegt ist.

PatchAsync(String, HttpContent, CancellationToken)

Sendet eine PATCH-Anforderung mit einem Abbruchtoken an einen URI, dargestellt als Zeichenfolge als asynchroner Vorgang.

PatchAsync(Uri, HttpContent)

Sendet eine PATCH-Anforderung als asynchronen Vorgang.

PatchAsync(Uri, HttpContent, CancellationToken)

Sendet eine PATCH-Anforderung mit einem Abbruchtoken als einen asynchronen Vorgang.

PostAsync(String, HttpContent)

Eine POST-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

PostAsync(String, HttpContent, CancellationToken)

Eine POST-Anforderung mit einem Abbruchtoken als asynchronen Vorgang senden.

PostAsync(Uri, HttpContent)

Eine POST-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

PostAsync(Uri, HttpContent, CancellationToken)

Eine POST-Anforderung mit einem Abbruchtoken als asynchronen Vorgang senden.

PutAsync(String, HttpContent)

Eine PUT-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

PutAsync(String, HttpContent, CancellationToken)

Eine PUT-Anforderung mit einem Abbruchtoken als asynchronen Vorgang senden.

PutAsync(Uri, HttpContent)

Eine PUT-Anforderung an den angegebenen URI als asynchronen Vorgang senden.

PutAsync(Uri, HttpContent, CancellationToken)

Eine PUT-Anforderung mit einem Abbruchtoken als asynchronen Vorgang senden.

Send(HttpRequestMessage)

Sendet eine HTTP-Anforderung mit der angegebenen Anforderung.

Send(HttpRequestMessage, CancellationToken)

Sendet eine HTTP-Anforderung mit der angegebenen Anforderung und einem Abbruchtoken.

Send(HttpRequestMessage, CancellationToken)

Sendet eine HTTP-Anforderung mit der angegebenen Anforderung und einem Abbruchtoken.

(Geerbt von HttpMessageInvoker)
Send(HttpRequestMessage, HttpCompletionOption)

Sendet eine HTTP-Anforderung.

Send(HttpRequestMessage, HttpCompletionOption, CancellationToken)

Sendet eine HTTP-Anforderung mit der angegebenen Anforderung, der Abschlussoption und einem Abbruchtoken.

SendAsync(HttpRequestMessage)

Senden Sie eine HTTP-Anforderung als asynchronen Vorgang.

SendAsync(HttpRequestMessage, CancellationToken)

Senden Sie eine HTTP-Anforderung als asynchronen Vorgang.

SendAsync(HttpRequestMessage, HttpCompletionOption)

Senden Sie eine HTTP-Anforderung als asynchronen Vorgang.

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

Senden Sie eine HTTP-Anforderung als asynchronen Vorgang.

ToString()

Gibt eine Zeichenfolge zurück, die das aktuelle Objekt darstellt.

(Geerbt von Object)

Erweiterungsmethoden

GetFromJsonAsync(HttpClient, String, Type, JsonSerializerOptions, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync(HttpClient, String, Type, JsonSerializerContext, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync(HttpClient, String, Type, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync(HttpClient, Uri, Type, JsonSerializerOptions, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync(HttpClient, Uri, Type, JsonSerializerContext, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync(HttpClient, Uri, Type, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync<TValue>(HttpClient, String, JsonSerializerOptions, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync<TValue>(HttpClient, String, JsonTypeInfo<TValue>, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync<TValue>(HttpClient, String, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync<TValue>(HttpClient, Uri, JsonSerializerOptions, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync<TValue>(HttpClient, Uri, JsonTypeInfo<TValue>, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

GetFromJsonAsync<TValue>(HttpClient, Uri, CancellationToken)

Sendet eine GET-Anforderung an den angegebenen URI und gibt den Wert zurück, der sich beim Deserialisieren des Antworttexts als JSON in einem asynchronen Vorgang ergibt.

PostAsJsonAsync<TValue>(HttpClient, String, TValue, JsonSerializerOptions, CancellationToken)

Sendet einer POST-Anforderung an den angegebenen URI, der den als JSON serialisierten value im Anforderungstext enthält.

PostAsJsonAsync<TValue>(HttpClient, String, TValue, JsonTypeInfo<TValue>, CancellationToken)

Sendet einer POST-Anforderung an den angegebenen URI, der den als JSON serialisierten value im Anforderungstext enthält.

PostAsJsonAsync<TValue>(HttpClient, String, TValue, CancellationToken)

Sendet einer POST-Anforderung an den angegebenen URI, der den als JSON serialisierten value im Anforderungstext enthält.

PostAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonSerializerOptions, CancellationToken)

Sendet einer POST-Anforderung an den angegebenen URI, der den als JSON serialisierten value im Anforderungstext enthält.

PostAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonTypeInfo<TValue>, CancellationToken)

Sendet einer POST-Anforderung an den angegebenen URI, der den als JSON serialisierten value im Anforderungstext enthält.

PostAsJsonAsync<TValue>(HttpClient, Uri, TValue, CancellationToken)

Sendet einer POST-Anforderung an den angegebenen URI, der den als JSON serialisierten value im Anforderungstext enthält.

PutAsJsonAsync<TValue>(HttpClient, String, TValue, JsonSerializerOptions, CancellationToken)

Senden einer PUT-Anforderung an den angegebenen URI, der den value serialisiert als JSON-Code im Anforderungstext enthält.

PutAsJsonAsync<TValue>(HttpClient, String, TValue, JsonTypeInfo<TValue>, CancellationToken)

Senden einer PUT-Anforderung an den angegebenen URI, der den value serialisiert als JSON-Code im Anforderungstext enthält.

PutAsJsonAsync<TValue>(HttpClient, String, TValue, CancellationToken)

Senden einer PUT-Anforderung an den angegebenen URI, der den value serialisiert als JSON-Code im Anforderungstext enthält.

PutAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonSerializerOptions, CancellationToken)

Senden einer PUT-Anforderung an den angegebenen URI, der den value serialisiert als JSON-Code im Anforderungstext enthält.

PutAsJsonAsync<TValue>(HttpClient, Uri, TValue, JsonTypeInfo<TValue>, CancellationToken)

Senden einer PUT-Anforderung an den angegebenen URI, der den value serialisiert als JSON-Code im Anforderungstext enthält.

PutAsJsonAsync<TValue>(HttpClient, Uri, TValue, CancellationToken)

Senden einer PUT-Anforderung an den angegebenen URI, der den value serialisiert als JSON-Code im Anforderungstext enthält.

Gilt für

Siehe auch