Configurer les options du serveur web ASP.NET Core Kestrel

Le serveur web Kestrel a des options de configuration de contraintes qui sont particulièrement utiles dans les déploiements exposés à Internet. Pour configurer les options de configuration Kestrel, appelez ConfigureKestrel dans Program.cs :

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    // ...
});

Définissez des contraintes sur la propriété KestrelServerOptions.Limits. Cette propriété conserve une instance de la classe KestrelServerLimits.

Limites générales

Délai d’expiration toujours actif

KeepAliveTimeout obtient ou définit le délai d’expiration Keep Alive :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
});

Ce délai d’expiration n’est pas appliqué lorsqu’un débogueur est attaché au processus Kestrel.

Nombre maximale de connexions client

MaxConcurrentConnections obtient ou définit le nombre maximal de connexions ouvertes :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
});

MaxConcurrentUpgradedConnections obtient ou définit le nombre maximal de connexions mises à niveau ouvertes :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
});

Une connexion mise à niveau est une connexion qui a basculé du protocole HTTP vers un autre protocole, tel que WebSockets. Une fois mise à niveau, une connexion n’est pas prise en compte dans la limite MaxConcurrentConnections.

Taille maximale du corps de la requête

MaxRequestBodySize obtient ou définit la taille maximale autorisée pour le corps d’une demande, en octets.

Pour remplacer la limite dans une application ASP.NET Core MVC, nous vous recommandons d’utiliser l’attribut RequestSizeLimitAttribute sur une méthode d’action :

[RequestSizeLimit(100_000_000)]
public IActionResult Get()

L’exemple suivant configure MaxRequestBodySize pour toutes les demandes :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxRequestBodySize = 100_000_000;
});

L’exemple suivant configure MaxRequestBodySize pour une demande spécifique en utilisant IHttpMaxRequestBodySizeFeature dans un intergiciel personnalisé :

app.Use(async (context, next) =>
{
    var httpMaxRequestBodySizeFeature = context.Features.Get<IHttpMaxRequestBodySizeFeature>();

    if (httpMaxRequestBodySizeFeature is not null)
        httpMaxRequestBodySizeFeature.MaxRequestBodySize = 10 * 1024;

    // ...

    await next(context);
});

Si l’application tente de configurer la limite sur une demande après qu’elle a commencé à lire la demande, une exception est levée. Utilisez la propriété IHttpMaxRequestBodySizeFeature.IsReadOnly pour vérifier s’il est sûr de définir la propriété MaxRequestBodySize.

Lorsqu’une application s’exécute hors processus derrière le module ASP.NET Core, IIS définit la limite et la taille limite du corps de demande de Kestrel est désactivée.

Débit données minimal du corps de la requête

Kestrel vérifie à chaque seconde si les données arrivent au débit spécifié en octets/seconde. Si le débit est inférieur au minimum, la connexion expire. La période de grâce est la durée que Kestrel accorde au client pour augmenter son taux d’envoi jusqu’au minimum. Pendant cette période, le débit n’est pas vérifié. La période de grâce permet d’éviter la suppression des connexions qui, initialement, envoient des données à une vitesse réduite en raison de la lenteur du démarrage de TCP. Un débit minimal s’applique également à la réponse.

MinRequestBodyDataRate obtient ou définit le débit de données minimal du corps de demande en octets/seconde. MinResponseDataRate obtient ou définit le débit de données minimal de réponse en octets/seconde.

L’exemple suivant configure MinRequestBodyDataRate et MinResponseDataRate pour toutes les demandes :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MinRequestBodyDataRate = new MinDataRate(
        bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate = new MinDataRate(
        bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
});

L’exemple suivant configure MinRequestBodyDataRate et MinResponseDataRate pour une demande spécifique en utilisant IHttpMinRequestBodyDataRateFeature et IHttpMinResponseDataRateFeature dans un intergiciel personnalisé :

app.Use(async (context, next) =>
{
    var httpMinRequestBodyDataRateFeature = context.Features
        .Get<IHttpMinRequestBodyDataRateFeature>();

    if (httpMinRequestBodyDataRateFeature is not null)
    {
        httpMinRequestBodyDataRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    var httpMinResponseDataRateFeature = context.Features
        .Get<IHttpMinResponseDataRateFeature>();

    if (httpMinResponseDataRateFeature is not null)
    {
        httpMinResponseDataRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    // ...

    await next(context);
});

IHttpMinResponseDataRateFeature n’est pas présent dans HttpContext.Features pour les requêtes HTTP/2. La modification des limites de débit par demande n’est généralement pas prise en charge pour HTTP/2 en raison de la prise en charge du protocole pour le multiplexage des demandes. Toutefois, IHttpMinRequestBodyDataRateFeature est toujours présent dans HttpContext.Features pour les requêtes HTTP/2, car la limite de débit de lecture peut toujours être désactivée entièrement sur une base par demande en définissant IHttpMinResponseDataRateFeature.MinDataRate sur null même pour une requête HTTP/2. Les tentatives de lecture de IHttpMinRequestBodyDataRateFeature.MinDataRate ou les tentatives de définition de cet élément sur une valeur autre que null entraînent une exception NotSupportedException pour les requêtes HTTP/2.

Les limites de débit à l’échelle du serveur configurées par le biais de KestrelServerOptions.Limits s’appliquent encore aux connexions HTTP/1.x et HTTP/2.

Délai d’expiration des en-têtes de requête

RequestHeadersTimeout obtient ou définit la durée maximale passée par le serveur à recevoir des en-têtes de demande :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Ce délai d’expiration n’est pas appliqué lorsqu’un débogueur est attaché au processus Kestrel.

Limites HTTP/2

Les limites de cette section sont définies sur KestrelServerLimits.Http2.

Flux de données maximal par connexion

MaxStreamsPerConnection limite le nombre de flux de requête simultanée par connexion HTTP/2. Les flux de données excédentaires sont refusés :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxStreamsPerConnection = 100;
});

