Partilhar via

Kestrel Servidor Web em ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

Importante

Estas informações referem-se a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

Por Tom Dykstra, Chris Rosse Stephen Halter

Kestrel é um servidor web multiplataforma para ASP.NET Core. Kestrel é o servidor recomendado para ASP.NET Core e é configurado por padrão em modelos de projeto ASP.NET Core.

As características do Kestrelincluem:

  • Multiplataforma:Kestrel é um servidor web multiplataforma que roda em Windows, Linux e macOS.
  • Alto desempenho:Kestrel é otimizado para lidar com um grande número de conexões simultâneas de forma eficiente.
  • Leve: Otimizado para execução em ambientes com recursos limitados, como contêineres e dispositivos de borda.
  • Segurança reforçada:Kestrel suporta HTTPS e é reforçada contra vulnerabilidades do servidor Web.
  • Suporte a protocolos amplos:Kestrel suporta protocolos Web comuns, incluindo:
  • Integração com o ASP.NET Core: Integração perfeita com outros componentes ASP.NET Core, como o pipeline de middleware, injeção de dependência e sistema de configuração.
  • Cargas de trabalho flexíveis: Kestrel suporta muitas cargas de trabalho:
    • ASP.NET estruturas de aplicativos, como APIs mínimas, MVC, páginas de Razor, SignalR, Blazore gRPC.
    • Construindo um proxy reverso com YARP.
  • Extensibilidade: Personalize Kestrel através de configuração, middleware e transportes personalizados.
  • Diagnóstico de desempenho:Kestrel fornece recursos internos de diagnóstico de desempenho, como registro em log e métricas.

Começar

ASP.NET Os modelos de projeto principal usam Kestrel por padrão quando não hospedados com o IIS. No seguinte Program.csgerado por modelo, o método WebApplication.CreateBuilder chama UseKestrel internamente:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Para obter mais informações sobre como configurar WebApplication e WebApplicationBuilder, consulte Minimal APIs quick reference.

Certificados de cliente opcionais

Para obter informações sobre aplicativos que devem proteger um subconjunto do aplicativo com um certificado, consulte Certificados de cliente opcionais.

Comportamento com o depurador ligado

Os seguintes prazos e limites de velocidade não são aplicados quando um depurador está ligado a um processo de Kestrel:

Recursos adicionais

Observação

A partir do ASP.NET Core 5.0, o transporte libuv do Kestrelestá obsoleto. O libuv transport não recebe atualizações para suportar novas plataformas de sistema operacional, como o Windows ARM64, e será removido em uma versão futura. Remova todas as chamadas para o método UseLibuv obsoleto e use o transporte de soquete padrão do Kestrel.

Kestrel é um servidor web multiplataforma para ASP.NET Core. Kestrel é o servidor Web incluído e habilitado por padrão nos modelos de projeto ASP.NET Core.

Kestrel suporta os seguintes cenários:

  • HTTPS
  • HTTP/2 (exceto no macOS†)
  • Atualização opaca usada para habilitar WebSockets
  • Soquetes Unix para alto desempenho por trás do Nginx

†HTTP/2 será suportado no macOS em uma versão futura.

Kestrel é suportado em todas as plataformas e versões suportadas pelo .NET Core.

Começar

ASP.NET Os modelos de projeto principal usam Kestrel por padrão quando não hospedados com o IIS. No seguinte Program.csgerado por modelo, o método WebApplication.CreateBuilder chama UseKestrel internamente:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Para obter mais informações sobre como configurar WebApplication e WebApplicationBuilder, consulte Minimal APIs quick reference.

Certificados de cliente opcionais

Para obter informações sobre aplicativos que devem proteger um subconjunto do aplicativo com um certificado, consulte Certificados de cliente opcionais.

Comportamento com o depurador anexado

Os seguintes tempos limite e limites de taxa não são impostos quando um depurador está anexado a um processo de Kestrel:

Recursos adicionais

Observação

A partir do ASP.NET Core 5.0, o transporte libuv do Kestrelestá obsoleto. O libuv transport não recebe atualizações para suportar novas plataformas de sistema operacional, como o Windows ARM64, e será removido em uma versão futura. Remova todas as chamadas para o método UseLibuv obsoleto e use o transporte de soquete padrão do Kestrel.

Kestrel é um servidor web multiplataforma para ASP.NET Core. Kestrel é o servidor Web incluído e habilitado por padrão nos modelos de projeto ASP.NET Core.

Kestrel suporta os seguintes cenários:

  • HTTPS
  • HTTP/2 (exceto no macOS†)
  • Atualização opaca usada para habilitar WebSockets
  • Soquetes Unix para alto desempenho por trás do Nginx

†HTTP/2 será suportado no macOS em uma versão futura.

Kestrel é suportado em todas as plataformas e versões suportadas pelo .NET Core.

Visualizar ou descarregar código de exemplo (como fazer download)

Começar

