Implémentation du serveur web Kestrel dans ASP.NET CoreKestrel web server implementation in ASP.NET Core

Par Tom Dykstra, Chris Ross et Stephen HalterBy Tom Dykstra, Chris Ross, and Stephen Halter

Pour obtenir la version 1.1 de cette rubrique, téléchargez Kestrel web server implementation in ASP.NET Core (version 1.1, PDF).For the 1.1 version of this topic, download Kestrel web server implementation in ASP.NET Core (version 1.1, PDF).

Kestrel est un serveur web multiplateforme pour ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel est le serveur web inclus par défaut dans les modèles de projets ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel prend en charge les scénarios suivants :Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Mise à niveau opaque utilisée pour activer les WebSocketsOpaque upgrade used to enable WebSockets
  • Sockets UNIX pour des performances élevées derrière NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (sauf sur macOS†)HTTP/2 (except on macOS†)

†HTTP/2 sera pris en charge sur macOS dans une prochaine version.†HTTP/2 will be supported on macOS in a future release.

  • HTTPSHTTPS
  • Mise à niveau opaque utilisée pour activer les WebSocketsOpaque upgrade used to enable WebSockets
  • Sockets UNIX pour des performances élevées derrière NginxUnix sockets for high performance behind Nginx

Kestrel est pris en charge sur toutes les plateformes et les versions prises en charge par .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Prise en charge de HTTP/2HTTP/2 support

HTTP/2 est disponible pour les applications ASP.NET Core si les conditions de base suivantes sont remplies :HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Système d’exploitation†Operating system†
    • Windows Server 2016/Windows 10 ou version ultérieure‡Windows Server 2016/Windows 10 or later‡
    • Linux avec OpenSSL 1.0.2 ou version ultérieure (par exemple, Ubuntu 16.04 ou version ultérieure)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Framework cible : .NET Core 2.2 ou version ultérieureTarget framework: .NET Core 2.2 or later
  • Connexion ALPN (Application-Layer Protocol Negotiation)Application-Layer Protocol Negotiation (ALPN) connection
  • TLS 1.2 ou connexion ultérieureTLS 1.2 or later connection

†HTTP/2 sera pris en charge sur macOS dans une prochaine version.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel propose une prise en charge limitée de HTTP/2 sous Windows Server 2012 R2 et Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. La prise en charge est limitée car la liste des suites de chiffrement TLS prises en charge sur ces systèmes d’exploitation est limitée.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Un certificat généré à l’aide d’Elliptic Curve Digital Signature algorithme (ECDSA) peut être requis pour sécuriser les connexions TLS.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Si une connexion HTTP/2 est établie, HttpRequest.Protocol retourne HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 est désactivé par défaut.HTTP/2 is disabled by default. Pour plus d’informations sur la configuration, consultez les sections Options Kestrel et ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Quand utiliser Kestrel avec un proxy inverse ?When to use Kestrel with a reverse proxy

Vous pouvez utiliser Kestrel par lui-même ou avec un serveur proxy inverse, comme Internet Information Services (IIS), Nginx ou Apache.You can use Kestrel by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Un serveur proxy inverse reçoit les requêtes HTTP en provenance du réseau et les transmet à Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel utilisé comme serveur web edge (accessible sur Internet) :Kestrel used as an edge (Internet-facing) web server:

Kestrel communique directement avec Internet sans serveur proxy inverse

Kestrel utilisé dans une configuration de proxy inverse :Kestrel used in a reverse proxy configuration:

Kestrel communique indirectement avec Internet via un serveur proxy inverse, par exemple IIS, Nginx ou Apache

Les deux configurations, avec ou sans serveur proxy inverse, sont des configurations d’hébergement prises en charge pour les applications ASP.NET Core 2.1 ou ultérieur qui reçoivent des requêtes d’Internet.Either configuration—with or without a reverse proxy server—is a supported hosting configuration for ASP.NET Core 2.1 or later apps that receive requests from the Internet.

Kestrel, s’il est utilisé comme serveur de périphérie sans serveur proxy inverse, ne prend pas en charge le partage de la même adresse IP et du même port entre plusieurs processus.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Quand Kestrel est configuré pour écouter sur un port, il gère tout le trafic pour ce port, quel que soit les en-têtes Host des requêtes.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Un proxy inverse qui peut partager des ports a la possibilité de transférer des requêtes à Kestrel sur une adresse IP et un port uniques.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Même si un serveur proxy inverse n’est pas nécessaire, en utiliser un peut être un bon choix.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Un proxy inverse :A reverse proxy:

  • Peut limiter la surface publique exposée des applications qu’il héberge.Can limit the exposed public surface area of the apps that it hosts.
  • Fournit une couche supplémentaire de configuration et de défense.Provide an additional layer of configuration and defense.
  • Peut mieux s’intégrer à l’infrastructure existante.Might integrate better with existing infrastructure.
  • Simplifie la configuration de l’équilibrage de charge et d’une communication sécurisée (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Seul le serveur proxy inverse nécessite un certificat X.509 : ce serveur peut donc communiquer avec vos serveurs d’applications sur le réseau interne avec du HTTP normal.Only the reverse proxy server requires an X.509 certificate, and that server can communicate with your app servers on the internal network using plain HTTP.

Avertissement

L’hébergement dans une configuration de proxy inverse nécessite le filtrage d’hôte.Hosting in a reverse proxy configuration requires host filtering.

Comment utiliser Kestrel dans les applications ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

Le package Microsoft.AspNetCore.Server.Kestrel est inclus dans le métapackage Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou version ultérieure).The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later).

