Effectuer des requêtes HTTP en utilisant IHttpClientFactory dans ASP.NET Core

Par Kirk Larkin, Steve Gordon, Glenn Condron et Ryan Nowak.

Une IHttpClientFactory peut être inscrite et utilisée pour configurer et créer des instances de HttpClient dans une application. IHttpClientFactory offre les avantages suivants :

• Fournit un emplacement central pour le nommage et la configuration d’instance de HttpClient logiques. Par exemple, un client nommé github peut être inscrit et configuré pour accéder à GitHub. Un client par défaut peut être inscrit pour l’accès général.
• Codifie le concept d’intergiciel (middleware) sortant via la délégation de gestionnaires dans HttpClient. Fournit des extensions pour les intergiciels basés sur Polly afin de tirer parti de la délégation de gestionnaires dans HttpClient.
• Gère les pools et la durée de vie des instances HttpClientMessageHandler sous-jacentes. La gestion automatique évite les problèmes courants liés au système DNS (Domain Name System) qui se produisent lors de la gestion manuelle des durées de vie HttpClient.
• Ajoute une expérience de journalisation configurable (via ILogger) pour toutes les requêtes envoyées via des clients créés par la fabrique.

L’exemple de code de cette version de rubrique utilise System.Text.Json pour désérialiser le contenu JSON retourné dans les réponses HTTP. Pour les exemples qui utilisent Json.NET et ReadAsAsync<T>, utilisez le sélecteur de version pour sélectionner une version 2.x de cette rubrique.

Modèles de consommation

Vous pouvez utiliser IHttpClientFactory dans une application de plusieurs façons :

• Utilisation de base
• Clients nommés
• Clients typés
• Clients générés

La meilleure approche dépend des exigences de l’application.

Utilisation de base

Inscrivez IHttpClientFactory en appelant AddHttpClient dans Program.cs :

var builder = WebApplication.CreateBuilder(args);

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

Une IHttpClientFactory peut être demandée à l’aide de l’injection de dépendances (DI). Le code suivant utilise IHttpClientFactory pour créer une instance HttpClient :

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);
        }
    }
}

L’utilisation de IHttpClientFactory comme dans l’exemple précédent est un bon moyen de refactoriser une application existante. Cela n’a aucun impact sur la façon dont HttpClient est utilisé. Aux endroits où des instances HttpClient sont créées dans une application existante, remplacez ces occurrences par des appels à CreateClient.

Clients nommés

Les clients nommés sont un bon choix dans les cas suivants :

• L’application nécessite de nombreuses utilisations distinctes de HttpClient.
• De nombreuses instances HttpClient ont une configuration différente.

Spécifiez la configuration d’un HttpClient nommé pendant son inscription dans 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");
});

Dans le code précédent, le client est configuré avec :

• L’adresse de base https://api.github.com/.
• Deux en-têtes requis pour fonctionner avec l’API GitHub.

CreateClient

Chaque fois que CreateClient est appelé :

• Une nouvelle instance de HttpClient est créée.
• L’action de configuration est appelée.

Pour créer un client nommé, passez son nom dans 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);
        }
    }
}

Dans le code précédent, la requête n’a pas besoin de spécifier un nom d’hôte. Le code peut simplement passer le chemin, car l’adresse de base configurée pour le client est utilisée.

Clients typés

Clients typés :

• Fournissent les mêmes fonctionnalités que les clients nommés, sans qu’il soit nécessaire d’utiliser des chaînes comme clés.
• Bénéficie de l’aide d’IntelliSense et du compilateur lors de l’utilisation des clients.
• Fournissent un emplacement unique pour configurer et interagir avec un HttpClient particulier. Par exemple, un client typé unique peut être utilisé :
  • Pour un point de terminaison principal unique.
  • Pour encapsuler toute la logique traitant du point de terminaison.
• Pour travailler avec l’injection de dépendances et injecter là où c’est nécessaire dans l’application.

Un client typé accepte un paramètre HttpClient dans son constructeur :

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");
}

Dans le code précédent :

• La configuration est déplacée dans le client typé.
• L’instance HttpClient fournie est stockée en tant que champ privé.

Vous pouvez créer des méthodes spécifiques à l’API qui exposent des fonctionnalités de HttpClient. Par exemple, la méthode encapsule le code GetAspNetCoreDocsBranches pour récupérer des branches GitHub de documentation.