ASP.NET Os modelos de projeto principal usam Kestrel por padrão quando não hospedados com o IIS. Em Program.cs, o método ConfigureWebHostDefaults chama UseKestrel:

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

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

Para obter mais informações sobre como criar o host, consulte as seções Configurar um host e Configurações padrão do construtor de Host Genérico do .NET no ASP.NET Core.

Certificados de cliente opcionais

Para obter informações sobre aplicativos que devem proteger um subconjunto do aplicativo com um certificado, consulte Certificados de cliente opcionais.

Recursos adicionais

Observação

A partir do ASP.NET Core 5.0, o transporte libuv do Kestrelestá obsoleto. O libuv transport não recebe atualizações para suportar novas plataformas de sistema operacional, como o Windows ARM64, e será removido em uma versão futura. Remova todas as chamadas para o método UseLibuv obsoleto e use o transporte de soquete padrão do Kestrel.

Kestrel é um servidor web multiplataforma para ASP.NET Core. Kestrel é o servidor Web incluído por padrão nos modelos de projeto ASP.NET Core.

Kestrel suporta os seguintes cenários:

  • HTTPS
  • Atualização opaca usada para ativar WebSockets
  • Soquetes Unix para alto desempenho por trás do Nginx
  • HTTP/2 (exceto no macOS†)

†HTTP/2 será suportado no macOS em uma versão futura.

Kestrel é suportado em todas as plataformas e versões suportadas pelo .NET Core.

Ver ou baixar código de exemplo (como baixar)

Suporte HTTP/2

HTTP/2 está disponível para aplicativos ASP.NET Core se os seguintes requisitos básicos forem atendidos:

  • Sistema operacional†
    • Windows Server 2016/Windows 10 ou posterior‡
    • Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)
  • Estrutura de destino: .NET Core 2.2 ou posterior
  • Negociação de Protocolo (ALPN) de Application-Layer conexão de
  • Conexão TLS 1.2 ou posterior

†HTTP/2 será suportado no macOS em uma versão futura. ‡Kestrel tem suporte limitado para HTTP/2 no Windows Server 2012 R2 e Windows 8.1. O suporte é limitado porque a lista de pacotes de codificação TLS suportados disponíveis nesses sistemas operacionais é limitada. Um certificado gerado usando um algoritmo de assinatura digital de curva elíptica (ECDSA) pode ser necessário para proteger conexões TLS.

Se for estabelecida uma conexão HTTP/2, HttpRequest.Protocol relata HTTP/2.

A partir do .NET Core 3.0, o HTTP/2 é habilitado por padrão. Para obter mais informações sobre configuração, consulte as opções Kestrel e as seções e ListenOptions.Protocols.

Quando usar Kestrel com um proxy reverso

Kestrel pode ser usado sozinho ou com um servidor proxy reverso . Um servidor proxy reverso recebe solicitações HTTP da rede e as encaminha para Kestrel. Exemplos de um servidor proxy reverso incluem:

Kestrel usado como um servidor Web de borda (voltado para a Internet):

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

Kestrel usado numa configuração de proxy reverso:

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

Qualquer configuração, com ou sem um servidor proxy reverso, é uma configuração de hospedagem suportada.

Kestrel usado como um servidor de borda sem um servidor proxy reverso não suporta o compartilhamento do mesmo IP e porta entre vários processos. Quando Kestrel está configurado para escutar numa porta, Kestrel lida com todo o tráfego dessa porta, independentemente dos cabeçalhos das solicitações Host. Um proxy reverso que pode compartilhar portas tem a capacidade de encaminhar solicitações para Kestrel em um IP e porta exclusivos.

Mesmo que um servidor proxy reverso não seja necessário, usar um servidor proxy reverso pode ser uma boa escolha.

Um proxy reverso:

  • Pode limitar a área de superfície pública exposta dos aplicativos que hospeda.
  • Forneça uma camada adicional de configuração e cibersegurança de defesa em profundidade.
  • Pode integrar-se melhor com a infraestrutura existente.
  • Simplifique o balanceamento de carga e a configuração de comunicação segura (HTTPS). 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.

Advertência

A hospedagem em uma configuração de proxy reverso requer configuração de middleware de cabeçalhos encaminhados.

Kestrel em aplicativos ASP.NET Core

ASP.NET Os modelos de projeto principal usam Kestrel por padrão. Em Program.cs, o método ConfigureWebHostDefaults chama UseKestrel:

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

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

Para obter mais informações sobre como criar o host, consulte as seções Configurar um host e Configurações padrão do construtor de Host Genérico do .NET no ASP.NET Core.

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

Kestrel opções

O servidor Web Kestrel tem opções de configuração de restrição que são especialmente úteis em implantações voltadas para a Internet.

Defina restrições na propriedade Limits da classe KestrelServerOptions. A propriedade Limits contém uma instância da classe KestrelServerLimits.

