Kelas System.Net.Http.HttpClient

  • Artikel

Artikel ini menyediakan keterangan tambahan untuk dokumentasi referensi untuk API ini.

Instans HttpClient kelas bertindak sebagai sesi untuk mengirim permintaan HTTP. Instans HttpClient adalah kumpulan pengaturan yang diterapkan ke semua permintaan yang dijalankan oleh instans tersebut. Selain itu, setiap HttpClient instans menggunakan kumpulan koneksinya sendiri, mengisolasi permintaannya dari permintaan yang dijalankan oleh instans lain HttpClient .

Instancing

HttpClient dimaksudkan untuk diinstansiasi sekali dan digunakan kembali selama masa pakai aplikasi. Di .NET Core dan .NET 5+, HttpClient mengumpulkan koneksi di dalam instans handler dan menggunakan kembali koneksi di beberapa permintaan. Jika Anda membuat instans kelas HttpClient untuk setiap permintaan, jumlah soket yang tersedia di bawah beban berat akan habis. Kelelahan ini akan mengakibatkan SocketException kesalahan.

Anda dapat mengonfigurasi opsi tambahan dengan meneruskan "handler", seperti HttpClientHandler (atau SocketsHttpHandler di .NET Core 2.1 atau yang lebih baru), sebagai bagian dari konstruktor. Properti koneksi pada handler tidak dapat diubah setelah permintaan dikirimkan, jadi salah satu alasan untuk membuat instans HttpClient baru adalah jika Anda perlu mengubah properti koneksi. Jika permintaan yang berbeda memerlukan pengaturan yang berbeda, ini juga dapat menyebabkan aplikasi memiliki beberapa HttpClient instans, di mana setiap instans dikonfigurasi dengan tepat, lalu permintaan dikeluarkan pada klien yang relevan.

HttpClient hanya menyelesaikan entri DNS saat koneksi dibuat. Ini tidak melacak durasi hidup (TTL) yang ditentukan oleh server DNS. Jika entri DNS berubah secara teratur, yang dapat terjadi dalam beberapa skenario kontainer, klien tidak akan menghormati pembaruan tersebut. Untuk mengatasi masalah ini, Anda dapat membatasi masa pakai koneksi dengan mengatur SocketsHttpHandler.PooledConnectionLifetime properti , sehingga pencarian DNS diperlukan saat koneksi diganti.

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

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

        httpClient = new HttpClient(socketsHandler);
    }
}

Sebagai alternatif untuk membuat hanya satu instans HttpClient, Anda juga dapat menggunakan IHttpClientFactory untuk mengelola instans HttpClient untuk Anda. Untuk informasi selengkapnya, lihat Panduan untuk menggunakan HttpClient.

Derivasi

juga HttpClient bertindak sebagai kelas dasar untuk klien HTTP yang lebih spesifik. Contohnya adalah FacebookHttpClient yang menyediakan metode tambahan khusus untuk layanan web Facebook (misalnya, GetFriends metode). Kelas turunan tidak boleh mengambil alih metode virtual pada kelas . Sebagai gantinya, gunakan kelebihan beban konstruktor yang menerima untuk mengonfigurasi pemrosesan pra-permintaan atau pasca-permintaan HttpMessageHandler .

Transportasi

HttpClient adalah API tingkat tinggi yang membungkus fungsionalitas tingkat bawah yang tersedia di setiap platform tempatnya berjalan.

Pada setiap platform, HttpClient mencoba menggunakan transportasi terbaik yang tersedia:

Host/Runtime Backend
Windows/.NET Framework HttpWebRequest
Windows/Mono HttpWebRequest
Windows/UWP Windows native WinHttpHandler (berkemampu HTTP 2.0)
Windows/.NET Core 1.0-2.0 Windows native WinHttpHandler (berkemampu HTTP 2.0)
Android/Xamarin Dipilih pada build-time. Dapat menggunakan HttpWebRequest atau dikonfigurasi untuk menggunakan asli Android HttpURLConnection
iOS, tvOS, watchOS/Xamarin Dipilih pada build-time. Dapat menggunakan HttpWebRequest atau dikonfigurasi untuk menggunakan Apple NSUrlSession (berkemampukan HTTP 2.0)
macOS/Xamarin Dipilih pada build-time. Dapat menggunakan HttpWebRequest atau dikonfigurasi untuk menggunakan Apple NSUrlSession (berkemampukan HTTP 2.0)
macOS/Mono HttpWebRequest
macOS/.NET Core 1.0-2.0 libcurlTransportasi HTTP berbasis -(berkemampuan HTTP 2.0)
Linux/Mono HttpWebRequest
Linux/.NET Core 1.0-2.0 libcurlTransportasi HTTP berbasis -(berkemampuan HTTP 2.0)
Versi .NET Core 2.1 dan yang lebih baru. System.Net.Http.SocketsHttpHandler

Pengguna juga dapat mengonfigurasi transportasi tertentu dengan HttpClient memanggil HttpClient konstruktor yang mengambil HttpMessageHandler.

.NET Framework & Mono

Secara default pada .NET Framework dan Mono, HttpWebRequest digunakan untuk mengirim permintaan ke server. Perilaku ini dapat dimodifikasi dengan menentukan handler yang berbeda di salah satu overload konstruktor dengan HttpMessageHandler parameter . Jika Anda memerlukan fitur seperti autentikasi atau penembolokan, Anda dapat menggunakan WebRequestHandler untuk mengonfigurasi pengaturan dan instans dapat diteruskan ke konstruktor. Handler yang dikembalikan dapat diteruskan ke kelebihan beban konstruktor yang memiliki HttpMessageHandler parameter .

.NET Core

Dimulai dengan .NET Core 2.1, System.Net.Http.SocketsHttpHandler kelas alih-alih HttpClientHandler menyediakan implementasi yang digunakan oleh kelas jaringan HTTP tingkat lebih tinggi seperti HttpClient. Penggunaan SocketsHttpHandler menawarkan sejumlah keuntungan:

  • Peningkatan performa yang signifikan jika dibandingkan dengan implementasi sebelumnya.
  • Penghapusan dependensi platform, yang menyederhanakan penyebaran dan layanan. Misalnya, libcurl tidak lagi menjadi dependensi pada .NET Core untuk macOS dan .NET Core untuk Linux.
  • Perilaku konsisten di semua platform .NET.

Jika perubahan ini tidak diinginkan, pada Windows Anda dapat terus menggunakan WinHttpHandler dengan merujuk paket NuGet-nya dan meneruskannya ke konstruktor HttpClient secara manual.

Mengonfigurasi perilaku menggunakan opsi konfigurasi runtime

Aspek tertentu dari HttpClientperilaku dapat disesuaikan melalui opsi konfigurasi Runtime. Namun, perilaku sakelar ini berbeda melalui versi .NET. Misalnya, di .NET Core 2.1 - 3.1, Anda dapat mengonfigurasi apakah SocketsHttpHandler digunakan secara default, tetapi opsi tersebut tidak lagi tersedia mulai dari .NET 5.

Pengumpulan koneksi

HttpClient mengumpulkan koneksi HTTP jika memungkinkan dan menggunakannya untuk lebih dari satu permintaan. Ini dapat memiliki manfaat performa yang signifikan, terutama untuk permintaan HTTPS, karena jabat tangan koneksi hanya dilakukan sekali.

properti kumpulan Koneksi ion dapat dikonfigurasi pada HttpClientHandler atau SocketsHttpHandler diteruskan selama konstruksi, termasuk MaxConnectionsPerServer, PooledConnectionIdleTimeout, dan PooledConnectionLifetime.

Membuang instans HttpClient menutup koneksi terbuka dan membatalkan permintaan yang tertunda.

Catatan

Jika Anda secara bersamaan mengirim permintaan HTTP/1.1 ke server yang sama, koneksi baru dapat dibuat. Bahkan jika Anda menggunakan HttpClient kembali instans, jika tingkat permintaan tinggi, atau jika ada batasan firewall, yang dapat menghabiskan soket yang tersedia karena timer pembersihan TCP default. Untuk membatasi jumlah koneksi bersamaan, Anda dapat mengatur MaxConnectionsPerServer properti . Secara default, jumlah koneksi HTTP/1.1 bersamaan tidak terbatas.

