Membuat permintaan HTTP menggunakan IHttpClientFactory di ASP.NET Core

Oleh Kirk Larkin, Steve Gordon, Glenn Condron, dan Ryan Nowak.

IHttpClientFactory dapat didaftarkan dan digunakan untuk mengonfigurasi dan membuat HttpClient instance di dalam aplikasi. IHttpClientFactory menawarkan manfaat berikut:

• Menyediakan lokasi pusat untuk penamaan dan konfigurasi instans HttpClient logis. Misalnya, klien bernama github dapat didaftarkan dan dikonfigurasi untuk mengakses GitHub. Klien default dapat didaftarkan untuk akses umum.
• Mengkodifikasi konsep middleware outbound melalui pendelegasian handler di HttpClient. Menyediakan ekstensi untuk middleware berbasis Polly untuk memanfaatkan pendelegasian handler di HttpClient.
• Mengelola pengumpulan dan masa pakai instans HttpClientMessageHandler yang mendasarinya. Manajemen otomatis menghindari masalah DNS umum (Sistem Nama Domain) yang terjadi saat mengelola HttpClient masa pakai secara manual.
• Menambahkan pengalaman pengelogan yang bisa dikonfigurasi (melalui ILogger) untuk semua permintaan yang dikirim melalui klien yang dibuat oleh pabrik.

Kode sampel dalam versi topik ini menggunakan System.Text.Json untuk mendeserialisasi konten JSON yang dikembalikan dalam respons HTTP. Untuk sampel yang menggunakan Json.NET dan ReadAsAsync<T>, gunakan pemilih versi untuk memilih versi 2.x dari topik ini.

Pola konsumsi

Ada beberapa cara menggunakan IHttpClientFactory dalam aplikasi:

• Penggunaan dasar
• Klien bernama khusus
• Klien yang dititik
• Klien yang dihasilkan

Pendekatan terbaiknya tergantung pada persyaratan aplikasi.

Penggunaan dasar

Daftar IHttpClientFactory dengan memanggil AddHttpClient di Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddHttpClient();

Sebuah IHttpClientFactory dapat diminta menggunakan injeksi dependensi (DI). Kode berikut ini menggunakan IHttpClientFactory untuk membuat instansHttpClient:

public class BasicModel : PageModel
{
    private readonly IHttpClientFactory _httpClientFactory;

    public BasicModel(IHttpClientFactory httpClientFactory) =>
        _httpClientFactory = httpClientFactory;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        var httpRequestMessage = new HttpRequestMessage(
            HttpMethod.Get,
            "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches")
        {
            Headers =
            {
                { HeaderNames.Accept, "application/vnd.github.v3+json" },
                { HeaderNames.UserAgent, "HttpRequestsSample" }
            }
        };

        var httpClient = _httpClientFactory.CreateClient();
        var httpResponseMessage = await httpClient.SendAsync(httpRequestMessage);

        if (httpResponseMessage.IsSuccessStatusCode)
        {
            using var contentStream =
                await httpResponseMessage.Content.ReadAsStreamAsync();
            
            GitHubBranches = await JsonSerializer.DeserializeAsync
                <IEnumerable<GitHubBranch>>(contentStream);
        }
    }
}

Menggunakan IHttpClientFactory seperti pada contoh sebelumnya adalah cara yang baik untuk merefaktor aplikasi yang ada. Ini tidak berdampak pada bagaimana HttpClient digunakan. Di tempat-tempat di mana instans HttpClient dibuat di aplikasi yang ada, ganti kemunculan tersebut dengan panggilan ke CreateClient.

Klien bernama

Klien bernama adalah pilihan yang baik saat:

• Aplikasi membutuhkan banyak kegunaan HttpClient yang berbeda.
• Banyak HttpClientyang memiliki konfigurasi yang berbeda.

Tentukan konfigurasi untuk HttpClient yang bernama tertentu selama pendaftarannya di Program.cs:

builder.Services.AddHttpClient("GitHub", httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com/");

    // using Microsoft.Net.Http.Headers;
    // The GitHub API requires two headers.
    httpClient.DefaultRequestHeaders.Add(
        HeaderNames.Accept, "application/vnd.github.v3+json");
    httpClient.DefaultRequestHeaders.Add(
        HeaderNames.UserAgent, "HttpRequestsSample");
});