Os exemplos a seguir usam o namespace Microsoft.AspNetCore.Server.Kestrel.Core:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Nos exemplos mostrados posteriormente neste artigo, Kestrel opções são configuradas no código C#. As opções Kestrel também podem ser definidas usando um provedor de configuração . Por exemplo, o do File Configuration Provider pode carregar a Kestrel configuração a partir de um ficheiro appsettings.json ou appsettings.{Environment}.json.

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

Observação

A configuração do ponto de extremidade KestrelServerOptions e é configurável a partir de provedores de configuração. A configuração Kestrel restante deve ser configurada em código C#.

Use uma das seguintes abordagens:

  • Configure Kestrel em Startup.ConfigureServices:

    1. Injete uma instância de IConfiguration na classe Startup. O exemplo a seguir pressupõe que a configuração injetada seja atribuída à propriedade Configuration.

    2. No Startup.ConfigureServices, carregue a seção Kestrel de configuração na configuração do Kestrel:

      using Microsoft.Extensions.Configuration

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.Configure<KestrelServerOptions>(
            Configuration.GetSection("Kestrel"));
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
    }
}

  • Configurar Kestrel ao configurar o host:

    No Program.cs, carregue a seção Kestrel da configuração na configuração do Kestrel.

    // using Microsoft.Extensions.DependencyInjection;

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

Ambas as abordagens anteriores funcionam com qualquer provedor de configuração .

Tempo limite de ligação ativa

KeepAliveTimeout

Obtém ou define o timeout de keep-alive . O padrão é de 2 minutos.

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);
})

Máximo de conexões de cliente

MaxConcurrentConnections MaxConcurrentUpgradedConnections

O número máximo de conexões TCP abertas simultâneas pode ser definido para todo o aplicativo com o seguinte código:

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 de HTTP ou HTTPS para outro protocolo (por exemplo, em uma solicitação WebSockets). Depois que uma conexão for atualizada, ela não é contabilizada no limite MaxConcurrentConnections.

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.

Tamanho máximo do corpo do pedido

MaxRequestBodySize

O tamanho máximo padrão do corpo da solicitação é de 30.000.000 bytes, o que equivale a aproximadamente 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:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Veja um exemplo que mostra como configurar a restrição para o aplicativo em cada solicitação:

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:

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 é lançada se o aplicativo configurar o limite numa solicitação depois que o aplicativo começar a ler a solicitação. Há uma propriedade IsReadOnly que indica se a propriedade MaxRequestBodySize está em estado somente leitura, o que significa que é tarde demais para configurar o limite.

Quando um aplicativo é executado fora de processo atrás do do Módulo Principal doASP.NET, o limite de tamanho do corpo da solicitação do Kestrelé desabilitado porque o IIS já define o limite.

Taxa mínima de fluxo de dados do corpo da requisição

MinRequestBodyDataRate MinResponseDataRate

Kestrel verifica a cada segundo se os dados estão chegando à taxa especificada em bytes/segundo. Se a taxa cair abaixo do mínimo, a conexão será expirada. O período de carência é a quantidade de tempo que Kestrel dá ao cliente para aumentar sua taxa de envio até o mínimo; a taxa não é verificada durante esse período. O período de carência ajuda a evitar a queda de conexões que inicialmente estão enviando dados em uma taxa lenta devido ao início lento do TCP.

A taxa mínima padrão é de 240 bytes/segundo com um período de carência de 5 segundos.

Uma taxa mínima também se aplica à resposta. 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 de propriedade e interface.

Aqui está um exemplo que mostra como configurar as taxas mínimas de dados no 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ínima por solicitação no 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 de limites de taxa por solicitação geralmente não é suportada para HTTP/2 devido ao suporte do protocolo para multiplexação de solicitações. No entanto, o IHttpMinRequestBodyDataRateFeature ainda está presente HttpContext.Features para solicitações HTTP/2, porque o limite de taxa de leitura ainda pode ser desativado totalmente por solicitação, definindo IHttpMinRequestBodyDataRateFeature.MinDataRate para null mesmo para uma solicitação HTTP/2. Tentar ler IHttpMinRequestBodyDataRateFeature.MinDataRate ou defini-lo para um valor diferente de null resultará na ocorrência de um NotSupportedException quando uma solicitação HTTP/2 for recebida.

Os limites de taxa em todo o servidor configurados via KestrelServerOptions.Limits ainda se aplicam a conexões HTTP/1.x e HTTP/2.

Tempo limite de cabeçalhos de solicitação

RequestHeadersTimeout

Obtém ou define a quantidade máxima de tempo que o servidor gasta recebendo cabeçalhos de solicitação. O padrão é de 30 segundos.

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);
})

Máximo de fluxos por ligação

Http2.MaxStreamsPerConnection limita o número de fluxos de solicitação simultâneos por conexão HTTP/2. Os fluxos em excesso são recusados.

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

O valor padrão é 100.

Tamanho da tabela de cabeçalho

