Implementación del servidor web Kestrel en ASP.NET CoreKestrel web server implementation in ASP.NET Core

Por Tom Dykstra, Chris Ross, Stephen Halter y Luke LathamBy Tom Dykstra, Chris Ross, Stephen Halter, and Luke Latham

Kestrel es un servidor web multiplataforma de ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel es el servidor web que se incluye de forma predeterminada en las plantillas de proyecto de ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel admite los siguientes escenarios:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Actualización opaca para habilitar WebSocketsOpaque upgrade used to enable WebSockets
  • Sockets de Unix para alto rendimiento detrás de NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (excepto en macOS†)HTTP/2 (except on macOS†)

†HTTP/2 se admitirá en una versión futura en macOS.†HTTP/2 will be supported on macOS in a future release.

Kestrel admite todas las plataformas y versiones que sean compatibles con .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

Compatibilidad con HTTP/2HTTP/2 support

HTTP/2 está disponible para las aplicaciones de ASP.NET Core si se cumplen los siguientes requisitos básicos:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Sistema operativo†Operating system†
    • Windows Server 2016/Windows 10 o posterior‡Windows Server 2016/Windows 10 or later‡
    • Linux con OpenSSL 1.0.2 o posterior (por ejemplo, Ubuntu 16.04 o posterior)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Plataforma de destino: .NET Core 2.2 o posteriorTarget framework: .NET Core 2.2 or later
  • Conexión con Application-Layer Protocol Negotiation (ALPN)Application-Layer Protocol Negotiation (ALPN) connection
  • Conexión con TLS 1.2 o una versión posteriorTLS 1.2 or later connection

†HTTP/2 se admitirá en una versión futura en macOS.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel tiene compatibilidad limitada para HTTP/2 en Windows Server 2012 R2 y Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. La compatibilidad es limitada porque la lista de conjuntos de cifrado TLS admitidos y disponibles en estos sistemas operativos está limitada.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Se puede requerir un certificado generado mediante Elliptic Curve Digital Signature Algorithm (ECDSA) para proteger las conexiones TLS.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Si se establece una conexión HTTP/2, HttpRequest.Protocol notifica HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 está deshabilitado de manera predeterminada.HTTP/2 is disabled by default. Para obtener más información sobre la configuración, consulte las secciones Opciones de Kestrel y ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Cuándo usar Kestrel con un proxy inversoWhen to use Kestrel with a reverse proxy

Kestrel se puede usar por sí solo o con un servidor proxy inverso, como Internet Information Services (IIS), Nginx o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Un servidor proxy inverso recibe las solicitudes HTTP de la red y las reenvía a Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel empleado como servidor web perimetral (accesible desde Internet):Kestrel used as an edge (Internet-facing) web server:

Kestrel se comunica directamente con Internet sin ningún servidor proxy inverso

Kestrel empleado en una configuración de proxy inverso:Kestrel used in a reverse proxy configuration:

Kestrel se comunica indirectamente con Internet a través de un servidor proxy inverso, como IIS, Nginx o Apache

Cualquiera de las configuraciones, con o sin servidor proxy inverso, es una configuración de hospedaje admitida.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Kestrel, utilizado como un servidor perimetral sin un servidor proxy inverso, no permite compartir la misma dirección IP y el mismo puerto entre varios procesos.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Si Kestrel se configura para escuchar en un puerto, controla todo el tráfico de ese puerto, independientemente de los encabezados Host de las solicitudes.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 inverso que puede compartir puertos es capaz de reenviar solicitudes a Kestrel en una única dirección IP y puerto.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Aunque no sea necesario un servidor proxy inverso, su uso puede ser útil.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Un proxy inverso puede hacer lo siguiente:A reverse proxy:

  • Limitar el área expuesta públicamente de las aplicaciones que hospeda.Can limit the exposed public surface area of the apps that it hosts.
  • Proporcionar una capa extra de configuración y defensa.Provide an additional layer of configuration and defense.
  • Posiblemente, integrarse mejor con la infraestructura existente.Might integrate better with existing infrastructure.
  • Simplificar el equilibrio de carga y la configuración de una comunicación segura (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Solamente el servidor proxy inverso necesita un certificado X.509 y dicho servidor se puede comunicar con los servidores de la aplicación en la red interna por medio de HTTP sin formato.Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

Advertencia

El hospedaje en una configuración de proxy inverso requiere filtrado de hosts.Hosting in a reverse proxy configuration requires host filtering.

Kestrel en aplicaciones ASP.NET CoreKestrel in ASP.NET Core apps

Las plantillas de proyecto de ASP.NET Core usan Kestrel de forma predeterminada.ASP.NET Core project templates use Kestrel by default. En Program.cs, el método ConfigureWebHostDefaults llama a UseKestrel:In Program.cs, the ConfigureWebHostDefaults method calls UseKestrel:

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Para más información sobre la creación del host, vea las secciones Configuración de un host y Configuración predeterminada del generador de Host genérico de .NET.For more information on building the host, see the Set up a host and Default builder settings sections of Host genérico de .NET.

Para proporcionar configuración adicional después de llamar a ConfigureWebHostDefaults, use ConfigureKestrel:To provide additional configuration after calling ConfigureWebHostDefaults, use ConfigureKestrel:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseStartup<Startup>();
        });

Opciones de KestrelKestrel options

El servidor web Kestrel tiene opciones de configuración de restricción que son especialmente útiles en las implementaciones con conexión a Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Establezca restricciones en la propiedad Limits de la clase KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. La propiedad Limits contiene una instancia de la clase KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

En los ejemplos siguientes se usa el espacio de nombres Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

En los ejemplos que se muestran más adelante en este artículo, las opciones de Kestrel se configuran en código de C#.In examples shown later in this article, Kestrel options are configured in C# code. Las opciones de Kestrel también se pueden establecer mediante un proveedor de configuración.Kestrel options can also be set using a configuration provider. Por ejemplo, el proveedor de configuración de archivo puede cargar la configuración de Kestrel desde un archivo appsettings.json o appsettings.{Environment}.json:For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

{
  "Kestrel": {
    "Limits": {
      "MaxConcurrentConnections": 100,
      "MaxConcurrentUpgradedConnections": 100
    },
    "DisableStringReuse": true
  }
}

Nota

KestrelServerOptions y la configuración del punto de conexión se pueden establecer a partir de proveedores de configuración.KestrelServerOptions and endpoint configuration are configurable from configuration providers. El resto de la configuración de Kestrel debe establecerse en código de C#.Remaining Kestrel configuration must be configured in C# code.

Siga uno de estos procedimientos:Use one of the following approaches:

  • Configure Kestrel en Startup.ConfigureServices:Configure Kestrel in Startup.ConfigureServices:

    1. Inserte una instancia de IConfiguration en la clase Startup.Inject an instance of IConfiguration into the Startup class. En el ejemplo siguiente se da por supuesto que la configuración insertada está asignada a la propiedad Configuration.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. En Startup.ConfigureServices, cargue la sección de configuración Kestrel en la configuración de Kestrel:In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:

      using Microsoft.Extensions.Configuration
      
      public class Startup
      {
          public Startup(IConfiguration configuration)
          {
              Configuration = configuration;
          }
      
          public IConfiguration Configuration { get; }
      
          public void ConfigureServices(IServiceCollection services)
          {
              services.Configure<KestrelServerOptions>(
                  Configuration.GetSection("Kestrel"));
          }
      
          public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
          {
              ...
          }
      }
      
  • Configure Kestrel al compilar el host:Configure Kestrel when building the host:

    En Program.cs, cargue la sección de configuración Kestrel en la configuración de Kestrel:In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

    // using Microsoft.Extensions.DependencyInjection;
    
    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((context, services) =>
            {
                services.Configure<KestrelServerOptions>(
                    context.Configuration.GetSection("Kestrel"));
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    

Los dos procedimientos anteriores funcionan con cualquier proveedor de configuración.Both of the preceding approaches work with any configuration provider.

Tiempo de expiración de la conexión persistenteKeep-alive timeout

KeepAliveTimeout

Obtiene o establece el tiempo de expiración de la conexión persistente.Gets or sets the keep-alive timeout. El valor predeterminado es de 2 minutos.Defaults to 2 minutes.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Las conexiones máximas de clienteMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

El número máximo de conexiones de TCP abiertas simultáneas que se pueden establecer para toda la aplicación con este código:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Hay un límite independiente para las conexiones que se han actualizado desde HTTP o HTTPS a otro protocolo (por ejemplo, en una solicitud de WebSockets).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Cuando se actualiza una conexión, no se cuenta con respecto al límite de MaxConcurrentConnections.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

El número máximo de conexiones es ilimitado de forma predeterminada (null).The maximum number of connections is unlimited (null) by default.

El tamaño máximo del cuerpo de solicitudMaximum request body size

MaxRequestBodySize

El tamaño máximo predeterminado del cuerpo de solicitud es 30 000 000 bytes, que son aproximadamente 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

El método recomendado para invalidar el límite de una aplicación ASP.NET Core MVC es usar el atributo RequestSizeLimitAttribute en un método de acción: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()

Este es un ejemplo que muestra cómo configurar la restricción en la aplicación y todas las solicitudes:Here's an example that shows how to configure the constraint for the app on every request:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Invalide la configuración en una solicitud específica de middleware: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));
    }

Se inicia una excepción si la aplicación configura el límite de una solicitud después de que la aplicación haya empezado a leer la solicitud.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Hay una propiedad IsReadOnly que señala si la propiedad MaxRequestBodySize tiene el estado de solo lectura, lo que significa que es demasiado tarde para configurar el límite.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.

Cuando se ejecuta una aplicación fuera de proceso detrás del módulo de ASP.NET Core, el límite de tamaño del cuerpo de la solicitud de Kestrel se deshabilita porque IIS ya establece el límite.When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit is disabled because IIS already sets the limit.

La velocidad mínima de los datos del cuerpo de solicitud.Minimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel comprueba cada segundo si los datos entran a la velocidad especificada en bytes por segundo.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Si la velocidad está por debajo del mínimo, se agota el tiempo de espera de la conexión. El período de gracia es la cantidad de tiempo que Kestrel da al cliente para aumentar su velocidad de envío hasta el mínimo; no se comprueba la velocidad durante ese tiempo.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. Este período de gracia permite evitar que se interrumpan las conexiones que inicialmente están enviando datos a una velocidad lenta debido a un inicio lento de TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

La velocidad mínima predeterminada es 240 bytes por segundo, con un período de gracia de cinco segundos.The default minimum rate is 240 bytes/second with a 5 second grace period.

También se aplica una velocidad mínima a la respuesta.A minimum rate also applies to the response. El código para establecer el límite de solicitudes y el límite de respuestas es el mismo, salvo que tienen RequestBody o Response en los nombres de propiedad y de interfaz.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.

Este es un ejemplo que muestra cómo configurar las velocidades de datos mínimas en Program.cs:Here's an example that shows how to configure the minimum data rates in Program.cs:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Invalide los límites de velocidad mínima por solicitud en el middleware: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));
    }

La característica IHttpMinResponseDataRateFeature a la que se hace referencia en el ejemplo anterior no está presente en HttpContext.Features para las solicitudes HTTP/2, porque generalmente no se permite modificar los límites de velocidad por solicitud debido a la compatibilidad del protocolo con la multiplexación de solicitudes.The IHttpMinResponseDataRateFeature referenced in the prior sample is not present in HttpContext.Features for HTTP/2 requests because modifying rate limits on a per-request basis is generally not supported for HTTP/2 due to the protocol's support for request multiplexing. Sin embargo, IHttpMinRequestBodyDataRateFeature sigue estando presente en HttpContext.Features para las solicitudes HTTP/2, ya que el límite de velocidad de lectura aún puede estar completamente deshabilitado por solicitud estableciendo IHttpMinRequestBodyDataRateFeature.MinDataRate en null incluso para una solicitud HTTP/2.However, the IHttpMinRequestBodyDataRateFeature is still present HttpContext.Features for HTTP/2 requests, because the read rate limit can still be disabled entirely on a per-request basis by setting IHttpMinRequestBodyDataRateFeature.MinDataRate to null even for an HTTP/2 request. Si se intenta leer IHttpMinRequestBodyDataRateFeature.MinDataRate o se intenta su establecimiento en un valor distinto de null, se obtendrá una excepción NotSupportedException con una solicitud HTTP/2 dada.Attempting to read IHttpMinRequestBodyDataRateFeature.MinDataRate or attempting to set it to a value other than null will result in a NotSupportedException being thrown given an HTTP/2 request.

Se siguen aplicando límites de velocidad en todo el servidor configurados con KestrelServerOptions.Limits a las conexiones HTTP/1.x y HTTP/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Tiempo de expiración de los encabezados de solicitudRequest headers timeout

RequestHeadersTimeout

Obtiene o establece la cantidad máxima de tiempo que el servidor pasa recibiendo las cabeceras de las solicitudes.Gets or sets the maximum amount of time the server spends receiving request headers. El valor predeterminado es 30 segundos.Defaults to 30 seconds.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Secuencias máximas por conexiónMaximum streams per connection