Dalam kode sebelumnya, klien dikonfigurasi dengan:

• Alamat dasar https://api.github.com/.
• Dua header yang diperlukan untuk bekerja dengan API GitHub.

CreateClient

Setiap kali CreateClient disebut:

• Instans HttpClient baru dibuat.
• Tindakan konfigurasi dijalankan.

Untuk membuat klien bernama, berikan namanya ke dalam CreateClient:

public class NamedClientModel : PageModel
{
    private readonly IHttpClientFactory _httpClientFactory;

    public NamedClientModel(IHttpClientFactory httpClientFactory) =>
        _httpClientFactory = httpClientFactory;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        var httpClient = _httpClientFactory.CreateClient("GitHub");
        var httpResponseMessage = await httpClient.GetAsync(
            "repos/dotnet/AspNetCore.Docs/branches");

        if (httpResponseMessage.IsSuccessStatusCode)
        {
            using var contentStream =
                await httpResponseMessage.Content.ReadAsStreamAsync();
            
            GitHubBranches = await JsonSerializer.DeserializeAsync
                <IEnumerable<GitHubBranch>>(contentStream);
        }
    }
}

Dalam kode sebelumnya, permintaan tidak perlu menentukan nama host. Kode hanya bisa melewati jalur karena alamat dasar yang dikonfigurasi untuk klien digunakan.

Klien yang dititik

Klien yang dititik:

• Memberikan kemampuan yang sama seperti klien bernama tanpa perlu menggunakan string sebagai kunci.
• Menyediakan bantuan IntelliSense dan bantuan dari compiler saat menggunakan klien.
• Menyediakan satu lokasi untuk mengonfigurasi dan berinteraksi dengan HttpClient tertentu. Misalnya, klien bertipe tunggal dapat digunakan:
  • Untuk satu titik akhir backend.
  • Untuk merangkum semua logika yang berhubungan dengan titik akhir.
• Bekerja dengan DI dan bisa disuntikkan jika diperlukan di aplikasi.

Klien bertipe menerima parameter HttpClient di dalam konstruktornya.

public class GitHubService
{
    private readonly HttpClient _httpClient;

    public GitHubService(HttpClient httpClient)
    {
        _httpClient = httpClient;

        _httpClient.BaseAddress = new Uri("https://api.github.com/");

        // using Microsoft.Net.Http.Headers;
        // The GitHub API requires two headers.
        _httpClient.DefaultRequestHeaders.Add(
            HeaderNames.Accept, "application/vnd.github.v3+json");
        _httpClient.DefaultRequestHeaders.Add(
            HeaderNames.UserAgent, "HttpRequestsSample");
    }

    public async Task<IEnumerable<GitHubBranch>?> GetAspNetCoreDocsBranchesAsync() =>
        await _httpClient.GetFromJsonAsync<IEnumerable<GitHubBranch>>(
            "repos/dotnet/AspNetCore.Docs/branches");
}

Dalam kode sebelumnya:

• Konfigurasi dipindahkan ke klien yang ditik.
• Instans yang disediakan HttpClient disimpan sebagai bidang privat.

Metode khusus API bisa dibuat yang mengekspos fungsionalitas HttpClient. Misalnya, metode GetAspNetCoreDocsBranches merangkum kode untuk mengambil dokumen GitHub cabang.

Kode berikut memanggil di untuk mendaftarkan kelas klien bertipe :

builder.Services.AddHttpClient<GitHubService>();

Klien bertipe didaftarkan sebagai transien di dalam DI. Dalam kode sebelumnya, AddHttpClient mendaftarkan GitHubService sebagai layanan sementara. Pendaftaran ini menggunakan metode pabrik untuk:

1. Buat instans HttpClient.
2. Membuat instans GitHubService, meneruskan instans HttpClient ke konstruktornya.

Klien terketik dapat langsung disuntikkan dan digunakan.

public class TypedClientModel : PageModel
{
    private readonly GitHubService _gitHubService;

