Implementação do servidor Web Kestrel no ASP.NET CoreKestrel web server implementation in ASP.NET Core

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

O Kestrel é um servidor Web multiplataforma para o ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. O Kestrel é o servidor Web que está incluído por padrão em modelos de projeto do ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

O Kestrel dá suporte aos seguintes cenários:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Atualização do Opaque usado para habilitar o WebSocketsOpaque upgrade used to enable WebSockets
  • Soquetes do UNIX para alto desempenho protegidos pelo NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (exceto em macOS†)HTTP/2 (except on macOS†)

†O HTTP/2 será compatível com macOS em uma versão futura.†HTTP/2 will be supported on macOS in a future release.

Há suporte para o Kestrel em todas as plataformas e versões compatíveis com o .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Compatibilidade com HTTP/2HTTP/2 support

O HTTP/2 estará disponível para aplicativos ASP.NET Core se os seguintes requisitos básicos forem atendidos:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Sistema operacional†Operating system†
    • Windows Server 2016/Windows 10 ou posterior‡Windows Server 2016/Windows 10 or later‡
    • Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Estrutura de destino: .NET Core 2.2 ou posteriorTarget framework: .NET Core 2.2 or later
  • Conexão ALPN (Negociação de protocolo de camada de aplicativo)Application-Layer Protocol Negotiation (ALPN) connection
  • Conexão TLS 1.2 ou posteriorTLS 1.2 or later connection

†O HTTP/2 será compatível com macOS em uma versão futura.†HTTP/2 will be supported on macOS in a future release. ‡O Kestrel tem suporte limitado para HTTP/2 no Windows Server 2012 R2 e Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. O suporte é limitado porque a lista de conjuntos de codificação TLS disponível nesses sistemas operacionais é limitada.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Um certificado gerado usando um ECDSA (Algoritmo de Assinatura Digital Curva Elíptica) pode ser necessário para proteger conexões TLS.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 está desabilitado por padrão.HTTP/2 is disabled by default. Para obter mais informações sobre a configuração, consulte as seções Opções do Kestrel e ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Quando usar o Kestrel com um proxy reversoWhen to use Kestrel with a reverse proxy

O Kestrel pode ser usado sozinho ou com um servidor proxy reverso, como o IIS (Serviços de Informações da Internet), o Nginx ou o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Um servidor proxy reverso recebe solicitações HTTP da rede e encaminha-as para o Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel usado como um servidor Web de borda (voltado para a Internet):Kestrel used as an edge (Internet-facing) web server:

O Kestrel se comunica diretamente com a Internet, sem um servidor proxy reverso

Kestrel usado em uma configuração de proxy reverso:Kestrel used in a reverse proxy configuration:

O Kestrel se comunica indiretamente com a Internet através de um servidor proxy reverso, tal como o IIS, o Nginx ou o Apache

A configuração, com ou sem um servidor proxy reverso, é uma configuração de hospedagem com suporte.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

O Kestrel usado como um servidor de borda sem um servidor proxy reverso não dá suporte ao compartilhamento do mesmo IP e da mesma porta entre vários processos.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Quando o Kestrel é configurado para escutar uma porta, ele manipula todo o tráfego dessa porta, independentemente dos cabeçalhos Host das solicitações.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Um proxy reverso que pode compartilhar portas tem a capacidade de encaminhar solicitações ao Kestrel em um IP e em uma porta exclusivos.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Mesmo se um servidor proxy reverso não for necessário, o uso de um servidor proxy reverso poderá ser uma boa opção.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Um proxy reverso:A reverse proxy:

  • Pode limitar a área da superfície pública exposta dos aplicativos que ele hospeda.Can limit the exposed public surface area of the apps that it hosts.
  • Fornece uma camada adicional de configuração e proteção.Provide an additional layer of configuration and defense.
  • Pode ser integrado melhor à infraestrutura existente.Might integrate better with existing infrastructure.
  • Simplifica o balanceamento de carga e a configuração de comunicação segura (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Somente o servidor proxy reverso requer um certificado X. 509 e esse servidor pode se comunicar com os servidores do aplicativo na rede interna usando HTTP simples.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.

Aviso

A hospedagem em uma configuração de proxy reverso exige a filtragem de host.Hosting in a reverse proxy configuration requires host filtering.

Como usar o Kestrel em aplicativos ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

Os modelos de projeto do ASP.NET Core usam o Kestrel por padrão.ASP.NET Core project templates use Kestrel by default. Em Program.cs, o código de modelo chama CreateDefaultBuilder, que chama UseKestrel em segundo plano.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

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 fornecer configuração adicional depois de CreateDefaultBuilder chamar ConfigureWebHostDefaultse, ConfigureKestreluse:To provide additional configuration after calling CreateDefaultBuilder and 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>();
        });

Se o aplicativo não chamar CreateDefaultBuilder para configurar o host, chame UseKestrel antes de chamar 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 HostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseIISIntegration()
            .UseStartup<Startup>();
        })
        .Build();

    host.Run();
}

Opções do KestrelKestrel options

O servidor Web do Kestrel tem opções de configuração de restrição especialmente úteis em implantações para a Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Defina restrições sobre a propriedade Limits da classe KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. A propriedade Limits contém uma instância da classe KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

Os exemplos a seguir usam o namespace Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Tempo limite de keep-aliveKeep-alive timeout

KeepAliveTimeout

Obtém ou define o tempo limite de keep-alive.Gets or sets the keep-alive timeout. O padrão é de dois 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);
})

Número máximo de conexões de clienteMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

O número máximo de conexões TCP abertas simultâneas pode ser definido para o aplicativo inteiro com o código a seguir: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);
})

Há um limite separado para conexões que foram atualizadas do HTTP ou HTTPS para outro protocolo (por exemplo, em uma solicitação do 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). Depois que uma conexão é atualizada, ela não é contada em relação ao limite 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);
})

O número máximo de conexões é ilimitado (nulo) por padrão.The maximum number of connections is unlimited (null) by default.

Tamanho máximo do corpo da solicitaçãoMaximum request body size

MaxRequestBodySize

O tamanho máximo do corpo da solicitação padrão é de 30.000.000 bytes, que equivale aproximadamente a 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

A abordagem recomendada para substituir o limite em um aplicativo ASP.NET Core MVC é usar o atributo RequestSizeLimitAttribute em um método de ação: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()

Aqui está um exemplo que mostra como configurar a restrição para o aplicativo em cada solicitação: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);
})

Substitua a configuração em uma solicitação específica no 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));
    }

Uma exceção será gerada se o aplicativo configurar o limite em uma solicitação depois que o aplicativo for iniciado para ler a solicitação.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Há uma propriedade IsReadOnly que indica se a propriedade MaxRequestBodySize está no estado somente leitura, o que significa que é tarde demais para configurar o limite.There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

Quando um aplicativo é executado fora do processo por trás do Módulo do ASP.NET Core, o limite de tamanho do corpo da solicitação do Kestrel fica desabilitado, pois o IIS já define o limite.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.

Taxa de dados mínima do corpo da solicitaçãoMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

O Kestrel verifica a cada segundo se os dados estão sendo recebidos na taxa especificada em bytes/segundo.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Se a taxa cair abaixo do mínimo, a conexão atingirá o tempo limite. O período de cortesia é o tempo que o Kestrel fornece ao cliente para aumentar sua taxa de envio até o mínimo; a taxa não é verificada durante esse período.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. O período de cortesia ajuda a evitar a remoção de conexões que inicialmente enviam dados em uma taxa baixa devido ao início lento do TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

A taxa mínima de padrão é de 240 bytes/segundo com um período de cortesia de 5 segundos.The default minimum rate is 240 bytes/second with a 5 second grace period.

Uma taxa mínima também se aplica à resposta.A minimum rate also applies to the response. O código para definir o limite de solicitação e o limite de resposta é o mesmo, exceto por ter RequestBody ou Response nos nomes da propriedade e da interface.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

Este é um exemplo que mostra como configurar as taxas mínima de dados em 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);
})

Substitua os limites de taxa mínimo por solicitação no 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));
    }

O IHttpMinResponseDataRateFeature referenciado no exemplo anterior não está presente no HttpContext.Features para solicitações HTTP/2, porque a modificação dos limites de taxa em cada solicitação não é geralmente compatível com HTTP/2 devido ao suporte de multiplexação de solicitação do protocolo.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. No entanto, o IHttpMinRequestBodyDataRateFeature ainda está presente em HttpContext.Features para solicitações HTTP/2, pois o limite de taxa de leitura ainda pode ser desabilitado totalmente em cada solicitação, definindo IHttpMinRequestBodyDataRateFeature.MinDataRate para null mesmo em uma solicitação 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. Tentar ler IHttpMinRequestBodyDataRateFeature.MinDataRate ou tentar defini-lo como um valor diferente de null resultará na geração de um NotSupportedException devido a uma solicitação HTTP/2.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.

Os limites de taxa de todo o servidor configurados por meio de KestrelServerOptions.Limits ainda se aplicam a conexões HTTP/1.x e HTTP/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Tempo limite dos cabeçalhos de solicitaçãoRequest headers timeout

RequestHeadersTimeout

Obtém ou define a quantidade máxima de tempo que o servidor gasta recebendo cabeçalhos de solicitação.Gets or sets the maximum amount of time the server spends receiving request headers. O padrão é 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);
})

Fluxos máximos por conexãoMaximum streams per connection

O Http2.MaxStreamsPerConnection limita o número de fluxos de solicitações simultâneas por conexão HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Os fluxos em excesso são recusados.Excess streams are refused.

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

O valor padrão é 100.The default value is 100.

Tamanho da tabela de cabeçalhoHeader table size

O decodificador HPACK descompacta os cabeçalhos HTTP para conexões HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. O Http2.HeaderTableSize limita o tamanho da tabela de compactação de cabeçalho usada pelo decodificador HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. O valor é fornecido em octetos e deve ser maior do que zero (0).The value is provided in octets and must be greater than zero (0).

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

O valor padrão é 4096.The default value is 4096.

Tamanho máximo do quadroMaximum frame size

Http2.MaxFrameSizeindica o tamanho máximo permitido de um conteúdo de quadro de conexão HTTP/2 recebido ou enviado pelo servidor.Http2.MaxFrameSize indicates the maximum allowed size of an HTTP/2 connection frame payload received or sent by the server. O valor é fornecido em octetos e deve estar entre 2^14 (16.384) e 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).

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

O valor padrão é 2^14 (16.384).The default value is 2^14 (16,384).

Tamanho máximo do cabeçalho de solicitaçãoMaximum request header size

Http2.MaxRequestHeaderFieldSize indica o tamanho máximo permitido em octetos de valores de cabeçalho de solicitação.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Esse limite se aplica tanto ao nome quanto ao valor em suas representações compactadas e descompactadas.This limit applies to both name and value in their compressed and uncompressed representations. O valor deve ser maior que zero (0).The value must be greater than zero (0).

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

O valor padrão é 8.192.The default value is 8,192.

Tamanho inicial da janela de conexãoInitial connection window size