Le code suivant appelle AddHttpClient dans Program.cs pour inscrire une classe cliente typée GitHubService :

builder.Services.AddHttpClient<GitHubService>();

Le client typé est inscrit comme étant transitoire avec injection de dépendances. Dans le code précédent, AddHttpClient inscrit GitHubService en tant que service temporaire. Cette inscription utilise une méthode de fabrique pour :

1. Créez une instance de HttpClient.
2. Créer une instance de GitHubService en passant l’instance de HttpClient à son constructeur.

Le client typé peut être injecté et utilisé directement :

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)
        {
            // ...
        }
    }
}

Vous pouvez également spécifier la configuration d’un client typé lors de l’inscription dans Program.cs au lieu de le faire dans le constructeur du client typé :

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

    // ...
});

Clients générés

IHttpClientFactory peut être utilisé en combinaison avec des bibliothèques tierces, comme Refit. Refit est une bibliothèque REST pour .NET. Il convertit les API REST en interfaces dynamiques. Appelez AddRefitClient pour générer une implémentation dynamique d’une interface, qui utilise HttpClient pour effectuer les appels HTTP externes.

Une interface personnalisée représente l’API externe :

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

Appelez AddRefitClient pour générer l’implémentation dynamique, puis appelez ConfigureHttpClient pour configurer le HttpClient sous-jacent :

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");
    });

Utilisez la DI pour accéder à l’implémentation dynamique de 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)
        {
            // ...
        }
    }
}

Effectuer des requêtes POST, PUT et DELETE

Dans les exemples précédents, toutes les requêtes HTTP utilisent le verbe HTTP GET. HttpClient prend également en charge d’autres verbes HTTP, notamment :

• POST
• PUT
• DELETE
• PATCH

Pour obtenir la liste complète des verbes HTTP pris en charge, consultez HttpMethod.

L’exemple suivant montre comment effectuer une requête 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();
}

Dans le code précédent, la méthode CreateItemAsync :

• Sérialise le paramètre TodoItem au format JSON à l’aide de System.Text.Json.
• Crée une instance de StringContent pour empaqueter le JSON sérialisé pour l’envoi dans le corps de la requête HTTP.
• Appelle PostAsync pour envoyer le contenu JSON à l’URL spécifiée. Il s’agit d’une URL relative qui est ajoutée à HttpClient.BaseAddress.
• Appelle EnsureSuccessStatusCode pour lever une exception si le code d’état de la réponse n’indique pas la réussite.

HttpClient prend également en charge d’autres types de contenu. Par exemple : MultipartContent et StreamContent. Pour obtenir la liste complète du contenu pris en charge, consultez HttpContent.

L’exemple suivant montre une requête 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();
}

Le code précédent est similaire à l’exemple POST La méthode SaveItemAsync appelle PutAsync au lieu de PostAsync.

L’exemple suivant montre une requête HTTP DELETE :

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

    httpResponseMessage.EnsureSuccessStatusCode();
}

Dans le code précédent, la méthode DeleteItemAsync appelle DeleteAsync. Étant donné que les requêtes HTTP DELETE ne contiennent généralement aucun corps, la méthode DeleteAsync ne fournit pas de surcharge qui accepte une instance de HttpContent.

Pour en savoir plus sur l’utilisation de différents verbes HTTP avec HttpClient, consultez HttpClient.

Middleware pour les requêtes sortantes

HttpClient intègre le concept de délégation des gestionnaires qui peuvent être liés ensemble pour les requêtes HTTP sortantes. IHttpClientFactory:

• Simplifie la définition des gestionnaires à appliquer pour chaque client nommé.
• Il prend en charge l’inscription et le chaînage de plusieurs gestionnaires pour créer un pipeline d’intergiciels pour les requêtes sortantes. Chacun de ces gestionnaires peut effectuer un travail avant et après la requête sortante. Ce modèle :
  • Est similaire au pipeline d’intergiciels entrants dans ASP.NET Core.
  • Fournit un mécanisme pour gérer les problèmes transversaux liés aux requêtes HTTP, par exemple :
    • mise en cache
    • gestion des erreurs
    • sérialisation
    • journalisation

Pour créer un gestionnaire de délégation :