Taille de la table d’en-tête

HeaderTableSize limite la taille des tables de compression d’en-tête, en octets, que l’encodeur et le décodeur HPACK sur le serveur peuvent utiliser. Le décodeur HPACK décompresse les en-têtes HTTP pour les connexions HTTP/2 :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.HeaderTableSize = 4096;
});

Taille de trame maximale

MaxFrameSize indique la taille de la plus grande charge utile de trame autorisée à être reçue, en octets :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxFrameSize = 16_384;
});

Taille maximale d’en-tête de requête

MaxRequestHeaderFieldSize indique la taille de la taille maximale autorisée d’une séquence de champs d’en-tête de demande. Cette limite s’applique aux séquences de noms et de valeurs dans leurs représentations compressées et non compressées :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
});

Taille de fenêtre de connexion initiale

InitialConnectionWindowSize indique la quantité de données de corps de demande que le serveur est prêt à recevoir et à mettre en mémoire tampon à la fois, agrégée entre toutes les demandes (flux) par connexion :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialConnectionWindowSize = 131_072;
});

Les requêtes sont également limitées par InitialStreamWindowSize.

Taille de la fenêtre de flux initiale

InitialStreamWindowSize indique la quantité de données de corps de demande que le serveur est prêt à recevoir et à mettre en mémoire tampon à la fois par flux :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialStreamWindowSize = 98_304;
});

Les requêtes sont également limitées par InitialConnectionWindowSize.

Configuration des requêtes ping Keep Alive HTTP/2

Kestrel peut être configuré pour envoyer des requêtes ping HTTP/2 aux clients connectés. Les requêtes ping HTTP/2 ont plusieurs objectifs :

• Maintenir actives les connexions inactives. Certains clients et serveurs proxy ferment les connexions inactives. Les requêtes ping HTTP/2 sont considérées comme une activité sur une connexion et empêchent la fermeture de la connexion pour cause d’inactivité.
• Fermez les connexions non saines. Les connexions où le client ne répond pas au ping Keep Alive dans le temps configuré sont fermées par le serveur.

Il existe deux options de configuration associées aux requêtes ping Keep Alive HTTP/2 :

• KeepAlivePingDelay est un TimeSpan qui configure l’intervalle de ping. Le serveur envoie une requête ping Keep Alive au client s’il ne reçoit aucune trame pendant cette période. Les requêtes ping Keep Alive sont désactivées quand cette option est définie sur TimeSpan.MaxValue.
• KeepAlivePingTimeout est un TimeSpan qui configure le délai d’expiration des requêtes ping. Si le serveur ne reçoit aucune trame, telle qu’une réponse ping, pendant ce délai d’expiration, la connexion est fermée. Le délai d’expiration Keep Alive est désactivé quand cette option est définie sur TimeSpan.MaxValue.

L’exemple suivant définit KeepAlivePingDelay et KeepAlivePingTimeout :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.KeepAlivePingDelay = TimeSpan.FromSeconds(30);
    serverOptions.Limits.Http2.KeepAlivePingTimeout = TimeSpan.FromMinutes(1);
});

Autres options

E/S synchrone

AllowSynchronousIO contrôle si une E/S synchrone est autorisée pour la demande et la réponse.

Avertissement

Un grand nombre d’opérations d’E/S synchrones de blocage peut entraîner une privation de pool de thread, ce qui fait que l’application ne répond pas. Activez uniquement AllowSynchronousIO lors de l’utilisation d’une bibliothèque qui ne prend pas en charge l’E/S asynchrone.

L’exemple suivant active une E/S synchrone :

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.AllowSynchronousIO = true;
});

Pour obtenir des informations sur les autres options et limites de Kestrel, consultez :

• KestrelServerOptions
• KestrelServerLimits
• ListenOptions

Comportement avec le débogueur attaché

Certains délais d’expiration et limites de débit ne sont pas appliqués lorsqu’un débogueur est attaché à un processus Kestrel. Pour plus d’informations, consultez Comportement avec le débogueur attaché.