Http2.InitialConnectionWindowSize indica os dados máximos do corpo da solicitação em bytes, que o servidor armazena em buffer ao mesmo tempo, agregados em todas as solicitações (fluxos) por conexão.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. As solicitações também são limitadas por Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. O valor deve ser maior ou igual a 65.535 e 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).

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

O valor padrão é 128 KB (131.072).The default value is 128 KB (131,072).

Tamanho inicial da janela de fluxoInitial stream window size

Http2.InitialStreamWindowSize indica o máximo de dados do corpo da solicitação, em bytes, que o servidor armazena em buffer ao mesmo tempo, por solicitação (fluxo).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). As solicitações também são limitadas por Http2.InitialConnectionWindowSize.Requests are also limited by Http2.InitialConnectionWindowSize. O valor deve ser maior ou igual a 65.535 e 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).

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

O valor padrão é 96 KB (98.304).The default value is 96 KB (98,304).

E/S síncronaSynchronous IO

AllowSynchronousIO controla se a E/S síncrona é permitida para a solicitação e resposta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. O valor padrão é false.The default value is false.

Aviso

Um grande número de operações de E/S síncronas de bloqueio pode levar à privação de pool de thread, o que faz com que o aplicativo não responda.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Habilite AllowSynchronousIO somente ao usar uma biblioteca em que não há suporte para E/S assíncrona.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

O exemplo a seguir ativa a E/S síncrona:The following example enables synchronous IO:

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

Para obter informações sobre outras opções e limites do Kestrel, confira:For information about other Kestrel options and limits, see:

Configuração do ponto de extremidadeEndpoint configuration

Por padrão, o ASP.NET Core associa a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (quando um certificado de desenvolvimento local está presente)https://localhost:5001 (when a local development certificate is present)

Especificar URLs usando:Specify URLs using the:

  • A variável de ambiente ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • O argumento de linha de comando --urls.--urls command-line argument.
  • A chave de configuração do host urls.urls host configuration key.
  • O método de extensão UseUrls.UseUrls extension method.

O valor fornecido usando essas abordagens pode ser um ou mais pontos de extremidade HTTP e HTTPS (HTTPS se houver um certificado padrão).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configure o valor como uma lista separada por ponto e vírgula (por exemplo, "Urls": "http://localhost:8000; http://localhost:8001" ).Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Veja mais informações sobre essas abordagens em URLs de servidor e Substituir configuração.For more information on these approaches, see Server URLs and Override configuration.

Um certificado de desenvolvimento é criado:A development certificate is created:

Alguns navegadores exigem a concessão de permissão explícita para confiar no certificado de desenvolvimento local.Some browsers require granting explicit permission to trust the local development certificate.

Os modelos de projeto configuram aplicativos para execução em HTTPS por padrão e incluem o redirecionamento de HTTPS e o suporte a HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Chame os métodos Listen ou ListenUnixSocket em KestrelServerOptions para configurar prefixos de URL e portas para o Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, o argumento de linha de comando --urls, a chave de configuração de host urls e a variável de ambiente ASPNETCORE_URLS também funcionam mas têm limitações que serão indicadas mais adiante nesta seção (um certificado padrão precisa estar disponível para a configuração do ponto de extremidade 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).

KestrelServerOptionsconfiguraçãoKestrelServerOptions configuration:

ConfigureEndpointDefaults (ação<escutaroptions >)ConfigureEndpointDefaults(Action<ListenOptions>)

Especifica uma Action de configuração a ser executada para cada ponto de extremidade especificado.Specifies a configuration Action to run for each specified endpoint. Chamar ConfigureEndpointDefaults várias vezes substitui as Actions pela última Action especificada.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.ConfigureEndpointDefaults(listenOptions =>
                {
                    // Configure endpoint defaults
                });
            })
            .UseStartup<Startup>();
        });
}

ConfigureHttpsDefaults (ação<HttpsConnectionAdapterOptions >)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Especifica uma Action de configuração a ser executada para cada ponto de extremidade HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Chamar ConfigureHttpsDefaults várias vezes substitui as Actions pela última Action especificada.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.ConfigureHttpsDefaults(listenOptions =>
                {
                    // certificate is an X509Certificate2
                    listenOptions.ServerCertificate = certificate;
                });
            })
            .UseStartup<Startup>();
        });
}

Configure(IConfiguration)Configure(IConfiguration)

Cria um carregador de configuração para configurar o Kestrel que usa uma IConfiguration como entrada.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. A configuração precisa estar no escopo da seção de configuração do Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configure o Kestrel para usar HTTPS.Configure Kestrel to use HTTPS.

Extensões ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps – Configure o Kestrel para usar HTTPS com o certificado padrão.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Gera uma exceção quando não há nenhum certificado padrão 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 é o caminho e o nome do arquivo de um arquivo de certificado, relativo ao diretório que contém os arquivos de conteúdo do aplicativo.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password é a senha necessária para acessar os dados do certificado X.509 .password is the password required to access the X.509 certificate data.
  • configureOptions é uma Action para configurar as HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Retorna o ListenOptions.Returns the ListenOptions.
  • storeName é o repositório de certificados do qual o certificado deve ser carregado.storeName is the certificate store from which to load the certificate.
  • subject é o nome da entidade do certificado.subject is the subject name for the certificate.
  • allowInvalid indica se certificados inválidos devem ser considerados, como os certificados autoassinados.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location é o local do repositório do qual o certificado deve ser carregado.location is the store location to load the certificate from.
  • serverCertificate é o certificado X.509.serverCertificate is the X.509 certificate.

Em produção, HTTPS precisa ser configurado explicitamente.In production, HTTPS must be explicitly configured. No mínimo, um certificado padrão precisa ser fornecido.At a minimum, a default certificate must be provided.

Configurações com suporte descritas a seguir:Supported configurations described next:

  • Nenhuma configuraçãoNo configuration
  • Substituir o certificado padrão da configuraçãoReplace the default certificate from configuration
  • Alterar os padrões no códigoChange the defaults in code

Nenhuma configuraçãoNo configuration

O Kestrel escuta em http://localhost:5000 e em https://localhost:5001 (se houver um certificado padrão disponível).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Substituir o certificado padrão da configuraçãoReplace the default certificate from configuration

CreateDefaultBuilder chama Configure(context.Configuration.GetSection("Kestrel")) por padrão ao carregar a configuração do Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Há um esquema de definições de configurações de aplicativo HTTPS padrão disponível para o Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Configure vários pontos de extremidade, incluindo URLs e os certificados a serem usados, por meio de um arquivo no disco ou de um repositório de certificados.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

No exemplo de appsettings.json a seguir:In the following appsettings.json example:

  • Defina AllowInvalid como true para permitir o uso de certificados inválidos (por exemplo, os certificados autoassinados).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Todo ponto de extremidade HTTPS que não especificar um certificado (HttpsDefaultCert no exemplo a seguir) será revertido para o certificado definido em Certificados > Padrão ou para o certificado de desenvolvimento.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>"
      }
    }
  }
}

Uma alternativa ao uso de Caminho e Senha para qualquer nó de certificado é especificar o certificado usando campos de repositório de certificados.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Por exemplo, o certificado Certificados > Padrão pode ser especificado como: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>"
}

Observações do esquema:Schema notes:

  • Os nomes de pontos de extremidade diferenciam maiúsculas de minúsculas.Endpoints names are case-insensitive. Por exemplo, HTTPS e Https são válidos.For example, HTTPS and Https are valid.
  • O parâmetro Url é necessário para cada ponto de extremidade.The Url parameter is required for each endpoint. O formato desse parâmetro é o mesmo que o do parâmetro de configuração de Urls de nível superior, exceto que ele é limitado a um ú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.
  • Esses pontos de extremidade substituem aqueles definidos na configuração de Urls de nível superior em vez de serem adicionados a eles.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Os pontos de extremidade definidos no código por meio de Listen são acumulados com os pontos de extremidade definidos na seção de configuração.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • A seção Certificate é opcional.The Certificate section is optional. Se a seção Certificate não for especificada, os padrões definidos nos cenários anteriores serão usados.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Se não houver nenhum padrão disponível, o servidor gerará uma exceção e não poderá ser iniciado.If no defaults are available, the server throws an exception and fails to start.
  • A seção Certificate é compatível com os certificados de CaminhoSenha e EntidadeRepositório.The Certificate section supports both PathPassword and SubjectStore certificates.
  • Qualquer número de pontos de extremidade pode ser definido dessa forma, contanto que eles não causem conflitos de porta.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}")) retorna um KestrelConfigurationLoader com um método .Endpoint(string name, listenOptions => { }) que pode ser usado para complementar as definições de um ponto de extremidade 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 IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseKestrel((context, serverOptions) =>
            {
                serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                    .Endpoint("HTTPS", listenOptions =>
                    {
                        listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                    });
            });
        });

KestrelServerOptions.ConfigurationLoaderpode ser acessado diretamente para continuar Iterando no carregador existente, como aquele fornecido pelo CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • A seção de configuração de cada ponto de extremidade está disponível nas opções no método Endpoint para que as configurações personalizadas possam ser lidas.The configuration section for each endpoint is a available on the options in the Endpoint method so that custom settings may be read.
  • Várias configurações podem ser carregadas chamando options.Configure(context.Configuration.GetSection("{SECTION}")) novamente com outra seção.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Somente a última configuração será usada, a menos que Load seja chamado explicitamente nas instâncias anteriores.Only the last configuration is used, unless Load is explicitly called on prior instances. O metapacote não chama Load, portanto, sua seção de configuração padrão pode ser substituída.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • O KestrelConfigurationLoader espelha a família de APIs Listen de KestrelServerOptions como sobrecargas de Endpoint, portanto, os pontos de extremidade de código e de configuração podem ser configurados no mesmo local.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Essas sobrecargas não usam nomes e consomem somente as definições padrão da configuração.These overloads don't use names and only consume default settings from configuration.

Alterar os padrões no códigoChange the defaults in code

ConfigureEndpointDefaults e ConfigureHttpsDefaults podem ser usados para alterar as configurações padrão de ListenOptions e HttpsConnectionAdapterOptions, incluindo a substituição do certificado padrão especificado no cenário 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. ConfigureEndpointDefaults e ConfigureHttpsDefaults devem ser chamados antes que qualquer ponto de extremidade seja configurado.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.ConfigureEndpointDefaults(listenOptions =>
                {
                    // Configure endpoint defaults
                });

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

Suporte do Kestrel para SNIKestrel support for SNI

A SNI (Indicação de Nome de Servidor) pode ser usada para hospedar vários domínios no mesmo endereço IP e na mesma porta.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Para que a SNI funcione, o cliente envia o nome do host da sessão segura para o servidor durante o handshake TLS para que o servidor possa fornecer o certificado correto.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. O cliente usa o certificado fornecido para a comunicação criptografada com o servidor durante a sessão segura que segue o handshake TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

O Kestrel permite a SNI por meio do retorno de chamada do ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. O retorno de chamada é invocado uma vez por conexão para permitir que o aplicativo inspecione o nome do host e selecione o certificado apropriado.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