    public TypedClientModel(GitHubService gitHubService) =>
        _gitHubService = gitHubService;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        try
        {
            GitHubBranches = await _gitHubService.GetAspNetCoreDocsBranchesAsync();
        }
        catch (HttpRequestException)
        {
            // ...
        }
    }
}

Konfigurasi untuk klien bertipe juga dapat ditentukan saat pendaftarannya di Program.cs, bukan melalui konstruktor klien bertipe.

builder.Services.AddHttpClient<GitHubService>(httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com/");

    // ...
});

Klien yang dihasilkan

IHttpClientFactory bisa digunakan dalam kombinasi dengan pustaka pihak ketiga seperti Refit. Refit adalah pustaka REST untuk .NET. Ini mengonversi REST API menjadi antarmuka langsung. Panggilan AddRefitClient untuk menghasilkan implementasi dinamis antarmuka, yang menggunakan HttpClient untuk melakukan panggilan HTTP eksternal.

Antarmuka kustom mewakili API eksternal:

public interface IGitHubClient
{
    [Get("/repos/dotnet/AspNetCore.Docs/branches")]
    Task<IEnumerable<GitHubBranch>> GetAspNetCoreDocsBranchesAsync();
}

Panggil AddRefitClient untuk menghasilkan implementasi dinamis lalu panggil ConfigureHttpClient untuk mengonfigurasi yang mendasar HttpClient:

builder.Services.AddRefitClient<IGitHubClient>()
    .ConfigureHttpClient(httpClient =>
    {
        httpClient.BaseAddress = new Uri("https://api.github.com/");

        // using Microsoft.Net.Http.Headers;
        // The GitHub API requires two headers.
        httpClient.DefaultRequestHeaders.Add(
            HeaderNames.Accept, "application/vnd.github.v3+json");
        httpClient.DefaultRequestHeaders.Add(
            HeaderNames.UserAgent, "HttpRequestsSample");
    });

Gunakan DI untuk mengakses implementasi dinamis dari IGitHubClient:

public class RefitModel : PageModel
{
    private readonly IGitHubClient _gitHubClient;

    public RefitModel(IGitHubClient gitHubClient) =>
        _gitHubClient = gitHubClient;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        try
        {
            GitHubBranches = await _gitHubClient.GetAspNetCoreDocsBranchesAsync();
        }
        catch (ApiException)
        {
            // ...
        }
    }
}

Membuat permintaan POST, PUT, dan DELETE

Dalam contoh sebelumnya, semua permintaan HTTP menggunakan kata kerja HTTP GET. HttpClient juga mendukung kata kerja HTTP lainnya, termasuk:

• POST
• PUT
• DELETE
• PATCH

Untuk daftar lengkap kata kerja HTTP yang didukung, lihat HttpMethod.

Contoh berikut menunjukkan cara membuat permintaan HTTP POST:

public async Task CreateItemAsync(TodoItem todoItem)
{
    var todoItemJson = new StringContent(
        JsonSerializer.Serialize(todoItem),
        Encoding.UTF8,
        Application.Json); // using static System.Net.Mime.MediaTypeNames;

    using var httpResponseMessage =
        await _httpClient.PostAsync("/api/TodoItems", todoItemJson);

    httpResponseMessage.EnsureSuccessStatusCode();
}

Dalam kode sebelumnya, metode CreateItemAsync:

• Menserialisasikan parameter TodoItem ke JSON menggunakan System.Text.Json.
• Membuat instans StringContent untuk mengemas JSON berseri untuk dikirim di dalam isi permintaan HTTP.
• Memanggil PostAsync untuk mengirim konten JSON ke URL yang ditentukan. Ini adalah URL relatif yang ditambahkan ke HttpClient.BaseAddress.
• Memanggil EnsureSuccessStatusCode untuk melempar pengecualian jika kode status respons tidak menunjukkan keberhasilan.

HttpClient juga mendukung jenis konten lainnya. Misalnya, MultipartContent dan StreamContent. Untuk daftar lengkap konten yang didukung, lihat HttpContent.

Contoh berikut menunjukkan permintaan HTTP PUT:

public async Task SaveItemAsync(TodoItem todoItem)
{
    var todoItemJson = new StringContent(
        JsonSerializer.Serialize(todoItem),
        Encoding.UTF8,
        Application.Json);

    using var httpResponseMessage =
        await _httpClient.PutAsync($"/api/TodoItems/{todoItem.Id}", todoItemJson);

    httpResponseMessage.EnsureSuccessStatusCode();
}

Kode sebelumnya mirip dengan contoh POST. Metode SaveItemAsync memanggil PutAsync alih-alih PostAsync.

Contoh berikut menunjukkan permintaan HTTP DELETE:

public async Task DeleteItemAsync(long itemId)
{
    using var httpResponseMessage =
        await _httpClient.DeleteAsync($"/api/TodoItems/{itemId}");

    httpResponseMessage.EnsureSuccessStatusCode();
}

Dalam kode sebelumnya, metode DeleteItemAsync memanggil DeleteAsync. Karena permintaan HTTP DELETE biasanya tidak memiliki isi, metode DeleteAsync ini tidak menyediakan kelebihan beban yang menerima instans HttpContent.

Untuk mempelajari selengkapnya mengenai penggunaan kata kerja HTTP yang berbeda dengan HttpClient, lihat HttpClient.

Middleware untuk permintaan yang keluar

HttpClient memiliki konsep mendelegasikan handler yang dapat ditautkan bersama untuk permintaan HTTP keluar. IHttpClientFactory:

• Menyederhanakan penentuan handler yang diterapkan pada setiap klien dengan nama tertentu.
• Mendukung pendaftaran dan penautan beberapa handler untuk membangun alur middleware permintaan keluar. Masing-masing handler ini dapat melakukan tugas sebelum dan sesudah permintaan keluar. Pola ini:
  • Mirip dengan alur middleware masuk di ASP.NET Core.
  • Menyediakan mekanisme untuk mengelola concern lintas dalam permintaan HTTP, seperti:
    • penembolokan
    • penanganan kesalahan
    • serialization
    • pengelogan

Untuk membuat pengendali pendelegasian:

• Berasal dari DelegatingHandler.
• Ambil alih SendAsync. Jalankan kode sebelum meneruskan permintaan ke handler berikutnya dalam alur:

public class ValidateHeaderHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (!request.Headers.Contains("X-API-KEY"))
        {
            return new HttpResponseMessage(HttpStatusCode.BadRequest)
            {
                Content = new StringContent(
                    "The API key header X-API-KEY is required.")
            };
        }

        return await base.SendAsync(request, cancellationToken);
    }
}

Kode sebelumnya memeriksa apakah X-API-KEY header ada dalam permintaan. Jika X-API-KEY hilang, BadRequest dikembalikan.

Lebih dari satu handler dapat ditambahkan ke konfigurasi untuk HttpClient dengan Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandler:

builder.Services.AddTransient<ValidateHeaderHandler>();

builder.Services.AddHttpClient("HttpMessageHandler")
    .AddHttpMessageHandler<ValidateHeaderHandler>();

Dalam kode sebelumnya, ValidateHeaderHandler terdaftar di DI. Setelah terdaftar, AddHttpMessageHandler dapat dipanggil, dengan meneruskan jenis data untuk pengelola.

Beberapa handler dapat didaftarkan dalam urutan yang harus mereka jalankan. Setiap handler membungkus handler berikutnya hingga final HttpClientHandler menjalankan permintaan:

builder.Services.AddTransient<SampleHandler1>();
builder.Services.AddTransient<SampleHandler2>();

builder.Services.AddHttpClient("MultipleHttpMessageHandlers")
    .AddHttpMessageHandler<SampleHandler1>()
    .AddHttpMessageHandler<SampleHandler2>();

Dalam kode sebelumnya, SampleHandler1 berjalan terlebih dahulu, sebelum SampleHandler2.

Menggunakan DI dalam middleware permintaan keluar

Saat IHttpClientFactory membuat handler pendelegasian baru, ia menggunakan DI untuk memenuhi parameter konstruktor handler. IHttpClientFactory membuat cakupan DI terpisah untuk setiap handler, yang dapat menyebabkan perilaku mengejutkan ketika handler mengonsumsi layanan tercakup.

