System.Net.Http.HttpClient sınıfı

  • Makale

Bu makale, bu API'nin başvuru belgelerine ek açıklamalar sağlar.

HttpClient Sınıf örneği, HTTP istekleri göndermek için bir oturum görevi görür. Örnek HttpClient , bu örnek tarafından yürütülen tüm isteklere uygulanan bir ayar koleksiyonudur. Buna ek olarak, her HttpClient örnek kendi bağlantı havuzunu kullanarak isteklerini diğer HttpClient örnekler tarafından yürütülen isteklerden yalıtmaktadır.

Örnek Oluşturma

HttpClient bir kez örneği oluşturulup bir uygulamanın ömrü boyunca yeniden kullanılması amaçlanmıştır. .NET Core ve .NET 5+ içinde HttpClient, işleyici örneğinin içindeki bağlantıları havuza alır ve birden çok istekte bağlantıyı yeniden kullanır. Her istek için bir HttpClient sınıfı örneği oluşturursanız, ağır yükler altında kullanılabilen yuva sayısı tükenir. Bu tükenme hatalara SocketException neden olur.

Oluşturucunun bir parçası olarak HttpClientHandler bir "işleyici" (veya .NET Core 2.1 veya SocketsHttpHandler üzeri) geçirerek ek seçenekleri yapılandırabilirsiniz. bir istek gönderildikten sonra işleyicideki bağlantı özellikleri değiştirilemez, bu nedenle bağlantı özelliklerini değiştirmeniz gerekiyorsa yeni bir HttpClient örneği oluşturmanın bir nedeni olabilir. Farklı istekler farklı ayarlar gerektiriyorsa, bu durum bir uygulamanın her örneğin uygun şekilde yapılandırıldığı ve ilgili istemcide istekler verildiği birden çok HttpClient örneğe sahip olmasına da yol açabilir.

HttpClient yalnızca bir bağlantı oluşturulduğunda DNS girdilerini çözümler. DNS sunucusu tarafından belirtilen yaşam süresi (TTL) sürelerini izlemez. DNS girişleri düzenli olarak değişirse ve bu bazı kapsayıcı senaryolarında gerçekleşebilirse, istemci bu güncelleştirmelere saygı duymaz. Bu sorunu çözmek için, özelliği ayarlayarak SocketsHttpHandler.PooledConnectionLifetime bağlantının ömrünü sınırlayabilirsiniz; böylece bağlantı değiştirildiğinde DNS araması gerekir.

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

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

        httpClient = new HttpClient(socketsHandler);
    }
}

Yalnızca bir HttpClient örneği oluşturmaya alternatif olarak, sizin için HttpClient örneklerini yönetmek için de kullanabilirsiniz IHttpClientFactory . Daha fazla bilgi için bkz . HttpClient kullanma yönergeleri.

Türev

ayrıca HttpClient , daha belirli HTTP istemcileri için temel sınıf işlevi görür. Örneğin, bir Facebook web hizmetine (örneğin, bir yöntem) özgü ek yöntemler sağlayan bir GetFriends FacebookHttpClient olabilir. Türetilmiş sınıflar, sınıftaki sanal yöntemleri geçersiz kılmamalıdır. Bunun yerine, herhangi bir istek öncesi veya istek sonrası işlemeyi yapılandırmak için kabul eden HttpMessageHandler bir oluşturucu aşırı yüklemesi kullanın.

Taşımalar

HttpClient, çalıştığı her platformda kullanılabilen alt düzey işlevselliği sarmalayan üst düzey bir API'dir.

Her platformda en HttpClient iyi kullanılabilir taşımayı kullanmaya çalışır:

Konak/Çalışma Zamanı Backend
Windows/.NET Framework HttpWebRequest
Windows/Mono HttpWebRequest
Windows/UWP Windows yerel WinHttpHandler (HTTP 2.0 özellikli)
Windows/.NET Core 1.0-2.0 Windows yerel WinHttpHandler (HTTP 2.0 özellikli)
Android/Xamarin Derleme zamanında seçildi. Android'in yerel verilerini kullanmak için kullanılabilir HttpWebRequest veya yapılandırılabilir HttpURLConnection
iOS, tvOS, watchOS/Xamarin Derleme zamanında seçildi. HttpWebRequest Apple'ın NSUrlSession (HTTP 2.0 özellikli) kullanımını kullanabilir veya yapılandırılabilir
macOS/Xamarin Derleme zamanında seçildi. HttpWebRequest Apple'ın NSUrlSession (HTTP 2.0 özellikli) kullanımını kullanabilir veya yapılandırılabilir
macOS/Mono HttpWebRequest
macOS/.NET Core 1.0-2.0 libcurl-tabanlı HTTP aktarımı (HTTP 2.0 özellikli)
Linux/Mono HttpWebRequest
Linux/.NET Core 1.0-2.0 libcurl-tabanlı HTTP aktarımı (HTTP 2.0 özellikli)
.NET Core 2.1 ve üzeri System.Net.Http.SocketsHttpHandler