Buffering dan masa pakai permintaan

Secara default, metode HttpClient (kecuali GetStreamAsync) buffer respons dari server, membaca semua isi respons ke dalam memori sebelum mengembalikan hasil asinkron. Permintaan tersebut akan berlanjut sampai salah satu hal berikut terjadi:

Anda dapat mengubah perilaku buffering berdasarkan per permintaan menggunakan parameter yang HttpCompletionOption tersedia pada beberapa metode kelebihan beban. Argumen ini dapat digunakan untuk menentukan apakah Task<TResult> harus dianggap selesai setelah hanya membaca header respons, atau setelah membaca dan buffer konten respons.

Jika aplikasi Anda yang menggunakan HttpClient dan kelas terkait di System.Net.Http namespace ingin mengunduh data dalam jumlah besar (50 megabyte atau lebih), aplikasi harus melakukan streaming unduhan tersebut dan tidak menggunakan buffering default. Jika Anda menggunakan buffering default, penggunaan memori klien akan menjadi sangat besar, berpotensi mengakibatkan performa yang berkurang secara substansial.

Keamanan utas

Metode berikut aman untuk utas:

Proksi

Secara default, HttpClient membaca konfigurasi proksi dari variabel lingkungan atau pengaturan pengguna/sistem, tergantung pada platform. Anda dapat mengubah perilaku ini dengan meneruskan WebProxy atau IWebProxy ke, dalam urutan prioritas:

  • Proxy Properti pada HttpClientHandler diteruskan selama konstruksi HttpClient
  • Properti DefaultProxy statis (memengaruhi semua instans)

Anda dapat menonaktifkan proksi menggunakan UseProxy. Konfigurasi default untuk pengguna Windows adalah mencoba dan mendeteksi proksi menggunakan penemuan jaringan, yang bisa lambat. Untuk aplikasi throughput tinggi di mana diketahui bahwa proksi tidak diperlukan, Anda harus menonaktifkan proksi.

Pengaturan proksi (seperti Credentials) harus diubah hanya sebelum permintaan pertama dibuat menggunakan HttpClient. Perubahan yang dilakukan setelah menggunakan HttpClient untuk pertama kalinya mungkin tidak tercermin dalam permintaan berikutnya.

Waktu habis

Anda dapat menggunakan Timeout untuk mengatur batas waktu default untuk semua permintaan HTTP dari instans HttpClient. Batas waktu hanya berlaku untuk metode xxxAsync yang menyebabkan permintaan/respons dimulai. Jika batas waktu tercapai, untuk permintaan tersebut Task<TResult> dibatalkan.

Anda dapat mengatur beberapa batas waktu tambahan jika Anda meneruskan SocketsHttpHandler instans saat membuat objek HttpClient:

Properti Deskripsi
ConnectTimeout Menentukan batas waktu yang digunakan saat permintaan memerlukan koneksi TCP baru untuk dibuat. Jika waktu habis terjadi, permintaan Task<TResult> dibatalkan.
PooledConnectionLifetime Menentukan batas waktu yang akan digunakan untuk setiap koneksi di kumpulan koneksi. Jika koneksi diam, koneksi segera ditutup; jika tidak, koneksi ditutup di akhir permintaan saat ini.
PooledConnectionIdleTimeout Jika koneksi di kumpulan koneksi diam selama ini, koneksi ditutup.
Expect100ContinueTimeout Jika permintaan memiliki header "Expect: 100-continue", permintaan akan menunda pengiriman konten hingga batas waktu atau hingga respons "100 lanjutkan" diterima.

HttpClient hanya menyelesaikan entri DNS saat koneksi dibuat. Ini tidak melacak durasi hidup (TTL) yang ditentukan oleh server DNS. Jika entri DNS berubah secara teratur, yang dapat terjadi dalam beberapa skenario kontainer, Anda dapat menggunakan PooledConnectionLifetime untuk membatasi masa pakai koneksi sehingga pencarian DNS diperlukan saat mengganti koneksi.