Misalnya, pertimbangkan antarmuka berikut dan implementasinya, yang mewakili tugas sebagai operasi dengan pengidentifikasi, OperationId:

public interface IOperationScoped
{
    string OperationId { get; }
}

public class OperationScoped : IOperationScoped
{
    public string OperationId { get; } = Guid.NewGuid().ToString()[^4..];
}

Seperti namanya, IOperationScoped terdaftar di DI menggunakan masa pakai tercakup:

builder.Services.AddScoped<IOperationScoped, OperationScoped>();

Penangan delegasi IOperationScoped berikut menggunakan IOperationScoped untuk mengatur tajuk untuk permintaan keluar.

public class OperationHandler : DelegatingHandler
{
    private readonly IOperationScoped _operationScoped;

    public OperationHandler(IOperationScoped operationScoped) =>
        _operationScoped = operationScoped;

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.Headers.Add("X-OPERATION-ID", _operationScoped.OperationId);

        return await base.SendAsync(request, cancellationToken);
    }
}

Dalam unduhanHttpRequestsSample, navigasikan ke /Operation dan refresh halaman. Nilai cakupan permintaan berubah untuk setiap permintaan, tetapi nilai cakupan handler hanya berubah setiap 5 detik.

Handler dapat bergantung pada layanan dari ruang lingkup mana pun. Layanan yang bergantung pada handler dibersihkan ketika handler dibersihkan.

Gunakan salah satu pendekatan berikut untuk berbagi status per permintaan dengan penangan pesan:

• Teruskan data ke handler menggunakan HttpRequestMessage.Options.
• Gunakan IHttpContextAccessor untuk mengakses permintaan saat ini.
• Buat objek penyimpanan kustom AsyncLocal<T> untuk meneruskan data.

Menggunakan handler berbasis Polly

IHttpClientFactory terintegrasi dengan pustaka pihak ketiga Polly. Polly adalah pustaka komprehensif untuk penanganan kesalahan sementara dan ketahanan pada .NET. Ini memungkinkan pengembang untuk mengekspresikan kebijakan seperti Retry, Circuit Breaker, Timeout, Bulkhead Isolation, dan Fallback dengan cara yang lancar dan aman utas.

Metode ekstensi disediakan untuk memungkinkan penerapan kebijakan Polly pada instans HttpClient yang telah dikonfigurasi. Ekstensi Polly mendukung penambahan handler berbasis Polly ke klien. Polly membutuhkan Microsoft. Extensions.Http.Polly paket NuGet.

Menangani kesalahan sementara

Kesalahan biasanya terjadi ketika panggilan HTTP eksternal bersifat sementara. AddTransientHttpErrorPolicy memungkinkan kebijakan didefinisikan untuk menangani kesalahan sementara. Kebijakan yang dikonfigurasi dengan AddTransientHttpErrorPolicy menangani respons berikut:

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy menyediakan akses ke objek yang dikonfigurasi PolicyBuilder untuk menangani kesalahan yang mewakili kemungkinan kesalahan sementara:

builder.Services.AddHttpClient("PollyWaitAndRetry")
    .AddTransientHttpErrorPolicy(policyBuilder =>
        policyBuilder.WaitAndRetryAsync(
            3, retryNumber => TimeSpan.FromMilliseconds(600)));

Dalam kode sebelumnya, suatu kebijakan WaitAndRetryAsync ditentukan. Permintaan yang gagal dicoba ulang hingga tiga kali dengan penundaan 600 ms antar upaya.

Memilih kebijakan secara dinamis

Metode ekstensi disediakan untuk menambahkan handler berbasis Polly, misalnya, AddPolicyHandler. Kelebihan beban berikut AddPolicyHandler memeriksa permintaan untuk memutuskan kebijakan mana yang akan diterapkan:

var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(10));
var longTimeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(30));

builder.Services.AddHttpClient("PollyDynamic")
    .AddPolicyHandler(httpRequestMessage =>
        httpRequestMessage.Method == HttpMethod.Get ? timeoutPolicy : longTimeoutPolicy);