Kullanıcılar ayrıca bir alan oluşturucuyu çağırarak HttpClient için HttpClient belirli bir HttpMessageHandleraktarım yapılandırabilir.

.NET Framework & Mono

.NET Framework ve Mono'da varsayılan olarak, HttpWebRequest sunucuya istek göndermek için kullanılır. Bu davranış, bir parametre ile oluşturucu aşırı yüklemelerinden birinde farklı bir HttpMessageHandler işleyici belirtilerek değiştirilebilir. Kimlik doğrulaması veya önbelleğe alma gibi özelliklere ihtiyacınız varsa, ayarları yapılandırmak için kullanabilirsiniz WebRequestHandler ve örnek oluşturucuya geçirilebilir. Döndürülen işleyici, parametresi olan HttpMessageHandler bir oluşturucu aşırı yüklemesine geçirilebilir.

.NET Core

.NET Core 2.1'den başlayarak, System.Net.Http.SocketsHttpHandler yerine sınıfı HttpClientHandler gibi HttpClientüst düzey HTTP ağ sınıfları tarafından kullanılan uygulamayı sağlar. kullanımı SocketsHttpHandler bir dizi avantaj sunar:

  • Önceki uygulamayla karşılaştırıldığında önemli bir performans artışı.
  • Dağıtım ve bakımı basitleştiren platform bağımlılıklarının ortadan kaldırılması. Örneğin, libcurl artık macOS için .NET Core ve Linux için .NET Core bağımlılığı değildir.
  • Tüm .NET platformları genelinde tutarlı davranış.

Bu değişiklik istenmeyen bir durumsa, Windows'ta NuGet paketinebaşvurarak ve el ile HttpClient'ın oluşturucusunageçirerek kullanmaya WinHttpHandler devam edebilirsiniz.

Çalışma zamanı yapılandırma seçeneklerini kullanarak davranışı yapılandırma

Çalışma zamanı yapılandırma seçenekleri aracılığıyla davranışların belirli yönleri HttpClientözelleştirilebilir. Ancak, bu anahtarların davranışı .NET sürümlerine göre farklılık gösterir. Örneğin, .NET Core 2.1 - 3.1'de varsayılan olarak kullanılıp kullanılmayacağını SocketsHttpHandler yapılandırabilirsiniz, ancak bu seçenek artık .NET 5'den başlayarak kullanılamaz.

Bağlantı havuzu

HttpClient mümkün olduğunda HTTP bağlantılarını havuza alır ve bunları birden fazla istek için kullanır. Bağlantı el sıkışması yalnızca bir kez yapıldığından, bu durum özellikle HTTPS istekleri için önemli bir performans avantajına sahip olabilir.

Bağlan ion havuzu özellikleri, , ve gibi bir HttpClientHandler üzerinde yapılandırılabilir veya SocketsHttpHandler oluşturma sırasında geçirilebilirMaxConnectionsPerServer.PooledConnectionLifetimePooledConnectionIdleTimeout

HttpClient örneğinin atılması açık bağlantıları kapatır ve bekleyen istekleri iptal eder.

Not

Aynı sunucuya eşzamanlı olarak HTTP/1.1 istekleri gönderirseniz, yeni bağlantılar oluşturulabilir. Örneği yeniden kullansanız HttpClient bile, istek oranı yüksekse veya güvenlik duvarı sınırlamaları varsa, varsayılan TCP temizleme zamanlayıcıları nedeniyle kullanılabilir yuvaları tüketebilir. Eşzamanlı bağlantı sayısını sınırlamak için özelliğini ayarlayabilirsiniz MaxConnectionsPerServer . Varsayılan olarak, eşzamanlı HTTP/1.1 bağlantı sayısı sınırsızdır.

Arabelleğe alma ve istek ömrü