O decodificador HPACK descompacta cabeçalhos HTTP para conexões HTTP/2. Http2.HeaderTableSize limita o tamanho da tabela de compressão de cabeçalho que o descodificador HPACK utiliza. O valor é fornecido em octetos e deve ser maior que zero (0).

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

O valor padrão é 4096.

Tamanho máximo do quadro

Http2.MaxFrameSize indica o tamanho máximo permitido de uma carga útil de quadro de conexão HTTP/2 recebida ou enviada pelo servidor. O valor é fornecido em octetos e deve estar entre 2^14 (16.384) e 2^24-1 (16.777.215).

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

O valor padrão é 2^14 (16.384).

Tamanho máximo do cabeçalho da solicitação

Http2.MaxRequestHeaderFieldSize indica o tamanho máximo permitido em octetos de valores de cabeçalho de solicitação. Esse limite se aplica ao nome e ao valor em suas representações compactadas e não compactadas. O valor deve ser maior que zero (0).

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

O valor padrão é 8.192.

Tamanho da janela de conexão inicial

Http2.InitialConnectionWindowSize indica o máximo de dados do corpo da solicitação em bytes que o servidor armazena em buffer de uma só vez agregados em todas as solicitações (fluxos) por conexão. Os pedidos também são limitados por Http2.InitialStreamWindowSize. O valor deve ser maior ou igual a 65.535 e menor que 2^31 (2.147.483.648).

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

O valor padrão é 128 KB (131.072).

Tamanho da janela de fluxo inicial

Http2.InitialStreamWindowSize indica o máximo de dados do corpo da solicitação em bytes que o servidor armazena em buffer de uma vez por solicitação (fluxo). Os pedidos também são limitados por Http2.InitialConnectionWindowSize. O valor deve ser maior ou igual a 65.535 e menor que 2^31 (2.147.483.648).

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

O valor padrão é 96 KB (98.304).

Trailers

Os trailers HTTP são semelhantes aos cabeçalhos HTTP, exceto que são enviados após o corpo da resposta ser enviado. Para o IIS e o HTTP.sys, apenas trailers de resposta HTTP/2 são suportados.

if (httpContext.Response.SupportsTrailers())
{
    httpContext.Response.DeclareTrailer("trailername");	

    // Write body
    httpContext.Response.WriteAsync("Hello world");

    httpContext.Response.AppendTrailer("trailername", "TrailerValue");
}

No código de exemplo anterior:

  • SupportsTrailers garante que os reboques são suportados para a resposta.
  • DeclareTrailer adiciona o nome do trailer fornecido ao cabeçalho de resposta Trailer. Declarar os trailers de uma resposta é opcional, mas recomendado. Se DeclareTrailer for chamado, deve ser antes que os cabeçalhos de resposta sejam enviados.
  • AppendTrailer anexa o trailer.

Repor

Reset permite que o servidor redefina uma solicitação HTTP/2 com um código de erro especificado. Um pedido de reinicialização é considerado abortado.

var resetFeature = httpContext.Features.Get<IHttpResetFeature>();
resetFeature.Reset(errorCode: 2);

Reset no exemplo de código anterior especifica o código de erro INTERNAL_ERROR. Para obter mais informações sobre códigos de erro HTTP/2, visite a seção código de erro de especificação HTTP/2.

E/S síncrona

AllowSynchronousIO controla se a E/S síncrona é permitida para a solicitação e a resposta. O valor padrão é false.

Advertência

Um grande número de operações de E/S síncronas de bloqueio pode levar ao esgotamento do pool de threads, tornando o aplicativo irresponível. Habilite AllowSynchronousIO somente ao usar uma biblioteca que não ofereça suporte a E/S assíncronas.

O exemplo a seguir habilita E/S síncronas:

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

Para obter informações sobre outras opções e limites Kestrel, consulte:

Configuração do ponto final

Por padrão, ASP.NET Core se liga a:

  • http://localhost:5000
  • https://localhost:5001 (quando existe um certificado de desenvolvimento local)

Especifique URLs usando:

  • ASPNETCORE_URLS variável de ambiente.
  • --urls argumento de linha de comando.
  • urls chave de configuração do host.
  • Método de Extensão UseUrls.

O valor fornecido por meio destas abordagens pode incluir um ou mais endpoints, tanto HTTP quanto HTTPS (sendo o HTTPS possível se houver um certificado padrão disponível). Configure o valor como uma lista separada por ponto-e-vírgula (por exemplo, "Urls": "http://localhost:8000;http://localhost:8001").

Para obter mais informações sobre essas abordagens, consulte Server URLs e Override configuration.

Um certificado de desenvolvimento é criado:

  • Quando o SDK do .NET Core está instalado.
  • A ferramenta dev-certs é usada para criar um certificado.

Alguns navegadores exigem a concessão de permissão explícita para confiar no certificado de desenvolvimento local.

Os modelos de projeto configuram aplicativos para serem executados em HTTPS por padrão e incluem redirecionamento HTTPS e suporte a HSTS.