Dalam kode sebelumnya, jika permintaan keluar adalah HTTP GET, batas waktu 10 detik diterapkan. Untuk metode HTTP lainnya, batas waktu 30 detik digunakan.

Menambahkan beberapa handler Polly

Adalah umum untuk menyusun kebijakan Polly:

builder.Services.AddHttpClient("PollyMultiple")
    .AddTransientHttpErrorPolicy(policyBuilder =>
        policyBuilder.RetryAsync(3))
    .AddTransientHttpErrorPolicy(policyBuilder =>
        policyBuilder.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30)));

Dalam contoh sebelumnya:

• Dua handler ditambahkan.
• Handler pertama menggunakan AddTransientHttpErrorPolicy untuk menambahkan kebijakan coba ulang. Permintaan yang gagal dicoba ulang hingga tiga kali.
• Panggilan kedua AddTransientHttpErrorPolicy menambahkan kebijakan pemutus sirkuit. Permintaan eksternal lebih lanjut diblokir selama 30 detik jika 5 upaya gagal terjadi secara berurutan. Kebijakan pemutus sirkuit bersifat stateful. Semua panggilan melalui klien ini memiliki status sirkuit yang sama.

Menambahkan kebijakan dari registri Polly

Pendekatan untuk mengelola kebijakan yang digunakan secara teratur adalah menentukannya sekali dan mendaftarkannya dengan PolicyRegistry. Contohnya:

var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(10));
var longTimeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(30));

var policyRegistry = builder.Services.AddPolicyRegistry();

policyRegistry.Add("Regular", timeoutPolicy);
policyRegistry.Add("Long", longTimeoutPolicy);

builder.Services.AddHttpClient("PollyRegistryRegular")
    .AddPolicyHandlerFromRegistry("Regular");

builder.Services.AddHttpClient("PollyRegistryLong")
    .AddPolicyHandlerFromRegistry("Long");

Dalam kode sebelumnya:

• Dua kebijakan, Regular dan Long, ditambahkan ke registri Polly.
• AddPolicyHandlerFromRegistry mengonfigurasi klien individu yang diberi nama untuk menggunakan kebijakan ini dari registri Polly.

Untuk informasi selengkapnya tentang IHttpClientFactory dan integrasi Polly, lihat wiki Polly.

HttpClient dan manajemen siklus hidup

Instans HttpClient baru dikembalikan setiap kali CreateClient dipanggil pada IHttpClientFactory. HttpMessageHandler Dibuat untuk setiap klien yang diberi nama. Pabrik mengelola masa pakai instans HttpMessageHandler.

IHttpClientFactory mengumpulkan instans HttpMessageHandler yang dibuat oleh pabrik untuk mengurangi konsumsi sumber daya. Instans HttpMessageHandler dapat digunakan kembali dari pool saat membuat instans HttpClient baru jika masa pakainya belum kedaluwarsa.

Pengelompokan handler diinginkan karena setiap handler biasanya mengelola koneksi HTTP yang mendasari secara mandiri. Membuat lebih banyak handler daripada yang dibutuhkan dapat mengakibatkan penundaan koneksi. Beberapa handler juga menjaga koneksi tetap terbuka tanpa batas waktu, yang dapat mencegah handler bereaksi terhadap perubahan DNS (Domain Name System).

Masa pakai handler default adalah dua menit. Nilai default dapat diganti untuk setiap klien yang diberi nama.

builder.Services.AddHttpClient("HandlerLifetime")
    .SetHandlerLifetime(TimeSpan.FromMinutes(5));

instans HttpClient umumnya dapat diperlakukan sebagai objek .NET tidak memerlukan penghapusan. Proses pembuangan membatalkan permintaan keluar dan menjamin instans HttpClient yang diberikan tidak dapat digunakan setelah memanggil Dispose. IHttpClientFactory melacak dan membuang sumber daya yang digunakan oleh instans HttpClient.

Menjaga satu instans HttpClient tetap hidup untuk durasi yang lama adalah pola umum yang digunakan sebelum adanya IHttpClientFactory. Pola ini menjadi tidak perlu setelah bermigrasi ke IHttpClientFactory.

