Konfigurieren von Optionen für den ASP.NET Core-Kestrel-Webserver

Der Kestrel-Webserver verfügt über einschränkende Konfigurationsoptionen, die besonders nützlich bei Bereitstellungen mit Internetzugriff sind. Rufen Sie zum Konfigurieren von Kestrel-Konfigurationsoptionen ConfigureKestrel in Program.cs auf:

var builder = WebApplication.CreateBuilder(args);

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

Legen Sie Einschränkungen für die KestrelServerOptions.Limits-Eigenschaft fest. Diese Eigenschaft enthält eine Instanz der KestrelServerLimits-Klasse.

Allgemeine Grenzwerte

Keep-Alive-Timeout

KeepAliveTimeout ruft das Keep-Alive-Timeout ab oder legt es fest:

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

Dieses Timeout wird nicht erzwungen, wenn ein Debugger an den Kestrel-Prozess angefügt ist.

Maximale Anzahl der Clientverbindungen

MaxConcurrentConnections ruft die maximale Anzahl offener Verbindungen ab oder legt sie fest:

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

MaxConcurrentUpgradedConnections ruft die maximale Anzahl offener, aktualisierter Verbindungen ab oder legt sie fest:

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

Bei einer aktualisierten Verbindung handelt es sich um eine Verbindung, die von HTTP in ein anderes Protokoll wie WebSockets umgestellt wurde. Nachdem eine Verbindung aktualisiert wurde, zählt diese nicht mehr für den MaxConcurrentConnections-Grenzwert.

Maximale Größe des Anforderungstexts

MaxRequestBodySize ruft die maximal zulässige Größe eines Anforderungstexts in Bytes ab oder legt sie fest.

Die empfohlene Methode zur Außerkraftsetzung des Grenzwerts in einer ASP.NET Core-MVC-App besteht im Verwenden des RequestSizeLimitAttribute-Attributs in einer Aktionsmethode:

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

Im folgenden Beispiel wird MaxRequestBodySize für alle Anforderungen konfiguriert:

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

Im folgenden Beispiel wird MaxRequestBodySize für eine bestimmte Anforderung mithilfe von IHttpMaxRequestBodySizeFeature in einer benutzerdefinierten Middleware konfiguriert:

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

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

    // ...

    await next(context);
});

Wenn die App versucht, den Grenzwert für eine Anforderung zu konfigurieren, nachdem mit dem Lesen der Anforderung begonnen wurde, wird eine Ausnahme ausgelöst. Verwenden Sie die Eigenschaft IHttpMaxRequestBodySizeFeature.IsReadOnly, um zu prüfen, ob Sie die Eigenschaft MaxRequestBodySize festlegen können.

Wenn eine App prozessextern hinter dem ASP.NET Core-Modul ausgeführt wird, wird der Grenzwert von IIS festgelegt und der Grenzwert von Kestrel für die Anforderungstextgröße deaktiviert.

Minimale Datenrate des Anforderungstexts

Kestrel überprüft sekündlich, ob Daten mit der angegebenen Rate in Bytes/Sekunde eingehen. Wenn die Rate den mindestens erforderlichen Wert unterschreitet, wird für die Verbindung wegen Timeout getrennt. Bei der Toleranzperiode handelt es sich um die Zeitspanne, die Kestrel dem Client gewährt, um die Senderate auf den mindestens erforderlichen Wert zu erhöhen. Die Rate wird während dieser Zeit nicht geprüft. Diese Toleranzperiode beugt dem Trennen von Verbindungen vor, die Daten aufgrund eines langsamen TCP-Starts anfänglich mit einer niedrigen Rate senden. Für die Antwort gilt ebenfalls eine mindestens erforderliche Rate.

MinRequestBodyDataRate ruft die Mindestdatenrate des Anforderungstexts in Bytes/s ab oder legt diese fest. MinResponseDataRate ruft die Mindestdatenrate der Antwort in Bytes/s ab oder legt diese fest.

Im folgenden Beispiel werden MinRequestBodyDataRate und MinResponseDataRate für alle Anforderungen konfiguriert:

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

Im folgenden Beispiel werden MinRequestBodyDataRate und MinResponseDataRate für eine bestimmte Anforderung mithilfe von IHttpMinRequestBodyDataRateFeature und IHttpMinResponseDataRateFeature in einer benutzerdefinierten Middleware konfiguriert:

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 ist in HttpContext.Features für HTTP/2-Anforderungen nicht vorhanden. Das Ändern der Ratenlimits auf Anforderungsbasis wird in der Regel für HTTP/2 nicht unterstützt, weil das Protokoll Anforderungsmultiplexing unterstützt. IHttpMinRequestBodyDataRateFeature ist jedoch in HttpContext.Features für HTTP/2-Anforderungen noch vorhanden, weil der Grenzwert für die Leserate weiterhin für jede Anforderung vollständig deaktiviert werden kann, indem IHttpMinResponseDataRateFeature.MinDataRate auch für eine HTTP/2-Anforderung auf null festgelegt wird. Versuche, IHttpMinRequestBodyDataRateFeature.MinDataRate zu lesen oder auf einen anderen Wert als null festzulegen, führen bei HTTP/2-Anforderungen zu NotSupportedException.