Chame os métodos Listen ou ListenUnixSocket em KestrelServerOptions com o objetivo de configurar prefixos de URLs e portas para Kestrel.

UseUrls, o argumento de linha de comando --urls, urls chave de configuração do host e a variável de ambiente ASPNETCORE_URLS também funcionam, mas têm as limitações observadas posteriormente nesta seção (um certificado padrão deve estar disponível para configuração de ponto de extremidade HTTPS).

KestrelServerOptions configuração:

ConfigureEndpointDefaults(Action<ListenOptions>)

Especifica uma configuração Action a ser executada para cada endpoint especificado. Chamar ConfigureEndpointDefaults várias vezes substitui os Actionanteriores pelo último Action especificado.

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

Observação

Os pontos de extremidade criados ao chamar Listenantes de chamarConfigureEndpointDefaults não terão os padrões aplicados.

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Especifica a configuração Action para executar em cada ponto de extremidade HTTPS. Chamar ConfigureHttpsDefaults várias vezes substitui os Actionanteriores pelo último Action especificado.

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

Observação

Os pontos de extremidade criados chamando Listenantes de chamando ConfigureHttpsDefaults não terão os padrões aplicados.

Configurar(IConfiguration)

Cria um carregador de configuração para definir Kestrel que utiliza um IConfiguration como entrada. A configuração deve ter como escopo a seção de configuração para Kestrel.

ListenOptions.UseHttps

Configure Kestrel para usar HTTPS.

ListenOptions.UseHttps extensões:

  • UseHttps: Configure Kestrel para usar HTTPS com o certificado padrão. Lança uma exceção se nenhum certificado padrão estiver configurado.
  • 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)

ListenOptions.UseHttps parâmetros:

  • filename é o caminho e o nome de arquivo de um arquivo de certificado, relativo ao diretório que contém os arquivos de conteúdo do aplicativo.
  • password é a senha necessária para acessar os dados do certificado X.509.
  • configureOptions é uma Action para configurar o HttpsConnectionAdapterOptions. Devolve o ListenOptions.
  • storeName é o armazenamento de certificados a partir do qual carregar o certificado.
  • subject é o nome do assunto do certificado.
  • allowInvalid indica se certificados inválidos devem ser considerados, como certificados autoassinados.
  • location é o local de armazenamento a partir do qual carregar o certificado.
  • serverCertificate é o certificado X.509.

Na produção, o HTTPS deve ser explicitamente configurado. No mínimo, um certificado padrão deve ser fornecido.

Configurações suportadas descritas a seguir:

  • Sem configuração
  • Substitua o certificado padrão da configuração
  • Alterar os padrões no código

Nenhuma configuração

Kestrel escuta http://localhost:5000 e https://localhost:5001 (se um certificado padrão estiver disponível).

Substitua o certificado padrão na configuração

CreateDefaultBuilder chama Configure(context.Configuration.GetSection("Kestrel")) por defeito para carregar a configuração de Kestrel. Um esquema de configuração padrão para definições de aplicações HTTPS está disponível para Kestrel. Configure vários pontos de extremidade, incluindo as URLs e os certificados a serem usados, a partir de um ficheiro no disco rígido ou de um armazenamento de certificados.

No exemplo appsettings.json seguinte:

  • Defina AllowInvalid como true para permitir o uso de certificados inválidos (por exemplo, certificados autoassinados).
  • Qualquer ponto de extremidade HTTPS que não especifique um certificado (HttpsDefaultCert no exemplo a seguir) retornará ao certificado definido em Certificados> Padrão ou ao certificado de desenvolvimento.
{
  "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 através de campos do repositório de certificados. Por exemplo, o certificado >certificado de padrão pode ser especificado como:

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

Notas de esquema:

  • Os nomes dos pontos de extremidade não diferenciam maiúsculas de minúsculas. Por exemplo, HTTPS e Https são válidos.
  • O parâmetro Url é necessário para cada ponto de extremidade. O formato para esse parâmetro é o mesmo que o parâmetro de configuração de Urls de nível superior, exceto que ele é limitado a um único valor.
  • Esses pontos de extremidade substituem aqueles definidos na configuração de nível superior Urls, em vez de serem adicionados a ela. Os pontos de extremidade definidos no código via Listen são cumulativos com os pontos de extremidade definidos na seção de configuração.
  • A secção Certificate é opcional. Se a seção Certificate não for especificada, os padrões definidos em cenários anteriores serão usados. Se nenhum padrão estiver disponível, o servidor lançará uma exceção e falhará ao iniciar.
  • A seção Certificate suporta tanto o Path–Password quanto certificados Subject–Store.
  • Qualquer número de pontos de extremidade pode ser definido desta forma, desde que não causem conflitos de porta.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) devolve um KestrelConfigurationLoader com um método .Endpoint(string name, listenOptions => { }) que pode ser utilizado para aperfeiçoar as definições de um endpoint configurado:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader pode ser acessado diretamente para continuar iterando no carregador existente, como o fornecido pelo CreateDefaultBuilder.

  • A seção de configuração para cada ponto de extremidade está disponível nas opções no método Endpoint para que as configurações personalizadas possam ser lidas.
  • Várias configurações podem ser carregadas ao chamar novamente o options.Configure(context.Configuration.GetSection("{SECTION}")) com outra secção. Somente a última configuração é usada, a menos que Load seja explicitamente chamada em instâncias anteriores. O metapacote não chama Load para que sua seção de configuração padrão possa ser substituída.
  • KestrelConfigurationLoader espelha a família Listen de APIs do KestrelServerOptions à medida que Endpoint sobrecarrega, portanto, o código e os pontos de extremidade de configuração podem ser configurados no mesmo local. Essas sobrecargas não usam nomes e consomem apenas as definições padrão.