Alternatif untuk IHttpClientFactory

Menggunakan IHttpClientFactory dalam aplikasi yang diaktifkan DI menghindari:

• Masalah kelelahan sumber daya karena pengumpulan instans HttpMessageHandler.
• Mengatasi masalah DNS yang kedaluwarsa dengan mereset HttpMessageHandler instans secara berkala.

Ada cara alternatif untuk menyelesaikan masalah sebelumnya menggunakan instans SocketsHttpHandler yang berusia panjang.

• Buat instans SocketsHttpHandler saat aplikasi dimulai dan gunakan untuk masa pakai aplikasi.
• Konfigurasikan PooledConnectionLifetime ke nilai yang sesuai berdasarkan waktu refresh DNS.
• Buat HttpClient instance menggunakan new HttpClient(handler, disposeHandler: false) sesuai kebutuhan.

Pendekatan sebelumnya menyelesaikan masalah manajemen sumber daya yang IHttpClientFactory diselesaikan dengan cara yang sama.

• Koneksi SocketsHttpHandler berbagi antar instans HttpClient. Berbagi ini mencegah kelelahan soket.
• Siklus SocketsHttpHandler koneksi sesuai PooledConnectionLifetime untuk menghindari masalah DNS usang.

Logging

Klien yang dibuat melalui IHttpClientFactory mencatat pesan log untuk semua permintaan. Aktifkan tingkat informasi yang sesuai dalam konfigurasi pengelogan untuk melihat pesan log default. Pengelogan tambahan, seperti pengelogan header permintaan, hanya disertakan pada tingkat pelacakan.

Kategori log yang digunakan untuk setiap klien menyertakan nama klien. Klien bernama MyNamedClient, misalnya, mencatat pesan dengan kategori "System.Net.Http.HttpClient.MyNamedClient. LogicalHandler". Pesan yang dibubuhi dengan LogicalHandler terjadi di luar pipeline penanganan permintaan. Pada saat permintaan, pesan dicatat sebelum penangan lain dalam jalur telah memprosesnya. Pada respons, pesan dicatat setelah handler alur lain menerima respons.

Pengelogan juga terjadi di dalam alur handler permintaan. Dalam contoh MyNamedClient, pesan tersebut dicatat dengan kategori log "System.Net.Http.Http.HttpClient.MyNamedClient. ClientHandler". Untuk permintaan, ini terjadi setelah semua handler lain berjalan dan segera sebelum permintaan dikirim. Pada respons, pengelogan ini mencakup status respons sebelum melewati kembali melalui alur handler.

Mengaktifkan pengelogan di luar dan di dalam alur memungkinkan inspeksi perubahan yang dilakukan oleh penangan alur lainnya. Ini dapat mencakup perubahan pada header permintaan atau ke kode status respons.

Menyertakan nama klien dalam kategori log memungkinkan pemfilteran log untuk klien bernama tertentu.

Mengonfigurasi HttpMessageHandler

Anda mungkin perlu mengontrol konfigurasi HttpMessageHandler bagian dalam yang digunakan oleh klien.

IHttpClientBuilder dikembalikan saat menambahkan klien bernama atau berjenis. Metode ekstensi ConfigurePrimaryHttpMessageHandler dapat digunakan untuk menentukan delegat. Delegasi dipakai untuk membuat dan mengonfigurasi primer HttpMessageHandler yang digunakan oleh klien tersebut:

builder.Services.AddHttpClient("ConfiguredHttpMessageHandler")
    .ConfigurePrimaryHttpMessageHandler(() =>
        new HttpClientHandler
        {
            AllowAutoRedirect = true,
            UseDefaultCredentials = true
        });

Cookies

Instans yang dikumpulkan HttpMessageHandler menghasilkan CookieContainer objek yang dibagikan. Berbagi objek yang tidak diantisipasi CookieContainer sering kali menghasilkan kode yang tidak benar. Untuk aplikasi yang memerlukan cookie, pertimbangkan:

• Menonaktifkan penanganan otomatis cookie
• Menghindari IHttpClientFactory