Les modèles de projet ASP.NET Core utilisent Kestrel par défaut.ASP.NET Core project templates use Kestrel by default. Dans Program.cs, le modèle de code appelle CreateDefaultBuilder, qui appelle UseKestrel en arrière-plan.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Pour fournir une configuration supplémentaire après l’appel de CreateDefaultBuilder, utilisez ConfigureKestrel :To provide additional configuration after calling CreateDefaultBuilder, use ConfigureKestrel:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        });

Si l’application n’appelle pas CreateDefaultBuilder pour configurer l’hôte, appelez UseKestrel avant d’appeler ConfigureKestrel :If the app doesn't call CreateDefaultBuilder to set up the host, call UseKestrel before calling ConfigureKestrel:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        })
        .Build();

    host.Run();
}

Pour fournir une configuration supplémentaire après l’appel de CreateDefaultBuilder, appelez UseKestrel :To provide additional configuration after calling CreateDefaultBuilder, call UseKestrel:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            // Set properties and call methods on options
        });

Options KestrelKestrel options

Le serveur web Kestrel a des options de configuration de contrainte qui sont particulièrement utiles dans les déploiements exposés à Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Définissez des contraintes sur la propriété Limits de la classe KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. La propriété Limits conserve une instance de la classe KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

Nombre maximale de connexions clientMaximum client connections

MaxConcurrentConnections
MaxConcurrentUpgradedConnections

Le nombre maximal de connexions TCP ouvertes simultanées peut être défini pour l’application entière avec le code suivant :The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

.ConfigureKestrel((context, options) =>
{
    options.Limits.MaxConcurrentConnections = 100;
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    options.Limits.MaxRequestBodySize = 10 * 1024;
    options.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Listen(IPAddress.Loopback, 5000);
    options.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Limits.MaxConcurrentConnections = 100;
        });

Il existe une limite distincte pour les connexions qui ont été mises à niveau à partir de HTTP ou HTTPS vers un autre protocole (par exemple, sur une demande WebSocket).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Une fois mise à niveau, une connexion n’est pas prise en compte dans la limite MaxConcurrentConnections.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

.ConfigureKestrel((context, options) =>
{
    options.Limits.MaxConcurrentConnections = 100;
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    options.Limits.MaxRequestBodySize = 10 * 1024;
    options.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Listen(IPAddress.Loopback, 5000);
    options.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Limits.MaxConcurrentUpgradedConnections = 100;
        });

Le nombre maximal de connexions est illimité (null) par défaut.The maximum number of connections is unlimited (null) by default.

Taille maximale du corps de la requêteMaximum request body size

MaxRequestBodySize

La taille maximale par défaut du corps de la requête est de 30 000 000 octets, soit environ 28,6 Mo.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

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 :The recommended approach to override the limit in an ASP.NET Core MVC app is to use the RequestSizeLimitAttribute attribute on an action method:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Voici un exemple qui montre comment configurer la contrainte pour l’application sur chaque requête :Here's an example that shows how to configure the constraint for the app on every request:

.ConfigureKestrel((context, options) =>
{
    options.Limits.MaxConcurrentConnections = 100;
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    options.Limits.MaxRequestBodySize = 10 * 1024;
    options.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Listen(IPAddress.Loopback, 5000);
    options.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Limits.MaxRequestBodySize = 10 * 1024;
        });

Vous pouvez remplacer le paramètre sur une demande spécifique dans l’intergiciel (middleware) :You can override the setting on a specific request in middleware:

app.Run(async (context) =>
{
    context.Features.Get<IHttpMaxRequestBodySizeFeature>()
        .MaxRequestBodySize = 10 * 1024;

    var minRequestRateFeature = 
        context.Features.Get<IHttpMinRequestBodyDataRateFeature>();
    var minResponseRateFeature = 
        context.Features.Get<IHttpMinResponseDataRateFeature>();

    if (minRequestRateFeature != null)
    {
        minRequestRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    if (minResponseRateFeature != null)
    {
        minResponseRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

Une exception est levée vous tentez de configurer la limite sur une requête une fois que l’application a commencé à la lire.An exception is thrown if you attempt to configure the limit on a request after the app has started to read the request. Il existe une propriété IsReadOnly qui indique si la propriété MaxRequestBodySize est en lecture seule ; si tel est le cas, il est trop tard pour configurer la limite.There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

Débit données minimal du corps de la requêteMinimum request body data rate

MinRequestBodyDataRate
MinResponseDataRate

Kestrel vérifie à chaque seconde si les données arrivent au débit spécifié en octets/seconde.Kestrel checks every second if data is arriving at the specified rate in bytes/second. 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 sa vitesse de transmission jusqu’à la limite minimale ; pendant cette période, le débit n’est pas vérifié.If the rate drops below the minimum, the connection is timed out. The grace period is the amount of time that Kestrel gives the client to increase its send rate up to the minimum; the rate isn't checked during that time. La période de grâce permet d’éviter la suppression des connexions qui, initialement, envoient des données à une vitesse lente en raison de la lenteur du démarrage de TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

Le débit minimal par défaut est 240 octets/seconde, avec une période de grâce de 5 secondes.The default minimum rate is 240 bytes/second with a 5 second grace period.

Un débit minimal s’applique également à la réponse.A minimum rate also applies to the response. Le code pour définir les limites de demande et de réponse est identique à l’exception de RequestBody ou Response dans les noms de propriété et d’interface.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

Voici un exemple qui montre comment configurer les débits de données minimaux dans Program.cs :Here's an example that shows how to configure the minimum data rates in Program.cs:

.ConfigureKestrel((context, options) =>
{
    options.Limits.MaxConcurrentConnections = 100;
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    options.Limits.MaxRequestBodySize = 10 * 1024;
    options.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Listen(IPAddress.Loopback, 5000);
    options.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Limits.MinRequestBodyDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
            options.Limits.MinResponseDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
        });

Vous pouvez remplacer les limites de débit minimal par requête dans l’intergiciel (middleware) :You can override the minimum rate limits per request in middleware:

app.Run(async (context) =>
{
    context.Features.Get<IHttpMaxRequestBodySizeFeature>()
        .MaxRequestBodySize = 10 * 1024;

    var minRequestRateFeature = 
        context.Features.Get<IHttpMinRequestBodyDataRateFeature>();
    var minResponseRateFeature = 
        context.Features.Get<IHttpMinResponseDataRateFeature>();

    if (minRequestRateFeature != null)
    {
        minRequestRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    if (minResponseRateFeature != null)
    {
        minResponseRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

Aucune des fonctionnalités de débit référencées dans l’exemple précédent n’est présente dans HttpContext.Features pour les requêtes HTTP/2, car la modification des limites de débit par requête n’est pas prise en charge pour HTTP/2 (le protocole prend en charge le multiplexage de requête).Neither rate feature referenced in the prior sample are present in HttpContext.Features for HTTP/2 requests because modifying rate limits on a per-request basis isn't supported for HTTP/2 due to the protocol's support for request multiplexing. 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.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Flux de données maximal par connexionMaximum streams per connection

Http2.MaxStreamsPerConnection limite le nombre de flux de requête simultanée par connexion HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Les flux de données excédentaires sont refusés.Excess streams are refused.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.Http2.MaxStreamsPerConnection = 100;
        });

La valeur par défaut est 100.The default value is 100.

Taille de la table d’en-têteHeader table size

Le décodeur HPACK décompresse les en-têtes HTTP pour les connexions HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize limite la taille de la table de compression d’en-tête que le décodeur HPACK utilise.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. La valeur est fournie en octets et doit être supérieure à zéro (0).The value is provided in octets and must be greater than zero (0).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.Http2.HeaderTableSize = 4096;
        });

La valeur par défaut est 4096.The default value is 4096.

Taille de trame maximaleMaximum frame size

Http2.MaxFrameSize Indique la taille maximale de charge utile dans la trame de connexion HTTP/2 à recevoir.Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. La valeur est fournie en octets et doit être comprise entre 2^14 (16,384) et 2^24-1 (16,777,215).The value is provided in octets and must be between 2^14 (16,384) and 2^24-1 (16,777,215).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.Http2.MaxFrameSize = 16384;
        });

La valeur par défaut est 2^14 (16,384).The default value is 2^14 (16,384).

Taille maximale d’en-tête de requêteMaximum request header size

Http2.MaxRequestHeaderFieldSize indique la taille maximale autorisée en octets des valeurs d’en-tête de requête.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Cette limite s’applique au nom et à la valeur dans leurs représentations compressées et non compressées.This limit applies to both name and value together in their compressed and uncompressed representations. La valeur doit être supérieure à zéro (0).The value must be greater than zero (0).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
        });

La valeur par défaut est 8 192.The default value is 8,192.

Taille de fenêtre de connexion initialeInitial connection window size

Http2.InitialConnectionWindowSize indique la quantité maximale de données de corps de requête, en octets, que le serveur met en mémoire tampon à un moment donné pour toutes les requêtes (flux) par connexion.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Les requêtes sont également limitées par Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. La valeur doit être supérieure ou égale à 65 535 et inférieure à 2^31 (2 147 483 648).The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.Http2.InitialConnectionWindowSize = 131072;
        });

La valeur par défaut est 128 Ko (131 072).The default value is 128 KB (131,072).

Taille de la fenêtre de flux initialeInitial stream window size

Http2.InitialStreamWindowSize indique la quantité maximale de données de corps de requête, en octets, que le serveur met en mémoire tampon à un moment donné par requête (flux).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Les requêtes sont également limitées par Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. La valeur doit être supérieure ou égale à 65 535 et inférieure à 2^31 (2 147 483 648).The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.Http2.InitialStreamWindowSize = 98304;
        });

La valeur par défaut est 96 Ko (98 304).The default value is 96 KB (98,304).

Pour plus d’informations sur les autres options et limites de Kestrel, consultez :For information about other Kestrel options and limits, see:

Configuration de point de terminaisonEndpoint configuration

Par défaut, ASP.NET Core se lie à :By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (quand un certificat de développement local est présent)https://localhost:5001 (when a local development certificate is present)

Un certificat de développement est créé :A development certificate is created:

Vous devez accorder à certains navigateurs l’autorisation explicite d’approuver le certificat de développement local.Some browsers require that you grant explicit permission to the browser to trust the local development certificate.

Les modèles de projet ASP.NET Core 2.1 et ultérieur configurent les applications pour une exécution par défaut sur HTTPS et pour l’inclusion de la redirection HTTPS et de la prise en charge de HSTS.ASP.NET Core 2.1 and later project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Appelez les méthodes Listen ou ListenUnixSocket sur KestrelServerOptions pour configurer les préfixes et les ports d’URL pour Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, l’argument de ligne de commande --urls, la clé de configuration d’hôte urls et la variable d’environnement ASPNETCORE_URLS fonctionnent également, mais ils présentent les limitations indiquées plus loin dans cette section (un certificat par défaut doit être disponible pour la configuration du point de terminaison HTTPS).UseUrls, the --urls command-line argument, urls host configuration key, and the ASPNETCORE_URLS environment variable also work but have the limitations noted later in this section (a default certificate must be available for HTTPS endpoint configuration).

Configuration de KestrelServerOptions pour ASP.NET Core 2.1 :ASP.NET Core 2.1 KestrelServerOptions configuration:

ConfigureEndpointDefaults(Action<ListenOptions>)ConfigureEndpointDefaults(Action<ListenOptions>)