Http2.MaxStreamsPerConnection limita el número de secuencias de solicitudes simultáneas por conexión HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Se rechazarán las secuencias en exceso.Excess streams are refused.

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

El valor predeterminado es 100.The default value is 100.

Tamaño de la tabla de encabezadoHeader table size

El descodificador HPACK descomprime los encabezados HTTP para las conexiones HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize limita el tamaño de la tabla de compresión de encabezado que usa el descodificador HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. El valor se proporciona en octetos y debe ser mayor que cero (0).The value is provided in octets and must be greater than zero (0).

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

El valor predeterminado es 4096.The default value is 4096.

Tamaño máximo de marcoMaximum frame size

Http2.MaxFrameSize indica el tamaño máximo permitido de una carga de marco de conexión HTTP/2 recibida o enviada por el servidor.Http2.MaxFrameSize indicates the maximum allowed size of an HTTP/2 connection frame payload received or sent by the server. El valor se proporciona en octetos y debe estar comprendido entre 2^14 (16 384) y 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).

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxFrameSize = 16384;
});

El valor predeterminado es 2^14 (16 384).The default value is 2^14 (16,384).

Tamaño máximo del encabezado de solicitudMaximum request header size

Http2.MaxRequestHeaderFieldSize indica el tamaño máximo permitido (en octetos) de los valores de los encabezados de solicitud.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Este límite se aplica al nombre y al valor en sus representaciones comprimidas y no comprimidas.This limit applies to both name and value in their compressed and uncompressed representations. El valor debe ser mayor que cero (0).The value must be greater than zero (0).

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

El valor predeterminado es 8192.The default value is 8,192.

Tamaño inicial de la ventana de conexiónInitial connection window size

Http2.InitialConnectionWindowSize indica la cantidad máxima de datos del cuerpo de solicitud (en bytes) que el servidor almacena en búfer a la vez de forma agregada en todas las solicitudes (transmisiones) por conexión.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Las solicitudes también están limitadas por Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. El valor debe ser igual o mayor que 65 535 y menor que 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).

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialConnectionWindowSize = 131072;
});

El valor predeterminado es 128 KB (131 072).The default value is 128 KB (131,072).

Tamaño inicial de la ventana de transmisiónInitial stream window size

Http2.InitialStreamWindowSize indica la cantidad máxima de datos del cuerpo de solicitud (en bytes) que el servidor almacena en búfer a la vez por solicitud (transmisión).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Las solicitudes también están limitadas por Http2.InitialConnectionWindowSize.Requests are also limited by Http2.InitialConnectionWindowSize. El valor debe ser igual o mayor que 65 535 y menor que 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).

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialStreamWindowSize = 98304;
});

El valor predeterminado es 96 KB (98 304).The default value is 96 KB (98,304).

E/S sincrónicaSynchronous IO

AllowSynchronousIO controla si se permite la E/S sincrónica para la solicitud y la respuesta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. El valor predeterminado es false.The default value is false.

Advertencia

Un gran número de operaciones de E/S sincrónicas de bloqueo puede dar lugar al colapso del grupo de subprocesos, lo que hace que la aplicación no responda.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Habilite solo AllowSynchronousIO al usar una biblioteca que no admite la E/S asincrónica.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

En el siguiente ejemplo se habilita la E/S sincrónica:The following example enables synchronous IO:

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

Para más información sobre otras opciones y límites de Kestrel, vea:For information about other Kestrel options and limits, see:

Configuración de punto de conexiónEndpoint configuration

ASP.NET Core enlaza de forma predeterminada a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (cuando hay presente un certificado de desarrollo local)https://localhost:5001 (when a local development certificate is present)

Especifique direcciones URL mediante los siguientes elementos:Specify URLs using the:

  • La variable de entorno ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • El argumento de la línea de comandos --urls.--urls command-line argument.
  • La clave de configuración de host urls.urls host configuration key.
  • El método de extensión UseUrls.UseUrls extension method.

El valor que estos métodos suministran puede ser uno o más puntos de conexión HTTP y HTTPS (este último, si hay disponible un certificado predeterminado).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configure el valor como una lista separada por punto y coma (por ejemplo, "Urls": "http://localhost:8000;http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Para más información sobre estos enfoques, consulte Direcciones URL del servidor e Invalidar la configuración.For more information on these approaches, see Server URLs and Override configuration.

Un certificado de desarrollo se crea:A development certificate is created:

Algunos exploradores necesitan que se conceda permiso explícito para confiar en el certificado de desarrollo local.Some browsers require granting explicit permission to trust the local development certificate.

Las plantillas de proyecto configuran aplicaciones para que se ejecuten en HTTPS de forma predeterminada e incluyen redirección de HTTPS y compatibilidad con HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Llame a los métodos Listen o ListenUnixSocket de KestrelServerOptions para configurar los puertos y los prefijos de dirección URL para Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, el argumento de línea de comandos --urls, la clave de configuración de host urls y la variable de entorno ASPNETCORE_URLS también funcionan, pero tienen las limitaciones que se indican más adelante en esta sección (debe haber disponible un certificado predeterminado para la configuración de puntos de conexión 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).

Configuración de KestrelServerOptions:KestrelServerOptions configuration:

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

Especifica una Action de configuración para que se ejecute con cada punto de conexión especificado.Specifies a configuration Action to run for each specified endpoint. Al llamar a ConfigureEndpointDefaults varias veces, se reemplazan las Action anteriores por la última Action especificada.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });
});

Nota

Los puntos de conexión que se crean mediante una llamada a Listen antes de llamar a ConfigureEndpointDefaults no tendrán aplicados los valores predeterminados.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

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

Especifica una Action de configuración para que se ejecute con cada punto de conexión HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Al llamar a ConfigureHttpsDefaults varias veces, se reemplazan las Action anteriores por la última Action especificada.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // certificate is an X509Certificate2
        listenOptions.ServerCertificate = certificate;
    });
});

Nota

Los puntos de conexión que se crean mediante una llamada a Listen antes de llamar a ConfigureHttpsDefaults no tendrán aplicados los valores predeterminados.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Configure(IConfiguration)Configure(IConfiguration)

Crea un cargador de configuración para configurar Kestrel que toma una IConfiguration como entrada.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. El ámbito de la configuración debe corresponderse con la sección de configuración de Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configure Kestrel para que use HTTPS.Configure Kestrel to use HTTPS.

Extensiones de ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps – Configure Kestrel para que use HTTPS con el certificado predeterminado.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Produce una excepción si no hay ningún certificado predeterminado configurado.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)

Parámetros de ListenOptions.UseHttps:ListenOptions.UseHttps parameters:

  • filename es la ruta de acceso y el nombre de archivo de un archivo de certificado correspondiente al directorio donde están los archivos de contenido de la aplicación.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password es la contraseña necesaria para obtener acceso a los datos del certificado X.509.password is the password required to access the X.509 certificate data.
  • configureOptions es una Action para configurar HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Devuelve ListenOptions.Returns the ListenOptions.
  • storeName es el almacén de certificados desde el que se carga el certificado.storeName is the certificate store from which to load the certificate.
  • subject es el nombre del sujeto del certificado.subject is the subject name for the certificate.
  • allowInvalid indica si se deben tener en cuenta los certificados no válidos, como los certificados autofirmados.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location es la ubicación del almacén desde el que se carga el certificado.location is the store location to load the certificate from.
  • serverCertificate es el certificado X.509.serverCertificate is the X.509 certificate.

En un entorno de producción, HTTPS se debe configurar explícitamente.In production, HTTPS must be explicitly configured. Como mínimo, debe existir un certificado predeterminado.At a minimum, a default certificate must be provided.

Estas son las configuraciones compatibles:Supported configurations described next:

  • Sin configuraciónNo configuration
  • Reemplazar el certificado predeterminado de configuraciónReplace the default certificate from configuration
  • Cambiar los valores predeterminados en el códigoChange the defaults in code

Sin configuraciónNo configuration

Kestrel escucha en http://localhost:5000 y en https://localhost:5001 (si hay disponible un certificado predeterminado).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Reemplazar el certificado predeterminado de configuraciónReplace the default certificate from configuration

CreateDefaultBuilder llama a Configure(context.Configuration.GetSection("Kestrel")) de forma predeterminada para cargar la configuración de Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Hay disponible un esquema de configuración de aplicación HTTPS predeterminado para Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Configure varios puntos de conexión (incluidas las direcciones URL y los certificados que va a usar) desde un archivo en disco o desde un almacén de certificados.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

En el siguiente ejemplo de appsettings.json:In the following appsettings.json example:

  • Establezca AllowInvalid en true para permitir el uso de certificados no válidos (por ejemplo, certificados autofirmados).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Cualquier punto de conexión HTTPS que no especifique un certificado (HttpsDefaultCert en el siguiente ejemplo) revierte al certificado definido en Certificados > Predeterminado o al certificado de desarrollo.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; required>",
          "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>"
      }
    }
  }
}

Una alternativa al uso de Path y Password en cualquier nodo de certificado consiste en especificar el certificado por medio de campos del almacén de certificados.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Por ejemplo, el certificado en Certificados > Predeterminado se puede especificar así:For example, the Certificates > Default certificate can be specified as:

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

Notas sobre el esquema:Schema notes:

  • En los nombres de los puntos de conexión se distingue entre mayúsculas y minúsculas.Endpoints names are case-insensitive. Por ejemplo, HTTPS y Https son válidos.For example, HTTPS and Https are valid.
  • El parámetro Url es necesario en cada punto de conexión.The Url parameter is required for each endpoint. El formato de este parámetro es el mismo que el del parámetro de configuración Urls de nivel superior, excepto por el hecho de que está limitado a un único valor.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • En vez de agregarse, estos puntos de conexión reemplazan a los que están definidos en la configuración Urls de nivel superior.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Los puntos de conexión definidos en el código a través de Listen son acumulativos con respecto a los puntos de conexión definidos en la sección de configuración.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • La sección Certificate es opcional.The Certificate section is optional. Si la sección Certificate no se especifica, se usan los valores predeterminados definidos en escenarios anteriores.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Si no hay valores predeterminados disponibles, el servidor produce una excepción y no se inicia.If no defaults are available, the server throws an exception and fails to start.
  • La sección Certificate admite certificadostanto PathPassword como SubjectStore.The Certificate section supports both PathPassword and SubjectStore certificates.
  • Se puede definir el número de puntos de conexión que se quiera de esta manera, siempre y cuando no produzcan conflictos de puerto.Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) devuelve un KestrelConfigurationLoader con un método .Endpoint(string name, listenOptions => { }) que se puede usar para complementar la configuración de un punto de conexión configurado:options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

Se puede acceder directamente a KestrelServerOptions.ConfigurationLoader para seguir con la iteración en el cargador existente, como el proporcionado por CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • La sección de configuración de cada punto de conexión está disponible en las opciones del método Endpoint para que se pueda leer la configuración personalizada.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Se pueden cargar varias configuraciones volviendo a llamar a options.Configure(context.Configuration.GetSection("{SECTION}")) con otra sección.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Se usa la última configuración, a menos que se llame explícitamente a Load en instancias anteriores.Only the last configuration is used, unless Load is explicitly called on prior instances. El metapaquete no llama a Load, con lo cual su sección de configuración predeterminada se puede reemplazar.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader refleja la familia Listen de API de KestrelServerOptions como sobrecargas de Endpoint, por lo que los puntos de conexión de configuración y código se pueden configurar en el mismo lugar.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. En estas sobrecargas no se usan nombres y solo consumen valores predeterminados de la configuración.These overloads don't use names and only consume default settings from configuration.

Cambiar los valores predeterminados en el códigoChange the defaults in code

ConfigureEndpointDefaults y ConfigureHttpsDefaults se pueden usar para cambiar la configuración predeterminada de ListenOptions y HttpsConnectionAdapterOptions, incluido sustituir el certificado predeterminado especificado en el escenario anterior.ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. Se debe llamar a ConfigureEndpointDefaults y a ConfigureHttpsDefaults antes de que se configure algún punto de conexión.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls12;
    });
});

Compatibilidad de Kestrel con SNIKestrel support for SNI

Indicación de nombre de servidor (SNI) se puede usar para hospedar varios dominios en la misma dirección IP y puerto.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Para que SNI funcione, el cliente envía el nombre de host de la sesión segura al servidor durante el protocolo de enlace TLS para que, de este modo, el servidor pueda proporcionar el certificado correcto.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. El cliente usa el certificado proporcionado para la comunicación cifrada con el servidor durante la sesión segura que sigue al protocolo de enlace TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel admite SNI a través de la devolución de llamada ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. La devolución de llamada se invoca una vez por conexión para permitir que la aplicación inspeccione el nombre de host y seleccione el certificado adecuado.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

La compatibilidad con SNI requiere lo siguiente:SNI support requires:

  • Ejecutarse en el marco de destino netcoreapp2.1 o posterior.Running on target framework netcoreapp2.1 or later. En net461 o posterior, se invoca la devolución de llamada, pero name siempre es null.On net461 or later, the callback is invoked but the name is always null. name también será null si el cliente no proporciona el parámetro de nombre de host en el protocolo de enlace TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Todos los sitios web deben ejecutarse en la misma instancia de Kestrel.All websites run on the same Kestrel instance. Kestrel no admite el uso compartido de una dirección IP y un puerto entre varias instancias sin un proxy inverso.Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.
webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.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;
            };
        });
    });
});

Registro de conexionesConnection logging

Llame a UseConnectionLogging para emitir registros de nivel de depuración para la comunicación a nivel de bytes en una conexión.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. El registro de conexiones es útil para solucionar problemas en la comunicación de bajo nivel, como durante el cifrado TLS y detrás de los servidores proxy.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Si UseConnectionLogging se coloca antes de UseHttps, se registra el tráfico cifrado.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Si UseConnectionLogging se coloca después de UseHttps, se registra el tráfico descifrado.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Enlazar a un socket TCPBind to a TCP socket

El método Listen se enlaza a un socket TCP y una expresión lambda de opciones permite configurar un certificado 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)
{
    CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.Listen(IPAddress.Loopback, 5000);
                serverOptions.Listen(IPAddress.Loopback, 5001, 
                    listenOptions =>
                    {
                        listenOptions.UseHttps("testCert.pfx", 
                            "testPassword");
                    });
            })
            .UseStartup<Startup>();
        });

En el ejemplo se configura HTTPS para un punto de conexión con ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Use la misma API para configurar otras opciones de Kestrel para puntos de conexión específicos.Use the same API to configure other Kestrel settings for specific endpoints.

En Windows, pueden crearse certificados autofirmados con el cmdlet New-SelfSignedCertificate de PowerShell.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Para obtener un ejemplo no compatible, vea UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

En macOS, Linux y Windows, pueden crearse certificados con OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Enlazar a un socket de UnixBind to a Unix socket

Escuche en un socket de Unix con ListenUnixSocket para mejorar el rendimiento con Nginx, tal como se muestra en este ejemplo:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • En el archivo de configuración de Nginx, establezca la entrada server > location > proxy_pass en http://unix:/tmp/{KESTREL SOCKET}:/;.In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} es el nombre del socket proporcionado para ListenUnixSocket (por ejemplo, kestrel-test.sock en el ejemplo anterior).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Asegúrese de que el socket es grabable por Nginx (por ejemplo, chmod go+w /tmp/kestrel-test.sock).Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

Puerto 0Port 0

Cuando se especifica el número de puerto 0, Kestrel se enlaza de forma dinámica a un puerto disponible.When the port number 0 is specified, Kestrel dynamically binds to an available port. En el siguiente ejemplo se muestra cómo averiguar qué puerto Kestrel está realmente enlazado a un runtime: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>");
    });
}

Cuando la aplicación se ejecuta, la salida de la ventana de consola indica el puerto dinámico en el que se puede tener acceso a la aplicación: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

LimitacionesLimitations

Configure puntos de conexión con los siguientes métodos:Configure endpoints with the following approaches:

  • UseUrls
  • El argumento de la línea de comandos --urls--urls command-line argument
  • La clave de configuración de host urlsurls host configuration key
  • La variable de entorno ASPNETCORE_URLSASPNETCORE_URLS environment variable

Estos métodos son útiles para que el código funcione con servidores que no sean de Kestrel.These methods are useful for making code work with servers other than Kestrel. Sin embargo, tenga en cuenta las siguientes limitaciones:However, be aware of the following limitations:

  • HTTPS no se puede usar con estos métodos, a menos que se proporcione un certificado predeterminado en la configuración del punto de conexión HTTPS (por ejemplo, por medio de la configuración KestrelServerOptions o de un archivo de configuración, tal y como se explicó anteriormente en este tema).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).
  • Cuando los métodos Listen y UseUrls se usan al mismo tiempo, los puntos de conexión de Listen sustituyen a los de UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configuración de puntos de conexión IISIIS endpoint configuration

Cuando se usa IIS, los enlaces de direcciones URL de IIS reemplazan a los enlaces que se hayan establecido por medio de Listen o de UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Para más información, vea el tema Módulo ASP.NET Core.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

La propiedad Protocols establece los protocolos HTTP (HttpProtocols) habilitados en un punto de conexión o para el servidor.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Asigne un valor a la propiedad Protocols desde el valor de enumeración HttpProtocols.Assign a value to the Protocols property from the HttpProtocols enum.

Valor de enumeración HttpProtocolsHttpProtocols enum value Protocolo de conexión permitidoConnection protocol permitted
Http1 HTTP/1.1 solo.HTTP/1.1 only. Puede usarse con o sin TLS.Can be used with or without TLS.
Http2 HTTP/2 solo.HTTP/2 only. Se pueden utilizar sin TLS solo si el cliente admite un modo de conocimientos previos.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 y HTTP/2.HTTP/1.1 and HTTP/2. HTTP/2 necesita que el cliente seleccione HTTP/2 en el protocolo de enlace Negociación de protocolo de nivel de aplicación (ALPN) de TLS; en caso contrario, el valor predeterminado de la conexión es HTTP/1.1.HTTP/2 requires the client to select HTTP/2 in the TLS Application-Layer Protocol Negotiation (ALPN) handshake; otherwise, the connection defaults to HTTP/1.1.

El valor ListenOptions.Protocols predeterminado de cualquier punto de conexión es HttpProtocols.Http1AndHttp2.The default ListenOptions.Protocols value for any endpoint is HttpProtocols.Http1AndHttp2.

Restricciones de TLS para HTTP/2:TLS restrictions for HTTP/2:

  • TLS 1.2 o versiones posterioresTLS version 1.2 or later
  • Renegociación deshabilitadaRenegotiation disabled
  • Compresión deshabilitadaCompression disabled
  • Tamaños de intercambio de claves efímeras mínimos:Minimum ephemeral key exchange sizes:
    • Curva elíptica Diffie-Hellman (ECDHE) [RFC4492] –; 224 bits como mínimoElliptic curve Diffie-Hellman (ECDHE) [RFC4492] – 224 bits minimum
    • Campo finito Diffie-Hellman (DHE) [TLS12] –; 2048 bits como mínimoFinite field Diffie-Hellman (DHE) [TLS12] – 2048 bits minimum
  • Conjunto de cifrado no restringidoCipher suite not blacklisted

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] con la curva elíptica P-256 [FIPS186] es compatible de forma predeterminada.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

El siguiente ejemplo permite conexiones HTTP/1.1 y HTTP/2 en el puerto 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Las conexiones se protegen mediante TLS con un certificado proporcionado:Connections are secured by TLS with a supplied certificate:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Si es necesario, use el middleware de conexión para filtrar los protocolos de enlace TLS por conexión en el caso de cifrados específicos:Use Connection Middleware to filter TLS handshakes on a per-connection basis for specific ciphers if required.

En el ejemplo siguiente se produce una excepción NotSupportedException con cualquier algoritmo de cifrado que no admita la aplicación.The following example throws NotSupportedException for any cipher algorithm that the app doesn't support. Como alternativa, defina y compare ITlsHandshakeFeature.CipherAlgorithm con una lista de conjuntos de cifrado aceptables.Alternatively, define and compare ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher suites.

No se usa ningún cifrado con un algoritmo de cifrado CipherAlgorithmType.Null .No encryption is used with a CipherAlgorithmType.Null cipher algorithm.

// using System.Net;
// using Microsoft.AspNetCore.Connections;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseTlsFilter();
    });
});
using System;
using System.Security.Authentication;
using Microsoft.AspNetCore.Connections.Features;

namespace Microsoft.AspNetCore.Connections
{
    public static class TlsFilterConnectionMiddlewareExtensions
    {
        public static IConnectionBuilder UseTlsFilter(
            this IConnectionBuilder builder)
        {
            return builder.Use((connection, next) =>
            {
                var tlsFeature = connection.Features.Get<ITlsHandshakeFeature>();

                if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
                {
                    throw new NotSupportedException("Prohibited cipher: " +
                        tlsFeature.CipherAlgorithm);
                }

                return next();
            });
        }
    }
}

El filtrado de conexiones también puede configurarse mediante una función lambda IConnectionBuilder:Connection filtering can also be configured via an IConnectionBuilder lambda:

// using System;
// using System.Net;
// using System.Security.Authentication;
// using Microsoft.AspNetCore.Connections;
// using Microsoft.AspNetCore.Connections.Features;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

En Linux, se puede usar CipherSuitesPolicy para filtrar los protocolos de enlace TLS por conexión:On Linux, CipherSuitesPolicy can be used to filter TLS handshakes on a per-connection basis:

// using System.Net.Security;
// using Microsoft.AspNetCore.Hosting;
// using Microsoft.AspNetCore.Server.Kestrel.Core;
// using Microsoft.Extensions.DependencyInjection;
// using Microsoft.Extensions.Hosting;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Defina el protocolo a partir de la configuraciónSet the protocol from configuration

CreateDefaultBuilder llama a serverOptions.Configure(context.Configuration.GetSection("Kestrel")) de forma predeterminada para cargar la configuración de Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

En el siguiente ejemplo de appsettings.json, se establece HTTP/1.1 como el protocolo de conexión predeterminado para todos los puntos de conexión:The following appsettings.json example establishes HTTP/1.1 as the default connection protocol for all endpoints:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

En el siguiente ejemplo de appsettings.json se establece el protocolo de conexión HTTP/1.1 para un punto de conexión específico:The following appsettings.json example establishes the HTTP/1.1 connection protocol for a specific endpoint:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Los protocolos especificados en el código invalidan los valores establecidos por la configuración.Protocols specified in code override values set by configuration.

Configuración de transporteTransport configuration

Para los proyectos que necesitan el uso de Libuv (UseLibuv):For projects that require the use of Libuv (UseLibuv):

  • Agregar una dependencia del paquete Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv al archivo de proyecto de la aplicación: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="{VERSION}" />
    
  • Llame a UseLibuv en IWebHostBuilder:Call UseLibuv on the IWebHostBuilder:

    public class Program
    {
         public static void Main(string[] args)
         {
             CreateHostBuilder(args).Build().Run();
         }
    
         public static IHostBuilder CreateHostBuilder(string[] args) =>
             Host.CreateDefaultBuilder(args)
                 .ConfigureWebHostDefaults(webBuilder =>
                 {
                     webBuilder.UseLibuv();
                     webBuilder.UseStartup<Startup>();
                 });
    }
    

Prefijos de URLURL prefixes

Al usar UseUrls, el argumento de línea de comandos --urls, la clave de configuración de host urls o una variable de entorno ASPNETCORE_URLS, los prefijos de dirección URL pueden tener cualquiera de estos formatos.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.

Solo son válidos los prefijos de dirección URL HTTP.Only HTTP URL prefixes are valid. Kestrel no admite HTTPS al configurar enlaces de dirección URL con UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Dirección IPv4 con número de puertoIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 es un caso especial que enlaza a todas las direcciones IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Dirección IPv6 con número de puertoIPv6 address with port number

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

    [::] es el equivalente en IPv6 de 0.0.0.0 en IPv4.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nombre de host con número de puertoHost name with port number

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

    Los nombres de host, * y + no son especiales.Host names, *, and +, aren't special. Todo lo que no se identifique como una dirección IP o un localhost válido se enlaza a todas las direcciones IP de IPv6 e IPv4.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Para enlazar distintos nombres de host a distintas aplicaciones ASP.NET Core en el mismo puerto, use HTTP.sys o un servidor proxy inverso, como IIS, Nginx o 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.

    Advertencia

    El hospedaje en una configuración de proxy inverso requiere filtrado de hosts.Hosting in a reverse proxy configuration requires host filtering.

  • Nombre localhost del host con el número de puerto o la IP de bucle invertido con el número de puertoHost localhost name with port number or loopback IP with port number

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

    Cuando se especifica localhost, Kestrel intenta enlazar a las interfaces de bucle invertido de IPv4 e IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Si el puerto solicitado lo está usando otro servicio en cualquier interfaz de bucle invertido, Kestrel no se puede iniciar.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Si ninguna de estas interfaces de bucle invertido está disponible por cualquier otra razón (normalmente porque no se admite IPv6), Kestrel registra una advertencia.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtrado de hostsHost filtering

Si bien Kestrel admite una configuración basada en prefijos como http://example.com:5000, pasa por alto completamente el nombre de host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. El host localhost es un caso especial que se usa para enlazar a direcciones de bucle invertido.Host localhost is a special case used for binding to loopback addresses. Cualquier otro host que no sea una dirección IP explícita se enlaza a todas las direcciones IP públicas.Any host other than an explicit IP address binds to all public IP addresses. Los encabezados Host no están validados.Host headers aren't validated.

Como solución alternativa, use el Middleware de filtrado de hosts.As a workaround, use Host Filtering Middleware. El middleware de filtrado de host lo proporciona el paquete Microsoft.AspNetCore.HostFiltering, que se proporciona implícitamente para aplicaciones ASP.NET Core.Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is implicitly provided for ASP.NET Core apps. El middleware se agrega por medio de CreateDefaultBuilder, que llama a 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>();
}

El Middleware de filtrado de hosts está deshabilitado de forma predeterminada.Host Filtering Middleware is disabled by default. Para habilitarlo, defina una clave AllowedHosts en appsettings.json/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. El valor es una lista delimitada por punto y coma de nombres de host sin los números de puerto:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Nota

