Configurar opções para o servidor Web Kestrel do ASP.NET Core

O servidor Web do Kestrel tem opções de configuração de restrição especialmente úteis em implantações para a Internet. Para configurar as opções de configuração Kestrel, chame ConfigureKestrel em Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Defina restrições sobre a propriedade KestrelServerOptions.Limits. Essa propriedade contém uma instância da classe KestrelServerLimits.

Limites gerais

Tempo limite de keep-alive

KeepAliveTimeout obtém ou define o tempo limite de keep-alive:

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

Esse tempo limite não é imposto quando um depurador é anexado ao processo Kestrel.

Número máximo de conexões de cliente

MaxConcurrentConnections obtém ou define o número máximo de conexões abertas:

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

MaxConcurrentUpgradedConnections obtém ou define o número máximo de conexões abertas e atualizadas:

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

Uma conexão atualizada é aquela que foi alternada de HTTP para outro protocolo, como WebSockets. Depois que uma conexão é atualizada, ela não é contada em relação ao limite de MaxConcurrentConnections.

Tamanho máximo do corpo da solicitação

MaxRequestBodySize obtém ou define o tamanho máximo permitido em bytes para todos os corpos de solicitação.

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(100_000_000)]
public IActionResult Get()

O exemplo a seguir configura MaxRequestBodySize para todas as solicitações:

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

O exemplo a seguir configura MaxRequestBodySize para uma solicitação específica usando IHttpMaxRequestBodySizeFeature em um middleware personalizado:

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

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

    // ...

    await next(context);
});

Se o aplicativo tentar configurar o limite em uma solicitação depois que ele começar a ler a solicitação, uma exceção será gerada. Use a propriedade IHttpMaxRequestBodySizeFeature.IsReadOnly para marcar se é seguro definir a propriedade MaxRequestBodySize.

Quando um aplicativo é executado fora do processo por trás do Módulo do ASP.NET Core, o IIS define o limite e o limite de tamanho do corpo da solicitação Kestrel é desabilitado.

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

O Kestrel verifica a cada segundo se os dados estão sendo recebidos na taxa especificada em bytes/segundo. Se a taxa cair abaixo do mínimo, a conexão atingirá o tempo limite. O período de cortesia é a quantidade de tempo Kestrel que permite que o cliente aumente sua taxa de envio até o mínimo. A taxa não é verificada durante esse período. 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. Uma taxa mínima também se aplica à resposta.

MinRequestBodyDataRate obtém ou define a taxa de dados mínima do corpo da solicitação em bytes/segundo. MinResponseDataRate obtém ou define a taxa de dados mínima de resposta em bytes/segundo.

O exemplo a seguir configura MinRequestBodyDataRate e MinResponseDataRate para todas as solicitações:

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

O exemplo a seguir configura MinRequestBodyDataRate e MinResponseDataRate para uma solicitação específica usando IHttpMinRequestBodyDataRateFeature e IHttpMinResponseDataRateFeature em um middleware personalizado:

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

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

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

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

    // ...

    await next(context);
});

IHttpMinResponseDataRateFeature não está presente em HttpContext.Features para solicitações HTTP/2. A modificação dos limites de taxa por solicitação geralmente não tem suporte para HTTP/2 devido ao suporte do protocolo para multiplexação de solicitação. 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 IHttpMinResponseDataRateFeature.MinDataRate para null mesmo em uma solicitação HTTP/2. Tentativas de ler IHttpMinRequestBodyDataRateFeature.MinDataRate ou tentativas de defini-lo como um valor diferente de null resultam em um NotSupportedException para solicitações HTTP/2.

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.

Tempo limite dos 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:

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

Esse tempo limite não é imposto quando um depurador é anexado ao processo Kestrel.

Limites HTTP/2

Os limites nesta seção são definidos em KestrelServerLimits.Http2.

Fluxos máximos por conexão

O MaxStreamsPerConnection limita o número de fluxos de solicitações simultâneas por conexão HTTP/2. Os fluxos em excesso são recusados:

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

Tamanho da tabela de cabeçalho

HeaderTableSize limita o tamanho das tabelas de compactação de cabeçalho, em octetos, que o codificador HPACK e o decodificador no servidor podem usar. O decodificador HPACK descompacta os cabeçalhos HTTP para conexões HTTP/2:

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

Tamanho máximo do quadro

MaxFrameSize indica o maior payload do quadro que tem permissão para ser recebido, em octetos:

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

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

MaxRequestHeaderFieldSize indica o tamanho do tamanho máximo permitido de uma sequência de campo de cabeçalho de solicitação. Esse limite se aplica às sequências de nome e valor em suas representações compactadas e descompactadas:

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

Tamanho inicial da janela de conexão

InitialConnectionWindowSize indica a quantidade de dados do corpo da solicitação que o servidor está disposto a receber e o buffer por vez agregado em todas as solicitações (fluxos) por conexão:

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

As solicitações também são limitadas por InitialStreamWindowSize.

Tamanho inicial da janela de fluxo

InitialStreamWindowSize indica a quantidade de dados do corpo da solicitação que o servidor está disposto a receber e o buffer por vez por fluxo:

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

As solicitações também são limitadas por InitialConnectionWindowSize.

Configuração de ping keep alive HTTP/2

Kestrel pode ser configurado para enviar pings HTTP/2 para clientes conectados. Os pings HTTP/2 servem para várias finalidades:

• Mantenha as conexões ociosas ativas. Alguns clientes e servidores proxy encerram conexões ociosas. Os pings HTTP/2 são considerados como atividade em uma conexão e impedem que a conexão seja encerrada como ociosa.
• Encerre conexões não íntegras. As conexões em que o cliente não responde ao ping de keep alive no tempo configurado são fechadas pelo servidor.

Há duas opções de configuração relacionadas a pings de keep alive HTTP/2:

• KeepAlivePingDelay é um TimeSpan que configura o intervalo de ping. O servidor enviará um ping de keep alive para o cliente se ele não receber nenhum quadro para esse período de tempo. Os pings de keep alive são desabilitados quando essa opção é definida como TimeSpan.MaxValue.
• KeepAlivePingTimeout é um TimeSpan que configura o tempo limite do ping. Se o servidor não receber nenhum quadro, como um ping de resposta, durante esse tempo limite, a conexão será encerrada. O tempo limite de keep alive é desabilitado quando essa opção é definida como TimeSpan.MaxValue.

O exemplo a seguir o define KeepAlivePingDelay e KeepAlivePingTimeout:

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

Outras opções

E/S Síncrona

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

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. Habilite AllowSynchronousIO somente ao usar uma biblioteca em que não há suporte para E/S assíncrona.

O exemplo a seguir ativa a E/S síncrona:

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

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

• KestrelServerOptions
• KestrelServerLimits
• ListenOptions

Comportamento com depurador anexado

Determinados tempos limite e limites de taxa não são impostos quando um depurador é anexado a um processo Kestrel. Para obter mais informações, consulte Comportamento com o depurador anexado.