• Dérivez de DelegatingHandler.
• Remplacez SendAsync. Exécutez du code avant de passer la requête au gestionnaire suivant dans le pipeline :

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);
    }
}

Le code précédent vérifie si l’en-tête X-API-KEY se trouve dans la requête. Si X-API-KEY est manquant, BadRequest est retourné.

Plusieurs gestionnaires peuvent être ajoutés à la configuration d’un HttpClient avec Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandler :

builder.Services.AddTransient<ValidateHeaderHandler>();

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

Dans le code précédent, le ValidateHeaderHandler est inscrit avec une injection de dépendances. Une fois inscrit, AddHttpMessageHandler peut être appelé en passant en entrée le type pour le gestionnaire.

Vous pouvez inscrire plusieurs gestionnaires dans l’ordre où ils doivent être exécutés. Chaque gestionnaire wrappe le gestionnaire suivant jusqu’à ce que le dernier HttpClientHandler exécute la requête :

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

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

Dans le code précédent, SampleHandler1 s’exécute en premier, avant SampleHandler2.

Utiliser l’intergiciel de requêtes sortantes

Lorsque IHttpClientFactory crée un gestionnaire de délégation, il utilise l’injection de dépendances pour remplir les paramètres du constructeur du gestionnaire. IHttpClientFactory crée une étendue de DI distincte pour chaque gestionnaire, ce qui peut entraîner un comportement surprenant lorsqu’un gestionnaire consomme un service délimité.

Par exemple, considérez l’interface suivante et son implémentation, qui représente une tâche en tant qu’opération avec un identificateur, OperationId :

public interface IOperationScoped
{
    string OperationId { get; }
}

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

Comme son nom l’indique, IOperationScoped est inscrit avec la DI à l’aide d’une durée de vie étendue :

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

Le gestionnaire de délégation suivant consomme et utilise IOperationScoped pour définir l’en-tête X-OPERATION-ID pour la requête sortante :

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);
    }
}

Dans le Téléchargement de HttpRequestsSample, accédez à /Operation et actualisez la page. La valeur de l’étendue de la requête change pour chaque requête, mais la valeur d’étendue du gestionnaire change uniquement toutes les 5 secondes.

Les gestionnaires peuvent dépendre des services de n’importe quelle étendue. Les services dont dépendent les gestionnaires sont supprimés lorsque le gestionnaire est supprimé.

Utilisez l’une des approches suivantes pour partager l’état de chaque requête avec les gestionnaires de messages :

• Passez des données dans le gestionnaire en utilisant HttpRequestMessage.Options.
• Utilisez IHttpContextAccessor pour accéder à la requête en cours.
• Créez un objet de stockage AsyncLocal<T> personnalisé pour passer les données.

Utiliser les gestionnaires Polly

IHttpClientFactory s’intègre à la bibliothèque tierce Polly. Polly est une bibliothèque complète de gestion des erreurs transitoires et de résilience pour .NET. Elle permet aux développeurs de formuler facilement et de façon thread-safe des stratégies, comme Retry (Nouvelle tentative), Circuit Breaker (Disjoncteur), Timeout (Délai d’attente), Bulkhead Isolation (Isolation par cloisonnement) et Fallback (Alternative de repli).

Des méthodes d’extension sont fournies pour permettre l’utilisation de stratégies Polly avec les instances configurées de HttpClient. Les extensions Polly prennent en charge l’ajout de gestionnaires basés sur Polly aux clients. Polly nécessite le package NuGet Microsoft.Extensions.Http.Polly.

Gérer les erreurs temporaires

Les erreurs se produisent généralement lorsque des appels HTTP externes sont temporaires. AddTransientHttpErrorPolicy permet à une stratégie d’être définie pour gérer les erreurs temporaires. Les stratégies configurées avec AddTransientHttpErrorPolicy gèrent les réponses suivantes :

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy fournit l’accès à un objet PolicyBuilder configuré pour gérer les erreurs représentant une erreur temporaire possible :

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

Dans le code précédent, une stratégie WaitAndRetryAsync est définie. Les requêtes qui ont échoué sont retentées jusqu’à trois fois avec un délai de 600 ms entre les tentatives.

Sélectionner dynamiquement des stratégies