Varsayılan olarak, HttpClient yöntemleri (hariç GetStreamAsync) sunucudan gelen yanıtları arabelleğe alır ve zaman uyumsuz sonucu döndürmeden önce tüm yanıt gövdesini belleğe okur. Bu istekler aşağıdakilerden biri gerçekleşene kadar devam eder:

Bazı yöntem aşırı yüklemelerinde kullanılabilen parametresini HttpCompletionOption kullanarak istek başına arabelleğe alma davranışını değiştirebilirsiniz. Bu bağımsız değişken, yalnızca yanıt üst bilgilerini okuduktan sonra veya yanıt içeriğini okuyup arabelleğe aldıktan sonra tamamlandı olarak kabul edilmesi gerekip gerekmediğini Task<TResult> belirtmek için kullanılabilir.

Ad alanında System.Net.Http ve ilgili sınıfları kullanan HttpClient uygulamanız büyük miktarda veri (50 megabayt veya daha fazla) indirmeyi planlıyorsa, uygulamanın bu indirmeleri akışla aktarması ve varsayılan arabelleğe almayı kullanmaması gerekir. Varsayılan arabelleğe almayı kullanırsanız, istemci bellek kullanımı çok büyük olur ve bu da önemli ölçüde düşük performansa neden olur.

İş parçacığı güvenliği

Aşağıdaki yöntemler iş parçacığı güvenlidir:

Proxy'ler

HttpClient varsayılan olarak platforma bağlı olarak ortam değişkenlerinden veya kullanıcı/sistem ayarlarından ara sunucu yapılandırmasını okur. Öncelik sırasına göre bir WebProxy veya IWebProxy geçirerek bu davranışı değiştirebilirsiniz:

  • Proxy HttpClient oluşturma sırasında geçirilen bir HttpClientHandler üzerindeki özelliği
  • DefaultProxy Statik özelliği (tüm örnekleri etkiler)

kullanarak UseProxyproxy'yi devre dışı bırakabilirsiniz. Windows kullanıcıları için varsayılan yapılandırma, ağ bulma kullanarak bir ara sunucuyu algılamayı denemektir ve bu da yavaş olabilir. Ara sunucu gerekli olmadığı bilinen yüksek aktarım hızı uygulamaları için ara sunucuyu devre dışı bırakmanız gerekir.

Proxy ayarları (gibi Credentials) yalnızca httpclient kullanılarak ilk istek yapılmadan önce değiştirilmelidir. HttpClient'ın ilk kez kullanılmasından sonra yapılan değişiklikler sonraki isteklere yansıtılamayabilir.

Zaman aşımları

HttpClient örneğinden gelen tüm HTTP istekleri için varsayılan bir zaman aşımı ayarlamak için kullanabilirsiniz Timeout . Zaman aşımı yalnızca bir isteğin/yanıtın başlatılmasına neden olan xxxAsync yöntemleri için geçerlidir. Zaman aşımına ulaşılırsa, Task<TResult> bu istek için iptal edilir.

HttpClient nesnesini oluştururken bir SocketsHttpHandler örneği geçirirseniz bazı ek zaman aşımları ayarlayabilirsiniz:

Özellik Açıklama
ConnectTimeout bir isteğin yeni bir TCP bağlantısının oluşturulmasını gerektirdiğinde kullanılan zaman aşımını belirtir. Zaman aşımı oluşursa istek Task<TResult> iptal edilir.
PooledConnectionLifetime Bağlantı havuzundaki her bağlantı için kullanılacak zaman aşımını belirtir. Bağlantı boştaysa, bağlantı hemen kapatılır; aksi takdirde, geçerli isteğin sonunda bağlantı kapatılır.
PooledConnectionIdleTimeout Bağlantı havuzundaki bir bağlantı bu kadar süre boşta kalırsa, bağlantı kapatılır.
Expect100ContinueTimeout İstekte "Bekleme: 100-devam" üst bilgisi varsa, zaman aşımına veya "100-devam" yanıtı alınana kadar içerik göndermeyi geciktirir.

HttpClient yalnızca bağlantılar oluşturulduğunda DNS girdilerini çözümler. DNS sunucusu tarafından belirtilen yaşam süresi (TTL) sürelerini izlemez. DNS girdileri düzenli olarak değişiyorsa ve bu bazı kapsayıcı senaryolarında gerçekleşebiliyorsa, bağlantıyı değiştirirken DNS araması yapılması için bağlantının ömrünü sınırlamak için öğesini kullanabilirsiniz PooledConnectionLifetime .