Classe System.Net.Http.HttpClient

Cet article fournit des remarques supplémentaires à la documentation de référence de cette API.

L’instance HttpClient de classe agit comme une session pour envoyer des requêtes HTTP. Une HttpClient instance est une collection de paramètres appliqués à toutes les requêtes exécutées par cette instance. En outre, chaque HttpClient instance utilise son propre pool de connexions, isolant ses requêtes des requêtes exécutées par d’autres HttpClient instances.

Instanciation

HttpClient est destiné à être instancié une fois et réutilisé tout au long de la durée d’une application. Dans .NET Core et .NET 5+, HttpClient regroupe les connexions à l’intérieur de l’instance du gestionnaire et réutilise une connexion entre plusieurs requêtes. Si vous instanciez une classe HttpClient pour chaque requête, le nombre de sockets disponibles sous de lourdes charges sera épuisé. Cet épuisement entraînera des erreurs SocketException.

Vous pouvez configurer des options supplémentaires en transmettant un « gestionnaire », tel que HttpClientHandler (ou SocketsHttpHandler dans .NET Core 2.1 ou version ultérieure), dans le cadre du constructeur. Les propriétés de connexion du gestionnaire ne peuvent pas être modifiées une fois qu’une demande a été envoyée. Par conséquent, une raison de créer une nouvelle instance HttpClient serait si vous devez modifier les propriétés de connexion. Si différentes demandes nécessitent des paramètres différents, cela peut également entraîner la présence d’une application ayant plusieurs HttpClient instances, où chaque instance est configurée de manière appropriée, puis les demandes sont émises sur le client approprié.

HttpClient résout uniquement les entrées DNS lorsqu’une connexion est créée. Il ne suit pas les durées de vie (TTL) spécifiées par le serveur DNS. Si les entrées DNS changent régulièrement, ce qui peut se produire dans certains scénarios de conteneur, le client ne respecte pas ces mises à jour. Pour résoudre ce problème, vous pouvez limiter la durée de vie de la connexion en définissant la SocketsHttpHandler.PooledConnectionLifetime propriété afin que la recherche DNS soit requise lorsque la connexion est remplacée.

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

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

        httpClient = new HttpClient(socketsHandler);
    }
}

En guise d’alternative à la création d’une seule instance HttpClient, vous pouvez également utiliser IHttpClientFactory pour gérer les instances HttpClient pour vous. Pour plus d’informations, consultez Instructions relatives à l’utilisation de HttpClient.

Dérivation

Il HttpClient agit également en tant que classe de base pour des clients HTTP plus spécifiques. Un exemple serait un FacebookHttpClient qui fournit des méthodes supplémentaires spécifiques à un service web Facebook (par exemple, une GetFriends méthode). Les classes dérivées ne doivent pas remplacer les méthodes virtuelles sur la classe. Utilisez plutôt une surcharge de constructeur qui accepte HttpMessageHandler pour configurer tout traitement avant la requête ou après la requête.

Transports

Il HttpClient s’agit d’une API de haut niveau qui encapsule les fonctionnalités de bas niveau disponibles sur chaque plateforme où elle s’exécute.

Sur chaque plateforme, HttpClient tente d’utiliser le meilleur transport disponible :

Les utilisateurs peuvent également configurer un transport spécifique pour HttpClient en appelant le constructeur HttpClient qui prend un HttpMessageHandler.

.NET Framework &Mono

Par défaut, sur .NET Framework et Mono, HttpWebRequest est utilisé pour envoyer des requêtes au serveur. Ce comportement peut être modifié en spécifiant un autre gestionnaire dans l’une des surcharges du constructeur avec un HttpMessageHandler paramètre. Si vous avez besoin de fonctionnalités telles que l’authentification ou la mise en cache, vous pouvez utiliser WebRequestHandler pour configurer les paramètres et l’instance peut être transmise au constructeur. Le gestionnaire retourné peut être passé à une surcharge de constructeur qui a un paramètre HttpMessageHandler.

.NET Core

À compter de .NET Core 2.1, la classe System.Net.Http.SocketsHttpHandler fournit plutôt que HttpClientHandler l’implémentation utilisée par des classes de mise en réseau HTTP de niveau supérieur tels que HttpClient. L'utilisation de SocketsHttpHandler offre un certain nombre d'avantages :

• Amélioration significative des performances par rapport à l’implémentation précédente.
• L’élimination des dépendances de plateforme, qui simplifie le déploiement et la maintenance. Par exemple, libcurl ne dépend plus de .NET Core pour macOS et .NET Core pour Linux.
• Comportement cohérent sur toutes les plateformes .NET.

Si cette modification n’est pas souhaitable, sur Windows, vous pouvez continuer à utiliser WinHttpHandler en référençant son package NuGet et en le transmettant manuellement au constructeur de HttpClient .