O suporte para SNI requer:SNI support requires:

  • Em execução na estrutura netcoreapp2.1 de destino ou posterior.Running on target framework netcoreapp2.1 or later. No net461 ou posterior, o retorno de chamada é invocado, nullmas o name sempre é.On net461 or later, the callback is invoked but the name is always null. O name também será null se o cliente não fornecer o parâmetro de nome do host no handshake TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Todos os sites executados na mesma instância do Kestrel.All websites run on the same Kestrel instance. Kestrel não é compatível com o compartilhamento de endereço IP e porta entre várias instâncias sem um proxy reverso.Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.
public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            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;
                        };
                    });
                });
            })
            .UseStartup<Startup>();
        });

Associar a um soquete TCPBind to a TCP socket

O método Listen é associado a um soquete TCP, e um lambda de opções permite a configuração do 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>();
        });

O exemplo configura o HTTPS de um ponto de extremidade com ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Use a mesma API para definir outras configurações do Kestrel para pontos de extremidade específicos.Use the same API to configure other Kestrel settings for specific endpoints.

No Windows, é possível criar certificados autoassinados usando o cmdlet New-SelfSignedCertificate do PowerShell.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Para ver um exemplo sem suporte, confira UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

Nas plataformas macOS, Linux e Windows, é possível criar certificados usando o OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Associar a um soquete do UNIXBind to a Unix socket

Escute em um soquete do UNIX com ListenUnixSocket para um melhor desempenho com o Nginx, conforme mostrado neste exemplo: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");
        });
})

Porta 0Port 0

Quando o número da porta 0 for especificado, o Kestrel se associará dinamicamente a uma porta disponível.When the port number 0 is specified, Kestrel dynamically binds to an available port. O exemplo a seguir mostra como determinar a qual porta o Kestrel realmente se associou no tempo de execução: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>");
    });
}

Quando o aplicativo é executado, a saída da janela do console indica a porta dinâmica na qual o aplicativo pode ser acessado: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

LimitaçõesLimitations

Configure pontos de extremidade com as seguintes abordagens:Configure endpoints with the following approaches:

  • UseUrls
  • O argumento de linha de comando --urls--urls command-line argument
  • A chave de configuração do host urlsurls host configuration key
  • A variável de ambiente ASPNETCORE_URLSASPNETCORE_URLS environment variable

Esses métodos são úteis para fazer com que o código funcione com servidores que não sejam o Kestrel.These methods are useful for making code work with servers other than Kestrel. No entanto, esteja ciente das seguintes limitações:However, be aware of the following limitations:

  • O protocolo HTTPS não pode ser usado com essas abordagens, a menos que um certificado padrão seja fornecido na configuração do ponto de extremidade HTTPS (por exemplo, usando a configuração KestrelServerOptions ou um arquivo de configuração, como já foi mostrado neste tópico).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).
  • Quando ambas as abordagens, Listen e UseUrls, são usadas ao mesmo tempo, os pontos de extremidade de Listen substituem os pontos de extremidade de UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configuração de ponto de extremidade do IISIIS endpoint configuration

Ao usar o IIS, as associações de URL para IIS substituem as associações definidas por Listen ou UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Para obter mais informações, confira o tópico Módulo do ASP.NET Core.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

A propriedade Protocols estabelece os protocolos HTTP (HttpProtocols) habilitados em um ponto de extremidade de conexão ou para o servidor.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Atribua um valor à propriedade Protocols com base na enumeração HttpProtocols.Assign a value to the Protocols property from the HttpProtocols enum.

Valor de enumeração HttpProtocolsHttpProtocols enum value Protocolo de conexão permitidoConnection protocol permitted
Http1 HTTP/1.1 apenas.HTTP/1.1 only. Pode ser usado com ou sem TLS.Can be used with or without TLS.
Http2 HTTP/2 apenas.HTTP/2 only. Poderá ser usado sem TLS apenas se o cliente for compatível com um Modo de conhecimento prévio.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 e HTTP/2.HTTP/1.1 and HTTP/2. O HTTP/2 requer que o cliente selecione HTTP/2 no handshake de ALPN (negociação de protocolo de camada de aplicativo) TLS; caso contrário, a conexão será padronizada como 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.

O valor ListenOptions.Protocols padrão para qualquer ponto de HttpProtocols.Http1AndHttp2extremidade é.The default ListenOptions.Protocols value for any endpoint is HttpProtocols.Http1AndHttp2.

Restrições TLS para HTTP/2:TLS restrictions for HTTP/2:

  • Versão TLS 1.2 ou posteriorTLS version 1.2 or later
  • Renegociação desabilitadaRenegotiation disabled
  • Compactação desabilitadaCompression disabled
  • Tamanhos mínimos de troca de chaves efêmera:Minimum ephemeral key exchange sizes:
    • ECDHE (Diffie-Hellman de curva elíptica) [RFC4492] – mínimo de 224 bitsElliptic curve Diffie-Hellman (ECDHE) [RFC4492] – 224 bits minimum
    • DHE (Diffie-Hellman de campo finito) [TLS12] – mínimo de 2048 bitsFinite field Diffie-Hellman (DHE) [TLS12] – 2048 bits minimum
  • Pacote de criptografia não autorizadoCipher suite not blacklisted

Há suporte para TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] com a curva elíptica P-256 [FIPS186] por padrão.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

O exemplo a seguir permite conexões HTTP/1.1 e HTTP/2 na porta 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. As conexões são protegidas pela TLS com um certificado fornecido:Connections are secured by TLS with a supplied certificate:

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

Opcionalmente, use a middleware de conexão para filtrar os Handshakes TLS em uma base por conexão para codificações específicas:Optionally use Connection Middleware to filter TLS handshakes on a per-connection basis for specific ciphers:

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

.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseConnectionHandler<TlsFilterConnectionHandler>();
    });
});
using System;
using System.Buffers;
using System.Security.Authentication;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Connections;
using Microsoft.AspNetCore.Connections.Features;

public class TlsFilterConnectionHandler : ConnectionHandler
{
    public override async Task OnConnectedAsync(ConnectionContext connection)
    {
        var tlsFeature = connection.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.
        //
        // A ITlsHandshakeFeature.CipherAlgorithm of CipherAlgorithmType.Null
        // indicates that no cipher algorithm supported by Kestrel matches the
        // requested algorithm(s).
        if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
        {
            throw new NotSupportedException("Prohibited cipher: " + tlsFeature.CipherAlgorithm);
        }

        while (true)
        {
            var result = await connection.Transport.Input.ReadAsync();
            var buffer = result.Buffer;

            if (!buffer.IsEmpty)
            {
                await connection.Transport.Output.WriteAsync(buffer.ToArray());
            }
            else if (result.IsCompleted)
            {
                break;
            }

            connection.Transport.Input.AdvanceTo(buffer.End);
        }
    }
}

Definir o protocolo com base na configuraçãoSet the protocol from configuration

CreateDefaultBuilder chama serverOptions.Configure(context.Configuration.GetSection("Kestrel")) por padrão ao carregar a configuração do Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

O exemplo appSettings. JSON a seguir estabelece o http/1.1 como o protocolo de conexão padrão para todos os pontos de extremidade:The following appsettings.json example establishes HTTP/1.1 as the default connection protocol for all endpoints:

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

O exemplo appSettings. JSON a seguir estabelece o protocolo de conexão HTTP/1.1 para um ponto de extremidade 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"
      }
    }
  }
}

Os protocolos especificados no código substituem os valores definidos pela configuração.Protocols specified in code override values set by configuration.

Configuração de transporteTransport configuration

Para projetos que exigem o uso de Libuv (UseLibuv):For projects that require the use of Libuv (UseLibuv):

  • Adicione uma dependência para o pacote Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv ao arquivo de projeto do aplicativo: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}" />
    
  • Ligue UseLibuv para o 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>();
                 });
    }
    

Prefixos de URLURL prefixes

Ao usar UseUrls, o argumento de linha de comando --urls, a chave de configuração de host urls ou a variável de ambiente ASPNETCORE_URLS, os prefixos de URL podem estar em um dos formatos a seguir.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.

Somente os prefixos de URL HTTP são válidos.Only HTTP URL prefixes are valid. O Kestrel não é compatível com HTTPS ao configurar associações de URL que usam UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Endereço IPv4 com o número da portaIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 é um caso especial que associa a todos os endereços IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Endereço IPv6 com número da portaIPv6 address with port number

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

    [::] é o equivalente do IPv6 ao IPv4 0.0.0.0.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nome do host com o número da portaHost name with port number

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

    Os nomes de host * e + não são especiais.Host names, *, and +, aren't special. Tudo o que não é reconhecido como um endereço IP ou um localhost válido é associado a todos os IPs IPv6 e IPv4.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Para associar nomes de host diferentes a diferentes aplicativos ASP.NET Core na mesma porta, use o HTTP.sys ou um servidor proxy reverso, como o IIS, o Nginx ou 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.

    Aviso

    A hospedagem em uma configuração de proxy reverso exige a filtragem de host.Hosting in a reverse proxy configuration requires host filtering.

  • Nome do localhost do host com o número da porta ou o IP de loopback com o número da portaHost localhost name with port number or loopback IP with port number

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

    Quando o localhost for especificado, o Kestrel tentará se associar às interfaces de loopback IPv4 e IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Se a porta solicitada está sendo usada por outro serviço em uma das interfaces de loopback, o Kestrel falha ao ser iniciado.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Se uma das interfaces de loopback não estiver disponível por qualquer outro motivo (geralmente porque não há suporte para o IPv6), o Kestrel registra um aviso em log.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtragem de hostHost filtering

Embora o Kestrel permita a configuração com base em prefixos como http://example.com:5000, ele geralmente ignora o nome do host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. O host localhost é um caso especial usado para a associação a endereços de loopback.Host localhost is a special case used for binding to loopback addresses. Todo host que não for um endereço IP explícito será associado a todos os endereços IP públicos.Any host other than an explicit IP address binds to all public IP addresses. Cabeçalhos Host não são validados.Host headers aren't validated.

Como uma solução alternativa, use o Middleware de Filtragem de Host.As a workaround, use Host Filtering Middleware. O middleware de filtragem de host é fornecido pelo pacote Microsoft. AspNetCore. HostFiltering , que é fornecido implicitamente para aplicativos ASP.NET Core.Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is implicitly provided for ASP.NET Core apps. O middleware é adicionado pelo CreateDefaultBuilder, que chama 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>();
}

Middleware de Filtragem de Host está desabilitado por padrão.Host Filtering Middleware is disabled by default. Para habilitar o middleware, defina uma chave AllowedHosts em appSettings. JSON/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. O valor dessa chave é uma lista separada por ponto e vírgula de nomes de host sem números de porta:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Observação