Middleware de encabezados reenviados también tiene una opción AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. El Middleware de encabezados reenviados y el Middleware de filtrado de hosts tienen una funcionalidad similar en diferentes escenarios.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Establecer AllowedHosts con el Middleware de encabezados reenviados es adecuado cuando el encabezado Host no se conserva mientras se reenvían solicitudes con un servidor proxy inverso o un equilibrador de carga.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. Establecer AllowedHosts con el Middleware de filtrado de hosts es adecuado cuando se usa Kestrel como un servidor perimetral de acceso público o cuando el encabezado Host se reenvía directamente.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.

Para obtener más información sobre el Middleware de encabezados reenviados, consulte Configuración de ASP.NET Core para trabajar con servidores proxy y equilibradores de carga.For more information on Forwarded Headers Middleware, see Configuración de ASP.NET Core para trabajar con servidores proxy y equilibradores de carga.

Kestrel es un servidor web multiplataforma de ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel es el servidor web que se incluye de forma predeterminada en las plantillas de proyecto de ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel admite los siguientes escenarios:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Actualización opaca para habilitar WebSocketsOpaque upgrade used to enable WebSockets
  • Sockets de Unix para alto rendimiento detrás de NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (excepto en macOS†)HTTP/2 (except on macOS†)

†HTTP/2 se admitirá en una versión futura en macOS.†HTTP/2 will be supported on macOS in a future release.

Kestrel admite todas las plataformas y versiones que sean compatibles con .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

Compatibilidad con HTTP/2HTTP/2 support

HTTP/2 está disponible para las aplicaciones de ASP.NET Core si se cumplen los siguientes requisitos básicos:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Sistema operativo†Operating system†
    • Windows Server 2016/Windows 10 o posterior‡Windows Server 2016/Windows 10 or later‡
    • Linux con OpenSSL 1.0.2 o posterior (por ejemplo, Ubuntu 16.04 o posterior)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Plataforma de destino: .NET Core 2.2 o posteriorTarget framework: .NET Core 2.2 or later
  • Conexión con Application-Layer Protocol Negotiation (ALPN)Application-Layer Protocol Negotiation (ALPN) connection
  • Conexión con TLS 1.2 o una versión posteriorTLS 1.2 or later connection

†HTTP/2 se admitirá en una versión futura en macOS.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel tiene compatibilidad limitada para HTTP/2 en Windows Server 2012 R2 y Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. La compatibilidad es limitada porque la lista de conjuntos de cifrado TLS admitidos y disponibles en estos sistemas operativos está limitada.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Se puede requerir un certificado generado mediante Elliptic Curve Digital Signature Algorithm (ECDSA) para proteger las conexiones TLS.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Si se establece una conexión HTTP/2, HttpRequest.Protocol notifica HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 está deshabilitado de manera predeterminada.HTTP/2 is disabled by default. Para obtener más información sobre la configuración, consulte las secciones Opciones de Kestrel y ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Cuándo usar Kestrel con un proxy inversoWhen to use Kestrel with a reverse proxy

Kestrel se puede usar por sí solo o con un servidor proxy inverso, como Internet Information Services (IIS), Nginx o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Un servidor proxy inverso recibe las solicitudes HTTP de la red y las reenvía a Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel empleado como servidor web perimetral (accesible desde Internet):Kestrel used as an edge (Internet-facing) web server:

Kestrel se comunica directamente con Internet sin ningún servidor proxy inverso

Kestrel empleado en una configuración de proxy inverso:Kestrel used in a reverse proxy configuration:

Kestrel se comunica indirectamente con Internet a través de un servidor proxy inverso, como IIS, Nginx o Apache

Cualquiera de las configuraciones, con o sin servidor proxy inverso, es una configuración de hospedaje admitida.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Kestrel, utilizado como un servidor perimetral sin un servidor proxy inverso, no permite compartir la misma dirección IP y el mismo puerto entre varios procesos.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Si Kestrel se configura para escuchar en un puerto, controla todo el tráfico de ese puerto, independientemente de los encabezados Host de las solicitudes.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 inverso que puede compartir puertos es capaz de reenviar solicitudes a Kestrel en una única dirección IP y puerto.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Aunque no sea necesario un servidor proxy inverso, su uso puede ser útil.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Un proxy inverso puede hacer lo siguiente:A reverse proxy:

  • Limitar el área expuesta públicamente de las aplicaciones que hospeda.Can limit the exposed public surface area of the apps that it hosts.
  • Proporcionar una capa extra de configuración y defensa.Provide an additional layer of configuration and defense.
  • Posiblemente, integrarse mejor con la infraestructura existente.Might integrate better with existing infrastructure.
  • Simplificar el equilibrio de carga y la configuración de una comunicación segura (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Solamente el servidor proxy inverso necesita un certificado X.509 y dicho servidor se puede comunicar con los servidores de la aplicación en la red interna por medio de HTTP sin formato.Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

Advertencia

El hospedaje en una configuración de proxy inverso requiere filtrado de hosts.Hosting in a reverse proxy configuration requires host filtering.

Cómo usar Kestrel en aplicaciones ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

El paquete Microsoft.AspNetCore.Server.Kestrel se incluye en el metapaquete Microsoft.AspNetCore.App.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

Las plantillas de proyecto de ASP.NET Core usan Kestrel de forma predeterminada.ASP.NET Core project templates use Kestrel by default. En Program.cs, el código de plantilla llama a CreateDefaultBuilder, que a su vez llama a UseKestrel en segundo plano.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>();

Para más información sobre CreateDefaultBuilder y la compilación del host, consulte la sección sobre cómo configurar un host de Host web de ASP.NET Core.For more information on CreateDefaultBuilder and building the host, see the Set up a host section of Host web de ASP.NET Core.

Para proporcionar configuración adicional después de llamar a CreateDefaultBuilder, use ConfigureKestrel:To provide additional configuration after calling CreateDefaultBuilder, use ConfigureKestrel:

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

Si la aplicación no llama a CreateDefaultBuilder para configurar el host, llame a UseKestrelantes de llamar a 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, serverOptions) =>
        {
            // Set properties and call methods on serverOptions
        })
        .Build();

    host.Run();
}

Opciones de KestrelKestrel options

El servidor web Kestrel tiene opciones de configuración de restricción que son especialmente útiles en las implementaciones con conexión a Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Establezca restricciones en la propiedad Limits de la clase KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. La propiedad Limits contiene una instancia de la clase KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

En los ejemplos siguientes se usa el espacio de nombres Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Las opciones de Kestrel, que se configuran en código de C# en los siguientes ejemplos, también se pueden establecer mediante un proveedor de configuración.Kestrel options, which are configured in C# code in the following examples, can also be set using a configuration provider. Por ejemplo, el proveedor de configuración de archivos puede cargar la configuración de Kestrel desde un archivo appsettings.json o appsettings.{Environment}.json:For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

{
  "Kestrel": {
    "Limits": {
      "MaxConcurrentConnections": 100,
      "MaxConcurrentUpgradedConnections": 100
    }
  }
}

Siga uno de estos procedimientos:Use one of the following approaches:

  • Configure Kestrel en Startup.ConfigureServices:Configure Kestrel in Startup.ConfigureServices:

    1. Inserte una instancia de IConfiguration en la clase Startup.Inject an instance of IConfiguration into the Startup class. En el ejemplo siguiente se da por supuesto que la configuración insertada está asignada a la propiedad Configuration.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. En Startup.ConfigureServices, cargue la sección de configuración Kestrel en la configuración de Kestrel:In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:

      using Microsoft.Extensions.Configuration
      
      public class Startup
      {
          public Startup(IConfiguration configuration)
          {
              Configuration = configuration;
          }
      
          public IConfiguration Configuration { get; }
      
          public void ConfigureServices(IServiceCollection services)
          {
              services.Configure<KestrelServerOptions>(
                  Configuration.GetSection("Kestrel"));
          }
      
          public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
          {
              ...
          }
      }
      
  • Configure Kestrel al compilar el host:Configure Kestrel when building the host:

    En Program.cs, cargue la sección de configuración Kestrel en la configuración de Kestrel:In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

    // using Microsoft.Extensions.DependencyInjection;
    
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureServices((context, services) =>
            {
                services.Configure<KestrelServerOptions>(
                    context.Configuration.GetSection("Kestrel"));
            })
            .UseStartup<Startup>();
    

Los dos procedimientos anteriores funcionan con cualquier proveedor de configuración.Both of the preceding approaches work with any configuration provider.

Tiempo de expiración de la conexión persistenteKeep-alive timeout

KeepAliveTimeout

Obtiene o establece el tiempo de expiración de la conexión persistente.Gets or sets the keep-alive timeout. El valor predeterminado es de 2 minutos.Defaults to 2 minutes.

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Las conexiones máximas de clienteMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

El número máximo de conexiones de TCP abiertas simultáneas que se pueden establecer para toda la aplicación con este código:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Hay un límite independiente para las conexiones que se han actualizado desde HTTP o HTTPS a otro protocolo (por ejemplo, en una solicitud de WebSockets).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Cuando se actualiza una conexión, no se cuenta con respecto al límite de MaxConcurrentConnections.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

El número máximo de conexiones es ilimitado de forma predeterminada (null).The maximum number of connections is unlimited (null) by default.

El tamaño máximo del cuerpo de solicitudMaximum request body size

MaxRequestBodySize

El tamaño máximo predeterminado del cuerpo de solicitud es 30 000 000 bytes, que son aproximadamente 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

El método recomendado para invalidar el límite de una aplicación ASP.NET Core MVC es usar el atributo RequestSizeLimitAttribute en un método de acción: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()

Este es un ejemplo que muestra cómo configurar la restricción en la aplicación y todas las solicitudes:Here's an example that shows how to configure the constraint for the app on every request:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Invalide la configuración en una solicitud específica de middleware: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));
    }

Se inicia una excepción si la aplicación configura el límite de una solicitud después de que la aplicación haya empezado a leer la solicitud.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Hay una propiedad IsReadOnly que señala si la propiedad MaxRequestBodySize tiene el estado de solo lectura, lo que significa que es demasiado tarde para configurar el límite.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.

Cuando se ejecuta una aplicación fuera de proceso detrás del módulo de ASP.NET Core, el límite de tamaño del cuerpo de la solicitud de Kestrel se deshabilita porque IIS ya establece el límite.When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit is disabled because IIS already sets the limit.

La velocidad mínima de los datos del cuerpo de solicitud.Minimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel comprueba cada segundo si los datos entran a la velocidad especificada en bytes por segundo.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Si la velocidad está por debajo del mínimo, se agota el tiempo de espera de la conexión. El período de gracia es la cantidad de tiempo que Kestrel da al cliente para aumentar su velocidad de envío hasta el mínimo; no se comprueba la velocidad durante ese tiempo.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. Este período de gracia permite evitar que se interrumpan las conexiones que inicialmente están enviando datos a una velocidad lenta debido a un inicio lento de TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

La velocidad mínima predeterminada es 240 bytes por segundo, con un período de gracia de cinco segundos.The default minimum rate is 240 bytes/second with a 5 second grace period.

También se aplica una velocidad mínima a la respuesta.A minimum rate also applies to the response. El código para establecer el límite de solicitudes y el límite de respuestas es el mismo, salvo que tienen RequestBody o Response en los nombres de propiedad y de interfaz.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.

Este es un ejemplo que muestra cómo configurar las velocidades de datos mínimas en Program.cs:Here's an example that shows how to configure the minimum data rates in Program.cs:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Invalide los límites de velocidad mínima por solicitud en el middleware: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));
    }

Ninguna de las características de velocidad a las que se hace referencia en el ejemplo anterior están presentes en HttpContext.Features para las solicitudes HTTP/2, porque no se permite modificar los límites de velocidad por solicitud en HTTP/2 debido a la compatibilidad del protocolo con la multiplexación de solicitudes.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. Se siguen aplicando límites de velocidad en todo el servidor configurados con KestrelServerOptions.Limits a las conexiones HTTP/1.x y HTTP/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Tiempo de expiración de los encabezados de solicitudRequest headers timeout

RequestHeadersTimeout

Obtiene o establece la cantidad máxima de tiempo que el servidor pasa recibiendo las cabeceras de las solicitudes.Gets or sets the maximum amount of time the server spends receiving request headers. El valor predeterminado es 30 segundos.Defaults to 30 seconds.

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Secuencias máximas por conexiónMaximum streams per connection

Http2.MaxStreamsPerConnection limita el número de secuencias de solicitudes simultáneas por conexión HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Se rechazarán las secuencias en exceso.Excess streams are refused.

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

El valor predeterminado es 100.The default value is 100.

Tamaño de la tabla de encabezadoHeader table size

El descodificador HPACK descomprime los encabezados HTTP para las conexiones HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize limita el tamaño de la tabla de compresión de encabezado que usa el descodificador HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. El valor se proporciona en octetos y debe ser mayor que cero (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, serverOptions) =>
        {
            serverOptions.Limits.Http2.HeaderTableSize = 4096;
        });