Spécifie une Action de configuration à exécuter pour chaque point de terminaison spécifié.Specifies a configuration Action to run for each specified endpoint. Le fait d’appeler ConfigureEndpointDefaults plusieurs fois remplace les Actions précédentes par la dernière Action spécifiée.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Spécifie une Action de configuration à exécuter pour chaque point de terminaison HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Le fait d’appeler ConfigureHttpsDefaults plusieurs fois remplace les Actions précédentes par la dernière Action spécifiée.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

Configure(IConfiguration)Configure(IConfiguration)

Crée un chargeur de configuration pour configurer Kestrel, qui prend en entrée une IConfiguration.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. La configuration doit être limitée à la section de configuration pour Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configure Kestrel pour l’utilisation de HTTPS.Configure Kestrel to use HTTPS.

Extensions de ListenOptions.UseHttps :ListenOptions.UseHttps extensions:

  • UseHttps – Configure Kestrel pour l’utilisation de HTTPS avec le certificat par défaut.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Lève une exception si aucun certificat par défaut n’est configuré.Throws an exception if no default certificate is configured.
  • UseHttps(string fileName)
  • UseHttps(string fileName, string password)
  • UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
  • UseHttps(StoreName storeName, string subject)
  • UseHttps(StoreName storeName, string subject, bool allowInvalid)
  • UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
  • UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
  • UseHttps(X509Certificate2 serverCertificate)
  • UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
  • UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

Paramètres de ListenOptions.UseHttps :ListenOptions.UseHttps parameters:

  • filename est le chemin et le nom d’un fichier de certificat, relatif au répertoire qui contient les fichiers de contenu de l’application.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password est le mot de passe nécessaire pour accéder aux données du certificat X.509.password is the password required to access the X.509 certificate data.
  • configureOptions est une Action pour configurer les HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Retourne l'ListenOptions.Returns the ListenOptions.
  • storeName est le magasin de certificats à partir duquel charger le certificat.storeName is the certificate store from which to load the certificate.
  • subject est le nom du sujet du certificat.subject is the subject name for the certificate.
  • allowInvalid indique si les certificats non valides doivent être considérés, comme les certificats auto-signés.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location est l’emplacement du magasin à partir duquel charger le certificat.location is the store location to load the certificate from.
  • serverCertificate est le certificat X.509.serverCertificate is the X.509 certificate.

En production, HTTPS doit être explicitement configuré.In production, HTTPS must be explicitly configured. Au minimum, un certificat par défaut doit être fourni.At a minimum, a default certificate must be provided.

Configurations prises en charge décrites dans la suite :Supported configurations described next:

  • Pas de configurationNo configuration
  • Remplacer le certificat par défaut dans la configurationReplace the default certificate from configuration
  • Changer les valeurs par défaut dans le codeChange the defaults in code

Pas de configurationNo configuration

Kestrel écoute sur http://localhost:5000 et sur https://localhost:5001 (si un certificat par défaut est disponible).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Spécifiez les URL avec :Specify URLs using the:

  • La variable d’environnement ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • L’argument de ligne de commande --urls.--urls command-line argument.
  • La clé de configuration d’hôte urls.urls host configuration key.
  • La méthode d’extension UseUrls.UseUrls extension method.

Pour plus d’informations, consultez URL de serveur et Remplacer la configuration.For more information, see Server URLs and Override configuration.

La valeur fournie avec ces approches peut être un ou plusieurs points de terminaison HTTP et HTTPS (HTTPS si un certificat par défaut est disponible).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configurez la valeur sous forme de liste délimitée par des points-virgules (par exemple "Urls": "http://localhost:8000; http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Remplacer le certificat par défaut dans la configurationReplace the default certificate from configuration

Par défaut, CreateDefaultBuilder appelle serverOptions.Configure(context.Configuration.GetSection("Kestrel")) pour charger la configuration de Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Un schéma de configuration des paramètres d’application HTTPS par défaut est disponible pour Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Configurez plusieurs points de terminaison, notamment les URL et les certificats à utiliser, à partir d’un fichier sur disque ou d’un magasin de certificats.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

Dans l’exemple de fichier appsettings.json suivant :In the following appsettings.json example:

  • Définissez AllowInvalid sur true pour permettre l’utilisation de certificats non valides (par exemple des certificats auto-signés).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Tout point de terminaison HTTPS qui ne spécifie pas de certificat (HttpsDefaultCert dans l’exemple qui suit) revient au certificat défini sous Certificats > Par défaut ou au certificat de développement.Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls back to the cert defined under Certificates > Default or the development certificate.
{
"Kestrel": {
  "EndPoints": {
    "Http": {
      "Url": "http://localhost:5000"
    },

    "HttpsInlineCertFile": {
      "Url": "https://localhost:5001",
      "Certificate": {
        "Path": "<path to .pfx file>",
        "Password": "<certificate password>"
      }
    },

    "HttpsInlineCertStore": {
      "Url": "https://localhost:5002",
      "Certificate": {
        "Subject": "<subject; required>",
        "Store": "<certificate store; defaults to My>",
        "Location": "<location; defaults to CurrentUser>",
        "AllowInvalid": "<true or false; defaults to false>"
      }
    },

    "HttpsDefaultCert": {
      "Url": "https://localhost:5003"
    },

    "Https": {
      "Url": "https://*:5004",
      "Certificate": {
      "Path": "<path to .pfx file>",
      "Password": "<certificate password>"
      }
    }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "<certificate password>"
      }
    }
  }
}

Une alternative à l’utilisation de Chemin et de Mot de passe pour un nœud de certificat consiste à spécifier le certificat avec des champs du magasin de certificats.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Par exemple, le certificat Certificats > Par défaut peut être spécifié en tant que :For example, the Certificates > Default certificate can be specified as:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; defaults to My>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