Middleware de Cabeçalhos Encaminhados também tem uma opção AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. Middleware de Cabeçalhos Encaminhados e Middleware de filtragem de Host têm funcionalidades semelhantes para cenários diferentes.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. A definição de AllowedHosts com Middleware de Cabeçalhos Encaminhados é apropriada quando o cabeçalho Host não é preservado ao encaminhar solicitações com um servidor proxy reverso ou um balanceador 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. A definição de AllowedHosts com Middleware de Filtragem de Host é apropriada quando o Kestrel é usado como um servidor de borda voltado ao público ou quando o cabeçalho Host é encaminhado diretamente.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 obter mais informações sobre o Middleware de Cabeçalhos Encaminhados, confira Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.For more information on Forwarded Headers Middleware, see Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.

O Kestrel é um servidor Web multiplataforma para o ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. O Kestrel é o servidor Web que está incluído por padrão em modelos de projeto do ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

O Kestrel dá suporte aos seguintes cenários:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Atualização do Opaque usado para habilitar o WebSocketsOpaque upgrade used to enable WebSockets
  • Soquetes do UNIX para alto desempenho protegidos pelo NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (exceto em macOS†)HTTP/2 (except on macOS†)

†O HTTP/2 será compatível com macOS em uma versão futura.†HTTP/2 will be supported on macOS in a future release.

Há suporte para o Kestrel em todas as plataformas e versões compatíveis com o .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Compatibilidade com HTTP/2HTTP/2 support

O HTTP/2 estará disponível para aplicativos ASP.NET Core se os seguintes requisitos básicos forem atendidos:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Sistema operacional†Operating system†
    • Windows Server 2016/Windows 10 ou posterior‡Windows Server 2016/Windows 10 or later‡
    • Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Estrutura de destino: .NET Core 2.2 ou posteriorTarget framework: .NET Core 2.2 or later
  • Conexão ALPN (Negociação de protocolo de camada de aplicativo)Application-Layer Protocol Negotiation (ALPN) connection
  • Conexão TLS 1.2 ou posteriorTLS 1.2 or later connection

†O HTTP/2 será compatível com macOS em uma versão futura.†HTTP/2 will be supported on macOS in a future release. ‡O Kestrel tem suporte limitado para HTTP/2 no Windows Server 2012 R2 e Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. O suporte é limitado porque a lista de conjuntos de codificação TLS disponível nesses sistemas operacionais é limitada.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Um certificado gerado usando um ECDSA (Algoritmo de Assinatura Digital Curva Elíptica) pode ser necessário para proteger conexões TLS.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 está desabilitado por padrão.HTTP/2 is disabled by default. Para obter mais informações sobre a configuração, consulte as seções Opções do Kestrel e ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Quando usar o Kestrel com um proxy reversoWhen to use Kestrel with a reverse proxy

O Kestrel pode ser usado sozinho ou com um servidor proxy reverso, como o IIS (Serviços de Informações da Internet), o Nginx ou o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Um servidor proxy reverso recebe solicitações HTTP da rede e encaminha-as para o Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel usado como um servidor Web de borda (voltado para a Internet):Kestrel used as an edge (Internet-facing) web server:

O Kestrel se comunica diretamente com a Internet, sem um servidor proxy reverso

Kestrel usado em uma configuração de proxy reverso:Kestrel used in a reverse proxy configuration:

O Kestrel se comunica indiretamente com a Internet através de um servidor proxy reverso, tal como o IIS, o Nginx ou o Apache

A configuração, com ou sem um servidor proxy reverso, é uma configuração de hospedagem com suporte.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

O Kestrel usado como um servidor de borda sem um servidor proxy reverso não dá suporte ao compartilhamento do mesmo IP e da mesma porta entre vários processos.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Quando o Kestrel é configurado para escutar uma porta, ele manipula todo o tráfego dessa porta, independentemente dos cabeçalhos Host das solicitações.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Um proxy reverso que pode compartilhar portas tem a capacidade de encaminhar solicitações ao Kestrel em um IP e em uma porta exclusivos.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Mesmo se um servidor proxy reverso não for necessário, o uso de um servidor proxy reverso poderá ser uma boa opção.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Um proxy reverso:A reverse proxy:

  • Pode limitar a área da superfície pública exposta dos aplicativos que ele hospeda.Can limit the exposed public surface area of the apps that it hosts.
  • Fornece uma camada adicional de configuração e proteção.Provide an additional layer of configuration and defense.
  • Pode ser integrado melhor à infraestrutura existente.Might integrate better with existing infrastructure.
  • Simplifica o balanceamento de carga e a configuração de comunicação segura (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Somente o servidor proxy reverso requer um certificado X. 509 e esse servidor pode se comunicar com os servidores do aplicativo na rede interna usando HTTP simples.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.

Aviso

A hospedagem em uma configuração de proxy reverso exige a filtragem de host.Hosting in a reverse proxy configuration requires host filtering.

Como usar o Kestrel em aplicativos ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

O pacote Microsoft. AspNetCore. Server. Kestrel está incluído no metapacote Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

Os modelos de projeto do ASP.NET Core usam o Kestrel por padrão.ASP.NET Core project templates use Kestrel by default. Em Program.cs, o código de modelo chama CreateDefaultBuilder, que chama UseKestrel em 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 fornecer configuração adicional após chamar 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
        });

Se o aplicativo não chamar CreateDefaultBuilder para configurar o host, chame UseKestrel antes de chamar 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();
}

Opções do KestrelKestrel options

O servidor Web do Kestrel tem opções de configuração de restrição especialmente úteis em implantações para a Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Defina restrições sobre a propriedade Limits da classe KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. A propriedade Limits contém uma instância da classe KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

Os exemplos a seguir usam o namespace Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Tempo limite de keep-aliveKeep-alive timeout

KeepAliveTimeout

Obtém ou define o tempo limite de keep-alive.Gets or sets the keep-alive timeout. O padrão é de dois 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);
});

Número máximo de conexões de clienteMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

O número máximo de conexões TCP abertas simultâneas pode ser definido para o aplicativo inteiro com o código a seguir: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);
});

Há um limite separado para conexões que foram atualizadas do HTTP ou HTTPS para outro protocolo (por exemplo, em uma solicitação do 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). Depois que uma conexão é atualizada, ela não é contada em relação ao limite 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);
});

O número máximo de conexões é ilimitado (nulo) por padrão.The maximum number of connections is unlimited (null) by default.

Tamanho máximo do corpo da solicitaçãoMaximum request body size

MaxRequestBodySize

O tamanho máximo do corpo da solicitação padrão é de 30.000.000 bytes, que equivale aproximadamente a 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

A abordagem recomendada para substituir o limite em um aplicativo ASP.NET Core MVC é usar o atributo RequestSizeLimitAttribute em um método de ação: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()

Aqui está um exemplo que mostra como configurar a restrição para o aplicativo em cada solicitação: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);
});

Substitua a configuração em uma solicitação específica no 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));
    }

Uma exceção será gerada se o aplicativo configurar o limite em uma solicitação depois que o aplicativo for iniciado para ler a solicitação.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Há uma propriedade IsReadOnly que indica se a propriedade MaxRequestBodySize está no estado somente leitura, o que significa que é tarde demais para configurar o limite.There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

Quando um aplicativo é executado fora do processo por trás do Módulo do ASP.NET Core, o limite de tamanho do corpo da solicitação do Kestrel fica desabilitado, pois o IIS já define o limite.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.

Taxa de dados mínima do corpo da solicitaçãoMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

O Kestrel verifica a cada segundo se os dados estão sendo recebidos na taxa especificada em bytes/segundo.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Se a taxa cair abaixo do mínimo, a conexão atingirá o tempo limite. O período de cortesia é o tempo que o Kestrel fornece ao cliente para aumentar sua taxa de envio até o mínimo; a taxa não é verificada durante esse período.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. O período de cortesia ajuda a evitar a remoção de conexões que inicialmente enviam dados em uma taxa baixa devido ao início lento do TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

A taxa mínima de padrão é de 240 bytes/segundo com um período de cortesia de 5 segundos.The default minimum rate is 240 bytes/second with a 5 second grace period.

Uma taxa mínima também se aplica à resposta.A minimum rate also applies to the response. O código para definir o limite de solicitação e o limite de resposta é o mesmo, exceto por ter RequestBody ou Response nos nomes da propriedade e da interface.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

Este é um exemplo que mostra como configurar as taxas mínima de dados em 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);
});

Substitua os limites de taxa mínimo por solicitação no 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));
    }

Nenhum desses recursos de taxa referenciados no exemplo anterior está presente no HttpContext.Features para solicitações HTTP/2, porque a modificação dos limites de taxa em cada solicitação não é compatível com HTTP/2 devido ao suporte de multiplexação de solicitação do protocolo.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. Os limites de taxa de todo o servidor configurados por meio de KestrelServerOptions.Limits ainda se aplicam a conexões HTTP/1.x e HTTP/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Tempo limite dos cabeçalhos de solicitaçãoRequest headers timeout

RequestHeadersTimeout

Obtém ou define a quantidade máxima de tempo que o servidor gasta recebendo cabeçalhos de solicitação.Gets or sets the maximum amount of time the server spends receiving request headers. O padrão é 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);
});

Fluxos máximos por conexãoMaximum streams per connection

O Http2.MaxStreamsPerConnection limita o número de fluxos de solicitações simultâneas por conexão HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Os fluxos em excesso são recusados.Excess streams are refused.

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

O valor padrão é 100.The default value is 100.

Tamanho da tabela de cabeçalhoHeader table size

O decodificador HPACK descompacta os cabeçalhos HTTP para conexões HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. O Http2.HeaderTableSize limita o tamanho da tabela de compactação de cabeçalho usada pelo decodificador HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. O valor é fornecido em octetos e deve ser maior do que zero (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;
        });

O valor padrão é 4096.The default value is 4096.

Tamanho máximo do quadroMaximum frame size

O Http2.MaxFrameSize indica o tamanho máximo do payload do quadro da conexão HTTP/2 a ser recebido.Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. O valor é fornecido em octetos e deve estar entre 2^14 (16.384) e 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;
        });

O valor padrão é 2^14 (16.384).The default value is 2^14 (16,384).

Tamanho máximo do cabeçalho de solicitaçãoMaximum request header size

Http2.MaxRequestHeaderFieldSize indica o tamanho máximo permitido em octetos de valores de cabeçalho de solicitação.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Esse limite se aplica ao nome e ao valor em suas representações compactadas e descompactadas.This limit applies to both name and value together in their compressed and uncompressed representations. O valor deve ser maior que zero (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;
        });

O valor padrão é 8.192.The default value is 8,192.

Tamanho inicial da janela de conexãoInitial connection window size

Http2.InitialConnectionWindowSize indica os dados máximos do corpo da solicitação em bytes, que o servidor armazena em buffer ao mesmo tempo, agregados em todas as solicitações (fluxos) por conexão.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. As solicitações também são limitadas por Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. O valor deve ser maior ou igual a 65.535 e 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;
        });

O valor padrão é 128 KB (131.072).The default value is 128 KB (131,072).

Tamanho inicial da janela de fluxoInitial stream window size

Http2.InitialStreamWindowSize indica o máximo de dados do corpo da solicitação, em bytes, que o servidor armazena em buffer ao mesmo tempo, por solicitação (fluxo).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). As solicitações também são limitadas por Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. O valor deve ser maior ou igual a 65.535 e 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;
        });