Serverweite Ratenlimits, die über KestrelServerOptions.Limits konfiguriert sind, gelten auch für HTTP/1.x- und HTTP/2-Verbindungen.

Timeout für Anforderungsheader

RequestHeadersTimeout ruft die maximale Zeitspanne ab, in der der Server Anforderungsheader empfängt, oder legt diese fest:

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

Dieses Timeout wird nicht erzwungen, wenn ein Debugger an den Kestrel-Prozess angefügt ist.

HTTP/2-Limits

Die Limits in diesem Abschnitt sind auf KestrelServerLimits.Http2 festgelegt.

Maximale Datenströme pro Verbindung

MaxStreamsPerConnection schränkt die Anzahl gleichzeitiger Anforderungsdatenströme pro HTTP/2-Verbindung ein. Überschüssige Datenströme werden zurückgewiesen:

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

Größe der Headertabelle

HeaderTableSize begrenzt die Größe der Headerkomprimierungstabellen in Oktetten, die der HPACK-Encoder und -Decoder auf dem Server verwenden kann. Der HPACK-Decoder dekomprimiert HTTP-Header für HTTP/2-Verbindungen:

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

Maximale Framegröße

MaxFrameSize gibt die Größe der größten Nutzdaten eines Frames an, die empfangen werden dürfen, in Oktetten an:

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

Maximale Größe des Anforderungsheaders

MaxRequestHeaderFieldSize gibt die maximal zulässige Größe einer Feldsequenz im Anforderungsheader an. Dieser Grenzwert gilt sowohl für Namens- als auch Wertsequenzen in der komprimierten und nicht komprimierten Darstellung:

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

Anfangsfenstergröße der Verbindung

InitialConnectionWindowSize gibt an, wie viele Anforderungstextdaten der Server jeweils zu empfangen und zu puffern bereit ist, und zwar aggregiert über alle Anforderungen (Datenströme) pro Verbindung:

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

Anforderungen werden auch durch InitialStreamWindowSize beschränkt.

Anfangsfenstergröße des Streams

InitialStreamWindowSize gibt an, wie viele Anforderungstextdaten der Server bereit ist, pro Datenstrom zu empfangen und zu puffern:

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

Anforderungen werden auch durch InitialConnectionWindowSize beschränkt.

Konfiguration für HTTP/2-Keep-Alive-Pings

Kestrel kann so konfiguriert werden, dass HTTP/2-Pings an verbundene Clients gesendet werden. HTTP/2-Pings dienen mehreren Zwecken:

• Verbindungen im Leerlauf werden aktiv gehalten. Einige Clients und Proxyserver trennen Verbindungen, die sich im Leerlauf befinden. HTTP/2-Pings werden als Aktivität einer Verbindung betrachtet und verhindern, dass die Verbindung getrennt wird.
• Fehlerhafte Verbindungen werden getrennt. Verbindungen, bei denen der Client nicht innerhalb der konfigurierten Zeit auf einen Keep-Alive-Ping antwortet, werden vom Server getrennt.

Es gibt zwei Konfigurationsoptionen für HTTP/2-Keep-Alive-Pings:

• KeepAlivePingDelay ist eine TimeSpan, die das Pingintervall konfiguriert. Der Server sendet einen Keep-Alive-Ping an den Client, wenn dieser für diesen Zeitraum keine Frames erhält. Durch Festlegen dieser Option auf TimeSpan.MaxValue werden Keep-Alive-Pings deaktiviert.
• KeepAlivePingTimeout ist eine TimeSpan, die das Ping-Timeout konfiguriert. Wenn der Server während dieses Timeouts keine Frames (z. B. als Antwort-Ping) empfängt, wird die Verbindung getrennt. Durch Festlegen dieser Option auf TimeSpan.MaxValue wird das Keep-Alive-Timeout deaktiviert.

Im folgenden Beispiel werden KeepAlivePingDelay und KeepAlivePingTimeout festgelegt:

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

Weitere Optionen

Synchrone E/A-Vorgänge

AllowSynchronousIO steuert, ob für Anforderung und Antwort synchrone E/A-Vorgänge zulässig sind.

Warnung

Sehr viele blockierende synchrone E/A-Vorgänge können zu einem Ressourcenmangel im Threadpool führen, wodurch die App nicht mehr reagiert. Aktivieren Sie AllowSynchronousIO nur bei Verwendung einer Bibliothek, die asynchrone E/A-Vorgänge nicht unterstützt.

Das folgende Beispiel aktiviert synchrone E/A-Vorgänge:

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

Weitere Informationen zu anderen Kestrel-Optionen und -Einschränkungen finden Sie unter:

• KestrelServerOptions
• KestrelServerLimits
• ListenOptions

Verhalten mit angefügtem Debugger

Bestimmte Timeouts und Ratenbegrenzungen werden nicht erzwungen, wenn ein Debugger an einen Kestrel-Prozess angefügt ist. Weitere Informationen finden Sie unter Verhalten mit angefügtem Debugger.