Notes de schéma :Schema notes:

  • Les noms des points de terminaison ne respectent pas la casse.Endpoints names are case-insensitive. Par exemple, HTTPS et Https sont valides.For example, HTTPS and Https are valid.

  • Le paramètre Url est obligatoire pour chaque point de terminaison.The Url parameter is required for each endpoint. Le format de ce paramètre est le même que celui du paramètre de configuration Urls du plus haut niveau, sauf qu’il est limité à une seule valeur.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.

  • Ces points de terminaison remplacent ceux qui sont définis dans le paramètre de configuration Urls du plus haut niveau configuration, au lieu de s’y ajouter.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Les points de terminaison définis dans le code via Listen sont cumulatifs avec les points de terminaison définis dans la section de configuration.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.

  • La section Certificate est facultative.The Certificate section is optional. Si la section Certificate n’est pas spécifiée, les valeurs par défaut définies dans les scénarios précédents sont utilisées.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Si aucune valeur par défaut n’est disponible, le serveur lève une exception et son démarrage échoue.If no defaults are available, the server throws an exception and fails to start.

  • La section Certificate prend en charge les certificats CheminMot de passe et SujetMagasin.The Certificate section supports both PathPassword and SubjectStore certificates.

  • Vous pouvez définir un nombre quelconque de points de terminaison de cette façon, pour autant qu’ils ne provoquent pas de conflits de port.Any number of endpoints may be defined in this way so long as they don't cause port conflicts.

  • options.Configure(context.Configuration.GetSection("Kestrel")) retourne un KestrelConfigurationLoader avec une méthode .Endpoint(string name, options => { }) qui peut être utilisée pour compléter les paramètres d’un point de terminaison configuré :options.Configure(context.Configuration.GetSection("Kestrel")) returns a KestrelConfigurationLoader with an .Endpoint(string name, options => { }) method that can be used to supplement a configured endpoint's settings:

    options.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", opt =>
        {
            opt.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
    

    Vous pouvez également accéder directement à KestrelServerOptions.ConfigurationLoader pour continuer à boucler sur le chargeur existant, comme celui fourni par CreateDefaultBuilder.You can also directly access KestrelServerOptions.ConfigurationLoader to keep iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • La section de configuration pour chaque point de terminaison est disponible sur les options de la méthode Endpoint, ce qui permet de lire les paramètres personnalisés.The configuration section for each endpoint is a available on the options in the Endpoint method so that custom settings may be read.

  • Plusieurs configurations peuvent être chargées en rappelant options.Configure(context.Configuration.GetSection("Kestrel")) avec une autre section.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("Kestrel")) again with another section. Seule la dernière configuration est utilisée, à moins que Load soit explicitement appelé sur les instances précédentes.Only the last configuration is used, unless Load is explicitly called on prior instances. Le métapackage n’appelle pas Load : sa section de configuration par défaut peut donc être remplacée.The metapackage doesn't call Load so that its default configuration section may be replaced.

  • KestrelConfigurationLoader reflète la famille d’API Listen de KestrelServerOptions sous forme de surcharges de Endpoint : le code et les points de terminaison de configuration peuvent donc être configurés au même emplacement.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Ces surcharges n’utilisent pas de noms et consomment seulement les paramètres par défaut de la configuration.These overloads don't use names and only consume default settings from configuration.

Changer les valeurs par défaut dans le codeChange the defaults in code

ConfigureEndpointDefaults et ConfigureHttpsDefaults peuvent être utilisés pour modifier les paramètres par défaut pour ListenOptions et HttpsConnectionAdapterOptions, notamment en remplaçant le certificat par défaut spécifié dans le scénario précédent.ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. ConfigureEndpointDefaults et ConfigureHttpsDefaults doivent être appelés avant que des points de terminaison soient configurés.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

options.ConfigureEndpointDefaults(opt =>
{
    opt.NoDelay = true;
});

options.ConfigureHttpsDefaults(httpsOptions =>
{
    httpsOptions.SslProtocols = SslProtocols.Tls12;
});

Prise en charge de SNI par KestrelKestrel support for SNI

L’indication du nom de serveur (SNI, Server Name Indication) peut être utilisée pour héberger plusieurs domaines sur la même adresse IP et le même port.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Pour que SNI fonctionne, le client envoie le nom d’hôte pour la session sécurisée au serveur pendant la négociation TLS afin que le serveur puisse fournir le certificat correct.For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. Le client utilise le certificat fourni pour la communication chiffrée avec le serveur pendant la session sécurisée qui suit la négociation TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel prend en charge SNI via le rappel de ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. Le rappel est appelé une fois par connexion pour permettre à l’application d’inspecter le nom d’hôte et de sélectionner le certificat approprié.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