Configurer le comportement à l’aide des options de configuration du runtime

Certains aspects du comportement sont HttpClientpersonnalisables via les options de configuration runtime. Toutefois, le comportement de ces commutateurs diffère par le biais des versions de .NET. Par exemple, dans .NET Core 2.1 - 3.1, vous pouvez configurer si SocketsHttpHandler elle est utilisée par défaut, mais cette option n’est plus disponible à partir de .NET 5.

Regroupement de connexions

HttpClient met en pool les connexions HTTP si possible et les utilise pour plusieurs requêtes. Cela peut avoir un avantage significatif en matière de performances, en particulier pour les requêtes HTTPS, car la négociation de connexion n’est effectuée qu’une seule fois.

Les propriétés du pool de connexions peuvent être configurées sur un HttpClientHandler ou SocketsHttpHandler transmis lors de la construction, notamment MaxConnectionsPerServer, PooledConnectionIdleTimeout, et PooledConnectionLifetime.

La suppression de l’instance HttpClient ferme les connexions ouvertes et annule les demandes en attente.

Mise en mémoire tampon et durée de vie des requêtes

Par défaut, les méthodes HttpClient (sauf GetStreamAsync) mettent en mémoire tampon les réponses du serveur, lisant tout le corps de la réponse en mémoire avant de renvoyer le résultat asynchrone. Ces demandes continuent jusqu’à ce que l’une des opérations suivantes se produise :

• Le Task<TResult> réussit et retourne un résultat.
• Le Timeout est atteint, auquel cas le Task<TResult> sera annulé.
• Le CancellationToken passable à certaines surcharges de méthode est déclenché.
• CancelPendingRequests() est appelée.
• HttpClient est supprimé.

Vous pouvez modifier le comportement de mise en mémoire tampon par requête à l’aide du HttpCompletionOption paramètre disponible sur certaines surcharges de méthode. Cet argument peut être utilisé pour spécifier si celui-ci Task<TResult> doit être considéré comme terminé après avoir lu uniquement les en-têtes de réponse, ou après avoir lu et mis en mémoire tampon le contenu de la réponse.

Si votre application qui utilise HttpClient et les classes associées dans l’espace System.Net.Http de noms a l’intention de télécharger de grandes quantités de données (50 mégaoctets ou plus), l’application doit diffuser en continu ces téléchargements et ne pas utiliser la mise en mémoire tampon par défaut. Si vous utilisez la mise en mémoire tampon par défaut, l’utilisation de la mémoire client est très importante, ce qui peut entraîner une réduction substantielle des performances.

Sécurité des threads

Les méthodes suivantes sont sécurisées pour les threads :

• CancelPendingRequests
• DeleteAsync
• GetAsync
• GetByteArrayAsync
• GetStreamAsync
• GetStringAsync
• PostAsync
• PutAsync
• SendAsync

Intermédiaires

Par défaut, HttpClient lit la configuration du proxy à partir de variables d’environnement ou de paramètres utilisateur/système, en fonction de la plateforme. Vous pouvez modifier ce comportement en transmettant un WebProxy ou IWebProxy à, dans l’ordre de priorité :

• La propriété Proxy sur un HttpClientHandler passé pendant la construction de HttpClient
• La DefaultProxy propriété statique (affecte toutes les instances)

Vous pouvez désactiver le proxy à l’aide UseProxyde . La configuration par défaut pour les utilisateurs Windows consiste à essayer de détecter un proxy à l’aide de la découverte réseau, ce qui peut être lent. Pour les applications à débit élevé où il est connu qu’un proxy n’est pas nécessaire, vous devez désactiver le proxy.

Les paramètres de proxy (comme Credentials) doivent être modifiés uniquement avant la première requête à l’aide de HttpClient. Les modifications apportées après l’utilisation de HttpClient pour la première fois peuvent ne pas être reflétées dans les requêtes suivantes.

Délais d’expiration

Vous pouvez utiliser Timeout pour définir un délai d’expiration par défaut pour toutes les requêtes HTTP de l’instance HttpClient. Le délai d’expiration s’applique uniquement aux méthodes xxxAsync qui provoquent l’initialisation d’une demande/réponse. Si le délai d’expiration est atteint, la Task<TResult> demande est annulée.

Vous pouvez définir des délais d’expiration supplémentaires si vous passez dans une SocketsHttpHandler instance lors de la construction de l’objet HttpClient :

HttpClient résout uniquement les entrées DNS lorsque les connexions sont créées. Il ne suit pas les durées de vie (TTL) spécifiées par le serveur DNS. Si les entrées DNS changent régulièrement, ce qui peut se produire dans certains scénarios de conteneur, vous pouvez utiliser pour PooledConnectionLifetime limiter la durée de vie de la connexion afin que la recherche DNS soit requise lors du remplacement de la connexion.