Panggilan ConfigurePrimaryHttpMessageHandler untuk menonaktifkan penanganan otomatis cookie :

builder.Services.AddHttpClient("NoAutomaticCookies")
    .ConfigurePrimaryHttpMessageHandler(() =>
        new HttpClientHandler
        {
            UseCookies = false
        });

Menggunakan IHttpClientFactory di aplikasi konsol

Di aplikasi konsol, tambahkan referensi paket berikut ke proyek:

• Microsoft.Extensions.Hosting
• Microsoft. Extensions.Http

Dalam contoh berikut:

• IHttpClientFactory dan GitHubService terdaftar dalam kontainer layanan Host Generik.
• GitHubService diminta dari DI, yang kemudian meminta instans IHttpClientFactory.
• GitHubService menggunakan IHttpClientFactory untuk membuat instans HttpClient, yang digunakannya untuk mengambil dokumen GitHub cabang.

using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddHttpClient();
        services.AddTransient<GitHubService>();
    })
    .Build();

try
{
    var gitHubService = host.Services.GetRequiredService<GitHubService>();
    var gitHubBranches = await gitHubService.GetAspNetCoreDocsBranchesAsync();

    Console.WriteLine($"{gitHubBranches?.Count() ?? 0} GitHub Branches");

    if (gitHubBranches is not null)
    {
        foreach (var gitHubBranch in gitHubBranches)
        {
            Console.WriteLine($"- {gitHubBranch.Name}");
        }
    }
}
catch (Exception ex)
{
    host.Services.GetRequiredService<ILogger<Program>>()
        .LogError(ex, "Unable to load branches from GitHub.");
}

public class GitHubService
{
    private readonly IHttpClientFactory _httpClientFactory;

    public GitHubService(IHttpClientFactory httpClientFactory) =>
        _httpClientFactory = httpClientFactory;

    public async Task<IEnumerable<GitHubBranch>?> GetAspNetCoreDocsBranchesAsync()
    {
        var httpRequestMessage = new HttpRequestMessage(
            HttpMethod.Get,
            "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches")
        {
            Headers =
            {
                { "Accept", "application/vnd.github.v3+json" },
                { "User-Agent", "HttpRequestsConsoleSample" }
            }
        };

        var httpClient = _httpClientFactory.CreateClient();
        var httpResponseMessage = await httpClient.SendAsync(httpRequestMessage);

        httpResponseMessage.EnsureSuccessStatusCode();

        using var contentStream =
            await httpResponseMessage.Content.ReadAsStreamAsync();
        
        return await JsonSerializer.DeserializeAsync
            <IEnumerable<GitHubBranch>>(contentStream);
    }
}

public record GitHubBranch(
    [property: JsonPropertyName("name")] string Name);

Middleware penyebaran header

Propagasi header adalah middleware ASP.NET Core untuk meneruskan header HTTP dari permintaan masuk ke permintaan HttpClient keluar. Untuk menggunakan penyebaran header:

• Instal paket Microsoft.AspNetCore.HeaderPropagation.

• Konfigurasikan HttpClient dan alur middleware di Program.cs:

  // Add services to the container.
  builder.Services.AddControllers();
  
  builder.Services.AddHttpClient("PropagateHeaders")
      .AddHeaderPropagation();
  
  builder.Services.AddHeaderPropagation(options =>
  {
      options.Headers.Add("X-TraceId");
  });
  
  var app = builder.Build();
  
  // Configure the HTTP request pipeline.
  app.UseHttpsRedirection();
  
  app.UseHeaderPropagation();
  
  app.MapControllers();
  

• Buat permintaan eksternal menggunakan instans HttpClient yang telah dikonfigurasi, yang mencakup header tambahan.

Sumber daya tambahan

• Melihat atau mengunduh kode sampel (cara mengunduh)
• Gunakan HttpClientFactory untuk menerapkan permintaan HTTP yang tangguh
• Menerapkan percobaan ulang panggilan HTTP dengan backoff eksponensial dengan kebijakan HttpClientFactory dan Polly
• Menerapkan pola Circuit Breaker
• Cara membuat serialisasi dan mendeserialisasi JSON di .NET