La prise en charge de SNI nécessite les points suivants :SNI support requires:

  • Exécution sur le framework cible netcoreapp2.1.Running on target framework netcoreapp2.1. Sur netcoreapp2.0 et net461, le rappel est appelé, mais name est toujours null.On netcoreapp2.0 and net461, the callback is invoked but the name is always null. name est également null si le client ne fournit pas le paramètre du nom d’hôte dans la négociation TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Tous les sites web s’exécutent sur la même instance Kestrel.All websites run on the same Kestrel instance. Kestrel ne prend pas en charge le partage d’une adresse IP et d’un port entre plusieurs instances sans un proxy inverse.Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.ListenAnyIP(5005, listenOptions =>
            {
                listenOptions.UseHttps(httpsOptions =>
                {
                    var localhostCert = CertificateLoader.LoadFromStoreCert(
                        "localhost", "My", StoreLocation.CurrentUser, 
                        allowInvalid: true);
                    var exampleCert = CertificateLoader.LoadFromStoreCert(
                        "example.com", "My", StoreLocation.CurrentUser, 
                        allowInvalid: true);
                    var subExampleCert = CertificateLoader.LoadFromStoreCert(
                        "sub.example.com", "My", StoreLocation.CurrentUser, 
                        allowInvalid: true);
                    var certs = new Dictionary<string, X509Certificate2>(
                        StringComparer.OrdinalIgnoreCase);
                    certs["localhost"] = localhostCert;
                    certs["example.com"] = exampleCert;
                    certs["sub.example.com"] = subExampleCert;

                    httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
                    {
                        if (name != null && certs.TryGetValue(name, out var cert))
                        {
                            return cert;
                        }

                        return exampleCert;
                    };
                });
            });
        });
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, options) =>
        {
            options.ListenAnyIP(5005, listenOptions =>
            {
                listenOptions.UseHttps(httpsOptions =>
                {
                    var localhostCert = CertificateLoader.LoadFromStoreCert(
                        "localhost", "My", StoreLocation.CurrentUser, 
                        allowInvalid: true);
                    var exampleCert = CertificateLoader.LoadFromStoreCert(
                        "example.com", "My", StoreLocation.CurrentUser, 
                        allowInvalid: true);
                    var subExampleCert = CertificateLoader.LoadFromStoreCert(
                        "sub.example.com", "My", StoreLocation.CurrentUser, 
                        allowInvalid: true);
                    var certs = new Dictionary<string, X509Certificate2>(
                        StringComparer.OrdinalIgnoreCase);
                    certs["localhost"] = localhostCert;
                    certs["example.com"] = exampleCert;
                    certs["sub.example.com"] = subExampleCert;

                    httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
                    {
                        if (name != null && certs.TryGetValue(name, out var cert))
                        {
                            return cert;
                        }

                        return exampleCert;
                    };
                });
            });
        })
        .Build();

Lier à un socket TCPBind to a TCP socket

La méthode Listen se lie à un socket TCP, et une expression lambda options permet la configuration d’un certificat X.509 :The Listen method binds to a TCP socket, and an options lambda permits X.509 certificate configuration:

public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Listen(IPAddress.Loopback, 5000);
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Listen(IPAddress.Loopback, 5000);
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Listen(IPAddress.Loopback, 5000);
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

L’exemple configure HTTPS pour un point de terminaison avec ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Utilisez la même API afin de configurer d’autres paramètres Kestrel pour des points de terminaison spécifiques.Use the same API to configure other Kestrel settings for specific endpoints.

Pour créer des certificats auto-signés sous Windows, vous pouvez utiliser la cmdlet PowerShell New-SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Vous trouverez un exemple non pris en charge sur la page UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

OpenSSL permet de créer des certificats sous macOS, Linux et Windows.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Lier à un socket UnixBind to a Unix socket

Écoutez sur un socket Unix avec ListenUnixSocket pour améliorer les performances avec Nginx, comme illustré dans cet exemple :Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

.ConfigureKestrel((context, options) =>
{
    options.ListenUnixSocket("/tmp/kestrel-test.sock");
    options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
});
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.ListenUnixSocket("/tmp/kestrel-test.sock");
            options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testpassword");
            });
        });

Port 0Port 0

Si vous spécifiez le numéro de port 0, Kestrel se lie dynamiquement à un port disponible.When the port number 0 is specified, Kestrel dynamically binds to an available port. L’exemple suivant montre comment déterminer le port auquel Kestrel se lie à l’exécution :The following example shows how to determine which port Kestrel actually bound at runtime:

public void Configure(IApplicationBuilder app)
{
    var serverAddressesFeature = 
        app.ServerFeatures.Get<IServerAddressesFeature>();

    app.UseStaticFiles();

    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html";
        await context.Response
            .WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
                "<title></title></head><body><p>Hosted by Kestrel</p>");

        if (serverAddressesFeature != null)
        {
            await context.Response
                .WriteAsync("<p>Listening on the following addresses: " +
                    string.Join(", ", serverAddressesFeature.Addresses) +
                    "</p>");
        }

        await context.Response.WriteAsync("<p>Request URL: " +
            $"{context.Request.GetDisplayUrl()}<p>");
    });
}

Quand l’application est exécutée, la sortie de la fenêtre de console indique le port dynamique où l’application peut être atteinte :When the app is run, the console window output indicates the dynamic port where the app can be reached:

Listening on the following addresses: http://127.0.0.1:48508

LimitationsLimitations

Configurez des points de terminaison avec les approches suivantes :Configure endpoints with the following approaches:

  • UseUrls
  • Arguments de ligne de commande --urls--urls command-line argument
  • La clé de configuration d’hôte urlsurls host configuration key
  • Variable d’environnement ASPNETCORE_URLSASPNETCORE_URLS environment variable

Ces méthodes sont utiles si vous voulez que votre code fonctionne avec des serveurs autres que Kestrel.These methods are useful for making code work with servers other than Kestrel. Toutefois, soyez conscient des limitations suivantes :However, be aware of the following limitations:

  • HTTPS ne peut pas être utilisé avec ces approches, sauf si un certificat par défaut est fourni dans la configuration du point de terminaison HTTPS (par exemple avec la configuration de KestrelServerOptions ou un fichier de configuration, comme illustré plus haut dans cette rubrique).HTTPS can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint configuration (for example, using KestrelServerOptions configuration or a configuration file as shown earlier in this topic).
  • Quand les deux approches Listen et UseUrls sont utilisées simultanément, les points de terminaison Listen remplacent les points de terminaison UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configuration de point de terminaison IISIIS endpoint configuration

Quand vous utilisez IIS, les liaisons d’URL pour IIS remplacent les liaisons qui sont définies par Listen ou par UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Pour plus d’informations, consultez la rubrique Module ASP.NET Core.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