O valor padrão é 96 KB (98.304).The default value is 96 KB (98,304).

E/S síncronaSynchronous IO

AllowSynchronousIO controla se a E/S síncrona é permitida para a solicitação e resposta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. O valor padrão é true.The default value is true.

Aviso

Um grande número de operações de E/S síncronas de bloqueio pode levar à privação de pool de thread, o que faz com que o aplicativo não responda.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Habilite AllowSynchronousIO somente ao usar uma biblioteca em que não há suporte para E/S assíncrona.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

O exemplo a seguir ativa a E/S síncrona:The following example enables synchronous IO:

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

Para obter informações sobre outras opções e limites do Kestrel, confira:For information about other Kestrel options and limits, see:

Configuração do ponto de extremidadeEndpoint configuration

Por padrão, o ASP.NET Core associa a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (quando um certificado de desenvolvimento local está presente)https://localhost:5001 (when a local development certificate is present)

Especificar URLs usando:Specify URLs using the:

  • A variável de ambiente ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • O argumento de linha de comando --urls.--urls command-line argument.
  • A chave de configuração do host urls.urls host configuration key.
  • O método de extensão UseUrls.UseUrls extension method.

O valor fornecido usando essas abordagens pode ser um ou mais pontos de extremidade HTTP e HTTPS (HTTPS se houver um certificado padrão).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configure o valor como uma lista separada por ponto e vírgula (por exemplo, "Urls": "http://localhost:8000; http://localhost:8001" ).Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Veja mais informações sobre essas abordagens em URLs de servidor e Substituir configuração.For more information on these approaches, see Server URLs and Override configuration.

Um certificado de desenvolvimento é criado:A development certificate is created:

Alguns navegadores exigem a concessão de permissão explícita para confiar no certificado de desenvolvimento local.Some browsers require granting explicit permission to trust the local development certificate.

Os modelos de projeto configuram aplicativos para execução em HTTPS por padrão e incluem o redirecionamento de HTTPS e o suporte a HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Chame os métodos Listen ou ListenUnixSocket em KestrelServerOptions para configurar prefixos de URL e portas para o Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, o argumento de linha de comando --urls, a chave de configuração de host urls e a variável de ambiente ASPNETCORE_URLS também funcionam mas têm limitações que serão indicadas mais adiante nesta seção (um certificado padrão precisa estar disponível para a configuração do ponto de extremidade 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).

KestrelServerOptionsconfiguraçãoKestrelServerOptions configuration:

ConfigureEndpointDefaults (ação<escutaroptions >)ConfigureEndpointDefaults(Action<ListenOptions>)

Especifica uma Action de configuração a ser executada para cada ponto de extremidade especificado.Specifies a configuration Action to run for each specified endpoint. Chamar ConfigureEndpointDefaults várias vezes substitui as Actions pela ú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
            });
        });

ConfigureHttpsDefaults (ação<HttpsConnectionAdapterOptions >)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Especifica uma Action de configuração a ser executada para cada ponto de extremidade HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Chamar ConfigureHttpsDefaults várias vezes substitui as Actions pela ú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;
            });
        });

Configure(IConfiguration)Configure(IConfiguration)

Cria um carregador de configuração para configurar o Kestrel que usa uma IConfiguration como entrada.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. A configuração precisa estar no escopo da seção de configuração do Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configure o Kestrel para usar HTTPS.Configure Kestrel to use HTTPS.

Extensões ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps – Configure o Kestrel para usar HTTPS com o certificado padrão.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Gera uma exceção quando não há nenhum certificado padrão 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 é o caminho e o nome do arquivo de um arquivo de certificado, relativo ao diretório que contém os arquivos de conteúdo do aplicativo.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password é a senha necessária para acessar os dados do certificado X.509 .password is the password required to access the X.509 certificate data.
  • configureOptions é uma Action para configurar as HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Retorna o ListenOptions.Returns the ListenOptions.
  • storeName é o repositório de certificados do qual o certificado deve ser carregado.storeName is the certificate store from which to load the certificate.
  • subject é o nome da entidade do certificado.subject is the subject name for the certificate.
  • allowInvalid indica se certificados inválidos devem ser considerados, como os certificados autoassinados.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location é o local do repositório do qual o certificado deve ser carregado.location is the store location to load the certificate from.
  • serverCertificate é o certificado X.509.serverCertificate is the X.509 certificate.

Em produção, HTTPS precisa ser configurado explicitamente.In production, HTTPS must be explicitly configured. No mínimo, um certificado padrão precisa ser fornecido.At a minimum, a default certificate must be provided.

Configurações com suporte descritas a seguir:Supported configurations described next:

  • Nenhuma configuraçãoNo configuration
  • Substituir o certificado padrão da configuraçãoReplace the default certificate from configuration
  • Alterar os padrões no códigoChange the defaults in code

Nenhuma configuraçãoNo configuration

O Kestrel escuta em http://localhost:5000 e em https://localhost:5001 (se houver um certificado padrão disponível).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Substituir o certificado padrão da configuraçãoReplace the default certificate from configuration

CreateDefaultBuilder chama Configure(context.Configuration.GetSection("Kestrel")) por padrão ao carregar a configuração do Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Há um esquema de definições de configurações de aplicativo HTTPS padrão disponível para o Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Configure vários pontos de extremidade, incluindo URLs e os certificados a serem usados, por meio de um arquivo no disco ou de um repositório de certificados.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

No exemplo de appsettings.json a seguir:In the following appsettings.json example:

  • Defina AllowInvalid como true para permitir o uso de certificados inválidos (por exemplo, os certificados autoassinados).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Todo ponto de extremidade HTTPS que não especificar um certificado (HttpsDefaultCert no exemplo a seguir) será revertido para o certificado definido em Certificados > Padrão ou para o certificado de desenvolvimento.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>"
      }
    }
  }
}

Uma alternativa ao uso de Caminho e Senha para qualquer nó de certificado é especificar o certificado usando campos de repositório de certificados.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Por exemplo, o certificado Certificados > Padrão pode ser especificado como: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>"
}

Observações do esquema:Schema notes:

  • Os nomes de pontos de extremidade diferenciam maiúsculas de minúsculas.Endpoints names are case-insensitive. Por exemplo, HTTPS e Https são válidos.For example, HTTPS and Https are valid.
  • O parâmetro Url é necessário para cada ponto de extremidade.The Url parameter is required for each endpoint. O formato desse parâmetro é o mesmo que o do parâmetro de configuração de Urls de nível superior, exceto que ele é limitado a um ú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.
  • Esses pontos de extremidade substituem aqueles definidos na configuração de Urls de nível superior em vez de serem adicionados a eles.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Os pontos de extremidade definidos no código por meio de Listen são acumulados com os pontos de extremidade definidos na seção de configuração.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • A seção Certificate é opcional.The Certificate section is optional. Se a seção Certificate não for especificada, os padrões definidos nos cenários anteriores serão usados.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Se não houver nenhum padrão disponível, o servidor gerará uma exceção e não poderá ser iniciado.If no defaults are available, the server throws an exception and fails to start.
  • A seção Certificate é compatível com os certificados de CaminhoSenha e EntidadeRepositório.The Certificate section supports both PathPassword and SubjectStore certificates.
  • Qualquer número de pontos de extremidade pode ser definido dessa forma, contanto que eles não causem conflitos de porta.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}")) retorna um KestrelConfigurationLoader com um método .Endpoint(string name, listenOptions => { }) que pode ser usado para complementar as definições de um ponto de extremidade 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;
                });
        });

KestrelServerOptions.ConfigurationLoaderpode ser acessado diretamente para continuar Iterando no carregador existente, como aquele fornecido pelo CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • A seção de configuração de cada ponto de extremidade está disponível nas opções no método Endpoint para que as configurações personalizadas possam ser lidas.The configuration section for each endpoint is a available on the options in the Endpoint method so that custom settings may be read.
  • Várias configurações podem ser carregadas chamando options.Configure(context.Configuration.GetSection("{SECTION}")) novamente com outra seção.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Somente a última configuração será usada, a menos que Load seja chamado explicitamente nas instâncias anteriores.Only the last configuration is used, unless Load is explicitly called on prior instances. O metapacote não chama Load, portanto, sua seção de configuração padrão pode ser substituída.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • O KestrelConfigurationLoader espelha a família de APIs Listen de KestrelServerOptions como sobrecargas de Endpoint, portanto, os pontos de extremidade de código e de configuração podem ser configurados no mesmo local.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Essas sobrecargas não usam nomes e consomem somente as definições padrão da configuração.These overloads don't use names and only consume default settings from configuration.

Alterar os padrões no códigoChange the defaults in code

ConfigureEndpointDefaults e ConfigureHttpsDefaults podem ser usados para alterar as configurações padrão de ListenOptions e HttpsConnectionAdapterOptions, incluindo a substituição do certificado padrão especificado no cenário 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. ConfigureEndpointDefaults e ConfigureHttpsDefaults devem ser chamados antes que qualquer ponto de extremidade seja configurado.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;
            });
        });

Suporte do Kestrel para SNIKestrel support for SNI

A SNI (Indicação de Nome de Servidor) pode ser usada para hospedar vários domínios no mesmo endereço IP e na mesma porta.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Para que a SNI funcione, o cliente envia o nome do host da sessão segura para o servidor durante o handshake TLS para que o servidor possa fornecer o certificado correto.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. O cliente usa o certificado fornecido para a comunicação criptografada com o servidor durante a sessão segura que segue o handshake TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

O Kestrel permite a SNI por meio do retorno de chamada do ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. O retorno de chamada é invocado uma vez por conexão para permitir que o aplicativo inspecione o nome do host e selecione o certificado apropriado.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

O suporte para SNI requer:SNI support requires:

  • Em execução na estrutura netcoreapp2.1 de destino ou posterior.Running on target framework netcoreapp2.1 or later. No net461 ou posterior, o retorno de chamada é invocado, nullmas o name sempre é.On net461 or later, the callback is invoked but the name is always null. O name também será null se o cliente não fornecer o parâmetro de nome do host no handshake TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Todos os sites executados na mesma instância do Kestrel.All websites run on the same Kestrel instance. Kestrel não é compatível com o compartilhamento de endereço IP e porta entre várias instâncias sem um proxy reverso.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;
                    };
                });
            });
        });

Associar a um soquete TCPBind to a TCP socket

O método Listen é associado a um soquete TCP, e um lambda de opções permite a configuração do 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");
            });
        });

O exemplo configura o HTTPS de um ponto de extremidade com ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Use a mesma API para definir outras configurações do Kestrel para pontos de extremidade específicos.Use the same API to configure other Kestrel settings for specific endpoints.

No Windows, é possível criar certificados autoassinados usando o cmdlet New-SelfSignedCertificate do PowerShell.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Para ver um exemplo sem suporte, confira UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

Nas plataformas macOS, Linux e Windows, é possível criar certificados usando o OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Associar a um soquete do UNIXBind to a Unix socket