Alterar os padrões no código

ConfigureEndpointDefaults e ConfigureHttpsDefaults podem ser usados para alterar as configurações padrão para ListenOptions e HttpsConnectionAdapterOptions, incluindo a substituição do certificado padrão especificado no cenário anterior. ConfigureEndpointDefaults e ConfigureHttpsDefaults devem ser chamados antes que quaisquer pontos de extremidade sejam configurados.

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

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

Kestrel suporte para SNI

A Indicação de Nome de Servidor (SNI) pode ser usada para hospedar vários domínios no mesmo endereço IP e porta. Para que o SNI funcione, o cliente envia o nome do host para a sessão segura para o servidor durante o handshake TLS para que o servidor possa fornecer o certificado correto. O cliente usa o certificado fornecido para comunicação criptografada com o servidor durante a sessão segura que segue o handshake TLS.

Kestrel suporta SNI através do retorno de chamada ServerCertificateSelector. O callback é invocado uma única vez por cada ligação para permitir que a aplicação inspecione o nome de anfitrião e selecione o certificado apropriado.

O suporte SNI requer:

  • Execução na estrutura de destino netcoreapp2.1 ou posterior. A partir de net461, a função de retorno é invocada, mas o name é sempre null. O name também é null se o cliente não fornecer o parâmetro de nome do host no handshake TLS.
  • Todos os sites são executados na instância Kestrel. Kestrel não suporta a partilha de um endereço IP e porta em várias instâncias sem um proxy reverso.
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;
            };
        });
    });
});

Registo de ligações

Chame UseConnectionLogging para emitir logs de nível de depuração para comunicação a nível de byte numa ligação. O registo de ligações é útil para solucionar problemas em comunicações de baixo nível, como durante a encriptação TLS e atrás de proxies. Se UseConnectionLogging for colocado antes do UseHttps, o tráfego criptografado será registado. Se UseConnectionLogging for colocado após UseHttps, o tráfego desencriptado é registado.

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

Conectar a um soquete TCP

O método Listen liga-se a um soquete TCP e um lambda de opções permite a configuração do certificado X.509:

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 HTTPS para um endpoint com ListenOptions. Use a mesma API para definir outras configurações de Kestrel para pontos de extremidade específicos.

No Windows, certificados autoassinados podem ser criados usando o cmdlet New-SelfSignedCertificate PowerShell. Para obter um exemplo sem suporte, consulte UpdateIISExpressSSLForChrome.ps1.

No macOS, Linux e Windows, os certificados podem ser criados usando OpenSSL.

Vincular a um soquete Unix

Ouça em um soquete Unix com ListenUnixSocket para melhorar o desempenho com o Nginx, como mostrado neste exemplo:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • No arquivo de configuração do Nginx, defina a entrada server>location>proxy_pass como http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} é o nome do soquete fornecido ao ListenUnixSocket (por exemplo, kestrel-test.sock no exemplo anterior).
  • Certifique-se de que o soquete é gravável por Nginx (por exemplo, chmod go+w /tmp/kestrel-test.sock).

Porta 0

Quando o número da porta 0 é especificado, Kestrel se liga dinamicamente a uma porta disponível. O exemplo a seguir mostra como determinar a que porta Kestrel está realmente vinculada durante o tempo de execução.

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 onde o aplicativo pode ser alcançado:

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

Limitações

Configure pontos de extremidade com as seguintes abordagens:

  • UseUrls
  • --urls argumento de linha de comando
  • urls chave de configuração do host
  • ASPNETCORE_URLS variável de ambiente

Esses métodos são úteis para fazer o código funcionar com servidores diferentes Kestrel. No entanto, esteja ciente das seguintes limitações:

  • HTTPS não pode ser utilizado com estas 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 de um arquivo de configuração conforme demonstrado anteriormente neste tópico).
  • Quando as abordagens Listen e UseUrls são usadas simultaneamente, os pontos de extremidade Listen substituem os pontos de extremidade UseUrls.

Configuração do ponto de extremidade do IIS