Des méthodes d’extension sont fournies pour ajouter des gestionnaires basés sur Polly, par exemple AddPolicyHandler. La surcharge de AddPolicyHandler suivante inspecte la requête pour déterminer la stratégie à appliquer :

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);

Dans le code précédent, si la requête sortante est un HTTP GET, un délai d’attente de 10 secondes est appliqué. Pour toutes les autres méthodes HTTP, un délai d’attente de 30 secondes est utilisé.

Ajouter plusieurs gestionnaires Polly

Il est courant d’imbriquer les stratégies Polly :

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

Dans l’exemple précédent :

• Deux gestionnaires sont ajoutés.
• Le premier gestionnaire utilise AddTransientHttpErrorPolicy pour ajouter une stratégie de nouvelle tentative. Les requêtes qui ont échoué sont retentées jusqu’à trois fois.
• Le deuxième appel à AddTransientHttpErrorPolicy ajoute une stratégie de disjoncteur. Les requêtes externes supplémentaires sont bloquées pendant 30 secondes si 5 tentatives successives échouent. Les stratégies de disjoncteur sont avec état. Tous les appels effectués via ce client partagent le même état du circuit.

Ajouter des stratégies à partir du Registre Polly

Une approche de la gestion des stratégies régulièrement utilisées consiste à les définir une seule fois et à les inscrire avec un PolicyRegistry. Par exemple :

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");

Dans le code précédent :

• Deux stratégies, Regular et Long, sont ajoutées au registre Polly.
• AddPolicyHandlerFromRegistry configure des clients nommés individuels pour utiliser ces stratégies à partir du registre Polly.

Pour plus d’informations sur les intégrations IHttpClientFactory et Polly, consultez le Wiki Polly.

HttpClient et gestion de la durée de vie

Une nouvelle instance HttpClient est retournée à chaque fois que CreateClient est appelé sur IHttpClientFactory. Un HttpMessageHandler est créé par client nommé. La fabrique gère les durées de vie des instances HttpMessageHandler.

IHttpClientFactory regroupe dans un pool les instances de HttpMessageHandler créées par la fabrique pour réduire la consommation des ressources. Une instance de HttpMessageHandler peut être réutilisée à partir du pool quand vous créez une instance de HttpClient si sa durée de vie n’a pas expiré.

Le regroupement de gestionnaires en pools est souhaitable, car chaque gestionnaire gère habituellement ses propres connexions HTTP sous-jacentes. La création de plus de gestionnaires que nécessaire peut entraîner des délais de connexion. Certains gestionnaires conservent aussi les connexions indéfiniment ouvertes, ce qui peut empêcher le gestionnaire de réagir aux changements du DNS (Domain Name System).

La durée de vie par défaut d’un gestionnaire est de deux minutes. La valeur par défaut peut être remplacée pour chaque client nommé :

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

Les instances HttpClient peuvent généralement être traitées en tant qu’objets .NET ne nécessitant pas une suppression. La suppression annule les requêtes sortantes et garantit que l’instance HttpClient donnée ne peut pas être utilisée après avoir appelé Dispose. IHttpClientFactory effectue le suivi et libère les ressources utilisées par les instances HttpClient.

Le fait de conserver une seule instance HttpClient active pendant une longue durée est un modèle commun utilisé avant le lancement de IHttpClientFactory. Ce modèle devient inutile après la migration vers IHttpClientFactory.

Alternatives à IHttpClientFactory

L’utilisation de IHttpClientFactory dans une application avec injection de dépendances évite :

• Les problèmes d’épuisement des ressources en regroupant les instances HttpMessageHandler.
• Les problèmes de DNS obsolète en permutant les instances HttpMessageHandler à intervalles réguliers.

Il existe d’autres façons de résoudre les problèmes précédents à l’aide d’une instance SocketsHttpHandler de longue durée.

• Créez une instance de SocketsHttpHandler lorsque l’application démarre et utilisez-la pour la durée de vie de l’application.
• Configurez PooledConnectionLifetime sur une valeur appropriée en fonction des temps d’actualisation DNS.
• Créez des instances HttpClient à l’aide de new HttpClient(handler, disposeHandler: false) si nécessaire.

Les approches précédentes résolvent les problèmes de gestion des ressources que IHttpClientFactory résout de la même manière.