Escute em um soquete do UNIX com ListenUnixSocket para um melhor desempenho com o Nginx, conforme mostrado neste exemplo: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");
    });
});

Porta 0Port 0

Quando o número da porta 0 for especificado, o Kestrel se associará dinamicamente a uma porta disponível.When the port number 0 is specified, Kestrel dynamically binds to an available port. O exemplo a seguir mostra como determinar a qual porta o Kestrel realmente se associou no tempo de execução: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>");
    });
}

Quando o aplicativo é executado, a saída da janela do console indica a porta dinâmica na qual o aplicativo pode ser acessado: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

LimitaçõesLimitations

Configure pontos de extremidade com as seguintes abordagens:Configure endpoints with the following approaches:

  • UseUrls
  • O argumento de linha de comando --urls--urls command-line argument
  • A chave de configuração do host urlsurls host configuration key
  • A variável de ambiente ASPNETCORE_URLSASPNETCORE_URLS environment variable

Esses métodos são úteis para fazer com que o código funcione com servidores que não sejam o Kestrel.These methods are useful for making code work with servers other than Kestrel. No entanto, esteja ciente das seguintes limitações:However, be aware of the following limitations:

  • O protocolo HTTPS não pode ser usado com essas abordagens, a menos que um certificado padrão seja fornecido na configuração do ponto de extremidade HTTPS (por exemplo, usando a configuração KestrelServerOptions ou um arquivo de configuração, como já foi mostrado neste tópico).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).
  • Quando ambas as abordagens, Listen e UseUrls, são usadas ao mesmo tempo, os pontos de extremidade de Listen substituem os pontos de extremidade de UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configuração de ponto de extremidade do IISIIS endpoint configuration

Ao usar o IIS, as associações de URL para IIS substituem as associações definidas por Listen ou UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Para obter mais informações, confira o tópico Módulo do ASP.NET Core.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

A propriedade Protocols estabelece os protocolos HTTP (HttpProtocols) habilitados em um ponto de extremidade de conexão ou para o servidor.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Atribua um valor à propriedade Protocols com base na enumeração HttpProtocols.Assign a value to the Protocols property from the HttpProtocols enum.

Valor de enumeração HttpProtocolsHttpProtocols enum value Protocolo de conexão permitidoConnection protocol permitted
Http1 HTTP/1.1 apenas.HTTP/1.1 only. Pode ser usado com ou sem TLS.Can be used with or without TLS.
Http2 HTTP/2 apenas.HTTP/2 only. Poderá ser usado sem TLS apenas se o cliente for compatível com um Modo de conhecimento prévio.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 e HTTP/2.HTTP/1.1 and HTTP/2. O HTTP/2 requer uma conexão TLS e ALPN (negociação de protocolo de camada de aplicativo) ; caso contrário, a conexão será padronizada como HTTP/1.1.HTTP/2 requires a TLS and Application-Layer Protocol Negotiation (ALPN) connection; otherwise, the connection defaults to HTTP/1.1.

O protocolo padrão é HTTP/1.1.The default protocol is HTTP/1.1.

Restrições TLS para HTTP/2:TLS restrictions for HTTP/2:

  • Versão TLS 1.2 ou posteriorTLS version 1.2 or later
  • Renegociação desabilitadaRenegotiation disabled
  • Compactação desabilitadaCompression disabled
  • Tamanhos mínimos de troca de chaves efêmera:Minimum ephemeral key exchange sizes:
    • ECDHE (Diffie-Hellman de curva elíptica) [RFC4492] – mínimo de 224 bitsElliptic curve Diffie-Hellman (ECDHE) [RFC4492] – 224 bits minimum
    • DHE (Diffie-Hellman de campo finito) [TLS12] – mínimo de 2048 bitsFinite field Diffie-Hellman (DHE) [TLS12] – 2048 bits minimum
  • Pacote de criptografia não autorizadoCipher suite not blacklisted

Há suporte para TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] com a curva elíptica P-256 [FIPS186] por padrão.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

O exemplo a seguir permite conexões HTTP/1.1 e HTTP/2 na porta 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. As conexões são protegidas pela TLS com um certificado fornecido: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");
    });
});

Crie opcionalmente uma implementação do IConnectionAdapter para filtrar os handshakes TLS por conexão para codificações específicas: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.
        //
        // A ITlsHandshakeFeature.CipherAlgorithm of CipherAlgorithmType.Null
        // indicates that no cipher algorithm supported by Kestrel matches the
        // requested algorithm(s).
        if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
        {
            throw new NotSupportedException("Prohibited cipher: " + tlsFeature.CipherAlgorithm);
        }

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

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

        public Stream ConnectionStream { get; }

        public void Dispose()
        {
        }
    }
}

Definir o protocolo com base na configuraçãoSet the protocol from configuration

CreateDefaultBuilder chama serverOptions.Configure(context.Configuration.GetSection("Kestrel")) por padrão ao carregar a configuração do Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

No exemplo appsettings.json a seguir, um protocolo de conexão padrão (HTTP/1.1 e HTTP/2) é estabelecido para todos os pontos de extremidade do 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"
    }
  }
}

O arquivo de configuração de exemplo a seguir estabelece um protocolo de conexão para um ponto de extremidade específico:The following configuration file example establishes a connection protocol for a specific endpoint:

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

Os protocolos especificados no código substituem os valores definidos pela configuração.Protocols specified in code override values set by configuration.

Configuração de transporteTransport configuration

Com a liberação do ASP.NET Core 2.1, o transporte padrão do Kestrel deixa de ser baseado no Libuv, baseando-se agora em soquetes gerenciados.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. Essa é uma alteração da falha para aplicativos ASP.NET Core 2.0 que atualizam para o 2.1 que chamam UseLibuv e dependem de um dos seguintes pacotes: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 projetos que exigem o uso de Libuv:For projects that require the use of Libuv:

  • Adicione uma dependência para o pacote Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv ao arquivo de projeto do aplicativo: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}" />
    
  • Chame 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>();
    }
    

Prefixos de URLURL prefixes

Ao usar UseUrls, o argumento de linha de comando --urls, a chave de configuração de host urls ou a variável de ambiente ASPNETCORE_URLS, os prefixos de URL podem estar em um dos formatos a seguir.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.

Somente os prefixos de URL HTTP são válidos.Only HTTP URL prefixes are valid. O Kestrel não é compatível com HTTPS ao configurar associações de URL que usam UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Endereço IPv4 com o número da portaIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 é um caso especial que associa a todos os endereços IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Endereço IPv6 com número da portaIPv6 address with port number

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

    [::] é o equivalente do IPv6 ao IPv4 0.0.0.0.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nome do host com o número da portaHost name with port number

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

    Os nomes de host * e + não são especiais.Host names, *, and +, aren't special. Tudo o que não é reconhecido como um endereço IP ou um localhost válido é associado a todos os IPs IPv6 e IPv4.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Para associar nomes de host diferentes a diferentes aplicativos ASP.NET Core na mesma porta, use o HTTP.sys ou um servidor proxy reverso, como o IIS, o Nginx ou 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.

    Aviso

    A hospedagem em uma configuração de proxy reverso exige a filtragem de host.Hosting in a reverse proxy configuration requires host filtering.

  • Nome do localhost do host com o número da porta ou o IP de loopback com o número da portaHost localhost name with port number or loopback IP with port number

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

    Quando o localhost for especificado, o Kestrel tentará se associar às interfaces de loopback IPv4 e IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Se a porta solicitada está sendo usada por outro serviço em uma das interfaces de loopback, o Kestrel falha ao ser iniciado.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Se uma das interfaces de loopback não estiver disponível por qualquer outro motivo (geralmente porque não há suporte para o IPv6), o Kestrel registra um aviso em log.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtragem de hostHost filtering

Embora o Kestrel permita a configuração com base em prefixos como http://example.com:5000, ele geralmente ignora o nome do host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. O host localhost é um caso especial usado para a associação a endereços de loopback.Host localhost is a special case used for binding to loopback addresses. Todo host que não for um endereço IP explícito será associado a todos os endereços IP públicos.Any host other than an explicit IP address binds to all public IP addresses. Cabeçalhos Host não são validados.Host headers aren't validated.

Como uma solução alternativa, use o Middleware de Filtragem de Host.As a workaround, use Host Filtering Middleware. O middleware de filtragem de host é fornecido pelo pacote Microsoft. AspNetCore. HostFiltering , que está incluído no metapacote Microsoft. AspNetCore. App (ASP.NET Core 2,1 ou 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). O middleware é adicionado pelo CreateDefaultBuilder, que chama 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>();
}

Middleware de Filtragem de Host está desabilitado por padrão.Host Filtering Middleware is disabled by default. Para habilitar o middleware, defina uma chave AllowedHosts em appSettings. JSON/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. O valor dessa chave é uma lista separada por ponto e vírgula de nomes de host sem números de porta:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Observação

Middleware de Cabeçalhos Encaminhados também tem uma opção AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. Middleware de Cabeçalhos Encaminhados e Middleware de filtragem de Host têm funcionalidades semelhantes para cenários diferentes.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. A definição de AllowedHosts com Middleware de Cabeçalhos Encaminhados é apropriada quando o cabeçalho Host não é preservado ao encaminhar solicitações com um servidor proxy reverso ou um balanceador 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. A definição de AllowedHosts com Middleware de Filtragem de Host é apropriada quando o Kestrel é usado como um servidor de borda voltado ao público ou quando o cabeçalho Host é encaminhado diretamente.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 obter mais informações sobre o Middleware de Cabeçalhos Encaminhados, confira Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.For more information on Forwarded Headers Middleware, see Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.

O Kestrel é um servidor Web multiplataforma para o ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. O Kestrel é o servidor Web que está incluído por padrão em modelos de projeto do ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

O Kestrel dá suporte aos seguintes cenários:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Atualização do Opaque usado para habilitar o WebSocketsOpaque upgrade used to enable WebSockets
  • Soquetes do UNIX para alto desempenho protegidos pelo NginxUnix sockets for high performance behind Nginx

Há suporte para o Kestrel em todas as plataformas e versões compatíveis com o .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Quando usar o Kestrel com um proxy reversoWhen to use Kestrel with a reverse proxy

O Kestrel pode ser usado sozinho ou com um servidor proxy reverso, como o IIS (Serviços de Informações da Internet), o Nginx ou o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Um servidor proxy reverso recebe solicitações HTTP da rede e encaminha-as para o Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel usado como um servidor Web de borda (voltado para a Internet):Kestrel used as an edge (Internet-facing) web server:

O Kestrel se comunica diretamente com a Internet, sem um servidor proxy reverso

Kestrel usado em uma configuração de proxy reverso:Kestrel used in a reverse proxy configuration:

O Kestrel se comunica indiretamente com a Internet através de um servidor proxy reverso, tal como o IIS, o Nginx ou o Apache

A configuração, com ou sem um servidor proxy reverso, é uma configuração de hospedagem com suporte.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