El valor predeterminado es 4096.The default value is 4096.

Tamaño máximo de marcoMaximum frame size

Http2.MaxFrameSize indica el tamaño máximo de la carga útil de la trama de conexión HTTP/2 que se puede recibir.Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. El valor se proporciona en octetos y debe estar comprendido entre 2^14 (16 384) y 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, serverOptions) =>
        {
            serverOptions.Limits.Http2.MaxFrameSize = 16384;
        });

El valor predeterminado es 2^14 (16 384).The default value is 2^14 (16,384).

Tamaño máximo del encabezado de solicitudMaximum request header size

Http2.MaxRequestHeaderFieldSize indica el tamaño máximo permitido (en octetos) de los valores de los encabezados de solicitud.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Este límite se aplica al nombre y al valor conjuntamente en sus representaciones comprimidas y no comprimidas.This limit applies to both name and value together in their compressed and uncompressed representations. El valor debe ser mayor que cero (0).The value must be greater than zero (0).

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

El valor predeterminado es 8192.The default value is 8,192.

Tamaño inicial de la ventana de conexiónInitial connection window size

Http2.InitialConnectionWindowSize indica la cantidad máxima de datos del cuerpo de solicitud (en bytes) que el servidor almacena en búfer a la vez de forma agregada en todas las solicitudes (transmisiones) por conexión.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Las solicitudes también están limitadas por Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. El valor debe ser igual o mayor que 65 535 y menor que 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, serverOptions) =>
        {
            serverOptions.Limits.Http2.InitialConnectionWindowSize = 131072;
        });

El valor predeterminado es 128 KB (131 072).The default value is 128 KB (131,072).

Tamaño inicial de la ventana de transmisiónInitial stream window size

Http2.InitialStreamWindowSize indica la cantidad máxima de datos del cuerpo de solicitud (en bytes) que el servidor almacena en búfer a la vez por solicitud (transmisión).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Las solicitudes también están limitadas por Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. El valor debe ser igual o mayor que 65 535 y menor que 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, serverOptions) =>
        {
            serverOptions.Limits.Http2.InitialStreamWindowSize = 98304;
        });

El valor predeterminado es 96 KB (98 304).The default value is 96 KB (98,304).

E/S sincrónicaSynchronous IO

AllowSynchronousIO controla si se permite la E/S sincrónica para la solicitud y la respuesta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. El valor predeterminado es true.The default value is true.

Advertencia

Un gran número de operaciones de E/S sincrónicas de bloqueo puede dar lugar al colapso del grupo de subprocesos, lo que hace que la aplicación no responda.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Habilite solo AllowSynchronousIO al usar una biblioteca que no admite la E/S asincrónica.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

En el siguiente ejemplo se habilita la E/S sincrónica:The following example enables synchronous IO:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.AllowSynchronousIO = true;
});

Para más información sobre otras opciones y límites de Kestrel, vea:For information about other Kestrel options and limits, see:

Configuración de punto de conexiónEndpoint configuration

ASP.NET Core enlaza de forma predeterminada a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (cuando hay presente un certificado de desarrollo local)https://localhost:5001 (when a local development certificate is present)

Especifique direcciones URL mediante los siguientes elementos:Specify URLs using the:

  • La variable de entorno ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • El argumento de la línea de comandos --urls.--urls command-line argument.
  • La clave de configuración de host urls.urls host configuration key.
  • El método de extensión UseUrls.UseUrls extension method.

El valor que estos métodos suministran puede ser uno o más puntos de conexión HTTP y HTTPS (este último, si hay disponible un certificado predeterminado).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configure el valor como una lista separada por punto y coma (por ejemplo, "Urls": "http://localhost:8000;http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Para más información sobre estos enfoques, consulte Direcciones URL del servidor e Invalidar la configuración.For more information on these approaches, see Server URLs and Override configuration.

Un certificado de desarrollo se crea:A development certificate is created:

Algunos exploradores necesitan que se conceda permiso explícito para confiar en el certificado de desarrollo local.Some browsers require granting explicit permission to trust the local development certificate.

Las plantillas de proyecto configuran aplicaciones para que se ejecuten en HTTPS de forma predeterminada e incluyen redirección de HTTPS y compatibilidad con HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Llame a los métodos Listen o ListenUnixSocket de KestrelServerOptions para configurar los puertos y los prefijos de dirección URL para Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, el argumento de línea de comandos --urls, la clave de configuración de host urls y la variable de entorno ASPNETCORE_URLS también funcionan, pero tienen las limitaciones que se indican más adelante en esta sección (debe haber disponible un certificado predeterminado para la configuración de puntos de conexión 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).

Configuración de KestrelServerOptions:KestrelServerOptions configuration:

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

Especifica una Action de configuración para que se ejecute con cada punto de conexión especificado.Specifies a configuration Action to run for each specified endpoint. Al llamar a ConfigureEndpointDefaults varias veces, se reemplazan las Action anteriores por la última Action especificada.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });
        });

Nota

Los puntos de conexión que se crean mediante una llamada a Listen antes de llamar a ConfigureEndpointDefaults no tendrán aplicados los valores predeterminados.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

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

Especifica una Action de configuración para que se ejecute con cada punto de conexión HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Al llamar a ConfigureHttpsDefaults varias veces, se reemplazan las Action anteriores por la última Action especificada.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                // certificate is an X509Certificate2
                listenOptions.ServerCertificate = certificate;
            });
        });

Nota

Los puntos de conexión que se crean mediante una llamada a Listen antes de llamar a ConfigureHttpsDefaults no tendrán aplicados los valores predeterminados.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Configure(IConfiguration)Configure(IConfiguration)

Crea un cargador de configuración para configurar Kestrel que toma una IConfiguration como entrada.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. El ámbito de la configuración debe corresponderse con la sección de configuración de Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configure Kestrel para que use HTTPS.Configure Kestrel to use HTTPS.

Extensiones de ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps – Configure Kestrel para que use HTTPS con el certificado predeterminado.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Produce una excepción si no hay ningún certificado predeterminado configurado.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)

Parámetros de ListenOptions.UseHttps:ListenOptions.UseHttps parameters:

  • filename es la ruta de acceso y el nombre de archivo de un archivo de certificado correspondiente al directorio donde están los archivos de contenido de la aplicación.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password es la contraseña necesaria para obtener acceso a los datos del certificado X.509.password is the password required to access the X.509 certificate data.
  • configureOptions es una Action para configurar HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Devuelve ListenOptions.Returns the ListenOptions.
  • storeName es el almacén de certificados desde el que se carga el certificado.storeName is the certificate store from which to load the certificate.
  • subject es el nombre del sujeto del certificado.subject is the subject name for the certificate.
  • allowInvalid indica si se deben tener en cuenta los certificados no válidos, como los certificados autofirmados.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location es la ubicación del almacén desde el que se carga el certificado.location is the store location to load the certificate from.
  • serverCertificate es el certificado X.509.serverCertificate is the X.509 certificate.

En un entorno de producción, HTTPS se debe configurar explícitamente.In production, HTTPS must be explicitly configured. Como mínimo, debe existir un certificado predeterminado.At a minimum, a default certificate must be provided.

Estas son las configuraciones compatibles:Supported configurations described next:

  • Sin configuraciónNo configuration
  • Reemplazar el certificado predeterminado de configuraciónReplace the default certificate from configuration
  • Cambiar los valores predeterminados en el códigoChange the defaults in code

Sin configuraciónNo configuration

Kestrel escucha en http://localhost:5000 y en https://localhost:5001 (si hay disponible un certificado predeterminado).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Reemplazar el certificado predeterminado de configuraciónReplace the default certificate from configuration

CreateDefaultBuilder llama a Configure(context.Configuration.GetSection("Kestrel")) de forma predeterminada para cargar la configuración de Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Hay disponible un esquema de configuración de aplicación HTTPS predeterminado para Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Configure varios puntos de conexión (incluidas las direcciones URL y los certificados que va a usar) desde un archivo en disco o desde un almacén de certificados.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

En el siguiente ejemplo de appsettings.json:In the following appsettings.json example:

  • Establezca AllowInvalid en true para permitir el uso de certificados no válidos (por ejemplo, certificados autofirmados).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Cualquier punto de conexión HTTPS que no especifique un certificado (HttpsDefaultCert en el siguiente ejemplo) revierte al certificado definido en Certificados > Predeterminado o al certificado de desarrollo.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; required>",
          "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>"
      }
    }
  }
}

Una alternativa al uso de Path y Password en cualquier nodo de certificado consiste en especificar el certificado por medio de campos del almacén de certificados.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Por ejemplo, el certificado en Certificados > Predeterminado se puede especificar así:For example, the Certificates > Default certificate can be specified as:

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

Notas sobre el esquema:Schema notes:

  • En los nombres de los puntos de conexión se distingue entre mayúsculas y minúsculas.Endpoints names are case-insensitive. Por ejemplo, HTTPS y Https son válidos.For example, HTTPS and Https are valid.
  • El parámetro Url es necesario en cada punto de conexión.The Url parameter is required for each endpoint. El formato de este parámetro es el mismo que el del parámetro de configuración Urls de nivel superior, excepto por el hecho de que está limitado a un único valor.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • En vez de agregarse, estos puntos de conexión reemplazan a los que están definidos en la configuración Urls de nivel superior.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Los puntos de conexión definidos en el código a través de Listen son acumulativos con respecto a los puntos de conexión definidos en la sección de configuración.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • La sección Certificate es opcional.The Certificate section is optional. Si la sección Certificate no se especifica, se usan los valores predeterminados definidos en escenarios anteriores.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Si no hay valores predeterminados disponibles, el servidor produce una excepción y no se inicia.If no defaults are available, the server throws an exception and fails to start.
  • La sección Certificate admite certificadostanto PathPassword como SubjectStore.The Certificate section supports both PathPassword and SubjectStore certificates.
  • Se puede definir el número de puntos de conexión que se quiera de esta manera, siempre y cuando no produzcan conflictos de puerto.Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) devuelve un KestrelConfigurationLoader con un método .Endpoint(string name, listenOptions => { }) que se puede usar para complementar la configuración de un punto de conexión configurado:options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

Se puede acceder directamente a KestrelServerOptions.ConfigurationLoader para seguir con la iteración en el cargador existente, como el proporcionado por CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • La sección de configuración de cada punto de conexión está disponible en las opciones del método Endpoint para que se pueda leer la configuración personalizada.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Se pueden cargar varias configuraciones volviendo a llamar a options.Configure(context.Configuration.GetSection("{SECTION}")) con otra sección.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Se usa la última configuración, a menos que se llame explícitamente a Load en instancias anteriores.Only the last configuration is used, unless Load is explicitly called on prior instances. El metapaquete no llama a Load, con lo cual su sección de configuración predeterminada se puede reemplazar.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader refleja la familia Listen de API de KestrelServerOptions como sobrecargas de Endpoint, por lo que los puntos de conexión de configuración y código se pueden configurar en el mismo lugar.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. En estas sobrecargas no se usan nombres y solo consumen valores predeterminados de la configuración.These overloads don't use names and only consume default settings from configuration.

Cambiar los valores predeterminados en el códigoChange the defaults in code

ConfigureEndpointDefaults y ConfigureHttpsDefaults se pueden usar para cambiar la configuración predeterminada de ListenOptions y HttpsConnectionAdapterOptions, incluido sustituir el certificado predeterminado especificado en el escenario anterior.ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. Se debe llamar a ConfigureEndpointDefaults y a ConfigureHttpsDefaults antes de que se configure algún punto de conexión.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });

            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                listenOptions.SslProtocols = SslProtocols.Tls12;
            });
        });

Compatibilidad de Kestrel con SNIKestrel support for SNI

Indicación de nombre de servidor (SNI) se puede usar para hospedar varios dominios en la misma dirección IP y puerto.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Para que SNI funcione, el cliente envía el nombre de host de la sesión segura al servidor durante el protocolo de enlace TLS para que, de este modo, el servidor pueda proporcionar el certificado correcto.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. El cliente usa el certificado proporcionado para la comunicación cifrada con el servidor durante la sesión segura que sigue al protocolo de enlace TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel admite SNI a través de la devolución de llamada ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. La devolución de llamada se invoca una vez por conexión para permitir que la aplicación inspeccione el nombre de host y seleccione el certificado adecuado.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

La compatibilidad con SNI requiere lo siguiente:SNI support requires:

  • Ejecutarse en el marco de destino netcoreapp2.1 o posterior.Running on target framework netcoreapp2.1 or later. En net461 o posterior, se invoca la devolución de llamada, pero name siempre es null.On net461 or later, the callback is invoked but the name is always null. name también será null si el cliente no proporciona el parámetro de nombre de host en el protocolo de enlace TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Todos los sitios web deben ejecutarse en la misma instancia de Kestrel.All websites run on the same Kestrel instance. Kestrel no admite el uso compartido de una dirección IP y un puerto entre varias instancias sin un proxy inverso.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, serverOptions) =>
        {
            serverOptions.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;
                    };
                });
            });
        });

Registro de conexionesConnection logging

