为 ASP.NET Core Kestrel Web 服务器配置选项

Kestrel Web 服务器具有约束配置选项，这些选项在面向 Internet 的部署中尤其有用。 要配置 Kestrel 配置选项，可以在 Program.cs 中调用 ConfigureKestrel：

var builder = WebApplication.CreateBuilder(args);

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

对 KestrelServerOptions.Limits 属性设置约束。 此属性包含 KestrelServerLimits 类的实例。

一般限制

保持活动状态超时

KeepAliveTimeout 获取或设置保持活动状态超时：

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

将调试器附加到 Kestrel 进程时，不会强制实施此超时限制。

客户端最大连接数

MaxConcurrentConnections 获取或设置最大打开的连接数：

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

MaxConcurrentUpgradedConnections 获取或设置最大打开、升级的连接数：

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

升级的连接是已从 HTTP 切换到另一个协议（如 WebSocket）的连接。 连接升级后，不会计入 MaxConcurrentConnections 限制。

请求正文最大大小

MaxRequestBodySize 获取或设置允许的请求正文的最大大小（以字节为单位）。

在 ASP.NET Core MVC 应用中替代限制的推荐方法是在操作方法上使用 RequestSizeLimitAttribute 属性：

[RequestSizeLimit(100_000_000)]
public IActionResult Get()

以下示例为所有请求配置 MaxRequestBodySize：

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

以下示例在一个自定义中间件中使用 IHttpMaxRequestBodySizeFeature 为特定请求配置 MaxRequestBodySize：

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

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

    // ...

    await next(context);
});

如果应用在开始读取请求后尝试配置请求的限制，则会引发异常。 使用 IHttpMaxRequestBodySizeFeature.IsReadOnly 属性检查设置 MaxRequestBodySize 属性是否安全。

当应用在 ASP.NET Core 模块后于进程外运行时，IIS 会设置限制，并且 Kestrel 的请求正文大小限制处于禁用状态。

请求正文最小数据速率

Kestrel 每秒检查一次数据是否以指定的速率（字节/秒）传入。 如果速率低于最小值，则连接超时。宽限期是 Kestrel 允许客户端将其发送速率提升到最小值的时间量。 在此期间不会检查速率。 宽限期有助于避免最初由于 TCP 慢启动而以较慢速率发送数据的连接中断。 最小速率也适用于响应。

MinRequestBodyDataRate 获取或设置请求正文的最小数据速率（以字节/秒为单位）。 MinResponseDataRate 获取或设置响应最小数据速率（以字节/秒为单位）。

以下示例为所有请求配置 MinRequestBodyDataRate 和 MinResponseDataRate：

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

以下示例在一个自定义中间件中使用 IHttpMinRequestBodyDataRateFeature 和 IHttpMinResponseDataRateFeature 为特定请求配置 MinRequestBodyDataRate 和 MinResponseDataRate：

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

用于 HTTP/2 请求的 HttpContext.Features 中不存在 IHttpMinResponseDataRateFeature。 由于协议支持请求多路复用，因此 HTTP/2 通常不支持基于每个请求修改速率限制。 不过，用于 HTTP/2 请求的 HttpContext.Features 中仍存在 IHttpMinRequestBodyDataRateFeature，因为仍可以通过将 IHttpMinResponseDataRateFeature.MinDataRate 设置为 null，即使对于 HTTP/2 请求，也可以按请求完全禁用读取速率限制。 尝试读取 IHttpMinRequestBodyDataRateFeature.MinDataRate 或尝试将其设置为除 null 以外的值会导致 HTTP/2 请求的 NotSupportedException。

通过 KestrelServerOptions.Limits 配置的服务器范围的速率限制仍适用于 HTTP/1.x 和 HTTP/2 连接。

请求标头超时

RequestHeadersTimeout 获取或设置服务器接收请求头所需的最大时间量：

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

将调试器附加到 Kestrel 进程时，不会强制实施此超时限制。

HTTP/2 限制

该部分中的限制在 KestrelServerLimits.Http2 上设置。

每个连接的最大流

MaxStreamsPerConnection 限制每个 HTTP/2 连接的并发请求流的数量。 拒绝过多的流：

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

标题表大小

HeaderTableSize 限制了服务器上 HPACK 编码器与解码器可以使用的标头压缩表的大小（以八进制数表示）。 HPACK 解码器为 HTTP/2 连接解压缩 HTTP 标头：

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

最大帧大小

MaxFrameSize 指示允许接收的最大帧有效负载的大小（以八进制数表示）：

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

最大请求标头大小

MaxRequestHeaderFieldSize 指示请求头字段序列的最大允许大小。 此限制适用于名称和值序列的压缩和未压缩表示形式：

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

初始连接窗口大小

InitialConnectionWindowSize 表示服务器一次愿意接收和缓冲多少请求正文数据，这些数据在每个连接的所有请求（流）中汇总：

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

请求也受 InitialStreamWindowSize 限制。

初始流窗口大小

InitialStreamWindowSize 表示服务器愿意为每个流一次接收和缓冲多少请求正文数据：

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

请求也受 InitialConnectionWindowSize 限制。

HTTP/2 保持活动 ping 配置

Kestrel 可以配置为向连接的客户端发送 HTTP/2 ping。 HTTP/2 ping 有多种用途：

• 使空闲连接保持活动状态。 某些客户端和代理服务器会关闭空闲的连接。 HTTP/2 ping 是对连接执行的活动，可防止空闲连接被关闭。
• 关闭不正常的连接。 服务器会关闭在配置的时间内客户端未响应保持活动 ping 的连接。

与 HTTP/2 保持活动 ping 关联的配置选项有两个：

• KeepAlivePingDelay 是配置 ping 间隔的 TimeSpan。 如果服务器在此时间段内没有收到任何帧，则服务器会向客户端发送保持活动 ping。 将此选项设置为 TimeSpan.MaxValue 时，会禁用保持活动 ping。
• KeepAlivePingTimeout 是配置 ping 超时的 TimeSpan。 如果服务器在此超时期间没有收到任何帧（如响应 ping），则连接将关闭。 将此选项设置为 TimeSpan.MaxValue 时，会禁用保持活动状态超时。

以下示例设置 KeepAlivePingDelay 和 KeepAlivePingTimeout：

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

其他选项

同步 I/O

AllowSynchronousIO 控制是否允许对请求和响应使用同步 I/O。

警告

大量阻止同步 I/O 的操作可能会导致线程池资源不足，进而导致应用无响应。 仅在使用不支持异步 I/O 的库时，才启用 AllowSynchronousIO。

以下示例会启用同步 I/O：

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

有关其他 Kestrel 选项和限制的信息，请参阅：

• KestrelServerOptions
• KestrelServerLimits
• ListenOptions

附加了调试器的行为

将调试器附加到 Kestrel 进程时，不会强制实施某些超时和速率限制。 有关详细信息，请参阅附加了调试器的行为。