O Kestrel usado como um servidor de borda sem um servidor proxy reverso não dá suporte ao compartilhamento do mesmo IP e da mesma porta entre vários processos.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Quando o Kestrel é configurado para escutar uma porta, ele manipula todo o tráfego dessa porta, independentemente dos cabeçalhos Host das solicitações.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Um proxy reverso que pode compartilhar portas tem a capacidade de encaminhar solicitações ao Kestrel em um IP e em uma porta exclusivos.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Mesmo se um servidor proxy reverso não for necessário, o uso de um servidor proxy reverso poderá ser uma boa opção.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Um proxy reverso:A reverse proxy:

  • Pode limitar a área da superfície pública exposta dos aplicativos que ele hospeda.Can limit the exposed public surface area of the apps that it hosts.
  • Fornece uma camada adicional de configuração e proteção.Provide an additional layer of configuration and defense.
  • Pode ser integrado melhor à infraestrutura existente.Might integrate better with existing infrastructure.
  • Simplifica o balanceamento de carga e a configuração de comunicação segura (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Somente o servidor proxy reverso requer um certificado X. 509 e esse servidor pode se comunicar com os servidores do aplicativo na rede interna usando HTTP simples.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.

Aviso

A hospedagem em uma configuração de proxy reverso exige a filtragem de host.Hosting in a reverse proxy configuration requires host filtering.

Como usar o Kestrel em aplicativos ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

O pacote Microsoft. AspNetCore. Server. Kestrel está incluído no metapacote Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

Os modelos de projeto do ASP.NET Core usam o Kestrel por padrão.ASP.NET Core project templates use Kestrel by default. Em Program.cs, o código de modelo chama CreateDefaultBuilder, que chama UseKestrel em segundo plano.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

Para fornecer configuração adicional após chamar CreateDefaultBuilder, chame 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
        });

Opções do KestrelKestrel options

O servidor Web do Kestrel tem opções de configuração de restrição especialmente úteis em implantações para a Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Defina restrições sobre a propriedade Limits da classe KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. A propriedade Limits contém uma instância da classe KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

Os exemplos a seguir usam o namespace Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Tempo limite de keep-aliveKeep-alive timeout

KeepAliveTimeout

Obtém ou define o tempo limite de keep-alive.Gets or sets the keep-alive timeout. O padrão é de dois minutos.Defaults to 2 minutes.

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

Número máximo de conexões de clienteMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

O número máximo de conexões TCP abertas simultâneas pode ser definido para o aplicativo inteiro com o código a seguir: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;
        });

Há um limite separado para conexões que foram atualizadas do HTTP ou HTTPS para outro protocolo (por exemplo, em uma solicitação do 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). Depois que uma conexão é atualizada, ela não é contada em relação ao limite 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;
        });

O número máximo de conexões é ilimitado (nulo) por padrão.The maximum number of connections is unlimited (null) by default.

Tamanho máximo do corpo da solicitaçãoMaximum request body size

MaxRequestBodySize

O tamanho máximo do corpo da solicitação padrão é de 30.000.000 bytes, que equivale aproximadamente a 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

A abordagem recomendada para substituir o limite em um aplicativo ASP.NET Core MVC é usar o atributo RequestSizeLimitAttribute em um método de ação: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()

Aqui está um exemplo que mostra como configurar a restrição para o aplicativo em cada solicitação: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;
        });

Substitua a configuração em uma solicitação específica no 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));
    }

Uma exceção será gerada se o aplicativo configurar o limite em uma solicitação depois que o aplicativo for iniciado para ler a solicitação.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Há uma propriedade IsReadOnly que indica se a propriedade MaxRequestBodySize está no estado somente leitura, o que significa que é tarde demais para configurar o limite.There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

Quando um aplicativo é executado fora do processo por trás do Módulo do ASP.NET Core, o limite de tamanho do corpo da solicitação do Kestrel fica desabilitado, pois o IIS já define o limite.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.

Taxa de dados mínima do corpo da solicitaçãoMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

O Kestrel verifica a cada segundo se os dados estão sendo recebidos na taxa especificada em bytes/segundo.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Se a taxa cair abaixo do mínimo, a conexão atingirá o tempo limite. O período de cortesia é o tempo que o Kestrel fornece ao cliente para aumentar sua taxa de envio até o mínimo; a taxa não é verificada durante esse período.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. O período de cortesia ajuda a evitar a remoção de conexões que inicialmente enviam dados em uma taxa baixa devido ao início lento do TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

A taxa mínima de padrão é de 240 bytes/segundo com um período de cortesia de 5 segundos.The default minimum rate is 240 bytes/second with a 5 second grace period.

Uma taxa mínima também se aplica à resposta.A minimum rate also applies to the response. O código para definir o limite de solicitação e o limite de resposta é o mesmo, exceto por ter RequestBody ou Response nos nomes da propriedade e da interface.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

Este é um exemplo que mostra como configurar as taxas mínima de dados em 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));
        });

Tempo limite dos cabeçalhos de solicitaçãoRequest headers timeout

RequestHeadersTimeout

Obtém ou define a quantidade máxima de tempo que o servidor gasta recebendo cabeçalhos de solicitação.Gets or sets the maximum amount of time the server spends receiving request headers. O padrão é 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 síncronaSynchronous IO

AllowSynchronousIO controla se a E/S síncrona é permitida para a solicitação e resposta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. O valor padrão é true.The default value is true.

Aviso

Um grande número de operações de E/S síncronas de bloqueio pode levar à privação de pool de thread, o que faz com que o aplicativo não responda.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Habilite AllowSynchronousIO somente ao usar uma biblioteca em que não há suporte para E/S assíncrona.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

O exemplo a seguir desativa a E/S síncrona:The following example disables synchronous IO:

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

Para obter informações sobre outras opções e limites do Kestrel, confira:For information about other Kestrel options and limits, see:

Configuração do ponto de extremidadeEndpoint configuration

Por padrão, o ASP.NET Core associa a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (quando um certificado de desenvolvimento local está presente)https://localhost:5001 (when a local development certificate is present)

Especificar URLs usando:Specify URLs using the:

  • A variável de ambiente ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • O argumento de linha de comando --urls.--urls command-line argument.
  • A chave de configuração do host urls.urls host configuration key.
  • O método de extensão UseUrls.UseUrls extension method.

O valor fornecido usando essas abordagens pode ser um ou mais pontos de extremidade HTTP e HTTPS (HTTPS se houver um certificado padrão).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configure o valor como uma lista separada por ponto e vírgula (por exemplo, "Urls": "http://localhost:8000; http://localhost:8001" ).Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Veja mais informações sobre essas abordagens em URLs de servidor e Substituir configuração.For more information on these approaches, see Server URLs and Override configuration.

Um certificado de desenvolvimento é criado:A development certificate is created:

Alguns navegadores exigem a concessão de permissão explícita para confiar no certificado de desenvolvimento local.Some browsers require granting explicit permission to trust the local development certificate.

Os modelos de projeto configuram aplicativos para execução em HTTPS por padrão e incluem o redirecionamento de HTTPS e o suporte a HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Chame os métodos Listen ou ListenUnixSocket em KestrelServerOptions para configurar prefixos de URL e portas para o Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, o argumento de linha de comando --urls, a chave de configuração de host urls e a variável de ambiente ASPNETCORE_URLS também funcionam mas têm limitações que serão indicadas mais adiante nesta seção (um certificado padrão precisa estar disponível para a configuração do ponto de extremidade 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).

KestrelServerOptionsconfiguraçãoKestrelServerOptions configuration:

ConfigureEndpointDefaults (ação<escutaroptions >)ConfigureEndpointDefaults(Action<ListenOptions>)

Especifica uma Action de configuração a ser executada para cada ponto de extremidade especificado.Specifies a configuration Action to run for each specified endpoint. Chamar ConfigureEndpointDefaults várias vezes substitui as Actions pela ú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
            });
        });

ConfigureHttpsDefaults (ação<HttpsConnectionAdapterOptions >)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Especifica uma Action de configuração a ser executada para cada ponto de extremidade HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Chamar ConfigureHttpsDefaults várias vezes substitui as Actions pela ú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;
            });
        });

Configure(IConfiguration)Configure(IConfiguration)

Cria um carregador de configuração para configurar o Kestrel que usa uma IConfiguration como entrada.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. A configuração precisa estar no escopo da seção de configuração do Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configure o Kestrel para usar HTTPS.Configure Kestrel to use HTTPS.

Extensões ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps – Configure o Kestrel para usar HTTPS com o certificado padrão.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Gera uma exceção quando não há nenhum certificado padrão 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 é o caminho e o nome do arquivo de um arquivo de certificado, relativo ao diretório que contém os arquivos de conteúdo do aplicativo.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password é a senha necessária para acessar os dados do certificado X.509 .password is the password required to access the X.509 certificate data.
  • configureOptions é uma Action para configurar as HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Retorna o ListenOptions.Returns the ListenOptions.
  • storeName é o repositório de certificados do qual o certificado deve ser carregado.storeName is the certificate store from which to load the certificate.
  • subject é o nome da entidade do certificado.subject is the subject name for the certificate.
  • allowInvalid indica se certificados inválidos devem ser considerados, como os certificados autoassinados.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location é o local do repositório do qual o certificado deve ser carregado.location is the store location to load the certificate from.
  • serverCertificate é o certificado X.509.serverCertificate is the X.509 certificate.

Em produção, HTTPS precisa ser configurado explicitamente.In production, HTTPS must be explicitly configured. No mínimo, um certificado padrão precisa ser fornecido.At a minimum, a default certificate must be provided.

Configurações com suporte descritas a seguir:Supported configurations described next:

  • Nenhuma configuraçãoNo configuration
  • Substituir o certificado padrão da configuraçãoReplace the default certificate from configuration
  • Alterar os padrões no códigoChange the defaults in code

Nenhuma configuraçãoNo configuration

O Kestrel escuta em http://localhost:5000 e em https://localhost:5001 (se houver um certificado padrão disponível).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Substituir o certificado padrão da configuraçãoReplace the default certificate from configuration

CreateDefaultBuilder chama Configure(context.Configuration.GetSection("Kestrel")) por padrão ao carregar a configuração do Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Há um esquema de definições de configurações de aplicativo HTTPS padrão disponível para o Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Configure vários pontos de extremidade, incluindo URLs e os certificados a serem usados, por meio de um arquivo no disco ou de um repositório de certificados.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

No exemplo de appsettings.json a seguir:In the following appsettings.json example:

  • Defina AllowInvalid como true para permitir o uso de certificados inválidos (por exemplo, os certificados autoassinados).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Todo ponto de extremidade HTTPS que não especificar um certificado (HttpsDefaultCert no exemplo a seguir) será revertido para o certificado definido em Certificados > Padrão ou para o certificado de desenvolvimento.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>"
      }
    }
  }
}

Uma alternativa ao uso de Caminho e Senha para qualquer nó de certificado é especificar o certificado usando campos de repositório de certificados.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Por exemplo, o certificado Certificados > Padrão pode ser especificado como: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>"
}