Llame a UseConnectionLogging para emitir registros de nivel de depuración para la comunicación a nivel de bytes en una conexión.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. El registro de conexiones es útil para solucionar problemas en la comunicación de bajo nivel, como durante el cifrado TLS y detrás de los servidores proxy.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Si UseConnectionLogging se coloca antes de UseHttps, se registra el tráfico cifrado.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Si UseConnectionLogging se coloca después de UseHttps, se registra el tráfico descifrado.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Enlazar a un socket TCPBind to a TCP socket

El método Listen se enlaza a un socket TCP y una expresión lambda de opciones permite configurar un certificado 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, serverOptions) =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

En el ejemplo se configura HTTPS para un punto de conexión con ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Use la misma API para configurar otras opciones de Kestrel para puntos de conexión específicos.Use the same API to configure other Kestrel settings for specific endpoints.

En Windows, pueden crearse certificados autofirmados con el cmdlet New-SelfSignedCertificate de PowerShell.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Para obtener un ejemplo no compatible, vea UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

En macOS, Linux y Windows, pueden crearse certificados con OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Enlazar a un socket de UnixBind to a Unix socket

Escuche en un socket de Unix con ListenUnixSocket para mejorar el rendimiento con Nginx, tal como se muestra en este ejemplo:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
});
  • En el archivo de configuración de Nginx, establezca la entrada server > location > proxy_pass en http://unix:/tmp/{KESTREL SOCKET}:/;.In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} es el nombre del socket proporcionado para ListenUnixSocket (por ejemplo, kestrel-test.sock en el ejemplo anterior).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Asegúrese de que el socket es grabable por Nginx (por ejemplo, chmod go+w /tmp/kestrel-test.sock).Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

Puerto 0Port 0

Cuando se especifica el número de puerto 0, Kestrel se enlaza de forma dinámica a un puerto disponible.When the port number 0 is specified, Kestrel dynamically binds to an available port. En el siguiente ejemplo se muestra cómo averiguar qué puerto Kestrel está realmente enlazado a un runtime: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>");
    });
}

Cuando la aplicación se ejecuta, la salida de la ventana de consola indica el puerto dinámico en el que se puede tener acceso a la aplicación: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

LimitacionesLimitations

Configure puntos de conexión con los siguientes métodos:Configure endpoints with the following approaches:

  • UseUrls
  • El argumento de la línea de comandos --urls--urls command-line argument
  • La clave de configuración de host urlsurls host configuration key
  • La variable de entorno ASPNETCORE_URLSASPNETCORE_URLS environment variable

Estos métodos son útiles para que el código funcione con servidores que no sean de Kestrel.These methods are useful for making code work with servers other than Kestrel. Sin embargo, tenga en cuenta las siguientes limitaciones:However, be aware of the following limitations:

  • HTTPS no se puede usar con estos métodos, a menos que se proporcione un certificado predeterminado en la configuración del punto de conexión HTTPS (por ejemplo, por medio de la configuración KestrelServerOptions o de un archivo de configuración, tal y como se explicó anteriormente en este tema).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).
  • Cuando los métodos Listen y UseUrls se usan al mismo tiempo, los puntos de conexión de Listen sustituyen a los de UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configuración de puntos de conexión IISIIS endpoint configuration

Cuando se usa IIS, los enlaces de direcciones URL de IIS reemplazan a los enlaces que se hayan establecido por medio de Listen o de UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Para más información, vea el tema Módulo ASP.NET Core.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

La propiedad Protocols establece los protocolos HTTP (HttpProtocols) habilitados en un punto de conexión o para el servidor.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Asigne un valor a la propiedad Protocols desde el valor de enumeración HttpProtocols.Assign a value to the Protocols property from the HttpProtocols enum.

Valor de enumeración HttpProtocolsHttpProtocols enum value Protocolo de conexión permitidoConnection protocol permitted
Http1 HTTP/1.1 solo.HTTP/1.1 only. Puede usarse con o sin TLS.Can be used with or without TLS.
Http2 HTTP/2 solo.HTTP/2 only. Se pueden utilizar sin TLS solo si el cliente admite un modo de conocimientos previos.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 y HTTP/2.HTTP/1.1 and HTTP/2. HTTP/2 necesita TLS y una conexión de Negociación de protocolo de nivel de aplicación (ALPN); en caso contrario, la opción predeterminada para la conexión es HTTP/1.1.HTTP/2 requires a TLS and Application-Layer Protocol Negotiation (ALPN) connection; otherwise, the connection defaults to HTTP/1.1.

El protocolo predeterminado es HTTP/1.1.The default protocol is HTTP/1.1.

Restricciones de TLS para HTTP/2:TLS restrictions for HTTP/2:

  • TLS 1.2 o versiones posterioresTLS version 1.2 or later
  • Renegociación deshabilitadaRenegotiation disabled
  • Compresión deshabilitadaCompression disabled
  • Tamaños de intercambio de claves efímeras mínimos:Minimum ephemeral key exchange sizes:
    • Curva elíptica Diffie-Hellman (ECDHE) [RFC4492] –; 224 bits como mínimoElliptic curve Diffie-Hellman (ECDHE) [RFC4492] – 224 bits minimum
    • Campo finito Diffie-Hellman (DHE) [TLS12] –; 2048 bits como mínimoFinite field Diffie-Hellman (DHE) [TLS12] – 2048 bits minimum
  • Conjunto de cifrado no restringidoCipher suite not blacklisted

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] con la curva elíptica P-256 [FIPS186] es compatible de forma predeterminada.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

El siguiente ejemplo permite conexiones HTTP/1.1 y HTTP/2 en el puerto 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Las conexiones se protegen mediante TLS con un certificado proporcionado:Connections are secured by TLS with a supplied certificate:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Opcionalmente, cree una implementación IConnectionAdapter para filtrar los protocolos de enlace TLS en una base por conexión para los cifrados específicos:Optionally create an IConnectionAdapter implementation to filter TLS handshakes on a per-connection basis for specific ciphers:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.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 the app doesn't
        // wish to support. Alternatively, define and compare
        // ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher
        // suites.
        //
        // No encryption is used with a CipherAlgorithmType.Null cipher algorithm.
        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()
        {
        }
    }
}

Defina el protocolo a partir de la configuraciónSet the protocol from configuration

CreateDefaultBuilder llama a serverOptions.Configure(context.Configuration.GetSection("Kestrel")) de forma predeterminada para cargar la configuración de Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

En el siguiente ejemplo de appsettings.json, se establece un protocolo de conexión predeterminado (HTTP/1.1 y HTTP/2) para todos los puntos de conexión 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"
    }
  }
}

El siguiente ejemplo de archivo de configuración establece un protocolo de conexión para un punto de conexión específico:The following configuration file example establishes a connection protocol for a specific endpoint:

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

Los protocolos especificados en el código invalidan los valores establecidos por la configuración.Protocols specified in code override values set by configuration.

Configuración de transporteTransport configuration

Desde el lanzamiento de ASP.NET Core 2.1, el transporte predeterminado de Kestrel deja de basarse en Libuv y pasa a basarse en sockets administrados.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. Se trata de un cambio muy importante para las aplicaciones ASP.NET Core 2.0 que actualizan a 2.1 y llaman a UseLibuv, y que dependen de cualquiera de los siguientes paquetes: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:

Para los proyectos que necesitan el uso de Libuv:For projects that require the use of Libuv:

  • Agregar una dependencia del paquete Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv al archivo de proyecto de la aplicación: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="{VERSION}" />
    
  • Llame a 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>();
    }
    

Prefijos de URLURL prefixes

Al usar UseUrls, el argumento de línea de comandos --urls, la clave de configuración de host urls o una variable de entorno ASPNETCORE_URLS, los prefijos de dirección URL pueden tener cualquiera de estos formatos.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.

Solo son válidos los prefijos de dirección URL HTTP.Only HTTP URL prefixes are valid. Kestrel no admite HTTPS al configurar enlaces de dirección URL con UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Dirección IPv4 con número de puertoIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 es un caso especial que enlaza a todas las direcciones IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Dirección IPv6 con número de puertoIPv6 address with port number

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

    [::] es el equivalente en IPv6 de 0.0.0.0 en IPv4.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nombre de host con número de puertoHost name with port number

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

    Los nombres de host, * y + no son especiales.Host names, *, and +, aren't special. Todo lo que no se identifique como una dirección IP o un localhost válido se enlaza a todas las direcciones IP de IPv6 e IPv4.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Para enlazar distintos nombres de host a distintas aplicaciones ASP.NET Core en el mismo puerto, use HTTP.sys o un servidor proxy inverso, como IIS, Nginx o 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.

    Advertencia

    El hospedaje en una configuración de proxy inverso requiere filtrado de hosts.Hosting in a reverse proxy configuration requires host filtering.

  • Nombre localhost del host con el número de puerto o la IP de bucle invertido con el número de puertoHost localhost name with port number or loopback IP with port number

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

    Cuando se especifica localhost, Kestrel intenta enlazar a las interfaces de bucle invertido de IPv4 e IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Si el puerto solicitado lo está usando otro servicio en cualquier interfaz de bucle invertido, Kestrel no se puede iniciar.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Si ninguna de estas interfaces de bucle invertido está disponible por cualquier otra razón (normalmente porque no se admite IPv6), Kestrel registra una advertencia.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtrado de hostsHost filtering

Si bien Kestrel admite una configuración basada en prefijos como http://example.com:5000, pasa por alto completamente el nombre de host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. El host localhost es un caso especial que se usa para enlazar a direcciones de bucle invertido.Host localhost is a special case used for binding to loopback addresses. Cualquier otro host que no sea una dirección IP explícita se enlaza a todas las direcciones IP públicas.Any host other than an explicit IP address binds to all public IP addresses. Los encabezados Host no están validados.Host headers aren't validated.

Como solución alternativa, use el Middleware de filtrado de hosts.As a workaround, use Host Filtering Middleware. El middleware de filtrado de host se facilita a través del paquete Microsoft.AspNetCore.HostFiltering, que se incluye en el metapaquete Microsoft.AspNetCore.App (ASP.NET Core 2.1 o 2.2).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 2.2). El middleware se agrega por medio de CreateDefaultBuilder, que llama a 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>();
}

El Middleware de filtrado de hosts está deshabilitado de forma predeterminada.Host Filtering Middleware is disabled by default. Para habilitarlo, defina una clave AllowedHosts en appsettings.json/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. El valor es una lista delimitada por punto y coma de nombres de host sin los números de puerto:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Nota

Middleware de encabezados reenviados también tiene una opción AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. El Middleware de encabezados reenviados y el Middleware de filtrado de hosts tienen una funcionalidad similar en diferentes escenarios.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Establecer AllowedHosts con el Middleware de encabezados reenviados es adecuado cuando el encabezado Host no se conserva mientras se reenvían solicitudes con un servidor proxy inverso o un equilibrador de carga.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. Establecer AllowedHosts con el Middleware de filtrado de hosts es adecuado cuando se usa Kestrel como un servidor perimetral de acceso público o cuando el encabezado Host se reenvía directamente.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.

Para obtener más información sobre el Middleware de encabezados reenviados, consulte Configuración de ASP.NET Core para trabajar con servidores proxy y equilibradores de carga.For more information on Forwarded Headers Middleware, see Configuración de ASP.NET Core para trabajar con servidores proxy y equilibradores de carga.

Kestrel es un servidor web multiplataforma de ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel es el servidor web que se incluye de forma predeterminada en las plantillas de proyecto de ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel admite los siguientes escenarios:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Actualización opaca para habilitar WebSocketsOpaque upgrade used to enable WebSockets
  • Sockets de Unix para alto rendimiento detrás de NginxUnix sockets for high performance behind Nginx

Kestrel admite todas las plataformas y versiones que sean compatibles con .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

Cuándo usar Kestrel con un proxy inversoWhen to use Kestrel with a reverse proxy

Kestrel se puede usar por sí solo o con un servidor proxy inverso, como Internet Information Services (IIS), Nginx o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Un servidor proxy inverso recibe las solicitudes HTTP de la red y las reenvía a Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel empleado como servidor web perimetral (accesible desde Internet):Kestrel used as an edge (Internet-facing) web server:

Kestrel se comunica directamente con Internet sin ningún servidor proxy inverso

Kestrel empleado en una configuración de proxy inverso:Kestrel used in a reverse proxy configuration:

Kestrel se comunica indirectamente con Internet a través de un servidor proxy inverso, como IIS, Nginx o Apache

