System.Net.Http.HttpClient-Klasse

  • Artikel

Dieser Artikel enthält ergänzende Hinweise zur Referenzdokumentation für diese API.

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

Instanziierung

HttpClient soll einmal instanziiert und während der gesamten Lebensdauer einer Anwendung wiederverwendet werden. In .NET Core und .NET 5+ werden HttpClient-Verbindungen innerhalb der Handlerinstanz und eine Verbindung über mehrere Anforderungen hinweg wiederverwendet. Wenn Sie eine HttpClient-Klasse für jede Anforderung instanziieren, wird die Anzahl der sockets, die unter schweren Lasten verfügbar sind, erschöpft. Diese Erschöpfung führt zu SocketException Fehlern.

Sie können zusätzliche Optionen konfigurieren, indem Sie einen "Handler" übergeben, z HttpClientHandler . B. (oder SocketsHttpHandler in .NET Core 2.1 oder höher), als Teil des Konstruktors. Die Verbindungseigenschaften des Handlers können nicht geändert werden, nachdem eine Anforderung übermittelt wurde. Ein Grund zum Erstellen einer neuen HttpClient-Instanz wäre daher, wenn Sie die Verbindungseigenschaften ändern müssen. Wenn unterschiedliche Anforderungen unterschiedliche Einstellungen erfordern, kann dies auch dazu führen, dass eine Anwendung mehrere HttpClient Instanzen aufweist, wobei jede Instanz entsprechend konfiguriert ist und dann Anforderungen auf dem relevanten Client ausgestellt werden.

HttpClient löst nur DNS-Einträge auf, wenn eine Verbindung erstellt wird. Die vom DNS-Server angegebene Gültigkeitsdauer (Time To Live, TTL) wird nicht nachverfolgt. Wenn sich DNS-Einträge regelmäßig ändern, was in einigen Containerszenarien vorkommen kann, berücksichtigt der Client diese Updates nicht. Um dieses Problem zu beheben, können Sie die Gültigkeitsdauer der Verbindung einschränken, indem Sie die SocketsHttpHandler.PooledConnectionLifetime-Eigenschaft festlegen, sodass die DNS-Suche erforderlich ist, wenn die Verbindung ersetzt wird.

public class GoodController : ApiController
{
    private static readonly HttpClient httpClient;

    static GoodController()
    {
        var socketsHandler = new SocketsHttpHandler
        {
            PooledConnectionLifetime = TimeSpan.FromMinutes(2)
        };

        httpClient = new HttpClient(socketsHandler);
    }
}

Alternativ zum Erstellen nur einer HttpClient-Instanz können Sie auch IHttpClientFactory die HttpClient-Instanzen für Sie verwalten. Weitere Informationen finden Sie unter Richtlinien für die Verwendung von HttpClient.

Ableitung

Dies HttpClient dient auch als Basisklasse für spezifischere HTTP-Clients. Ein Beispiel wäre ein FacebookHttpClient, der zusätzliche Methoden bereitstellt, die für einen Facebook-Webdienst spezifisch sind (z. B. eine GetFriends Methode). Abgeleitete Klassen sollten die virtuellen Methoden für die Klasse nicht außer Kraft setzen. Verwenden Sie stattdessen eine Konstruktorüberladung, die akzeptiert HttpMessageHandler , um jede Voranforderungs- oder Nachanforderungsverarbeitung zu konfigurieren.

Transportprotokolle

Dies HttpClient ist eine allgemeine API, die die funktionalität der unteren Ebene umschließt, die auf jeder Plattform verfügbar ist, auf der sie ausgeführt wird.

Auf jeder Plattform versucht, HttpClient den besten verfügbaren Transport zu verwenden:

Host/Runtime Back-End
Windows/.NET Framework HttpWebRequest
Windows/Mono HttpWebRequest
Windows/UWP Windows native WinHttpHandler (HTTP 2.0-fähig)
Windows/.NET Core 1.0-2.0 Windows native WinHttpHandler (HTTP 2.0-fähig)
Android/Xamarin Zur Buildzeit ausgewählt. Kann entweder für die native Verwendung von Android verwendet HttpWebRequest oder konfiguriert werden HttpURLConnection
iOS, tvOS, watchOS/Xamarin Zur Buildzeit ausgewählt. Kann entweder für die Verwendung von Apples NSUrlSession (HTTP 2.0-fähig) verwendet HttpWebRequest oder konfiguriert werden.
macOS/Xamarin Zur Buildzeit ausgewählt. Kann entweder für die Verwendung von Apples NSUrlSession (HTTP 2.0-fähig) verwendet HttpWebRequest oder konfiguriert werden.
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 konfigurieren HttpClient , indem sie den Konstruktor aufrufen, der HttpClient einen aufruft HttpMessageHandler.

.NET Framework & Mono

Standardmäßig wird .NET Framework und Mono verwendet, HttpWebRequest um Anforderungen an den Server zu senden. Dieses Verhalten kann geändert werden, indem ein anderer Handler in einer der Konstruktorüberladungen mit einem HttpMessageHandler Parameter angegeben wird. Wenn Sie Features wie Authentifizierung oder Zwischenspeicherung benötigen, können WebRequestHandler Sie Einstellungen konfigurieren und die Instanz kann an den Konstruktor übergeben werden. Der zurückgegebene Handler kann an eine Konstruktorüberladung übergeben werden, die über einen HttpMessageHandler Parameter verfügt.

.NET Core

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

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

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

Konfigurieren des Verhaltens mithilfe von Laufzeitkonfigurationsoptionen

Bestimmte Aspekte des Verhaltens von HttpClient's Verhalten können über Laufzeitkonfigurationsoptionen angepasst werden. Das Verhalten dieser Switches unterscheidet sich jedoch von .NET-Versionen. In .NET Core 2.1 - 3.1 können Sie z. B. konfigurieren, ob SocketsHttpHandler standardmäßig verwendet wird, diese Option ist jedoch ab .NET 5 nicht mehr verfügbar.

Verbindungspooling

HttpClient-Pools HTTP-Verbindungen, sofern möglich und verwendet sie für mehr als eine Anforderung. Dies kann einen erheblichen Leistungsvorteil haben, insbesondere für HTTPS-Anforderungen, da der Verbindungs-Handshake nur einmal ausgeführt wird.

Verbinden ion-Pooleigenschaften können während der Konstruktion für ein HttpClientHandler oder SocketsHttpHandler übergeben werden, einschließlich MaxConnectionsPerServer, PooledConnectionIdleTimeoutund PooledConnectionLifetime.

Durch das Löschen der HttpClient-Instanz werden die geöffneten Verbindungen geschlossen und alle ausstehenden Anforderungen abgebrochen.

Hinweis

Wenn Sie gleichzeitig HTTP/1.1-Anforderungen an denselben Server senden, können neue Verbindungen erstellt werden. Auch wenn Sie die HttpClient Instanz wiederverwenden, wenn die Anzahl der Anforderungen hoch ist oder Firewalleinschränkungen bestehen, die die verfügbaren Sockets aufgrund der standardmäßigen TCP-sauber uptimer ausschöpfen können. Um die Anzahl der gleichzeitigen Verbindungen zu begrenzen, können Sie die MaxConnectionsPerServer Eigenschaft festlegen. Standardmäßig ist die Anzahl gleichzeitiger HTTP/1.1-Verbindungen unbegrenzt.

Puffer- und Anforderungsdauer

Standardmäßig puffern HttpClient-Methoden (mit Ausnahme GetStreamAsync) die Antworten vom Server, und lesen sie den gesamten Antworttext in den Arbeitsspeicher, bevor das asynchrone Ergebnis zurückgegeben wird. Diese Anforderungen werden bis zu einem der folgenden Anforderungen fortgesetzt:

Sie können das Pufferverhalten auf Anforderungsbasis mithilfe des Parameters ändern, der HttpCompletionOption für einige Methodenüberladungen verfügbar ist. Dieses Argument kann verwendet werden, um anzugeben, ob das Task<TResult> Argument nach dem Lesen nur der Antwortheader oder nach dem Lesen und Puffern des Antwortinhalts als vollständig betrachtet werden soll.

Wenn Ihre App, die klassen im System.Net.Http Namespace verwendet HttpClient und verwandte Klassen verwendet, große Datenmengen (50 MB oder mehr) herunterladen möchte, sollte die App diese Downloads streamen und nicht die Standardpufferung verwenden. Wenn Sie die Standardpufferung verwenden, wird die Clientspeicherauslastung sehr groß, was zu erheblich reduzierter Leistung führt.

Threadsicherheit

Die folgenden Methoden sind threadsicher:

Proxys

Standardmäßig liest HttpClient die Proxykonfiguration aus Umgebungsvariablen oder Benutzer-/Systemeinstellungen, je nach Plattform. Sie können dieses Verhalten ändern, indem Sie eine WebProxy oder IWebProxy an die Reihenfolge der Rangfolge übergeben:

  • Die Proxy Eigenschaft für einen HttpClientHandler, der während der HttpClient-Konstruktion übergeben wurde
  • Die DefaultProxy statische Eigenschaft (wirkt sich auf alle Instanzen aus)

Sie können den Proxy mithilfe von UseProxy. Die Standardkonfiguration für Windows-Benutzer besteht darin, einen Proxy mithilfe der Netzwerkermittlung zu testen und zu erkennen, was langsam sein kann. Für Anwendungen mit hohem Durchsatz, bei denen bekannt ist, dass kein Proxy erforderlich ist, sollten Sie den Proxy deaktivieren.

Proxyeinstellungen (wie Credentials) sollten nur geändert werden, bevor die erste Anforderung über den HttpClient erfolgt. Änderungen, die nach der erstmaligen Verwendung des HttpClient vorgenommen wurden, werden möglicherweise nicht in nachfolgenden Anforderungen wiedergegeben.

Timeouts

Sie können ein Timeout Standardtimeout für alle HTTP-Anforderungen aus der HttpClient-Instanz festlegen. Das Timeout gilt nur für die xxxAsync-Methoden, die dazu führen, dass eine Anforderung/Antwort initiiert wird. Wenn das Timeout erreicht ist, wird die Task<TResult> Anforderung für diese Anforderung abgebrochen.

Sie können einige zusätzliche Timeouts festlegen, wenn Sie beim Erstellen des HttpClient-Objekts eine SocketsHttpHandler Instanz übergeben:

Eigenschaft Beschreibung
ConnectTimeout Gibt ein Timeout an, das verwendet wird, wenn eine Anforderung eine neue TCP-Verbindung erstellt werden muss. Wenn das Timeout auftritt, wird die Anforderung Task<TResult> abgebrochen.
PooledConnectionLifetime Gibt ein Timeout an, das für jede Verbindung im Verbindungspool verwendet werden soll. Wenn die Verbindung leer ist, wird die Verbindung sofort geschlossen; andernfalls wird die Verbindung am Ende der aktuellen Anforderung geschlossen.
PooledConnectionIdleTimeout Wenn eine Verbindung im Verbindungspool für diese lange Leerlauf ist, wird die Verbindung geschlossen.
Expect100ContinueTimeout Wenn die Anforderung über einen Header "Erwartet: 100-continue" verfügt, verzögert sich das Senden von Inhalten bis zum Timeout oder bis eine Antwort "100-continue" empfangen wird.

HttpClient löst nur DNS-Einträge auf, wenn die Verbindungen erstellt werden. Die vom DNS-Server angegebene Gültigkeitsdauer (Time To Live, TTL) wird nicht nachverfolgt. Wenn DNS-Einträge regelmäßig geändert werden, was in einigen Containerszenarien passieren kann, können Sie die PooledConnectionLifetime Lebensdauer der Verbindung einschränken, sodass die DNS-Suche beim Ersetzen der Verbindung erforderlich ist.