Ao usar o IIS, as associações de URL para ligações de substituição do IIS são definidas por Listen ou UseUrls. Para obter mais informações, consulte o tópico ASP.NET Core Module.

ListenOptions.Protocolos

A propriedade Protocols estabelece os protocolos HTTP (HttpProtocols) ativados num ponto final de conexão ou para o servidor. Atribua um valor à propriedade Protocols a partir do HttpProtocols enum.

HttpProtocols valor de enum Protocolo de conexão permitido
Http1 HTTP/1.1 apenas. Pode ser usado com ou sem TLS.
Http2 HTTP/2 apenas. Pode ser usado sem TLS somente se o cliente suportar um modo Conhecimento Prévio.
Http1AndHttp2 HTTP/1.1 e HTTP/2. HTTP/2 requer que o cliente selecione HTTP/2 no TLS Application-Layer Protocol Negotiation (ALPN) handshake; caso contrário, o padrão de conexão é HTTP/1.1.

O valor ListenOptions.Protocols padrão para qualquer ponto de extremidade é HttpProtocols.Http1AndHttp2.

Restrições TLS para HTTP/2:

  • TLS versão 1.2 ou posterior
  • Renegociação desativada
  • Compressão desativada
  • Tamanhos mínimos de troca de chaves efêmeras:
    • Curva elíptica Diffie-Hellman (ECDHE) [RFC4492]: mínimo de 224 bits
    • Diffie-Hellman de campo finito (DHE) [TLS12]: mínimo de 2048 bits
  • Cipher suite não proibido.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] com a curva elíptica P-256 [FIPS186] é suportada por padrão.

O exemplo a seguir permite conexões HTTP/1.1 e HTTP/2 na porta 8000. As conexões são protegidas por TLS com um certificado fornecido:

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

Use o middleware de conexão para filtrar handshakes TLS por conexão para cifras específicas, se necessário.

O exemplo a seguir lança NotSupportedException para qualquer algoritmo de codificação que o aplicativo não suporta. Como alternativa, defina e compare ITlsHandshakeFeature.CipherAlgorithm com uma lista de pacotes de codificação aceitáveis.

Nenhuma criptografia é usada com um CipherAlgorithmType.Null algoritmo de cifra.

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

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

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

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

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

                return next();
            });
        }
    }
}

A filtragem de conexão também pode ser configurada através de uma função lambda IConnectionBuilder.

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

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

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

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

No Linux, CipherSuitesPolicy pode ser usado para filtrar handshakes TLS por conexão:

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

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

Defina o protocolo a partir da configuração

CreateDefaultBuilder chama serverOptions.Configure(context.Configuration.GetSection("Kestrel")) por padrão para carregar a configuração de Kestrel.

O exemplo appsettings.json a seguir estabelece HTTP/1.1 como protocolo de ligação padrão para todos os endpoints.

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

O exemplo de appsettings.json a seguir estabelece o protocolo de conexão HTTP/1.1 para um ponto de extremidade específico:

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

Os protocolos especificados no código substituem os valores definidos pela configuração.

Prefixos de URL

Ao usar UseUrls, --urls argumento de linha de comando, urls chave de configuração do host ou ASPNETCORE_URLS variável de ambiente, os prefixos de URL podem estar em qualquer um dos seguintes formatos.

Apenas os prefixos de URL HTTP são válidos. Kestrel não suporta HTTPS ao configurar associações de URL usando UseUrls.

  • Endereço IPv4 com número de porta

    http://65.55.39.10:80/

    0.0.0.0 é um caso especial que se liga a todos os endereços IPv4.

  • Endereço IPv6 com número de porta

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

    [::] é o equivalente IPv6 do IPv4 0.0.0.0.

  • Nome do host com número da porta

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

    Os nomes dos anfitriões, *e +não são especiais. Qualquer elemento não reconhecido como um endereço IP válido ou localhost associa-se a todos os endereços IP IPv4 e IPv6. Para vincular nomes de host diferentes a aplicativos ASP.NET Core diferentes na mesma porta, use HTTP.sys ou um servidor proxy reverso, como IIS, Nginx ou Apache.

    Advertência

    A hospedagem numa configuração de proxy reverso requer configuração de middleware de cabeçalhos encaminhados.

  • Nome do host localhost com o número de porta ou IP de loopback com o número de porta

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

    Quando localhost é especificado, Kestrel tenta vincular-se às interfaces de loopback separadas para IPv4 e IPv6. Se a porta solicitada estiver em uso por outro serviço em qualquer interface de loopback, Kestrel falha ao iniciar. Se qualquer interface de loopback estiver indisponível por qualquer outro motivo (mais comumente porque o IPv6 não é suportado), Kestrel registrará um aviso.

Filtragem de host

Embora o Kestrel ofereça suporte à configuração com base em prefixos como http://example.com:5000, Kestrel ignora em grande parte o nome do host. O Host localhost é um caso especial usado para ligação a endereços de loopback. Qualquer host que não seja um endereço IP explícito se liga a todos os endereços IP públicos. Host cabeçalhos não são validados.

