設定 ASP.NET Core Kestrel Web 伺服器的選項

Kestrel Web 伺服器所含的條件約束組態選項，在網際網路對應部署方面特別有用。 若要設定 Kestrel 組態選項，請在 Program.cs 中呼叫 ConfigureKestrel：

var builder = WebApplication.CreateBuilder(args);

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

在 KestrelServerOptions.Limits 屬性上設定條件約束。 此屬性會保存 KestrelServerLimits 類別的執行個體。

一般限制

Keep-alive 逾時

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 切換到另一個通訊協定的連線，例如 WebSockets。 升級連線之後，它不會納入 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);
});

IHttpMinResponseDataRateFeature 不存在於 HTTP/2 要求的 HttpContext.Features 中。 由於通訊協定對要求多工處理的支援，因此通常不支援針對 HTTP/2 修改基於每個要求的速率限制。 不過，IHttpMinRequestBodyDataRateFeature 仍存在 HTTP/2 要求的 HttpContext.Features 中，您仍能透過將 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 提供多個用途：

• 讓閒置連線保持運作。 某些用戶端和 Proxy 伺服器會關閉閒置的連線。 HTTP/2 Ping 被視為連線上的活動，並防止連線因閒置而關閉。
• 關閉狀況不良的連線。 用戶端未在設定的時間內回應保持運作 Ping 的連線，將由伺服器關閉。

HTTP/2 有兩個與 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 處理序時，並不會強制執行某些逾時和速率限制。 如需詳細資訊，請參閱附加偵錯工具時的行為。