Cualquiera de las configuraciones, con o sin servidor proxy inverso, es una configuración de hospedaje admitida.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Kestrel, utilizado como un servidor perimetral sin un servidor proxy inverso, no permite compartir la misma dirección IP y el mismo puerto entre varios procesos.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Si Kestrel se configura para escuchar en un puerto, controla todo el tráfico de ese puerto, independientemente de los encabezados Host de las solicitudes.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 inverso que puede compartir puertos es capaz de reenviar solicitudes a Kestrel en una única dirección IP y puerto.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Aunque no sea necesario un servidor proxy inverso, su uso puede ser útil.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Un proxy inverso puede hacer lo siguiente:A reverse proxy:

  • Limitar el área expuesta públicamente de las aplicaciones que hospeda.Can limit the exposed public surface area of the apps that it hosts.
  • Proporcionar una capa extra de configuración y defensa.Provide an additional layer of configuration and defense.
  • Posiblemente, integrarse mejor con la infraestructura existente.Might integrate better with existing infrastructure.
  • Simplificar el equilibrio de carga y la configuración de una comunicación segura (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Solamente el servidor proxy inverso necesita un certificado X.509 y dicho servidor se puede comunicar con los servidores de la aplicación en la red interna por medio de HTTP sin formato.Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

Advertencia

El hospedaje en una configuración de proxy inverso requiere filtrado de hosts.Hosting in a reverse proxy configuration requires host filtering.

Cómo usar Kestrel en aplicaciones ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

El paquete Microsoft.AspNetCore.Server.Kestrel se incluye en el metapaquete Microsoft.AspNetCore.App.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

Las plantillas de proyecto de ASP.NET Core usan Kestrel de forma predeterminada.ASP.NET Core project templates use Kestrel by default. En Program.cs, el código de plantilla llama a CreateDefaultBuilder, que a su vez llama a UseKestrel en segundo plano.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

Para proporcionar configuración adicional después de llamar a CreateDefaultBuilder, llame a UseKestrel:To provide additional configuration after calling CreateDefaultBuilder, call UseKestrel:

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

Para más información sobre CreateDefaultBuilder y la compilación del host, consulte la sección sobre cómo configurar un host de Host web de ASP.NET Core.For more information on CreateDefaultBuilder and building the host, see the Set up a host section of Host web de ASP.NET Core.

Opciones de KestrelKestrel options

El servidor web Kestrel tiene opciones de configuración de restricción que son especialmente útiles en las implementaciones con conexión a Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Establezca restricciones en la propiedad Limits de la clase KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. La propiedad Limits contiene una instancia de la clase KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

En los ejemplos siguientes se usa el espacio de nombres Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Las opciones de Kestrel, que se configuran en código de C# en los siguientes ejemplos, también se pueden establecer mediante un proveedor de configuración.Kestrel options, which are configured in C# code in the following examples, can also be set using a configuration provider. Por ejemplo, el proveedor de configuración de archivos puede cargar la configuración de Kestrel desde un archivo appsettings.json o appsettings.{Environment}.json:For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

{
  "Kestrel": {
    "Limits": {
      "MaxConcurrentConnections": 100,
      "MaxConcurrentUpgradedConnections": 100
    }
  }
}

Siga uno de estos procedimientos:Use one of the following approaches:

  • Configure Kestrel en Startup.ConfigureServices:Configure Kestrel in Startup.ConfigureServices:

    1. Inserte una instancia de IConfiguration en la clase Startup.Inject an instance of IConfiguration into the Startup class. En el ejemplo siguiente se da por supuesto que la configuración insertada está asignada a la propiedad Configuration.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. En Startup.ConfigureServices, cargue la sección de configuración Kestrel en la configuración de Kestrel:In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:

      using Microsoft.Extensions.Configuration
      
      public class Startup
      {
          public Startup(IConfiguration configuration)
          {
              Configuration = configuration;
          }
      
          public IConfiguration Configuration { get; }
      
          public void ConfigureServices(IServiceCollection services)
          {
              services.Configure<KestrelServerOptions>(
                  Configuration.GetSection("Kestrel"));
          }
      
          public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
          {
              ...
          }
      }
      
  • Configure Kestrel al compilar el host:Configure Kestrel when building the host:

    En Program.cs, cargue la sección de configuración Kestrel en la configuración de Kestrel:In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

    // using Microsoft.Extensions.DependencyInjection;
    
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureServices((context, services) =>
            {
                services.Configure<KestrelServerOptions>(
                    context.Configuration.GetSection("Kestrel"));
            })
            .UseStartup<Startup>();
    

Los dos procedimientos anteriores funcionan con cualquier proveedor de configuración.Both of the preceding approaches work with any configuration provider.

Tiempo de expiración de la conexión persistenteKeep-alive timeout

KeepAliveTimeout

Obtiene o establece el tiempo de expiración de la conexión persistente.Gets or sets the keep-alive timeout. El valor predeterminado es de 2 minutos.Defaults to 2 minutes.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
        });

Las conexiones máximas de clienteMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

El número máximo de conexiones de TCP abiertas simultáneas que se pueden establecer para toda la aplicación con este código:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxConcurrentConnections = 100;
        });

Hay un límite independiente para las conexiones que se han actualizado desde HTTP o HTTPS a otro protocolo (por ejemplo, en una solicitud de WebSockets).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Cuando se actualiza una conexión, no se cuenta con respecto al límite de MaxConcurrentConnections.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
        });

El número máximo de conexiones es ilimitado de forma predeterminada (null).The maximum number of connections is unlimited (null) by default.

El tamaño máximo del cuerpo de solicitudMaximum request body size

MaxRequestBodySize

El tamaño máximo predeterminado del cuerpo de solicitud es 30 000 000 bytes, que son aproximadamente 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

El método recomendado para invalidar el límite de una aplicación ASP.NET Core MVC es usar el atributo RequestSizeLimitAttribute en un método de acción: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()

Este es un ejemplo que muestra cómo configurar la restricción en la aplicación y todas las solicitudes:Here's an example that shows how to configure the constraint for the app on every request:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
        });

Invalide la configuración en una solicitud específica de middleware: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));
    }

Se inicia una excepción si la aplicación configura el límite de una solicitud después de que la aplicación haya empezado a leer la solicitud.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Hay una propiedad IsReadOnly que señala si la propiedad MaxRequestBodySize tiene el estado de solo lectura, lo que significa que es demasiado tarde para configurar el límite.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.

Cuando se ejecuta una aplicación fuera de proceso detrás del módulo de ASP.NET Core, el límite de tamaño del cuerpo de la solicitud de Kestrel se deshabilita porque IIS ya establece el límite.When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit is disabled because IIS already sets the limit.

La velocidad mínima de los datos del cuerpo de solicitud.Minimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel comprueba cada segundo si los datos entran a la velocidad especificada en bytes por segundo.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Si la velocidad está por debajo del mínimo, se agota el tiempo de espera de la conexión. El período de gracia es la cantidad de tiempo que Kestrel da al cliente para aumentar su velocidad de envío hasta el mínimo; no se comprueba la velocidad durante ese tiempo.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. Este período de gracia permite evitar que se interrumpan las conexiones que inicialmente están enviando datos a una velocidad lenta debido a un inicio lento de TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

La velocidad mínima predeterminada es 240 bytes por segundo, con un período de gracia de cinco segundos.The default minimum rate is 240 bytes/second with a 5 second grace period.

También se aplica una velocidad mínima a la respuesta.A minimum rate also applies to the response. El código para establecer el límite de solicitudes y el límite de respuestas es el mismo, salvo que tienen RequestBody o Response en los nombres de propiedad y de interfaz.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.

Este es un ejemplo que muestra cómo configurar las velocidades de datos mínimas en Program.cs:Here's an example that shows how to configure the minimum data rates in Program.cs:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MinRequestBodyDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
            serverOptions.Limits.MinResponseDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
        });

Tiempo de expiración de los encabezados de solicitudRequest headers timeout

RequestHeadersTimeout

Obtiene o establece la cantidad máxima de tiempo que el servidor pasa recibiendo las cabeceras de las solicitudes.Gets or sets the maximum amount of time the server spends receiving request headers. El valor predeterminado es 30 segundos.Defaults to 30 seconds.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
        });

E/S sincrónicaSynchronous IO

AllowSynchronousIO controla si se permite la E/S sincrónica para la solicitud y la respuesta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. El valor predeterminado es true.The default value is true.

Advertencia

Un gran número de operaciones de E/S sincrónicas de bloqueo puede dar lugar al colapso del grupo de subprocesos, lo que hace que la aplicación no responda.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Habilite solo AllowSynchronousIO al usar una biblioteca que no admite la E/S asincrónica.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

En el siguiente ejemplo se deshabilita la E/S sincrónica:The following example disables synchronous IO:

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

Para más información sobre otras opciones y límites de Kestrel, vea:For information about other Kestrel options and limits, see:

Configuración de punto de conexiónEndpoint configuration

ASP.NET Core enlaza de forma predeterminada a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (cuando hay presente un certificado de desarrollo local)https://localhost:5001 (when a local development certificate is present)

Especifique direcciones URL mediante los siguientes elementos:Specify URLs using the:

  • La variable de entorno ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • El argumento de la línea de comandos --urls.--urls command-line argument.
  • La clave de configuración de host urls.urls host configuration key.
  • El método de extensión UseUrls.UseUrls extension method.

El valor que estos métodos suministran puede ser uno o más puntos de conexión HTTP y HTTPS (este último, si hay disponible un certificado predeterminado).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configure el valor como una lista separada por punto y coma (por ejemplo, "Urls": "http://localhost:8000;http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Para más información sobre estos enfoques, consulte Direcciones URL del servidor e Invalidar la configuración.For more information on these approaches, see Server URLs and Override configuration.

Un certificado de desarrollo se crea:A development certificate is created:

Algunos exploradores necesitan que se conceda permiso explícito para confiar en el certificado de desarrollo local.Some browsers require granting explicit permission to trust the local development certificate.

Las plantillas de proyecto configuran aplicaciones para que se ejecuten en HTTPS de forma predeterminada e incluyen redirección de HTTPS y compatibilidad con HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Llame a los métodos Listen o ListenUnixSocket de KestrelServerOptions para configurar los puertos y los prefijos de dirección URL para Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, el argumento de línea de comandos --urls, la clave de configuración de host urls y la variable de entorno ASPNETCORE_URLS también funcionan, pero tienen las limitaciones que se indican más adelante en esta sección (debe haber disponible un certificado predeterminado para la configuración de puntos de conexión 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).

Configuración de KestrelServerOptions:KestrelServerOptions configuration:

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

Especifica una Action de configuración para que se ejecute con cada punto de conexión especificado.Specifies a configuration Action to run for each specified endpoint. Al llamar a ConfigureEndpointDefaults varias veces, se reemplazan las Action anteriores por la última Action especificada.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });
        });

Nota

Los puntos de conexión que se crean mediante una llamada a Listen antes de llamar a ConfigureEndpointDefaults no tendrán aplicados los valores predeterminados.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

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

Especifica una Action de configuración para que se ejecute con cada punto de conexión HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Al llamar a ConfigureHttpsDefaults varias veces, se reemplazan las Action anteriores por la última Action especificada.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                // certificate is an X509Certificate2
                listenOptions.ServerCertificate = certificate;
            });
        });

Nota

Los puntos de conexión que se crean mediante una llamada a Listen antes de llamar a ConfigureHttpsDefaults no tendrán aplicados los valores predeterminados.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Configure(IConfiguration)Configure(IConfiguration)

Crea un cargador de configuración para configurar Kestrel que toma una IConfiguration como entrada.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. El ámbito de la configuración debe corresponderse con la sección de configuración de Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configure Kestrel para que use HTTPS.Configure Kestrel to use HTTPS.

Extensiones de ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps – Configure Kestrel para que use HTTPS con el certificado predeterminado.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Produce una excepción si no hay ningún certificado predeterminado configurado.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)

Parámetros de ListenOptions.UseHttps:ListenOptions.UseHttps parameters:

  • filename es la ruta de acceso y el nombre de archivo de un archivo de certificado correspondiente al directorio donde están los archivos de contenido de la aplicación.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password es la contraseña necesaria para obtener acceso a los datos del certificado X.509.password is the password required to access the X.509 certificate data.
  • configureOptions es una Action para configurar HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Devuelve ListenOptions.Returns the ListenOptions.
  • storeName es el almacén de certificados desde el que se carga el certificado.storeName is the certificate store from which to load the certificate.
  • subject es el nombre del sujeto del certificado.subject is the subject name for the certificate.
  • allowInvalid indica si se deben tener en cuenta los certificados no válidos, como los certificados autofirmados.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location es la ubicación del almacén desde el que se carga el certificado.location is the store location to load the certificate from.
  • serverCertificate es el certificado X.509.serverCertificate is the X.509 certificate.

En un entorno de producción, HTTPS se debe configurar explícitamente.In production, HTTPS must be explicitly configured. Como mínimo, debe existir un certificado predeterminado.At a minimum, a default certificate must be provided.

Estas son las configuraciones compatibles:Supported configurations described next:

  • Sin configuraciónNo configuration
  • Reemplazar el certificado predeterminado de configuraciónReplace the default certificate from configuration
  • Cambiar los valores predeterminados en el códigoChange the defaults in code

Sin configuraciónNo configuration

Kestrel escucha en http://localhost:5000 y en https://localhost:5001 (si hay disponible un certificado predeterminado).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Reemplazar el certificado predeterminado de configuraciónReplace the default certificate from configuration

CreateDefaultBuilder llama a Configure(context.Configuration.GetSection("Kestrel")) de forma predeterminada para cargar la configuración de Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Hay disponible un esquema de configuración de aplicación HTTPS predeterminado para Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Configure varios puntos de conexión (incluidas las direcciones URL y los certificados que va a usar) desde un archivo en disco o desde un almacén de certificados.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