• Le SocketsHttpHandler partage les connexions entre les instances HttpClient. Ce partage empêche l’épuisement des sockets.
• Le SocketsHttpHandler permute les connexions en fonction de PooledConnectionLifetime pour éviter les problèmes de DNS obsolète.

Journalisation

Les clients créés via IHttpClientFactory enregistrent les messages de journalisation pour toutes les requêtes. Activez le niveau d’informations approprié dans la configuration de journalisation pour voir les messages de journalisation par défaut. Une journalisation supplémentaire, comme celle des en-têtes des requêtes, est incluse seulement au niveau de trace.

La catégorie de journal utilisée pour chaque client comprend le nom du client. Par exemple, un client nommé MyNamedClient journalise les messages avec la catégorie « System.Net.Http.HttpClient.MyNamedClient.LogicalHandler ». Les messages avec le suffixe LogicalHandler se produisent en dehors du pipeline du gestionnaire de requêtes. Lors d’une requête, les messages sont journalisés avant que d’autres gestionnaires du pipeline l’aient traitée. Lors d’une réponse, les messages sont journalisés une fois que tous les autres gestionnaires du pipeline ont reçu la réponse.

La journalisation se produit également à l’intérieur du pipeline du gestionnaire de requêtes. Dans l’exemple MyNamedClient, ces messages sont enregistrés avec la catégorie de journal « System.Net.Http.HttpClient.MyNamedClient.ClientHandler ». Pour la requête, cela se produit après que tous les autres gestionnaires ont été exécutés et immédiatement avant l’envoi de la requête. Lors de la réponse, cette journalisation inclut l’état de la réponse avant qu’elle repasse à travers le pipeline de gestionnaires.

L’activation de la journalisation à l’extérieur et à l’intérieur du pipeline permet l’inspection des changements apportés par les autres gestionnaires du pipeline. Cela peut comprendre des changements apportés aux en-têtes des requêtes ou au code d’état de la réponse.

L’ajout du nom du client dans la catégorie de journalisation permet de filtrer le journal pour des clients nommés spécifiques.

Configurer le HttpMessageHandler

Il peut être nécessaire de contrôler la configuration du HttpMessageHandler interne utilisé par un client.

Un IHttpClientBuilder est retourné quand vous ajoutez des clients nommés ou typés. La méthode d’extension ConfigurePrimaryHttpMessageHandler peut être utilisée pour définir un délégué. Le délégué est utilisé pour créer et configurer le HttpMessageHandler principal utilisé par ce client :

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

Cookies

Le regroupement des instances HttpMessageHandler engendre le partage d’objets CookieContainer. Le partage d’objets CookieContainer imprévus entraîne souvent un code incorrect. Pour les applications qui nécessitent des cookie, tenez compte de ce qui suit :

• Désactivation de la gestion de cookie automatique
• Éviter IHttpClientFactory

Appelez ConfigurePrimaryHttpMessageHandler pour désactiver la gestion de cookie automatique :

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

Utiliser IHttpClientFactory dans une application console

Dans une application console, ajoutez les références de package suivantes au projet :

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

Dans l’exemple suivant :

• IHttpClientFactory et GitHubService sont inscrits dans le conteneur de service dans de l’hôte générique.
• GitHubService est demandé à la DI, qui demande à son tour une instance de IHttpClientFactory.
• GitHubService utilise IHttpClientFactory pour créer une instance de HttpClient, qu’elle utilise pour récupérer des branches GitHub de documentation.

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);

Intergiciel de propagation d’en-tête

La propagation d’en-tête est un intergiciel ASP.NET Core pour propager les en-têtes HTTP de la requête entrante vers les requêtes HttpClient sortantes. Pour utiliser la propagation d’en-tête :

• Installez le package Microsoft.AspNetCore.HeaderPropagation.

• Configurez le pipeline de HttpClient et d’intergiciel dans 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();
  

• Effectuez des requêtes sortantes à l’aide de l’instance HttpClient configurée, qui inclut les en-têtes ajoutés.

Ressources supplémentaires

• Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
• Utilisez HttpClientFactory pour implémenter des requêtes HTTP résilientes
• Implémenter de nouvelles tentatives d’appel HTTP avec interruption exponentielle avec des stratégies Polly et HttpClientFactory
• Implémenter le modèle Disjoncteur
• Comment sérialiser et désérialiser JSON dans .NET