Como solução alternativa, use o Host Filtering Middleware. O Middleware de Filtragem de Host é fornecido pelo pacote Microsoft.AspNetCore.HostFiltering, que é fornecido implicitamente para aplicativos ASP.NET Core. O middleware é adicionado por CreateDefaultBuilder, que chama 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>();
}

O Middleware de Filtragem de Host está desativado por padrão. Para habilitar o middleware, defina uma chave AllowedHosts no appsettings.json/appsettings.{Environment}.json. O valor é uma lista delimitada por ponto-e-vírgula de nomes de host sem números de porta:

appsettings.json:

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

Observação

Forwarded Headers Middleware também dispõe de uma opção AllowedHosts. O middleware de cabeçalhos encaminhados e o middleware de filtragem de host têm funcionalidade semelhante para diferentes cenários. A configuração AllowedHosts com o middleware de cabeçalhos encaminhados é apropriada quando, num servidor proxy reverso ou balanceador de carga, o cabeçalho Host não é preservado durante o encaminhamento de solicitações. A configuração AllowedHosts com o Host Filtering Middleware é apropriada quando Kestrel é usado como um servidor de borda voltado para o público ou quando o cabeçalho Host é encaminhado diretamente.

Para obter mais informações sobre Middlewares de Encaminhamento de Cabeçalhos, consulte como configurar o ASP.NET Core para funcionar com servidores proxy e balanceadores de carga.

Configuração de transporte Libuv

Para projetos que requerem a utilização de Libuv (UseLibuv):

  • Adicione uma dependência para o pacote Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv ao arquivo de projeto do aplicativo:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                  Version="{VERSION}" />

  • Ligue para UseLibuv no 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>();
            });
}

Drenagem de solicitações HTTP/1.1

Abrir conexões HTTP é demorado. Para HTTPS, também consome muitos recursos. Portanto, Kestrel tenta reutilizar conexões pelo protocolo HTTP/1.1. O conteúdo da solicitação deve ser totalmente consumido para permitir que a conexão seja reutilizada. A aplicação nem sempre consome o corpo da solicitação, como em pedidos POST, onde o servidor retorna um redirecionamento ou uma resposta 404. No caso de redirecionamento do POST:

  • O cliente pode já ter enviado parte dos dados POST.
  • O servidor grava a resposta 301.
  • A conexão não pode ser usada para uma nova solicitação até que os dados POST do corpo da solicitação anterior tenham sido totalmente lidos.
  • Kestrel tenta drenar o corpo do pedido. Drenar o corpo da solicitação significa ler e descartar os dados sem processá-los.

O processo de drenagem faz uma compensação entre permitir que a conexão seja reutilizada e o tempo necessário para drenar os dados restantes:

  • A drenagem tem um tempo limite de cinco segundos, que não é configurável.
  • Se todos os dados especificados pelo cabeçalho Content-Length ou Transfer-Encoding não tiverem sido lidos antes do tempo limite, a conexão será fechada.

Às vezes, você pode querer encerrar a solicitação imediatamente, antes ou depois de escrever a resposta. Por exemplo, os clientes podem ter limites de dados restritivos, portanto, limitar os dados carregados pode ser uma prioridade. Nesses casos, para encerrar uma solicitação, chame HttpContext.Abort de um controlador, Razor Página ou middleware.

Existem advertências ao usar Abort:

  • A criação de novas conexões pode ser lenta e cara.
  • Não há garantia de que o cliente tenha lido a resposta antes do fechamento da conexão.
  • Chamar Abort deve ser raro e reservado para casos de erro graves, não erros comuns.
    • Só ligue para Abort quando um problema específico precisa ser resolvido. Por exemplo, ligue para Abort se clientes mal-intencionados estiverem tentando POST dados ou quando houver um bug no código do cliente que cause solicitações grandes ou numerosas.
    • Não chame Abort para situações de erro comuns, como HTTP 404 (Não encontrado).

Chamar HttpResponse.CompleteAsync antes de chamar Abort garante que o servidor tenha concluído a gravação da resposta. No entanto, o comportamento do cliente não é previsível e eles podem não ler a resposta antes que a conexão seja abortada.

Esse processo é diferente para HTTP/2 porque o protocolo suporta abortar fluxos de solicitação individuais sem fechar a conexão. O tempo limite de drenagem de cinco segundos não se aplica. Se houver algum dado do corpo da solicitação não lido depois de concluir uma resposta, o servidor enviará um quadro HTTP/2 RST. Os quadros de dados adicionais do corpo da solicitação são ignorados.

Se possível, é melhor que os clientes utilizem o cabeçalho de solicitação Expect: 100-continue e aguardem que o servidor responda antes de começar a enviar o corpo da solicitação. Isso dá ao cliente a oportunidade de examinar a resposta e abortar antes de enviar dados desnecessários.

Recursos adicionais