La propriété Protocols établit les protocoles HTTP (HttpProtocols) activés sur un point de terminaison de connexion ou pour le serveur.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Affectez une valeur à la propriété Protocols à partir de l’énumération HttpProtocols.Assign a value to the Protocols property from the HttpProtocols enum.

Valeur enum HttpProtocolsHttpProtocols enum value Protocole de connexion autoriséConnection protocol permitted
Http1 HTTP/1.1 uniquement.HTTP/1.1 only. Peut être utilisé avec ou sans TLS.Can be used with or without TLS.
Http2 HTTP/2 uniquement.HTTP/2 only. Principalement utilisé avec TLS.Primarily used with TLS. Peut être utilisé sans TLS, uniquement si le client prend en charge un mode de connaissance préalable (Prior Knowledge).May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 et HTTP/2.HTTP/1.1 and HTTP/2. Nécessite une connexion TLS et ALPN (Application-Layer Protocol Negotiation) pour négocier HTTP/2 ; sinon, la connexion par défaut est HTTP/1.1.Requires a TLS and Application-Layer Protocol Negotiation (ALPN) connection to negotiate HTTP/2; otherwise, the connection defaults to HTTP/1.1.

Le protocole par défaut est HTTP/1.1.The default protocol is HTTP/1.1.

Restrictions TLS pour HTTP/2 :TLS restrictions for HTTP/2:

  • TLS version 1.2 ou ultérieureTLS version 1.2 or later
  • Renégociation désactivéeRenegotiation disabled
  • Compression désactivéeCompression disabled
  • Tailles minimales de l’échange de clé éphémère :Minimum ephemeral key exchange sizes:
    • Diffie-Hellman à courbe elliptique (ECDHE) [RFC4492] – 224 bits minimumElliptic curve Diffie-Hellman (ECDHE) [RFC4492] – 224 bits minimum
    • Diffie-Hellman à champ fini (DHE) [TLS12] – 2 048 bits minimumFinite field Diffie-Hellman (DHE) [TLS12] – 2048 bits minimum
  • Suite de chiffrement non inscrite sur liste rougeCipher suite not blacklisted

Prise en charge par défaut de TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] avec la courbe elliptique P-256 [FIPS186].TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

L’exemple suivant autorise les connexions HTTP/1.1 et HTTP/2 sur le port 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Les connexions sont sécurisées par TLS avec un certificat fourni :Connections are secured by TLS with a supplied certificate:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Listen(IPAddress.Any, 8000, listenOptions =>
            {
                listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

Le cas échéant, créez une implémentation IConnectionAdapter pour filtrer les négociations TLS par connexion pour des chiffrements spécifiques :Optionally create an IConnectionAdapter implementation to filter TLS handshakes on a per-connection basis for specific ciphers:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            options.Listen(IPAddress.Any, 8000, listenOptions =>
            {
                listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
                listenOptions.UseHttps("testCert.pfx", "testPassword");
                listenOptions.ConnectionAdapters.Add(new TlsFilterAdapter());
            });
        });
private class TlsFilterAdapter : IConnectionAdapter
{
    public bool IsHttps => false;

    public Task<IAdaptedConnection> OnConnectionAsync(ConnectionAdapterContext context)
    {
        var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

        // Throw NotSupportedException for any cipher algorithm that you don't 
        // wish to support. Alternatively, define and compare 
        // ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher 
        // suites.
        //
        // A ITlsHandshakeFeature.CipherAlgorithm of CipherAlgorithmType.Null 
        // indicates that no cipher algorithm supported by Kestrel matches the 
        // requested algorithm(s).
        if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
        {
            throw new NotSupportedException("Prohibited cipher: " + tlsFeature.CipherAlgorithm);
        }

        return Task.FromResult<IAdaptedConnection>(new AdaptedConnection(context.ConnectionStream));
    }

    private class AdaptedConnection : IAdaptedConnection
    {
        public AdaptedConnection(Stream adaptedStream)
        {
            ConnectionStream = adaptedStream;
        }

        public Stream ConnectionStream { get; }

        public void Dispose()
        {
        }
    }
}

Définir le protocole à partir de la configurationSet the protocol from configuration

Par défaut, CreateDefaultBuilder appelle serverOptions.Configure(context.Configuration.GetSection("Kestrel")) pour charger la configuration de Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

Dans l’exemple appsettings.json suivant, un protocole de connexion par défaut (HTTP/1.1 et HTTP/2) est établi pour l’ensemble des points de terminaison de Kestrel :In the following appsettings.json example, a default connection protocol (HTTP/1.1 and HTTP/2) is established for all of Kestrel's endpoints:

{
  "Kestrel": {
    "EndPointDefaults": {
      "Protocols": "Http1AndHttp2"
    }
  }
}

L’exemple de fichier de configuration suivant établit un protocole de connexion pour un point de terminaison spécifique :The following configuration file example establishes a connection protocol for a specific endpoint:

{
  "Kestrel": {
    "EndPoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1AndHttp2"
      }
    }
  }
}

Les protocoles spécifiés dans le code remplacent les valeurs définies par configuration.Protocols specified in code override values set by configuration.

Configuration du transportTransport configuration

Dans ASP.NET Core 2.1, le transport par défaut de Kestrel n’est plus basé sur Libuv, mais sur des sockets managés.With the release of ASP.NET Core 2.1, Kestrel's default transport is no longer based on Libuv but instead based on managed sockets. Il s’agit d’un changement cassant pour les applications ASP.NET Core 2.0 mises à niveau vers la version 2.1 qui appellent UseLibuv et qui dépendent d’un des packages suivants :This is a breaking change for ASP.NET Core 2.0 apps upgrading to 2.1 that call UseLibuv and depend on either of the following packages:

Pour les projets ASP.NET Core 2.1 ou ultérieur qui utilisent le métapaquet Microsoft.AspNetCore.App et nécessitent l’utilisation de Libuv :For ASP.NET Core 2.1 or later projects that use the Microsoft.AspNetCore.App metapackage and require the use of Libuv:

  • Ajoutez une dépendance pour le package Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv au fichier projet de l’application :Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's project file:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv" 
                      Version="<LATEST_VERSION>" />
    
  • Appelez UseLibuv :Call UseLibuv:

    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }
    
        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseLibuv()
                .UseStartup<Startup>();
    }
    

Préfixes d’URLURL prefixes

Quand vous utilisez UseUrls, l’argument de ligne de commande --urls, la clé de configuration d’hôte urls ou la variable d’environnement ASPNETCORE_URLS, les préfixes d’URL peuvent être dans un des formats suivants.When using UseUrls, --urls command-line argument, urls host configuration key, or ASPNETCORE_URLS environment variable, the URL prefixes can be in any of the following formats.

Seuls les préfixes d’URL HTTP sont valides.Only HTTP URL prefixes are valid. Kestrel ne prend pas en charge HTTPS lors de la configuration de liaisons d’URL avec UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Adresse IPv4 avec numéro de portIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 est un cas spécial qui se lie à toutes les adresses IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Adresse IPv6 avec numéro de portIPv6 address with port number

    http://[0:0:0:0:0:ffff:4137:270a]:80/
    

    [::] est l’équivalent IPv6 de 0.0.0.0 dans IPv4.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nom d’hôte avec numéro de portHost name with port number

    http://contoso.com:80/
    http://*:80/
    

    Les noms d’hôte, * et + ne sont pas spéciaux.Host names, *, and +, aren't special. Tout ce qui n’est pas reconnu comme adresse IP valide ou localhost se lie à toutes les adresses IP IPv4 et IPv6.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Pour lier différents noms d’hôte à différentes applications ASP.NET Core sur le même port, utilisez HTTP.sys ou un serveur proxy inverse, comme IIS, Nginx ou Apache.To bind different host names to different ASP.NET Core apps on the same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.

    Avertissement

    L’hébergement dans une configuration de proxy inverse nécessite le filtrage d’hôte.Hosting in a reverse proxy configuration requires host filtering.

  • Nom localhost de l’hôte avec numéro de port ou adresse IP de bouclage avec numéro de portHost localhost name with port number or loopback IP with port number

    http://localhost:5000/
    http://127.0.0.1:5000/
    http://[::1]:5000/
    

    Quand localhost est spécifié, Kestrel tente de se lier aux interfaces de bouclage IPv4 et IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Si le port demandé est en cours d’utilisation par un autre service sur l’une des interfaces de bouclage, Kestrel ne démarre pas.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Si l’une des interfaces de bouclage n’est pas disponible pour une raison quelconque (généralement du fait de la non-prise en charge d’IPv6), Kestrel journalise un avertissement.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtrage d’hôtesHost filtering

Si Kestrel prend en charge la configuration basée sur les préfixes, comme http://example.com:5000, il ignore en grande partie le nom d’hôte.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. L’hôte localhost est un cas spécial utilisé pour la liaison à des adresses de bouclage.Host localhost is a special case used for binding to loopback addresses. Tout hôte autre qu’une adresse IP explicite se lie à toutes les adresses IP publiques.Any host other than an explicit IP address binds to all public IP addresses. Les en-têtes Host ne sont pas validés.Host headers aren't validated.

En guise de solution de contournement, utilisez le middleware de filtrage d’hôtes.As a workaround, use Host Filtering Middleware. Le middleware de filtrage d’hôtes est fourni par le package Microsoft.AspNetCore.HostFiltering, qui est inclus dans le métapaquet Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou version ultérieure).Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later). L’intergiciel (middleware) est ajouté par CreateDefaultBuilder, qui appelle AddHostFiltering :The middleware is added by CreateDefaultBuilder, which calls AddHostFiltering:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Le middleware de filtrage d’hôtes est désactivé par défaut.Host Filtering Middleware is disabled by default. Pour activer le middleware, définissez une clé AllowedHosts dans appsettings.json/appsettings.<nom_environnement>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. La valeur est une liste délimitée par des points-virgules des noms d’hôte sans numéros de port :The value is a semicolon-delimited list of host names without port numbers:

appsettings.json :appsettings.json:

{
  "AllowedHosts": "example.com;localhost"
}

Notes

Le middleware des en-têtes transférés a aussi une option AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. Le middleware des en-têtes transférés et le middleware de filtrage d’hôtes ont des fonctionnalités similaires pour différents scénarios.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. La définition d’AllowedHosts avec le middleware des en-têtes transférés est appropriée quand l’en-tête Host n’est pas conservé durant le transfert des requêtes avec un serveur proxy inverse ou un équilibreur de charge.Setting AllowedHosts with Forwarded Headers Middleware is appropriate when the Host header isn't preserved while forwarding requests with a reverse proxy server or load balancer. La définition d’AllowedHosts avec le middleware de filtrage d’hôtes est appropriée quand Kestrel est utilisé comme serveur de périphérie public ou que l’en-tête Host est directement transféré.Setting AllowedHosts with Host Filtering Middleware is appropriate when Kestrel is used as a public-facing edge server or when the Host header is directly forwarded.

Pour plus d’informations sur le middleware des en-têtes transférés, consultez Configurer ASP.NET Core pour l’utilisation de serveurs proxy et d’équilibreurs de charge.For more information on Forwarded Headers Middleware, see Configurer ASP.NET Core pour l’utilisation de serveurs proxy et d’équilibreurs de charge.

Ressources supplémentairesAdditional resources