En el siguiente ejemplo de appsettings.json:In the following appsettings.json example:

  • Establezca AllowInvalid en true para permitir el uso de certificados no válidos (por ejemplo, certificados autofirmados).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Cualquier punto de conexión HTTPS que no especifique un certificado (HttpsDefaultCert en el siguiente ejemplo) revierte al certificado definido en Certificados > Predeterminado o al certificado de desarrollo.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; required>",
          "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>"
      }
    }
  }
}

Una alternativa al uso de Path y Password en cualquier nodo de certificado consiste en especificar el certificado por medio de campos del almacén de certificados.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Por ejemplo, el certificado en Certificados > Predeterminado se puede especificar así:For example, the Certificates > Default certificate can be specified as:

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

Notas sobre el esquema:Schema notes:

  • En los nombres de los puntos de conexión se distingue entre mayúsculas y minúsculas.Endpoints names are case-insensitive. Por ejemplo, HTTPS y Https son válidos.For example, HTTPS and Https are valid.
  • El parámetro Url es necesario en cada punto de conexión.The Url parameter is required for each endpoint. El formato de este parámetro es el mismo que el del parámetro de configuración Urls de nivel superior, excepto por el hecho de que está limitado a un único valor.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • En vez de agregarse, estos puntos de conexión reemplazan a los que están definidos en la configuración Urls de nivel superior.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Los puntos de conexión definidos en el código a través de Listen son acumulativos con respecto a los puntos de conexión definidos en la sección de configuración.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • La sección Certificate es opcional.The Certificate section is optional. Si la sección Certificate no se especifica, se usan los valores predeterminados definidos en escenarios anteriores.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Si no hay valores predeterminados disponibles, el servidor produce una excepción y no se inicia.If no defaults are available, the server throws an exception and fails to start.
  • La sección Certificate admite certificadostanto PathPassword como SubjectStore.The Certificate section supports both PathPassword and SubjectStore certificates.
  • Se puede definir el número de puntos de conexión que se quiera de esta manera, siempre y cuando no produzcan conflictos de puerto.Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) devuelve un KestrelConfigurationLoader con un método .Endpoint(string name, listenOptions => { }) que se puede usar para complementar la configuración de un punto de conexión configurado:options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

Se puede acceder directamente a KestrelServerOptions.ConfigurationLoader para seguir con la iteración en el cargador existente, como el proporcionado por CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • La sección de configuración de cada punto de conexión está disponible en las opciones del método Endpoint para que se pueda leer la configuración personalizada.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Se pueden cargar varias configuraciones volviendo a llamar a options.Configure(context.Configuration.GetSection("{SECTION}")) con otra sección.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Se usa la última configuración, a menos que se llame explícitamente a Load en instancias anteriores.Only the last configuration is used, unless Load is explicitly called on prior instances. El metapaquete no llama a Load, con lo cual su sección de configuración predeterminada se puede reemplazar.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader refleja la familia Listen de API de KestrelServerOptions como sobrecargas de Endpoint, por lo que los puntos de conexión de configuración y código se pueden configurar en el mismo lugar.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. En estas sobrecargas no se usan nombres y solo consumen valores predeterminados de la configuración.These overloads don't use names and only consume default settings from configuration.

Cambiar los valores predeterminados en el códigoChange the defaults in code

ConfigureEndpointDefaults y ConfigureHttpsDefaults se pueden usar para cambiar la configuración predeterminada de ListenOptions y HttpsConnectionAdapterOptions, incluido sustituir el certificado predeterminado especificado en el escenario anterior.ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. Se debe llamar a ConfigureEndpointDefaults y a ConfigureHttpsDefaults antes de que se configure algún punto de conexión.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });

            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                listenOptions.SslProtocols = SslProtocols.Tls12;
            });
        });

Compatibilidad de Kestrel con SNIKestrel support for SNI

Indicación de nombre de servidor (SNI) se puede usar para hospedar varios dominios en la misma dirección IP y puerto.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Para que SNI funcione, el cliente envía el nombre de host de la sesión segura al servidor durante el protocolo de enlace TLS para que, de este modo, el servidor pueda proporcionar el certificado correcto.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. El cliente usa el certificado proporcionado para la comunicación cifrada con el servidor durante la sesión segura que sigue al protocolo de enlace TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel admite SNI a través de la devolución de llamada ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. La devolución de llamada se invoca una vez por conexión para permitir que la aplicación inspeccione el nombre de host y seleccione el certificado adecuado.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

La compatibilidad con SNI requiere lo siguiente:SNI support requires:

  • Ejecutarse en el marco de destino netcoreapp2.1 o posterior.Running on target framework netcoreapp2.1 or later. En net461 o posterior, se invoca la devolución de llamada, pero name siempre es null.On net461 or later, the callback is invoked but the name is always null. name también será null si el cliente no proporciona el parámetro de nombre de host en el protocolo de enlace TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Todos los sitios web deben ejecutarse en la misma instancia de Kestrel.All websites run on the same Kestrel instance. Kestrel no admite el uso compartido de una dirección IP y un puerto entre varias instancias sin un proxy inverso.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>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.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();

Registro de conexionesConnection logging

Llame a UseConnectionLogging para emitir registros de nivel de depuración para la comunicación a nivel de bytes en una conexión.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. El registro de conexiones es útil para solucionar problemas en la comunicación de bajo nivel, como durante el cifrado TLS y detrás de los servidores proxy.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Si UseConnectionLogging se coloca antes de UseHttps, se registra el tráfico cifrado.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Si UseConnectionLogging se coloca después de UseHttps, se registra el tráfico descifrado.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Enlazar a un socket TCPBind to a TCP socket

El método Listen se enlaza a un socket TCP y una expresión lambda de opciones permite configurar un certificado 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>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.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(serverOptions =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

En el ejemplo se configura HTTPS para un punto de conexión con ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Use la misma API para configurar otras opciones de Kestrel para puntos de conexión específicos.Use the same API to configure other Kestrel settings for specific endpoints.

En Windows, pueden crearse certificados autofirmados con el cmdlet New-SelfSignedCertificate de PowerShell.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Para obtener un ejemplo no compatible, vea UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

En macOS, Linux y Windows, pueden crearse certificados con OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Enlazar a un socket de UnixBind to a Unix socket

Escuche en un socket de Unix con ListenUnixSocket para mejorar el rendimiento con Nginx, tal como se muestra en este ejemplo:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testpassword");
            });
        });
  • En el archivo de configuración de Nginx, establezca la entrada server > location > proxy_pass en http://unix:/tmp/{KESTREL SOCKET}:/;.In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} es el nombre del socket proporcionado para ListenUnixSocket (por ejemplo, kestrel-test.sock en el ejemplo anterior).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Asegúrese de que el socket es grabable por Nginx (por ejemplo, chmod go+w /tmp/kestrel-test.sock).Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

Puerto 0Port 0

Cuando se especifica el número de puerto 0, Kestrel se enlaza de forma dinámica a un puerto disponible.When the port number 0 is specified, Kestrel dynamically binds to an available port. En el siguiente ejemplo se muestra cómo averiguar qué puerto Kestrel está realmente enlazado a un runtime: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>");
    });
}

Cuando la aplicación se ejecuta, la salida de la ventana de consola indica el puerto dinámico en el que se puede tener acceso a la aplicación: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

LimitacionesLimitations

Configure puntos de conexión con los siguientes métodos:Configure endpoints with the following approaches:

  • UseUrls
  • El argumento de la línea de comandos --urls--urls command-line argument
  • La clave de configuración de host urlsurls host configuration key
  • La variable de entorno ASPNETCORE_URLSASPNETCORE_URLS environment variable

Estos métodos son útiles para que el código funcione con servidores que no sean de Kestrel.These methods are useful for making code work with servers other than Kestrel. Sin embargo, tenga en cuenta las siguientes limitaciones:However, be aware of the following limitations:

  • HTTPS no se puede usar con estos métodos, a menos que se proporcione un certificado predeterminado en la configuración del punto de conexión HTTPS (por ejemplo, por medio de la configuración KestrelServerOptions o de un archivo de configuración, tal y como se explicó anteriormente en este tema).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).
  • Cuando los métodos Listen y UseUrls se usan al mismo tiempo, los puntos de conexión de Listen sustituyen a los de UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configuración de puntos de conexión IISIIS endpoint configuration

Cuando se usa IIS, los enlaces de direcciones URL de IIS reemplazan a los enlaces que se hayan establecido por medio de Listen o de UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Para más información, vea el tema Módulo ASP.NET Core.For more information, see the ASP.NET Core Module topic.

Configuración de transporteTransport configuration

Desde el lanzamiento de ASP.NET Core 2.1, el transporte predeterminado de Kestrel deja de basarse en Libuv y pasa a basarse en sockets administrados.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. Se trata de un cambio muy importante para las aplicaciones ASP.NET Core 2.0 que actualizan a 2.1 y llaman a UseLibuv, y que dependen de cualquiera de los siguientes paquetes: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:

Para los proyectos que necesitan el uso de Libuv:For projects that require the use of Libuv:

  • Agregar una dependencia del paquete Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv al archivo de proyecto de la aplicación: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="{VERSION}" />
    
  • Llame a 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>();
    }
    

Prefijos de URLURL prefixes

Al usar UseUrls, el argumento de línea de comandos --urls, la clave de configuración de host urls o una variable de entorno ASPNETCORE_URLS, los prefijos de dirección URL pueden tener cualquiera de estos formatos.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.

Solo son válidos los prefijos de dirección URL HTTP.Only HTTP URL prefixes are valid. Kestrel no admite HTTPS al configurar enlaces de dirección URL con UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Dirección IPv4 con número de puertoIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 es un caso especial que enlaza a todas las direcciones IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Dirección IPv6 con número de puertoIPv6 address with port number

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

    [::] es el equivalente en IPv6 de 0.0.0.0 en IPv4.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nombre de host con número de puertoHost name with port number

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

    Los nombres de host, * y + no son especiales.Host names, *, and +, aren't special. Todo lo que no se identifique como una dirección IP o un localhost válido se enlaza a todas las direcciones IP de IPv6 e IPv4.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Para enlazar distintos nombres de host a distintas aplicaciones ASP.NET Core en el mismo puerto, use HTTP.sys o un servidor proxy inverso, como IIS, Nginx o 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.

    Advertencia

    El hospedaje en una configuración de proxy inverso requiere filtrado de hosts.Hosting in a reverse proxy configuration requires host filtering.

  • Nombre localhost del host con el número de puerto o la IP de bucle invertido con el número de puertoHost localhost name with port number or loopback IP with port number

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

    Cuando se especifica localhost, Kestrel intenta enlazar a las interfaces de bucle invertido de IPv4 e IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Si el puerto solicitado lo está usando otro servicio en cualquier interfaz de bucle invertido, Kestrel no se puede iniciar.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Si ninguna de estas interfaces de bucle invertido está disponible por cualquier otra razón (normalmente porque no se admite IPv6), Kestrel registra una advertencia.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtrado de hostsHost filtering

Si bien Kestrel admite una configuración basada en prefijos como http://example.com:5000, pasa por alto completamente el nombre de host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. El host localhost es un caso especial que se usa para enlazar a direcciones de bucle invertido.Host localhost is a special case used for binding to loopback addresses. Cualquier otro host que no sea una dirección IP explícita se enlaza a todas las direcciones IP públicas.Any host other than an explicit IP address binds to all public IP addresses. Los encabezados Host no están validados.Host headers aren't validated.

Como solución alternativa, use el Middleware de filtrado de hosts.As a workaround, use Host Filtering Middleware. El middleware de filtrado de host se facilita a través del paquete Microsoft.AspNetCore.HostFiltering, que se incluye en el metapaquete Microsoft.AspNetCore.App (ASP.NET Core 2.1 o 2.2).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 2.2). El middleware se agrega por medio de CreateDefaultBuilder, que llama a 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>();
}

El Middleware de filtrado de hosts está deshabilitado de forma predeterminada.Host Filtering Middleware is disabled by default. Para habilitarlo, defina una clave AllowedHosts en appsettings.json/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. El valor es una lista delimitada por punto y coma de nombres de host sin los números de puerto:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Nota

Middleware de encabezados reenviados también tiene una opción AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. El Middleware de encabezados reenviados y el Middleware de filtrado de hosts tienen una funcionalidad similar en diferentes escenarios.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Establecer AllowedHosts con el Middleware de encabezados reenviados es adecuado cuando el encabezado Host no se conserva mientras se reenvían solicitudes con un servidor proxy inverso o un equilibrador de carga.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. Establecer AllowedHosts con el Middleware de filtrado de hosts es adecuado cuando se usa Kestrel como un servidor perimetral de acceso público o cuando el encabezado Host se reenvía directamente.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.

Para obtener más información sobre el Middleware de encabezados reenviados, consulte Configuración de ASP.NET Core para trabajar con servidores proxy y equilibradores de carga.For more information on Forwarded Headers Middleware, see Configuración de ASP.NET Core para trabajar con servidores proxy y equilibradores de carga.

Recursos adicionalesAdditional resources