Observações do esquema:Schema notes:

  • Os nomes de pontos de extremidade diferenciam maiúsculas de minúsculas.Endpoints names are case-insensitive. Por exemplo, HTTPS e Https são válidos.For example, HTTPS and Https are valid.
  • O parâmetro Url é necessário para cada ponto de extremidade.The Url parameter is required for each endpoint. O formato desse parâmetro é o mesmo que o do parâmetro de configuração de Urls de nível superior, exceto que ele é limitado a um ú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.
  • Esses pontos de extremidade substituem aqueles definidos na configuração de Urls de nível superior em vez de serem adicionados a eles.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Os pontos de extremidade definidos no código por meio de Listen são acumulados com os pontos de extremidade definidos na seção de configuração.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • A seção Certificate é opcional.The Certificate section is optional. Se a seção Certificate não for especificada, os padrões definidos nos cenários anteriores serão usados.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Se não houver nenhum padrão disponível, o servidor gerará uma exceção e não poderá ser iniciado.If no defaults are available, the server throws an exception and fails to start.
  • A seção Certificate é compatível com os certificados de CaminhoSenha e EntidadeRepositório.The Certificate section supports both PathPassword and SubjectStore certificates.
  • Qualquer número de pontos de extremidade pode ser definido dessa forma, contanto que eles não causem conflitos de porta.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}")) retorna um KestrelConfigurationLoader com um método .Endpoint(string name, listenOptions => { }) que pode ser usado para complementar as definições de um ponto de extremidade 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;
                });
        });

KestrelServerOptions.ConfigurationLoaderpode ser acessado diretamente para continuar Iterando no carregador existente, como aquele fornecido pelo CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • A seção de configuração de cada ponto de extremidade está disponível nas opções no método Endpoint para que as configurações personalizadas possam ser lidas.The configuration section for each endpoint is a available on the options in the Endpoint method so that custom settings may be read.
  • Várias configurações podem ser carregadas chamando options.Configure(context.Configuration.GetSection("{SECTION}")) novamente com outra seção.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Somente a última configuração será usada, a menos que Load seja chamado explicitamente nas instâncias anteriores.Only the last configuration is used, unless Load is explicitly called on prior instances. O metapacote não chama Load, portanto, sua seção de configuração padrão pode ser substituída.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • O KestrelConfigurationLoader espelha a família de APIs Listen de KestrelServerOptions como sobrecargas de Endpoint, portanto, os pontos de extremidade de código e de configuração podem ser configurados no mesmo local.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Essas sobrecargas não usam nomes e consomem somente as definições padrão da configuração.These overloads don't use names and only consume default settings from configuration.

Alterar os padrões no códigoChange the defaults in code

ConfigureEndpointDefaults e ConfigureHttpsDefaults podem ser usados para alterar as configurações padrão de ListenOptions e HttpsConnectionAdapterOptions, incluindo a substituição do certificado padrão especificado no cenário 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. ConfigureEndpointDefaults e ConfigureHttpsDefaults devem ser chamados antes que qualquer ponto de extremidade seja configurado.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;
            });
        });

Suporte do Kestrel para SNIKestrel support for SNI

A SNI (Indicação de Nome de Servidor) pode ser usada para hospedar vários domínios no mesmo endereço IP e na mesma porta.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Para que a SNI funcione, o cliente envia o nome do host da sessão segura para o servidor durante o handshake TLS para que o servidor possa fornecer o certificado correto.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. O cliente usa o certificado fornecido para a comunicação criptografada com o servidor durante a sessão segura que segue o handshake TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

O Kestrel permite a SNI por meio do retorno de chamada do ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. O retorno de chamada é invocado uma vez por conexão para permitir que o aplicativo inspecione o nome do host e selecione o certificado apropriado.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

O suporte para SNI requer:SNI support requires:

  • Em execução na estrutura netcoreapp2.1 de destino ou posterior.Running on target framework netcoreapp2.1 or later. No net461 ou posterior, o retorno de chamada é invocado, nullmas o name sempre é.On net461 or later, the callback is invoked but the name is always null. O name também será null se o cliente não fornecer o parâmetro de nome do host no handshake TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Todos os sites executados na mesma instância do Kestrel.All websites run on the same Kestrel instance. Kestrel não é compatível com o compartilhamento de endereço IP e porta entre várias instâncias sem um proxy reverso.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();

Associar a um soquete TCPBind to a TCP socket

O método Listen é associado a um soquete TCP, e um lambda de opções permite a configuração do 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");
            });
        });

O exemplo configura o HTTPS de um ponto de extremidade com ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Use a mesma API para definir outras configurações do Kestrel para pontos de extremidade específicos.Use the same API to configure other Kestrel settings for specific endpoints.

No Windows, é possível criar certificados autoassinados usando o cmdlet New-SelfSignedCertificate do PowerShell.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Para ver um exemplo sem suporte, confira UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

Nas plataformas macOS, Linux e Windows, é possível criar certificados usando o OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Associar a um soquete do UNIXBind to a Unix socket

Escute em um soquete do UNIX com ListenUnixSocket para um melhor desempenho com o Nginx, conforme mostrado neste exemplo: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");
            });
        });

Porta 0Port 0

Quando o número da porta 0 for especificado, o Kestrel se associará dinamicamente a uma porta disponível.When the port number 0 is specified, Kestrel dynamically binds to an available port. O exemplo a seguir mostra como determinar a qual porta o Kestrel realmente se associou no tempo de execução: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>");
    });
}

Quando o aplicativo é executado, a saída da janela do console indica a porta dinâmica na qual o aplicativo pode ser acessado: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

LimitaçõesLimitations

Configure pontos de extremidade com as seguintes abordagens:Configure endpoints with the following approaches:

  • UseUrls
  • O argumento de linha de comando --urls--urls command-line argument
  • A chave de configuração do host urlsurls host configuration key
  • A variável de ambiente ASPNETCORE_URLSASPNETCORE_URLS environment variable

Esses métodos são úteis para fazer com que o código funcione com servidores que não sejam o Kestrel.These methods are useful for making code work with servers other than Kestrel. No entanto, esteja ciente das seguintes limitações:However, be aware of the following limitations:

  • O protocolo HTTPS não pode ser usado com essas abordagens, a menos que um certificado padrão seja fornecido na configuração do ponto de extremidade HTTPS (por exemplo, usando a configuração KestrelServerOptions ou um arquivo de configuração, como já foi mostrado neste tópico).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).
  • Quando ambas as abordagens, Listen e UseUrls, são usadas ao mesmo tempo, os pontos de extremidade de Listen substituem os pontos de extremidade de UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configuração de ponto de extremidade do IISIIS endpoint configuration

Ao usar o IIS, as associações de URL para IIS substituem as associações definidas por Listen ou UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Para obter mais informações, confira o tópico Módulo do ASP.NET Core.For more information, see the ASP.NET Core Module topic.

Configuração de transporteTransport configuration

Com a liberação do ASP.NET Core 2.1, o transporte padrão do Kestrel deixa de ser baseado no Libuv, baseando-se agora em soquetes gerenciados.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. Essa é uma alteração da falha para aplicativos ASP.NET Core 2.0 que atualizam para o 2.1 que chamam UseLibuv e dependem de um dos seguintes pacotes: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 projetos que exigem o uso de Libuv:For projects that require the use of Libuv:

  • Adicione uma dependência para o pacote Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv ao arquivo de projeto do aplicativo: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}" />
    
  • Chame 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>();
    }
    

Prefixos de URLURL prefixes

Ao usar UseUrls, o argumento de linha de comando --urls, a chave de configuração de host urls ou a variável de ambiente ASPNETCORE_URLS, os prefixos de URL podem estar em um dos formatos a seguir.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.

Somente os prefixos de URL HTTP são válidos.Only HTTP URL prefixes are valid. O Kestrel não é compatível com HTTPS ao configurar associações de URL que usam UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Endereço IPv4 com o número da portaIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 é um caso especial que associa a todos os endereços IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Endereço IPv6 com número da portaIPv6 address with port number

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

    [::] é o equivalente do IPv6 ao IPv4 0.0.0.0.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nome do host com o número da portaHost name with port number

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

    Os nomes de host * e + não são especiais.Host names, *, and +, aren't special. Tudo o que não é reconhecido como um endereço IP ou um localhost válido é associado a todos os IPs IPv6 e IPv4.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Para associar nomes de host diferentes a diferentes aplicativos ASP.NET Core na mesma porta, use o HTTP.sys ou um servidor proxy reverso, como o IIS, o Nginx ou 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.

    Aviso

    A hospedagem em uma configuração de proxy reverso exige a filtragem de host.Hosting in a reverse proxy configuration requires host filtering.

  • Nome do localhost do host com o número da porta ou o IP de loopback com o número da portaHost localhost name with port number or loopback IP with port number

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

    Quando o localhost for especificado, o Kestrel tentará se associar às interfaces de loopback IPv4 e IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Se a porta solicitada está sendo usada por outro serviço em uma das interfaces de loopback, o Kestrel falha ao ser iniciado.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Se uma das interfaces de loopback não estiver disponível por qualquer outro motivo (geralmente porque não há suporte para o IPv6), o Kestrel registra um aviso em log.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtragem de hostHost filtering

Embora o Kestrel permita a configuração com base em prefixos como http://example.com:5000, ele geralmente ignora o nome do host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. O host localhost é um caso especial usado para a associação a endereços de loopback.Host localhost is a special case used for binding to loopback addresses. Todo host que não for um endereço IP explícito será associado a todos os endereços IP públicos.Any host other than an explicit IP address binds to all public IP addresses. Cabeçalhos Host não são validados.Host headers aren't validated.

Como uma solução alternativa, use o Middleware de Filtragem de Host.As a workaround, use Host Filtering Middleware. O middleware de filtragem de host é fornecido pelo pacote Microsoft. AspNetCore. HostFiltering , que está incluído no metapacote Microsoft. AspNetCore. App (ASP.NET Core 2,1 ou 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). O middleware é adicionado pelo CreateDefaultBuilder, que chama 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>();
}

Middleware de Filtragem de Host está desabilitado por padrão.Host Filtering Middleware is disabled by default. Para habilitar o middleware, defina uma chave AllowedHosts em appSettings. JSON/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. O valor dessa chave é uma lista separada por ponto e vírgula de nomes de host sem números de porta:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Observação

Middleware de Cabeçalhos Encaminhados também tem uma opção AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. Middleware de Cabeçalhos Encaminhados e Middleware de filtragem de Host têm funcionalidades semelhantes para cenários diferentes.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. A definição de AllowedHosts com Middleware de Cabeçalhos Encaminhados é apropriada quando o cabeçalho Host não é preservado ao encaminhar solicitações com um servidor proxy reverso ou um balanceador 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. A definição de AllowedHosts com Middleware de Filtragem de Host é apropriada quando o Kestrel é usado como um servidor de borda voltado ao público ou quando o cabeçalho Host é encaminhado diretamente.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 obter mais informações sobre o Middleware de Cabeçalhos Encaminhados, confira Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.For more information on Forwarded Headers Middleware, see Configure o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.

Recursos adicionaisAdditional resources