Implementierung des Webservers Kestrel in ASP.NET CoreKestrel web server implementation in ASP.NET Core

Von Tom Dykstra, Chris Ross und Stephen HalterBy Tom Dykstra, Chris Ross, and Stephen Halter

Einführung in Kestrel, dem plattformübergreifenden Webserver für ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel ist der Webserver, der standardmäßig in ASP.NET Core-Projektvorlagen enthalten ist.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel unterstützt die folgenden Szenarios:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Nicht transparente Upgrades, die zum Aktivieren von WebSockets verwendet werdenOpaque upgrade used to enable WebSockets
  • Unix-Sockets für eine hohe Leistung im Hintergrund von NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (außer unter macOS†)HTTP/2 (except on macOS†)

†HTTP/2 wird unter macOS in einem zukünftigen Release unterstützt.†HTTP/2 will be supported on macOS in a future release.

Kestrel wird auf allen Plattformen und für alle Versionen unterstützt, die .NET Core unterstützt.Kestrel is supported on all platforms and versions that .NET Core supports.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

HTTP/2-UnterstützungHTTP/2 support

HTTP/2 ist für ASP.NET Core-Apps verfügbar, wenn die folgenden Basisanforderungen erfüllt sind:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Betriebssystem†Operating system†
    • Windows Server 2016/Windows 10 oder höher‡Windows Server 2016/Windows 10 or later‡
    • Linux mit OpenSSL 1.0.2 oder höher (z.B. Ubuntu 16.04 oder höher)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Zielframework: .NET Core 2.2 oder höherTarget framework: .NET Core 2.2 or later
  • ALPN-Verbindung (Application-Layer Protocol Negotiation)Application-Layer Protocol Negotiation (ALPN) connection
  • TLS 1.2-Verbindung oder höherTLS 1.2 or later connection

†HTTP/2 wird unter macOS in einem zukünftigen Release unterstützt.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel bietet eingeschränkte Unterstützung für HTTP/2 unter Windows Server 2012 R2 und Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Die Unterstützung ist eingeschränkt, weil die Liste der unterstützten TLS-Verschlüsselungssammlungen unter diesen Betriebssystemen begrenzt ist.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Zum Sichern von TLS-Verbindungen ist möglicherweise ein durch einen Elliptic Curve Digital Signature Algorithm (ECDSA) generiertes Zertifikat erforderlich.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Wenn eine HTTP/2-Verbindung hergestellt wurde, meldet HttpRequest.ProtocolHTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 ist standardmäßig deaktiviert.HTTP/2 is disabled by default. Weitere Informationen zur Konfiguration finden Sie in den Abschnitten Kestrel-Optionen und ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Verwenden von Kestrel mit einem ReverseproxyWhen to use Kestrel with a reverse proxy

Kestrel kann eigenständig oder mit einem Reverseproxyserver wie z.B. Internet Information Services (IIS), Nginx oder Apache verwendet werden.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Ein Reverseproxyserver empfängt HTTP-Anforderungen aus dem Netzwerk und leitet diese an Kestrel weiter.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel bei Verwendung als Webserver mit direkter Internetverbindung:Kestrel used as an edge (Internet-facing) web server:

Kestrel kommuniziert direkt und ohne Reverseproxyserver mit dem Internet

Kestrel bei Verwendung in einer Reverseproxykonfiguration:Kestrel used in a reverse proxy configuration:

Kestrel kommuniziert indirekt mit dem Internet über einen Reverseproxyserver wie IIS, Nginx oder Apache

Jede der beiden Konfigurationen – mit oder ohne einen Reverseproxyserver – stellt eine unterstützte Hostingkonfiguration dar.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Bei Verwendung als Edgeserver ohne Reverseproxyserver unterstützt Kestrel die gemeinsame Nutzung der gleichen IP-Adresse und des gleichen Ports durch mehrere Prozesse nicht.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Wenn Kestrel für das Lauschen an einem Port konfiguriert ist, verarbeitet Kestrel den gesamten Datenverkehr für diesen Port unabhängig von den Host-Headern der Anforderungen.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Ein Reverseproxy, der Ports freigeben kann, kann Anforderungen an Kestrel über eine eindeutige IP und einen eindeutigen Port weiterleiten.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Auch wenn kein Reverseproxyserver erforderlich ist, kann die Verwendung eines solchen empfehlenswert sein.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Für einen Reverseproxy gilt Folgendes:A reverse proxy:

  • Er kann die verfügbar gemachten öffentlichen Oberflächen der von ihm gehosteten Apps einschränken.Can limit the exposed public surface area of the apps that it hosts.
  • Er stellt eine zusätzliche Ebene für Konfiguration und Schutz bereit.Provide an additional layer of configuration and defense.
  • Er lässt sich besser in die vorhandene Infrastruktur integrieren.Might integrate better with existing infrastructure.
  • Er vereinfacht die Konfiguration von Lastenausgleich und sicherer Kommunikation (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Nur der Reverseproxyserver erfordert ein X.509-Zertifikat, und dieser Server kann mit den Servern der App im internen Netzwerk über einfaches HTTP kommunizieren.Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

Warnung

Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.Hosting in a reverse proxy configuration requires host filtering.

Kestrel in ASP.NET Core-AppsKestrel in ASP.NET Core apps

ASP.NET Core-Projektvorlagen verwenden Kestrel standardmäßig.ASP.NET Core project templates use Kestrel by default. In Program.cs ruft die ConfigureWebHostDefaults-Methode UseKestrelauf:In Program.cs, the ConfigureWebHostDefaults method calls 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>();
        });

Weitere Informationen zum Erstellen des Hosts finden Sie im Artikel Generischer .NET-Host in den Abschnitten Einrichten eines Hosts und Standardeinstellungen für den Generator.For more information on building the host, see the Set up a host and Default builder settings sections of Generischer .NET-Host.

Um zusätzliche Konfiguration nach dem Aufruf von ConfigureWebHostDefaults bereitzustellen, verwenden Sie ConfigureKestrel:To provide additional configuration after calling 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-OptionenKestrel options

Der Kestrel-Webserver verfügt über einschränkende Konfigurationsoptionen, die besonders nützlich bei Bereitstellungen mit Internetzugriff sind.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Legen Sie Einschränkungen für die Limits-Eigenschaft der KestrelServerOptions-Klasse fest.Set constraints on the Limits property of the KestrelServerOptions class. Die Limits-Eigenschaft enthält eine Instanz der KestrelServerLimits-Klasse.The Limits property holds an instance of the KestrelServerLimits class.

In den folgenden Beispielen wird der Microsoft.AspNetCore.Server.Kestrel.Core-Namespace verwendet:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

In den Beispielen, die weiter unten in diesem Artikel aufgeführt sind, werden Kestrel-Optionen in C#-Code konfiguriert.In examples shown later in this article, Kestrel options are configured in C# code. Kestrel-Optionen können ebenso mithilfe eines Konfigurationsanbieters festgelegt werden.Kestrel options can also be set using a configuration provider. Beispielsweise kann der Dateikonfigurationsanbieter die Kestrel-Konfiguration aus einer appsettings.json- oder appsettings.{Umgebung}.json-Datei laden:For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

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

Hinweis

KestrelServerOptions und die Endpunktkonfiguration können über Konfigurationsanbieter konfiguriert werden.KestrelServerOptions and endpoint configuration are configurable from configuration providers. Die verbleibende Kestrel-Konfiguration muss in C#-Code konfiguriert werden.Remaining Kestrel configuration must be configured in C# code.

Verwenden Sie einen der folgenden Ansätze:Use one of the following approaches:

  • Konfigurieren Sie Kestrel in Startup.ConfigureServices:Configure Kestrel in Startup.ConfigureServices:

    1. Fügen Sie eine Instanz von IConfiguration in die Startup-Klasse ein.Inject an instance of IConfiguration into the Startup class. Im folgenden Beispiel wird davon ausgegangen, dass die eingefügte Konfiguration der Configuration-Eigenschaft zugewiesen wird.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. Laden Sie in Startup.ConfigureServices den Abschnitt Kestrel der Konfiguration in die Konfiguration von Kestrel:In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:

      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)
          {
              ...
          }
      }
      
  • Konfigurieren Sie Kestrel beim Erstellen des Hosts:Configure Kestrel when building the host:

    Laden Sie in Program.cs den Abschnitt Kestrel der Konfiguration in die Konfiguration von Kestrel:In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

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

Beide vorangehenden Ansätze funktionieren mit jedem Konfigurationsanbieter.Both of the preceding approaches work with any configuration provider.

Keep-Alive-TimeoutKeep-alive timeout

KeepAliveTimeout

Ruft das Keep-Alive-Timeout ab oder legt es fest.Gets or sets the keep-alive timeout. Standardwert: 2 Minuten.Defaults to 2 minutes.

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

Maximale Anzahl der ClientverbindungenMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Die maximale Anzahl von gleichzeitig geöffneten TCP-Verbindungen kann mithilfe von folgendem Code für die gesamte App festgelegt werden:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

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

Es gibt einen separaten Grenzwert für Verbindungen, die von HTTP oder HTTPS auf ein anderes Protokoll aktualisiert wurden (z.B. auf eine WebSockets-Anforderung).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Nachdem eine Verbindung aktualisiert wurde, zählt diese nicht mehr für den MaxConcurrentConnections-Grenzwert.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

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

Die maximale Anzahl von Verbindungen ist standardmäßig nicht begrenzt (NULL).The maximum number of connections is unlimited (null) by default.

Maximale Größe des AnforderungstextsMaximum request body size

MaxRequestBodySize

Die maximale Größe des Anforderungstexts beträgt standardmäßig 30.000.000 Byte, also ungefähr 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Die empfohlene Methode zur Außerkraftsetzung des Grenzwerts in einer ASP.NET Core-MVC-App besteht im Verwenden des RequestSizeLimitAttribute-Attributs in einer Aktionsmethode:The recommended approach to override the limit in an ASP.NET Core MVC app is to use the RequestSizeLimitAttribute attribute on an action method:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Im folgenden Beispiel wird veranschaulicht, wie die Einschränkungen auf jeder Anforderung für die App konfiguriert werden:Here's an example that shows how to configure the constraint for the app on every request:

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

Außer Kraft setzen der Einstellung für eine bestimmte Anforderung in Middleware:Override the setting on a specific request in 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));
    }

Eine Ausnahme wird ausgelöst, wenn die App den Grenzwert einer Anforderung konfiguriert, nachdem die App bereits mit dem Lesen der Anforderung begonnen hat.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Es gibt eine IsReadOnly-Eigenschaft, die angibt, wenn sich die MaxRequestBodySize-Eigenschaft im schreibgeschützten Zustand befindet, also wenn der Grenzwert nicht mehr konfiguriert werden kann.There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

Wenn eine App prozessextern hinter dem ASP.NET Core-Modul ausgeführt wird, ist das Größenlimit von Kestrel für Anforderungstext deaktiviert, weil IIS dieses Limit bereits festlegt.When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit is disabled because IIS already sets the limit.

Minimale Datenrate des AnforderungstextsMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel überprüft sekündlich, ob Daten mit der angegebenen Rate in Bytes/Sekunde eingehen.Kestrel checks every second if data is arriving at the specified rate in bytes/second. 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ährenddessen nicht überprüft.If the rate drops below the minimum, the connection is timed out. The grace period is the amount of time that Kestrel gives the client to increase its send rate up to the minimum; the rate isn't checked during that time. Diese Toleranzperiode beugt dem Trennen von Verbindungen vor, die Daten aufgrund eines langsamen TCP-Starts anfänglich mit einer niedrigen Rate senden.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

Die mindestens erforderliche Rate beträgt standardmäßig 240 Bytes/Sekunde mit einer Toleranzperiode von 5 Sekunden.The default minimum rate is 240 bytes/second with a 5 second grace period.

Für die Antwort gilt ebenfalls eine mindestens erforderliche Rate.A minimum rate also applies to the response. Der Code zum Festlegen des Grenzwerts für Anforderung und Antwort ist abgesehen von RequestBody oder Response in den Namen von Eigenschaften und Schnittstelle identisch.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

In diesem Beispiel wird veranschaulicht, wie Sie die mindestens erforderlichen Datenraten in Program.cs konfigurieren:Here's an example that shows how to configure the minimum data rates in 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);
})

Außer Kraft setzen des minimalen Ratenlimits pro Anforderung in Middleware:Override the minimum rate limits per request in 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));
    }

Das IHttpMinResponseDataRateFeature aus dem vorherigen Beispiel ist in HttpContext.Features für HTTP/2-Anforderungen nicht vorhanden, weil die Änderung von Ratenlimits für jede Anforderung aufgrund der Unterstützung für Anforderungsmultiplexing von HTTP/2 von diesem Protokoll unterstützt wird.The IHttpMinResponseDataRateFeature referenced in the prior sample is not present in HttpContext.Features for HTTP/2 requests because modifying rate limits on a per-request basis is generally not supported for HTTP/2 due to the protocol's support for request multiplexing. IHttpMinRequestBodyDataRateFeature ist jedoch in HttpContext.Features für HTTP/2-Anforderungen noch vorhanden, weil das Leseratenlimit weiterhin für jede Anforderung vollständig deaktiviert werden kann, indem IHttpMinRequestBodyDataRateFeature.MinDataRate auch für eine HTTP/2-Anforderung auf null festgelegt wird.However, the IHttpMinRequestBodyDataRateFeature is still present HttpContext.Features for HTTP/2 requests, because the read rate limit can still be disabled entirely on a per-request basis by setting IHttpMinRequestBodyDataRateFeature.MinDataRate to null even for an HTTP/2 request. Der Versuch, IHttpMinRequestBodyDataRateFeature.MinDataRate zu lesen oder auf einen anderen Wert als null festzulegen, führt dazu, dass bei einer HTTP/2-Anforderung eine NotSupportedException ausgelöst wird.Attempting to read IHttpMinRequestBodyDataRateFeature.MinDataRate or attempting to set it to a value other than null will result in a NotSupportedException being thrown given an HTTP/2 request.

Serverweite Ratenlimits, die über KestrelServerOptions.Limits konfiguriert sind, gelten auch für HTTP/1.x- und HTTP/2-Verbindungen.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Timeout für AnforderungsheaderRequest headers timeout

RequestHeadersTimeout

Ruft die maximale Zeitspanne ab, während der der Server Anforderungsheader empfängt, oder legt diese fest.Gets or sets the maximum amount of time the server spends receiving request headers. Der Standardwert beträgt 30 Sekunden.Defaults to 30 seconds.

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

Maximale Datenströme pro VerbindungMaximum streams per connection

Http2.MaxStreamsPerConnection schränkt die Anzahl gleichzeitiger Anforderungsdatenströme pro HTTP/2-Verbindung ein.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Überschüssige Datenströme werden zurückgewiesen.Excess streams are refused.

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

Der Standardwert ist 100.The default value is 100.

Größe der HeadertabelleHeader table size

Der HPACK-Decoder dekomprimiert HTTP-Header für HTTP/2-Verbindungen.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize schränkt die Größe der Headerkomprimierungstabelle ein, die der HPACK-Decoder verwendet.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. Der Wert wird in Oktetten bereitgestellt und muss größer als null (0) sein.The value is provided in octets and must be greater than zero (0).

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

Der Standardwert ist 4096.The default value is 4096.

Maximale FramegrößeMaximum frame size

Http2.MaxFrameSize gibt die maximal zulässige Größe einer vom Server empfangenen oder gesendeten HTTP/2-Verbindungsrahmen-Nutzlast an.Http2.MaxFrameSize indicates the maximum allowed size of an HTTP/2 connection frame payload received or sent by the server. Der Wert wird in Oktetten bereitgestellt und muss zwischen 2^14 (16.384) und 2^24-1 (16.777.215) liegen.The value is provided in octets and must be between 2^14 (16,384) and 2^24-1 (16,777,215).

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

Der Standardwert ist 2^14 (16.384).The default value is 2^14 (16,384).

Maximale Größe des AnforderungsheadersMaximum request header size

Http2.MaxRequestHeaderFieldSize gibt die maximal zulässige Größe in Oktetten der Anforderungsheaderwerte an.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Dieser Grenzwert gilt sowohl für den Namen als auch den Wert in der komprimierten und nicht komprimierten Darstellung.This limit applies to both name and value in their compressed and uncompressed representations. Der Wert muss größer als 0 (null) sein.The value must be greater than zero (0).

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

Der Standardwert ist 8.192.The default value is 8,192.

Anfangsfenstergröße der VerbindungInitial connection window size

Http2.InitialConnectionWindowSize gibt die maximalen Anforderungstextdaten in Byte an, die der Server auf einmal für alle Anforderungen (Streams) pro Verbindung aggregiert.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Anforderungen werden auch durch Http2.InitialStreamWindowSize beschränkt.Requests are also limited by Http2.InitialStreamWindowSize. Der Wert muss größer als oder gleich 65.535 und kleiner als 2^31 (2.147.483.648) sein.The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

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

Der Standardwert ist 128 KB (131.072).The default value is 128 KB (131,072).

Anfangsfenstergröße des StreamsInitial stream window size

Http2.InitialStreamWindowSize gibt die maximalen Anforderungstextdaten in Byte an, die der Server auf einmal pro Anforderung (Stream) puffert.Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Anforderungen werden auch durch Http2.InitialConnectionWindowSize beschränkt.Requests are also limited by Http2.InitialConnectionWindowSize. Der Wert muss größer als oder gleich 65.535 und kleiner als 2^31 (2.147.483.648) sein.The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

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

Der Standardwert ist 96 KB (98.304).The default value is 96 KB (98,304).

Synchrone E/A-VorgängeSynchronous I/O

AllowSynchronousIO steuert, ob für Anforderung und Antwort synchrone E/A-Vorgänge zulässig sind.AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. Der Standardwert ist false.The default value is false.

Warnung

Sehr viele blockierende synchrone E/A-Vorgänge können zu einem Ressourcenmangel im Threadpool führen, wodurch die App nicht mehr reagiert.A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Aktivieren Sie AllowSynchronousIO nur bei Verwendung einer Bibliothek, die asynchrone E/A-Vorgänge nicht unterstützt.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous I/O.

Das folgende Beispiel aktiviert synchrone E/A-Vorgänge:The following example enables synchronous I/O:

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

Weitere Informationen zu anderen Kestrel-Optionen und -Einschränkungen finden Sie unter:For information about other Kestrel options and limits, see:

EndpunktkonfigurationEndpoint configuration

Standardmäßig wird ASP.NET Core an Folgendes gebunden:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (wenn ein lokales Entwicklungszertifikat vorhanden ist)https://localhost:5001 (when a local development certificate is present)

Verwenden Sie Folgendes zum Angeben der URLs:Specify URLs using the:

  • Die Umgebungsvariable ASPNETCORE_URLSASPNETCORE_URLS environment variable.
  • Das Befehlszeilenargument --urls--urls command-line argument.
  • Den Hostkonfigurationsschlüssel urlsurls host configuration key.
  • Die Erweiterungsmethode UseUrlsUseUrls extension method.

Der Wert, der mit diesen Ansätzen angegeben wird, kann mindestens ein HTTP- oder HTTPS-Endpunkt sein (HTTPS wenn ein Standardzertifikat verfügbar ist).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Konfigurieren Sie den Wert als eine durch Semikolons getrennte Liste (z.B. "Urls": "http://localhost:8000;http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Weitere Informationen zu diesen Ansätzen finden Sie unter Server-URLs und Außerkraftsetzen der Konfiguration.For more information on these approaches, see Server URLs and Override configuration.

Ein Entwicklungszertifikat wird erstellt:A development certificate is created:

Einige Browser erfordern, dass Sie die explizite Berechtigung erteilen, dem lokalen Entwicklungszertifikat zu vertrauen.Some browsers require granting explicit permission to trust the local development certificate.

Projektvorlagen konfigurieren Apps, damit sie standardmäßig auf HTTPS ausgeführt werden und die HTTPS-Umleitung und HSTS-Unterstützung enthalten.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Rufen Sie die Listen- oder ListenUnixSocket-Methode unter KestrelServerOptions auf, um URL-Präfixe und Ports für Kestrel zu konfigurieren.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, das Befehlszeilenargument --urls, der Hostkonfigurationsschlüssel urls und die Umgebungsvariable ASPNETCORE_URLS funktionieren ebenfalls, verfügen jedoch über Einschränkungen, die im Verlauf dieses Abschnitts erläutert werden (Ein Standardzertifikat muss für die HTTPS-Endpunktkonfiguration verfügbar sein).UseUrls, the --urls command-line argument, urls host configuration key, and the ASPNETCORE_URLS environment variable also work but have the limitations noted later in this section (a default certificate must be available for HTTPS endpoint configuration).

KestrelServerOptions-Konfiguration:KestrelServerOptions configuration:

ConfigureEndpointDefaults(Action<ListenOptions>)ConfigureEndpointDefaults(Action<ListenOptions>)

Gibt die Konfiguration von Action zum Ausführen von jedem angegebenen Endpunkt an.Specifies a configuration Action to run for each specified endpoint. Mehrmalige Aufrufe von ConfigureEndpointDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

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

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureEndpointDefaults erstellt werden, werden die Standardwerte nicht angewendet.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Gibt die Konfiguration von Action zum Ausführen von jedem HTTPS-Endpunkt an.Specifies a configuration Action to run for each HTTPS endpoint. Mehrmalige Aufrufe von ConfigureHttpsDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

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

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureHttpsDefaults erstellt werden, werden die Standardwerte nicht angewendet.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Configure(IConfiguration)Configure(IConfiguration)

Erstellt ein Konfigurationsladeprogramm für das Einrichten von Kestrel, was IConfiguration als Eingabe erfordert.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. Die Konfiguration muss auf den Konfigurationsabschnitt für Kestrel festgelegt werden.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Konfiguriert Kestrel zur Verwendung von HTTPS.Configure Kestrel to use HTTPS.

ListenOptions.UseHttps-Erweiterungen:ListenOptions.UseHttps extensions:

  • UseHttps: Hiermit wird Kestrel zur Verwendung von HTTPS mit dem Standardzertifikat konfiguriert.UseHttps: Configure Kestrel to use HTTPS with the default certificate. Löst eine Ausnahme aus, wenn kein Standardzertifikat konfiguriert ist.Throws an exception if no default certificate is configured.
  • 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-Parameter:ListenOptions.UseHttps parameters:

  • filename entspricht dem Pfad und Dateinamen einer Zertifikatdatei relativ zu dem Verzeichnis, das die Inhaltsdateien der App enthält.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password ist das für den Zugriff auf die X.509-Zertifikatsdaten erforderliche Kennwort.password is the password required to access the X.509 certificate data.
  • configureOptions ist eine Action zum Konfigurieren von HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Gibt ListenOptions zurück.Returns the ListenOptions.
  • storeName ist der Zertifikatspeicher, aus dem das Zertifikat geladen wird.storeName is the certificate store from which to load the certificate.
  • subject ist der Name des Antragstellers für das Zertifikat.subject is the subject name for the certificate.
  • allowInvalid gibt an, ob ungültige Zertifikate berücksichtigt werden sollten, z.B. selbstsignierte Zertifikate.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location ist der Speicherort, aus dem das Zertifikat geladen wird.location is the store location to load the certificate from.
  • serverCertificate ist das X.509-Zertifikat.serverCertificate is the X.509 certificate.

In der Produktion muss HTTPS explizit konfiguriert sein.In production, HTTPS must be explicitly configured. Zumindest muss ein Standardzertifikat angegeben werden.At a minimum, a default certificate must be provided.

Die im Folgenden beschriebenen unterstützten Konfigurationen:Supported configurations described next:

  • Keine KonfigurationNo configuration
  • Ersetzen des Standardzertifikats aus der KonfigurationReplace the default certificate from configuration
  • Ändern des Standards im CodeChange the defaults in code

Keine KonfigurationNo configuration

Kestrel überwacht http://localhost:5000 und https://localhost:5001 (wenn ein Standardzertifikat verfügbar ist).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Ersetzen des Standardzertifikats aus der KonfigurationReplace the default certificate from configuration

CreateDefaultBuilder ruft Configure(context.Configuration.GetSection("Kestrel")) standardmäßig zum Laden der Kestrel-Konfiguration auf.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Ein Standardkonfigurationsschema für HTTPS-App-Einstellungen ist für Kestrel verfügbar.A default HTTPS app settings configuration schema is available for Kestrel. Konfigurieren Sie mehrere Endpunkte, einschließlich der zu verwendenden URLs und Zertifikate aus einer Datei auf dem Datenträger oder einem Zertifikatspeicher.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

Die Vorgehensweise im folgenden appsettings.json-Beispiel:In the following appsettings.json example:

  • Legen Sie AllowInvalid auf true fest, um die Verwendung von ungültigen Zertifikaten zu erlauben (z.B. selbstsignierte Zertifikate).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Jeder HTTPS-Endpunkt, der kein Zertifikat angibt (im folgenden Beispiel HttpsDefaultCert), greift auf das unter Zertifikate > Standard festgelegte Zertifikat oder das Entwicklungszertifikat zurück.Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls back to the cert defined under Certificates > Default or the development certificate.
{
  "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>"
      }
    }
  }
}

Alternativ zur Verwendung von Pfad und Kennwort für alle Zertifikatknoten können Sie das Zertifikat mithilfe von Zertifikatspeicherfeldern angeben.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Das Zertifikat unter Zertifikate > Standard kann beispielweise wie folgt angegeben werden:For example, the Certificates > Default certificate can be specified as:

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

Schema-Hinweise:Schema notes:

  • Bei den Namen der Endpunkte wird die Groß-/Kleinschreibung nicht beachtet.Endpoints names are case-insensitive. Zum Beispiel sind HTTPS und Https gültig.For example, HTTPS and Https are valid.
  • Der Parameter Url ist für jeden Endpunkt erforderlich.The Url parameter is required for each endpoint. Das Format für diesen Parameter ist identisch mit dem allgemeinen Konfigurationsparameter Urls, mit der Ausnahme, dass er auf einen einzelnen Wert begrenzt ist.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Diese Endpunkte ersetzen die in der allgemeinen Urls-Konfiguration festgelegten Endpunkte, anstatt zu ihnen hinzuzufügen.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Endpunkte, die über Listen in Code definiert werden, werden den im Konfigurationsabschnitt definierten Endpunkten hinzugefügt.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • Der Certificate-Abschnitt ist optional.The Certificate section is optional. Wenn der Certificate-Abschnitt nicht angegeben ist, werden die in früheren Szenarios definierten Standardwerte verwendet.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Wenn keine Standardwerte verfügbar sind, löst der Server eine Ausnahme aus und startet nicht.If no defaults are available, the server throws an exception and fails to start.
  • Der Certificate-Abschnitt unterstützt die Zertifikate PfadKennwort und SubjectStore (Antragsteller–Speicher).The Certificate section supports both PathPassword and SubjectStore certificates.
  • Auf diese Weise kann eine beliebige Anzahl von Endpunkten definiert werden, solange Sie keine Portkonflikte verursachen.Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) gibt KestrelConfigurationLoader mit der Methode .Endpoint(string name, listenOptions => { }) zurück, die dazu verwendet werden kann, die Einstellungen eines Endpunkts zu ergänzen:options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

Auf KestrelServerOptions.ConfigurationLoader kann direkt zugegriffen werden, um die Iteration auf dem vorhandenen Ladeprogramm fortzusetzen, etwa auf dem von CreateDefaultBuilder bereitgestellten Ladeprogramm.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • Der Konfigurationsabschnitt ist für jeden Endpunkt in den Optionen der Methode Endpoint verfügbar, sodass benutzerdefinierte Einstellungen gelesen werden können.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Mehrere Konfigurationen können durch erneutes Aufrufen von options.Configure(context.Configuration.GetSection("{SECTION}")) mit einem anderen Abschnitt geladen werden.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Sofern Load nicht in einer vorherigen Instanz explizit aufgerufen wird, wird nur die letzte Konfiguration verwendet.Only the last configuration is used, unless Load is explicitly called on prior instances. Das Metapaket ruft Load nicht auf, sodass der Abschnitt mit der Standardkonfiguration ersetzt werden kann.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader spiegelt die API-Familie Listen von KestrelServerOptions als Endpoint-Überladungen, weshalb Code und Konfigurationsendpunkte am selben Ort konfiguriert werden können.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Diese Überladungen verwenden keine Namen und nutzen nur Standardeinstellungen aus der Konfiguration.These overloads don't use names and only consume default settings from configuration.

Ändern des Standards im CodeChange the defaults in code

ConfigureEndpointDefaults und ConfigureHttpsDefaults können zum Ändern der Standardeinstellungen für ListenOptions und HttpsConnectionAdapterOptions verwendet werden, einschließlich der Standardzertifikate, die im vorherigen Szenario festgelegt wurden.ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. ConfigureEndpointDefaults und ConfigureHttpsDefaults sollten aufgerufen werden, bevor Endpunkte konfiguriert werden.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

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

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

Kestrel-Unterstützung für SNIKestrel support for SNI

Die Servernamensanzeige (SNI) kann zum Hosten mehrerer Domänen auf der gleichen IP-Adresse und dem gleichen Port verwendet werden.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Damit die Servernamensanzeige funktioniert, sendet der Client während des TLS-Handshakes den Hostnamen für die sichere Sitzung an den Server, sodass der Server das richtige Zertifikat bereitstellen kann.For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. Der Client verwendet das beigestellte Zertifikat für die verschlüsselte Kommunikation mit dem Server während der sicheren Sitzung nach dem TLS-Handshake.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel unterstützt die Servernamensanzeige über den ServerCertificateSelector-Rückruf.Kestrel supports SNI via the ServerCertificateSelector callback. Der Rückruf wird für jede Verbindung einmal aufgerufen, um der App zu ermöglichen, den Hostnamen zu überprüfen und das entsprechende Zertifikat auszuwählen.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Für die Unterstützung der Servernamensanzeige benötigen Sie Folgendes:SNI support requires:

  • Wird auf dem Zielframework netcoreapp2.1 oder höher ausgeführt.Running on target framework netcoreapp2.1 or later. In net461 oder höher, wird der Rückruf aufgerufen, name ist aber immer null.On net461 or later, the callback is invoked but the name is always null. name ist auch null, wenn der Client den Hostnamenparameter nicht im TLS-Handshake angibt.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Alle Websites werden in derselben Kestrel-Instanz ausgeführt.All websites run on the same Kestrel instance. Kestrel unterstützt ohne Reverseproxy keine gemeinsame IP-Adresse und keinen gemeinsamen Port für mehrere Instanzen.Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.
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;
            };
        });
    });
});

VerbindungsprotokollierungConnection logging

Rufen Sie UseConnectionLogging auf, um Protokolle auf Debugebene für die Kommunikation auf Byteebene für eine Verbindung auszugeben.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. Die Verbindungsprotokollierung ist beim Beheben von Problemen bei der Low-Level-Kommunikation hilfreich, wie z. B. bei der TLS-Verschlüsselung und bei Proxys.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Wenn UseConnectionLogging vor UseHttps platziert wird, wird der verschlüsselte Datenverkehr protokolliert.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Wenn UseConnectionLogging nach UseHttps platziert wird, wird der entschlüsselte Datenverkehr protokolliert.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

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

Binden an einen TCP-SocketBind to a TCP socket

Die Listen-Methode wird an ein TCP-Socket gebunden, und ein Lambdaausdruck einer Option lässt die Konfiguration des X.509-Zertifikats zu:The Listen method binds to a TCP socket, and an options lambda permits X.509 certificate configuration:

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

Im Beispiel wird HTTPS für einen Endpunkt mit ListenOptions konfiguriert.The example configures HTTPS for an endpoint with ListenOptions. Verwenden Sie die gleiche API zum Konfigurieren anderer Kestrel-Einstellungen für bestimmte Endpunkte.Use the same API to configure other Kestrel settings for specific endpoints.

Unter Windows können selbstsignierte Zertifikate mit dem PowerShell-Cmdlet „New-SelfSignedCertificate“ erstellt werden.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Ein nicht unterstütztes Beispiel finden Sie unter UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

Unter macOS, Linux und Windows können Zertifikate mithilfe von OpenSSL erstellt werden.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Binden an einen Unix-SocketBind to a Unix socket

Wie in diesem Beispiel dargestellt, lauschen Sie an einem Unix-Socket mit ListenUnixSocket, um eine verbesserte Leistung mit Nginx zu erzielen:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • Legen Sie den Eintrag server > location > proxy_pass in der Nginx-Konfigurationsdatei auf http://unix:/tmp/{KESTREL SOCKET}:/; fest.In the Nginx configuration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} ist der Name des für ListenUnixSocket bereitgestellten Socket (zum Beispiel kestrel-test.sock im vorherigen Beispiel).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Stellen Sie sicher, dass der Socket von Nginx beschreibbar ist (z. B. chmod go+w /tmp/kestrel-test.sock).Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

Port 0Port 0

Wenn die Portnummer 0 angegeben wird, wird Kestrel dynamisch an einen verfügbaren Port gebunden.When the port number 0 is specified, Kestrel dynamically binds to an available port. Im folgenden Beispiel wird veranschaulicht, wie bestimmt werden kann, für welchen Port Kestrel zur Laufzeit eine Bindung erstellt hat:The following example shows how to determine which port Kestrel actually bound at runtime:

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

Wenn die App ausgeführt wird, gibt das Ausgabefenster der Konsole den dynamischen Port an, über den die App erreicht werden kann:When the app is run, the console window output indicates the dynamic port where the app can be reached:

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

EinschränkungenLimitations

Konfigurieren Sie Endpunkte mithilfe der folgenden Ansätze:Configure endpoints with the following approaches:

  • UseUrls
  • Befehlszeilenargument --urls--urls command-line argument
  • Hostkonfigurationsschlüssel urlsurls host configuration key
  • Umgebungsvariable ASPNETCORE_URLSASPNETCORE_URLS environment variable

Diese Methoden sind nützlich, wenn Ihr Code mit anderen Servern als Kestrel funktionieren soll.These methods are useful for making code work with servers other than Kestrel. Beachten Sie jedoch die folgenden Einschränkungen:However, be aware of the following limitations:

  • HTTPS kann nicht mit diesen Ansätzen verwendet werden, außer ein Standardzertifikat wird in der HTTPS-Endpunktkonfiguration angegeben (z.B. wenn Sie wie zuvor in diesem Artikel gezeigt die KestrelServerOptions-Konfiguration oder eine Konfigurationsdatei verwenden).HTTPS can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint configuration (for example, using KestrelServerOptions configuration or a configuration file as shown earlier in this topic).
  • Wenn die Ansätze Listen und UseUrls gleichzeitig verwendet werden, überschreiben die Listen-Endpunkte die UseUrls-Endpunkte.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

IIS-EndpunktkonfigurationIIS endpoint configuration

Bei der Verwendung von IIS werden die URL-Bindungen für IIS-Überschreibungsbindungen durch Listen oder UseUrls festgelegt.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Weitere Informationen finden Sie im Artikel ASP.NET Core-Modul.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

Die Protocols-Eigenschaft richtet die HTTP-Protokolle (HttpProtocols) ein, die für einen Verbindungsendpunkt oder für den Server aktiviert werden.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Weisen Sie der Protocols-Eigenschaft einen Wert aus der HttpProtocols-Enumeration zu.Assign a value to the Protocols property from the HttpProtocols enum.

HttpProtocols-EnumerationswertHttpProtocols enum value Zulässiges VerbindungsprotokollConnection protocol permitted
Http1 Nur HTTP/1.1.HTTP/1.1 only. Kann mit oder ohne TLS verwendet werden.Can be used with or without TLS.
Http2 Nur HTTP/2.HTTP/2 only. Kann nur ohne TLS verwendet werden, wenn der Client einen Vorabkenntnis-Modus unterstützt.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 und HTTP/2.HTTP/1.1 and HTTP/2. Für HTTP/2 muss der Client HTTP/2 im TLS ALPN-Handshake (Application-Layer Protocol Negotiation) auswählen, andernfalls wird standardmäßig eine HTTP/1.1 verwendet.HTTP/2 requires the client to select HTTP/2 in the TLS Application-Layer Protocol Negotiation (ALPN) handshake; otherwise, the connection defaults to HTTP/1.1.

Der Standardwert von ListenOptions.Protocols ist für alle Endpunkte HttpProtocols.Http1AndHttp2.The default ListenOptions.Protocols value for any endpoint is HttpProtocols.Http1AndHttp2.

TLS-Einschränkungen für HTTP/2:TLS restrictions for HTTP/2:

  • TLS Version 1.2 oder höherTLS version 1.2 or later
  • Erneute Aushandlung deaktiviertRenegotiation disabled
  • Komprimierung deaktiviertCompression disabled
  • Minimale Größen für Austausch von flüchtigen Schlüsseln:Minimum ephemeral key exchange sizes:
    • ECDHE (Elliptic Curve Diffie-Hellman) [RFC4492]: mindestens 224 BitsElliptic curve Diffie-Hellman (ECDHE) [RFC4492]: 224 bits minimum
    • DHE (Finite Field Diffie-Hellman) [TLS12]: mindestens 2048 BitsFinite field Diffie-Hellman (DHE) [TLS12]: 2048 bits minimum
  • Verschlüsselungssammlung nicht verbotenCipher suite not prohibited.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] mit der elliptischen P-256-Kurve [FIPS186] wird standardmäßig unterstützt.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

Das folgende Beispiel erlaubt HTTP/1.1- und HTTP/2-Verbindungen an Port 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Die Verbindungen werden durch TLS mit einem bereitgestellten Zertifikat geschützt:Connections are secured by TLS with a supplied certificate:

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

Verwenden Sie Verbindungsmiddleware, um TLS-Handshakes auf Verbindungsbasis für bestimmte Verschlüsselungen zu filtern, falls erforderlich.Use Connection Middleware to filter TLS handshakes on a per-connection basis for specific ciphers if required.

Im folgenden Beispiel wird NotSupportedException für jeden Verschlüsselungsalgorithmus ausgelöst, der von der App nicht unterstützt wird.The following example throws NotSupportedException for any cipher algorithm that the app doesn't support. Alternativ können Sie ITlsHandshakeFeature.CipherAlgorithm definieren und mit einer Liste zulässiger Verschlüsselungssammlungen vergleichen.Alternatively, define and compare ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher suites.

Es wird keine Verschlüsselung mit einem CipherAlgorithmType.Null-Verschlüsselungsalgorithmus verwendet.No encryption is used with a CipherAlgorithmType.Null cipher algorithm.

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

Die Verbindungsfilterung kann auch über einen IConnectionBuilder-Lambdaausdruck konfiguriert werden:Connection filtering can also be configured via an IConnectionBuilder lambda:

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

Unter Linux kann CipherSuitesPolicy zum Filtern von TLS-Handshakes auf Verbindungsbasis verwendet werden:On Linux, CipherSuitesPolicy can be used to filter TLS handshakes on a per-connection basis:

// 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,
                    // ...
                });
        };
    });
});

Festlegen des Protokolls aus der KonfigurationSet the protocol from configuration

CreateDefaultBuilder ruft serverOptions.Configure(context.Configuration.GetSection("Kestrel")) standardmäßig zum Laden der Kestrel-Konfiguration auf.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

Das folgende appsettings.json-Beispiel richtet HTTP/1.1 als Standardverbindungsprotokoll für alle Endpunkte ein:The following appsettings.json example establishes HTTP/1.1 as the default connection protocol for all endpoints:

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

Das folgende appsettings.json-Beispiel richtet HTTP/1.1 als Verbindungsprotokoll für einen bestimmten Endpunkt ein:The following appsettings.json example establishes the HTTP/1.1 connection protocol for a specific endpoint:

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

Protokolle, die in Code angegeben werden, setzen Werte außer Kraft, der durch die Konfiguration festgelegt werden.Protocols specified in code override values set by configuration.

TransportkonfigurationTransport configuration

Für Projekte, die den Einsatz von Libuv (UseLibuv) erfordern:For projects that require the use of Libuv (UseLibuv):

  • Fügen Sie für das Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv-Paket eine Abhängigkeit auf die Projektdatei der App hinzu:Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's project file:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                       Version="{VERSION}" />
    
  • UseLibuv auf IWebHostBuilder aufrufen:Call UseLibuv on the 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>();
                 });
    }
    

URL-PräfixeURL prefixes

Bei der Verwendung von UseUrls, dem Befehlszeilenargument --urls, dem Hostkonfigurationsschlüssel urls oder der Umgebungsvariable ASPNETCORE_URLS können die URL-Präfixe in den folgenden Formaten vorliegen.When using UseUrls, --urls command-line argument, urls host configuration key, or ASPNETCORE_URLS environment variable, the URL prefixes can be in any of the following formats.

Nur HTTP-URL-Präfixe sind gültig.Only HTTP URL prefixes are valid. Kestrel unterstützt HTTPS nicht beim Konfigurieren von URL-Bindungen mit UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • IPv4-Adresse mit PortnummerIPv4 address with port number

    http://65.55.39.10:80/
    

    Bei 0.0.0.0 handelt es sich um einen Sonderfall, für den eine Bindung an alle IPv4-Adressen erfolgt.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • IPv6-Adresse mit PortnummerIPv6 address with port number

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

    [::] stellt das Äquivalent von IPv6 zu 0.0.0.0 für IPv4 dar.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Hostname mit PortnummerHost name with port number

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

    Hostnamen, * und + sind nicht spezifisch.Host names, *, and +, aren't special. Alle Elemente, die nicht als gültige IP-Adresse oder localhost erkannt werden, werden an alle IPv4- und IPv6-IP-Adressen gebunden.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Verwenden Sie HTTP.sys oder einen Reverseproxyserver zum Binden verschiedener Hostnamen an verschiedene ASP.NET Core-Apps auf demselben Port, z.B. IIS, Nginx oder Apache.To bind different host names to different ASP.NET Core apps on the same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.

    Warnung

    Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.Hosting in a reverse proxy configuration requires host filtering.

  • localhost-Hostname mit Portnummer oder Loopback-IP mit PortnummerHost localhost name with port number or loopback IP with port number

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

    Wenn localhost angegeben ist, versucht Kestrel, eine Bindung zu IPv4- und IPv6-Loopback-Schnittstellen zu erstellen.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Wenn der erforderliche Port von einem anderen Dienst auf einer der Loopback-Schnittstellen verwendet wird, tritt beim Starten von Kestrel ein Fehler auf.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Wenn eine der Loopback-Schnittstellen aus anderen Gründen nicht verfügbar ist (meistens durch die fehlende Unterstützung von IPv6), protokolliert Kestrel eine Warnung.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Host-FilterungHost filtering

Obwohl Kestrel die Konfiguration basierend auf Präfixe wie http://example.com:5000 unterstützt, ignoriert Kestrel den Hostnamen weitgehend.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. Der Host localhost ist ein Sonderfall, der für die Bindung an Loopback-Adressen verwendet wird.Host localhost is a special case used for binding to loopback addresses. Jeder Host, der keine explizite IP-Adresse ist, wird an alle öffentlichen IP-Adressen gebunden.Any host other than an explicit IP address binds to all public IP addresses. Host-Header werden nicht überprüft.Host headers aren't validated.

Verwenden Sie Middleware zum Filtern von Hosts, um dieses Problem zu umgehen.As a workaround, use Host Filtering Middleware. Die Middleware zum Filtern von Hosts wird durch das Microsoft.AspNetCore.HostFiltering-Paket bereitgestellt, das implizit für ASP.NET Core-Apps zur Verfügung steht.Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is implicitly provided for ASP.NET Core apps. Die Middleware wird von CreateDefaultBuilder hinzugefügt, wodurch AddHostFiltering aufgerufen wird:The middleware is added by CreateDefaultBuilder, which calls 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>();
}

Die Middleware zum Filtern von Hosts ist standardmäßig deaktiviert.Host Filtering Middleware is disabled by default. Wenn Sie die Middleware aktivieren möchten, definieren Sie einen AllowedHosts-Schlüssel in appsettings.json/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. Der Wert ist eine durch Semikolons getrennte Liste von Hostnamen ohne Portnummern:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Hinweis

Middleware für weitergeleitete Header hat auch eine AllowedHosts-Option.Forwarded Headers Middleware also has an AllowedHosts option. Middleware für weitergeleitete Header und Middleware zum Filtern von Hosts besitzen ähnliche Funktionen für unterschiedliche Szenarios.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Legen Sie AllowedHosts mit Middleware für weitergeleitete Header fest, wenn der Host-Header beim Weiterleiten von Anforderungen mit einem Reverseproxyserver oder einem Lastenausgleichsmodul nicht beibehalten wird.Setting AllowedHosts with Forwarded Headers Middleware is appropriate when the Host header isn't preserved while forwarding requests with a reverse proxy server or load balancer. Legen Sie AllowedHosts mit Middleware zum Filtern von Hosts fest, wenn Kestrel als öffentlicher Edgeserver verwendet oder der Host-Header direkt weitergeleitet wird.Setting AllowedHosts with Host Filtering Middleware is appropriate when Kestrel is used as a public-facing edge server or when the Host header is directly forwarded.

Weitere Informationen zu Middleware für weitergeleitete Header finden Sie unter Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und Lastenausgleich.For more information on Forwarded Headers Middleware, see Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und Lastenausgleich.

Einführung in Kestrel, dem plattformübergreifenden Webserver für ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel ist der Webserver, der standardmäßig in ASP.NET Core-Projektvorlagen enthalten ist.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel unterstützt die folgenden Szenarios:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Nicht transparente Upgrades, die zum Aktivieren von WebSockets verwendet werdenOpaque upgrade used to enable WebSockets
  • Unix-Sockets für eine hohe Leistung im Hintergrund von NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (außer unter macOS†)HTTP/2 (except on macOS†)

†HTTP/2 wird unter macOS in einem zukünftigen Release unterstützt.†HTTP/2 will be supported on macOS in a future release.

Kestrel wird auf allen Plattformen und für alle Versionen unterstützt, die .NET Core unterstützt.Kestrel is supported on all platforms and versions that .NET Core supports.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

HTTP/2-UnterstützungHTTP/2 support

HTTP/2 ist für ASP.NET Core-Apps verfügbar, wenn die folgenden Basisanforderungen erfüllt sind:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Betriebssystem†Operating system†
    • Windows Server 2016/Windows 10 oder höher‡Windows Server 2016/Windows 10 or later‡
    • Linux mit OpenSSL 1.0.2 oder höher (z.B. Ubuntu 16.04 oder höher)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Zielframework: .NET Core 2.2 oder höherTarget framework: .NET Core 2.2 or later
  • ALPN-Verbindung (Application-Layer Protocol Negotiation)Application-Layer Protocol Negotiation (ALPN) connection
  • TLS 1.2-Verbindung oder höherTLS 1.2 or later connection

†HTTP/2 wird unter macOS in einem zukünftigen Release unterstützt.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel bietet eingeschränkte Unterstützung für HTTP/2 unter Windows Server 2012 R2 und Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Die Unterstützung ist eingeschränkt, weil die Liste der unterstützten TLS-Verschlüsselungssammlungen unter diesen Betriebssystemen begrenzt ist.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Zum Sichern von TLS-Verbindungen ist möglicherweise ein durch einen Elliptic Curve Digital Signature Algorithm (ECDSA) generiertes Zertifikat erforderlich.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Wenn eine HTTP/2-Verbindung hergestellt wurde, meldet HttpRequest.ProtocolHTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 ist standardmäßig deaktiviert.HTTP/2 is disabled by default. Weitere Informationen zur Konfiguration finden Sie in den Abschnitten Kestrel-Optionen und ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Verwenden von Kestrel mit einem ReverseproxyWhen to use Kestrel with a reverse proxy

Kestrel kann eigenständig oder mit einem Reverseproxyserver wie z.B. Internet Information Services (IIS), Nginx oder Apache verwendet werden.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Ein Reverseproxyserver empfängt HTTP-Anforderungen aus dem Netzwerk und leitet diese an Kestrel weiter.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel bei Verwendung als Webserver mit direkter Internetverbindung:Kestrel used as an edge (Internet-facing) web server:

Kestrel kommuniziert direkt und ohne Reverseproxyserver mit dem Internet

Kestrel bei Verwendung in einer Reverseproxykonfiguration:Kestrel used in a reverse proxy configuration:

Kestrel kommuniziert indirekt mit dem Internet über einen Reverseproxyserver wie IIS, Nginx oder Apache

Jede der beiden Konfigurationen – mit oder ohne einen Reverseproxyserver – stellt eine unterstützte Hostingkonfiguration dar.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Bei Verwendung als Edgeserver ohne Reverseproxyserver unterstützt Kestrel die gemeinsame Nutzung der gleichen IP-Adresse und des gleichen Ports durch mehrere Prozesse nicht.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Wenn Kestrel für das Lauschen an einem Port konfiguriert ist, verarbeitet Kestrel den gesamten Datenverkehr für diesen Port unabhängig von den Host-Headern der Anforderungen.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Ein Reverseproxy, der Ports freigeben kann, kann Anforderungen an Kestrel über eine eindeutige IP und einen eindeutigen Port weiterleiten.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Auch wenn kein Reverseproxyserver erforderlich ist, kann die Verwendung eines solchen empfehlenswert sein.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Für einen Reverseproxy gilt Folgendes:A reverse proxy:

  • Er kann die verfügbar gemachten öffentlichen Oberflächen der von ihm gehosteten Apps einschränken.Can limit the exposed public surface area of the apps that it hosts.
  • Er stellt eine zusätzliche Ebene für Konfiguration und Schutz bereit.Provide an additional layer of configuration and defense.
  • Er lässt sich besser in die vorhandene Infrastruktur integrieren.Might integrate better with existing infrastructure.
  • Er vereinfacht die Konfiguration von Lastenausgleich und sicherer Kommunikation (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Nur der Reverseproxyserver erfordert ein X.509-Zertifikat, und dieser Server kann mit den Servern der App im internen Netzwerk über einfaches HTTP kommunizieren.Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

Warnung

Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.Hosting in a reverse proxy configuration requires host filtering.

Verwenden von Kestrel in ASP.NET Core-AppsHow to use Kestrel in ASP.NET Core apps

Das Paket Microsoft.AspNetCore.Server.Kestrel ist im Metapaket Microsoft.AspNetCore.App enthalten.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

ASP.NET Core-Projektvorlagen verwenden Kestrel standardmäßig.ASP.NET Core project templates use Kestrel by default. Der Vorlagencode in Program.cs ruft CreateDefaultBuilder auf, wodurch UseKestrel im Hintergrund aufgerufen wird.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

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

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Weitere Informationen zum CreateDefaultBuilder und zum Erstellen des Hosts finden Sie im Abschnitt Einrichten eines Hosts von ASP.NET Core-Webhost.For more information on CreateDefaultBuilder and building the host, see the Set up a host section of ASP.NET Core-Webhost.

Um zusätzliche Konfiguration nach dem Aufruf von CreateDefaultBuilder bereitzustellen, verwenden Sie ConfigureKestrel:To provide additional configuration after calling CreateDefaultBuilder, use ConfigureKestrel:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            // Set properties and call methods on serverOptions
        });

Wenn die App CreateDefaultBuilder nicht aufruft, um den Host einzurichten, rufen Sie UseKestrel auf, bevor Sie ConfigureKestrel aufrufen:If the app doesn't call CreateDefaultBuilder to set up the host, call UseKestrel before calling ConfigureKestrel:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            // Set properties and call methods on serverOptions
        })
        .Build();

    host.Run();
}

Kestrel-OptionenKestrel options

Der Kestrel-Webserver verfügt über einschränkende Konfigurationsoptionen, die besonders nützlich bei Bereitstellungen mit Internetzugriff sind.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Legen Sie Einschränkungen für die Limits-Eigenschaft der KestrelServerOptions-Klasse fest.Set constraints on the Limits property of the KestrelServerOptions class. Die Limits-Eigenschaft enthält eine Instanz der KestrelServerLimits-Klasse.The Limits property holds an instance of the KestrelServerLimits class.

In den folgenden Beispielen wird der Microsoft.AspNetCore.Server.Kestrel.Core-Namespace verwendet:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Kestrel-Optionen, die in den folgenden Beispielen in C#-Code konfiguriert sind, können auch mit einem Konfigurationsanbieter festgelegt werden.Kestrel options, which are configured in C# code in the following examples, can also be set using a configuration provider. Beispielsweise kann der Dateikonfigurationsanbieter die Kestrel-Konfiguration aus einer appsettings.json- oder appsettings.{Umgebung}.json-Datei laden:For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

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

Verwenden Sie einen der folgenden Ansätze:Use one of the following approaches:

  • Konfigurieren Sie Kestrel in Startup.ConfigureServices:Configure Kestrel in Startup.ConfigureServices:

    1. Fügen Sie eine Instanz von IConfiguration in die Startup-Klasse ein.Inject an instance of IConfiguration into the Startup class. Im folgenden Beispiel wird davon ausgegangen, dass die eingefügte Konfiguration der Configuration-Eigenschaft zugewiesen wird.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. Laden Sie in Startup.ConfigureServices den Abschnitt Kestrel der Konfiguration in die Konfiguration von Kestrel:In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:

      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)
          {
              ...
          }
      }
      
  • Konfigurieren Sie Kestrel beim Erstellen des Hosts:Configure Kestrel when building the host:

    Laden Sie in Program.cs den Abschnitt Kestrel der Konfiguration in die Konfiguration von Kestrel:In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

    // using Microsoft.Extensions.DependencyInjection;
    
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureServices((context, services) =>
            {
                services.Configure<KestrelServerOptions>(
                    context.Configuration.GetSection("Kestrel"));
            })
            .UseStartup<Startup>();
    

Beide vorangehenden Ansätze funktionieren mit jedem Konfigurationsanbieter.Both of the preceding approaches work with any configuration provider.

Keep-Alive-TimeoutKeep-alive timeout

KeepAliveTimeout

Ruft das Keep-Alive-Timeout ab oder legt es fest.Gets or sets the keep-alive timeout. Standardwert: 2 Minuten.Defaults to 2 minutes.

.ConfigureKestrel((context, 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);
});

Maximale Anzahl der ClientverbindungenMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Die maximale Anzahl von gleichzeitig geöffneten TCP-Verbindungen kann mithilfe von folgendem Code für die gesamte App festgelegt werden:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

.ConfigureKestrel((context, 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);
});

Es gibt einen separaten Grenzwert für Verbindungen, die von HTTP oder HTTPS auf ein anderes Protokoll aktualisiert wurden (z.B. auf eine WebSockets-Anforderung).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Nachdem eine Verbindung aktualisiert wurde, zählt diese nicht mehr für den MaxConcurrentConnections-Grenzwert.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

.ConfigureKestrel((context, 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);
});

Die maximale Anzahl von Verbindungen ist standardmäßig nicht begrenzt (NULL).The maximum number of connections is unlimited (null) by default.

Maximale Größe des AnforderungstextsMaximum request body size

MaxRequestBodySize

Die maximale Größe des Anforderungstexts beträgt standardmäßig 30.000.000 Byte, also ungefähr 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Die empfohlene Methode zur Außerkraftsetzung des Grenzwerts in einer ASP.NET Core-MVC-App besteht im Verwenden des RequestSizeLimitAttribute-Attributs in einer Aktionsmethode:The recommended approach to override the limit in an ASP.NET Core MVC app is to use the RequestSizeLimitAttribute attribute on an action method:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Im folgenden Beispiel wird veranschaulicht, wie die Einschränkungen auf jeder Anforderung für die App konfiguriert werden:Here's an example that shows how to configure the constraint for the app on every request:

.ConfigureKestrel((context, 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);
});

Außer Kraft setzen der Einstellung für eine bestimmte Anforderung in Middleware:Override the setting on a specific request in 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));
    }

Eine Ausnahme wird ausgelöst, wenn die App den Grenzwert einer Anforderung konfiguriert, nachdem die App bereits mit dem Lesen der Anforderung begonnen hat.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Es gibt eine IsReadOnly-Eigenschaft, die angibt, wenn sich die MaxRequestBodySize-Eigenschaft im schreibgeschützten Zustand befindet, also wenn der Grenzwert nicht mehr konfiguriert werden kann.There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

Wenn eine App prozessextern hinter dem ASP.NET Core-Modul ausgeführt wird, ist das Größenlimit von Kestrel für Anforderungstext deaktiviert, weil IIS dieses Limit bereits festlegt.When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit is disabled because IIS already sets the limit.

Minimale Datenrate des AnforderungstextsMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel überprüft sekündlich, ob Daten mit der angegebenen Rate in Bytes/Sekunde eingehen.Kestrel checks every second if data is arriving at the specified rate in bytes/second. 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ährenddessen nicht überprüft.If the rate drops below the minimum, the connection is timed out. The grace period is the amount of time that Kestrel gives the client to increase its send rate up to the minimum; the rate isn't checked during that time. Diese Toleranzperiode beugt dem Trennen von Verbindungen vor, die Daten aufgrund eines langsamen TCP-Starts anfänglich mit einer niedrigen Rate senden.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

Die mindestens erforderliche Rate beträgt standardmäßig 240 Bytes/Sekunde mit einer Toleranzperiode von 5 Sekunden.The default minimum rate is 240 bytes/second with a 5 second grace period.

Für die Antwort gilt ebenfalls eine mindestens erforderliche Rate.A minimum rate also applies to the response. Der Code zum Festlegen des Grenzwerts für Anforderung und Antwort ist abgesehen von RequestBody oder Response in den Namen von Eigenschaften und Schnittstelle identisch.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

In diesem Beispiel wird veranschaulicht, wie Sie die mindestens erforderlichen Datenraten in Program.cs konfigurieren:Here's an example that shows how to configure the minimum data rates in Program.cs:

.ConfigureKestrel((context, 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);
});

Außer Kraft setzen des minimalen Ratenlimits pro Anforderung in Middleware:Override the minimum rate limits per request in 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));
    }

Keines dieser Ratenfeatures, auf die im vorherigen Beispiel verwiesen wird, ist in HttpContext.Features für HTTP/2-Anforderungen vorhanden, da die Änderung von Ratenlimits für jede Anforderung aufgrund der Unterstützung für Anforderungsmultiplexing des Protokolls nicht für HTTP/2 unterstützt wird.Neither rate feature referenced in the prior sample are present in HttpContext.Features for HTTP/2 requests because modifying rate limits on a per-request basis isn't supported for HTTP/2 due to the protocol's support for request multiplexing. Serverweite Ratenlimits, die über KestrelServerOptions.Limits konfiguriert sind, gelten auch für HTTP/1.x- und HTTP/2-Verbindungen.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Timeout für AnforderungsheaderRequest headers timeout

RequestHeadersTimeout

Ruft die maximale Zeitspanne ab, während der der Server Anforderungsheader empfängt, oder legt diese fest.Gets or sets the maximum amount of time the server spends receiving request headers. Der Standardwert beträgt 30 Sekunden.Defaults to 30 seconds.

.ConfigureKestrel((context, 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);
});

Maximale Datenströme pro VerbindungMaximum streams per connection

Http2.MaxStreamsPerConnection schränkt die Anzahl gleichzeitiger Anforderungsdatenströme pro HTTP/2-Verbindung ein.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Überschüssige Datenströme werden zurückgewiesen.Excess streams are refused.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.MaxStreamsPerConnection = 100;
        });

Der Standardwert ist 100.The default value is 100.

Größe der HeadertabelleHeader table size

Der HPACK-Decoder dekomprimiert HTTP-Header für HTTP/2-Verbindungen.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize schränkt die Größe der Headerkomprimierungstabelle ein, die der HPACK-Decoder verwendet.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. Der Wert wird in Oktetten bereitgestellt und muss größer als null (0) sein.The value is provided in octets and must be greater than zero (0).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.HeaderTableSize = 4096;
        });

Der Standardwert ist 4096.The default value is 4096.

Maximale FramegrößeMaximum frame size

Http2.MaxFrameSize gibt die maximale Größe der zu empfangenden HTTP/2-Verbindungsframenutzlast an.Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. Der Wert wird in Oktetten bereitgestellt und muss zwischen 2^14 (16.384) und 2^24-1 (16.777.215) liegen.The value is provided in octets and must be between 2^14 (16,384) and 2^24-1 (16,777,215).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.MaxFrameSize = 16384;
        });

Der Standardwert ist 2^14 (16.384).The default value is 2^14 (16,384).

Maximale Größe des AnforderungsheadersMaximum request header size

Http2.MaxRequestHeaderFieldSize gibt die maximal zulässige Größe in Oktetten der Anforderungsheaderwerte an.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Dieser Grenzwert gilt zusammen für den Namen und Wert in komprimierten und nicht komprimierten Darstellungen.This limit applies to both name and value together in their compressed and uncompressed representations. Der Wert muss größer als 0 (null) sein.The value must be greater than zero (0).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
        });

Der Standardwert ist 8.192.The default value is 8,192.

Anfangsfenstergröße der VerbindungInitial connection window size

Http2.InitialConnectionWindowSize gibt die maximalen Anforderungstextdaten in Byte an, die der Server auf einmal für alle Anforderungen (Streams) pro Verbindung aggregiert.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Anforderungen werden auch durch Http2.InitialStreamWindowSize beschränkt.Requests are also limited by Http2.InitialStreamWindowSize. Der Wert muss größer als oder gleich 65.535 und kleiner als 2^31 (2.147.483.648) sein.The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.InitialConnectionWindowSize = 131072;
        });

Der Standardwert ist 128 KB (131.072).The default value is 128 KB (131,072).

Anfangsfenstergröße des StreamsInitial stream window size

Http2.InitialStreamWindowSize gibt die maximalen Anforderungstextdaten in Byte an, die der Server auf einmal pro Anforderung (Stream) puffert.Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Anforderungen werden auch durch Http2.InitialStreamWindowSize beschränkt.Requests are also limited by Http2.InitialStreamWindowSize. Der Wert muss größer als oder gleich 65.535 und kleiner als 2^31 (2.147.483.648) sein.The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.InitialStreamWindowSize = 98304;
        });

Der Standardwert ist 96 KB (98.304).The default value is 96 KB (98,304).

Synchrone E/A-VorgängeSynchronous I/O

AllowSynchronousIO steuert, ob für Anforderung und Antwort synchrone E/A-Vorgänge zulässig sind.AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. Der Standardwert ist true.The default value is true.

Warnung

Sehr viele blockierende synchrone E/A-Vorgänge können zu einem Ressourcenmangel im Threadpool führen, wodurch die App nicht mehr reagiert.A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Aktivieren Sie AllowSynchronousIO nur bei Verwendung einer Bibliothek, die asynchrone E/A-Vorgänge nicht unterstützt.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous I/O.

Das folgende Beispiel aktiviert synchrone E/A-Vorgänge:The following example enables synchronous I/O:

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

Weitere Informationen zu anderen Kestrel-Optionen und -Einschränkungen finden Sie unter:For information about other Kestrel options and limits, see:

EndpunktkonfigurationEndpoint configuration

Standardmäßig wird ASP.NET Core an Folgendes gebunden:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (wenn ein lokales Entwicklungszertifikat vorhanden ist)https://localhost:5001 (when a local development certificate is present)

Verwenden Sie Folgendes zum Angeben der URLs:Specify URLs using the:

  • Die Umgebungsvariable ASPNETCORE_URLSASPNETCORE_URLS environment variable.
  • Das Befehlszeilenargument --urls--urls command-line argument.
  • Den Hostkonfigurationsschlüssel urlsurls host configuration key.
  • Die Erweiterungsmethode UseUrlsUseUrls extension method.

Der Wert, der mit diesen Ansätzen angegeben wird, kann mindestens ein HTTP- oder HTTPS-Endpunkt sein (HTTPS wenn ein Standardzertifikat verfügbar ist).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Konfigurieren Sie den Wert als eine durch Semikolons getrennte Liste (z.B. "Urls": "http://localhost:8000;http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Weitere Informationen zu diesen Ansätzen finden Sie unter Server-URLs und Außerkraftsetzen der Konfiguration.For more information on these approaches, see Server URLs and Override configuration.

Ein Entwicklungszertifikat wird erstellt:A development certificate is created:

Einige Browser erfordern, dass Sie die explizite Berechtigung erteilen, dem lokalen Entwicklungszertifikat zu vertrauen.Some browsers require granting explicit permission to trust the local development certificate.

Projektvorlagen konfigurieren Apps, damit sie standardmäßig auf HTTPS ausgeführt werden und die HTTPS-Umleitung und HSTS-Unterstützung enthalten.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Rufen Sie die Listen- oder ListenUnixSocket-Methode unter KestrelServerOptions auf, um URL-Präfixe und Ports für Kestrel zu konfigurieren.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, das Befehlszeilenargument --urls, der Hostkonfigurationsschlüssel urls und die Umgebungsvariable ASPNETCORE_URLS funktionieren ebenfalls, verfügen jedoch über Einschränkungen, die im Verlauf dieses Abschnitts erläutert werden (Ein Standardzertifikat muss für die HTTPS-Endpunktkonfiguration verfügbar sein).UseUrls, the --urls command-line argument, urls host configuration key, and the ASPNETCORE_URLS environment variable also work but have the limitations noted later in this section (a default certificate must be available for HTTPS endpoint configuration).

KestrelServerOptions-Konfiguration:KestrelServerOptions configuration:

ConfigureEndpointDefaults(Action<ListenOptions>)ConfigureEndpointDefaults(Action<ListenOptions>)

Gibt die Konfiguration von Action zum Ausführen von jedem angegebenen Endpunkt an.Specifies a configuration Action to run for each specified endpoint. Mehrmalige Aufrufe von ConfigureEndpointDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });
        });

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureEndpointDefaults erstellt werden, werden die Standardwerte nicht angewendet.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Gibt die Konfiguration von Action zum Ausführen von jedem HTTPS-Endpunkt an.Specifies a configuration Action to run for each HTTPS endpoint. Mehrmalige Aufrufe von ConfigureHttpsDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                // certificate is an X509Certificate2
                listenOptions.ServerCertificate = certificate;
            });
        });

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureHttpsDefaults erstellt werden, werden die Standardwerte nicht angewendet.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Configure(IConfiguration)Configure(IConfiguration)

Erstellt ein Konfigurationsladeprogramm für das Einrichten von Kestrel, was IConfiguration als Eingabe erfordert.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. Die Konfiguration muss auf den Konfigurationsabschnitt für Kestrel festgelegt werden.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Konfiguriert Kestrel zur Verwendung von HTTPS.Configure Kestrel to use HTTPS.

ListenOptions.UseHttps-Erweiterungen:ListenOptions.UseHttps extensions:

  • UseHttps: Hiermit wird Kestrel zur Verwendung von HTTPS mit dem Standardzertifikat konfiguriert.UseHttps: Configure Kestrel to use HTTPS with the default certificate. Löst eine Ausnahme aus, wenn kein Standardzertifikat konfiguriert ist.Throws an exception if no default certificate is configured.
  • 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-Parameter:ListenOptions.UseHttps parameters:

  • filename entspricht dem Pfad und Dateinamen einer Zertifikatdatei relativ zu dem Verzeichnis, das die Inhaltsdateien der App enthält.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password ist das für den Zugriff auf die X.509-Zertifikatsdaten erforderliche Kennwort.password is the password required to access the X.509 certificate data.
  • configureOptions ist eine Action zum Konfigurieren von HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Gibt ListenOptions zurück.Returns the ListenOptions.
  • storeName ist der Zertifikatspeicher, aus dem das Zertifikat geladen wird.storeName is the certificate store from which to load the certificate.
  • subject ist der Name des Antragstellers für das Zertifikat.subject is the subject name for the certificate.
  • allowInvalid gibt an, ob ungültige Zertifikate berücksichtigt werden sollten, z.B. selbstsignierte Zertifikate.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location ist der Speicherort, aus dem das Zertifikat geladen wird.location is the store location to load the certificate from.
  • serverCertificate ist das X.509-Zertifikat.serverCertificate is the X.509 certificate.

In der Produktion muss HTTPS explizit konfiguriert sein.In production, HTTPS must be explicitly configured. Zumindest muss ein Standardzertifikat angegeben werden.At a minimum, a default certificate must be provided.

Die im Folgenden beschriebenen unterstützten Konfigurationen:Supported configurations described next:

  • Keine KonfigurationNo configuration
  • Ersetzen des Standardzertifikats aus der KonfigurationReplace the default certificate from configuration
  • Ändern des Standards im CodeChange the defaults in code

Keine KonfigurationNo configuration

Kestrel überwacht http://localhost:5000 und https://localhost:5001 (wenn ein Standardzertifikat verfügbar ist).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Ersetzen des Standardzertifikats aus der KonfigurationReplace the default certificate from configuration

CreateDefaultBuilder ruft Configure(context.Configuration.GetSection("Kestrel")) standardmäßig zum Laden der Kestrel-Konfiguration auf.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Ein Standardkonfigurationsschema für HTTPS-App-Einstellungen ist für Kestrel verfügbar.A default HTTPS app settings configuration schema is available for Kestrel. Konfigurieren Sie mehrere Endpunkte, einschließlich der zu verwendenden URLs und Zertifikate aus einer Datei auf dem Datenträger oder einem Zertifikatspeicher.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

Die Vorgehensweise im folgenden appsettings.json-Beispiel:In the following appsettings.json example:

  • Legen Sie AllowInvalid auf true fest, um die Verwendung von ungültigen Zertifikaten zu erlauben (z.B. selbstsignierte Zertifikate).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Jeder HTTPS-Endpunkt, der kein Zertifikat angibt (im folgenden Beispiel HttpsDefaultCert), greift auf das unter Zertifikate > Standard festgelegte Zertifikat oder das Entwicklungszertifikat zurück.Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls back to the cert defined under Certificates > Default or the development certificate.
{
  "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>"
      }
    }
  }
}

Alternativ zur Verwendung von Pfad und Kennwort für alle Zertifikatknoten können Sie das Zertifikat mithilfe von Zertifikatspeicherfeldern angeben.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Das Zertifikat unter Zertifikate > Standard kann beispielweise wie folgt angegeben werden:For example, the Certificates > Default certificate can be specified as:

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

Schema-Hinweise:Schema notes:

  • Bei den Namen der Endpunkte wird die Groß-/Kleinschreibung nicht beachtet.Endpoints names are case-insensitive. Zum Beispiel sind HTTPS und Https gültig.For example, HTTPS and Https are valid.
  • Der Parameter Url ist für jeden Endpunkt erforderlich.The Url parameter is required for each endpoint. Das Format für diesen Parameter ist identisch mit dem allgemeinen Konfigurationsparameter Urls, mit der Ausnahme, dass er auf einen einzelnen Wert begrenzt ist.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Diese Endpunkte ersetzen die in der allgemeinen Urls-Konfiguration festgelegten Endpunkte, anstatt zu ihnen hinzuzufügen.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Endpunkte, die über Listen in Code definiert werden, werden den im Konfigurationsabschnitt definierten Endpunkten hinzugefügt.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • Der Certificate-Abschnitt ist optional.The Certificate section is optional. Wenn der Certificate-Abschnitt nicht angegeben ist, werden die in früheren Szenarios definierten Standardwerte verwendet.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Wenn keine Standardwerte verfügbar sind, löst der Server eine Ausnahme aus und startet nicht.If no defaults are available, the server throws an exception and fails to start.
  • Der Certificate-Abschnitt unterstützt die Zertifikate PfadKennwort und SubjectStore (Antragsteller–Speicher).The Certificate section supports both PathPassword and SubjectStore certificates.
  • Auf diese Weise kann eine beliebige Anzahl von Endpunkten definiert werden, solange Sie keine Portkonflikte verursachen.Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) gibt KestrelConfigurationLoader mit der Methode .Endpoint(string name, listenOptions => { }) zurück, die dazu verwendet werden kann, die Einstellungen eines Endpunkts zu ergänzen:options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

Auf KestrelServerOptions.ConfigurationLoader kann direkt zugegriffen werden, um die Iteration auf dem vorhandenen Ladeprogramm fortzusetzen, etwa auf dem von CreateDefaultBuilder bereitgestellten Ladeprogramm.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • Der Konfigurationsabschnitt ist für jeden Endpunkt in den Optionen der Methode Endpoint verfügbar, sodass benutzerdefinierte Einstellungen gelesen werden können.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Mehrere Konfigurationen können durch erneutes Aufrufen von options.Configure(context.Configuration.GetSection("{SECTION}")) mit einem anderen Abschnitt geladen werden.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Sofern Load nicht in einer vorherigen Instanz explizit aufgerufen wird, wird nur die letzte Konfiguration verwendet.Only the last configuration is used, unless Load is explicitly called on prior instances. Das Metapaket ruft Load nicht auf, sodass der Abschnitt mit der Standardkonfiguration ersetzt werden kann.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader spiegelt die API-Familie Listen von KestrelServerOptions als Endpoint-Überladungen, weshalb Code und Konfigurationsendpunkte am selben Ort konfiguriert werden können.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Diese Überladungen verwenden keine Namen und nutzen nur Standardeinstellungen aus der Konfiguration.These overloads don't use names and only consume default settings from configuration.

Ändern des Standards im CodeChange the defaults in code

ConfigureEndpointDefaults und ConfigureHttpsDefaults können zum Ändern der Standardeinstellungen für ListenOptions und HttpsConnectionAdapterOptions verwendet werden, einschließlich der Standardzertifikate, die im vorherigen Szenario festgelegt wurden.ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. ConfigureEndpointDefaults und ConfigureHttpsDefaults sollten aufgerufen werden, bevor Endpunkte konfiguriert werden.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });

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

Kestrel-Unterstützung für SNIKestrel support for SNI

Die Servernamensanzeige (SNI) kann zum Hosten mehrerer Domänen auf der gleichen IP-Adresse und dem gleichen Port verwendet werden.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Damit die Servernamensanzeige funktioniert, sendet der Client während des TLS-Handshakes den Hostnamen für die sichere Sitzung an den Server, sodass der Server das richtige Zertifikat bereitstellen kann.For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. Der Client verwendet das beigestellte Zertifikat für die verschlüsselte Kommunikation mit dem Server während der sicheren Sitzung nach dem TLS-Handshake.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel unterstützt die Servernamensanzeige über den ServerCertificateSelector-Rückruf.Kestrel supports SNI via the ServerCertificateSelector callback. Der Rückruf wird für jede Verbindung einmal aufgerufen, um der App zu ermöglichen, den Hostnamen zu überprüfen und das entsprechende Zertifikat auszuwählen.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Für die Unterstützung der Servernamensanzeige benötigen Sie Folgendes:SNI support requires:

  • Wird auf dem Zielframework netcoreapp2.1 oder höher ausgeführt.Running on target framework netcoreapp2.1 or later. In net461 oder höher, wird der Rückruf aufgerufen, name ist aber immer null.On net461 or later, the callback is invoked but the name is always null. name ist auch null, wenn der Client den Hostnamenparameter nicht im TLS-Handshake angibt.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Alle Websites werden in derselben Kestrel-Instanz ausgeführt.All websites run on the same Kestrel instance. Kestrel unterstützt ohne Reverseproxy keine gemeinsame IP-Adresse und keinen gemeinsamen Port für mehrere Instanzen.Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, 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;
                    };
                });
            });
        });

VerbindungsprotokollierungConnection logging

Rufen Sie UseConnectionLogging auf, um Protokolle auf Debugebene für die Kommunikation auf Byteebene für eine Verbindung auszugeben.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. Die Verbindungsprotokollierung ist beim Beheben von Problemen bei der Low-Level-Kommunikation hilfreich, wie z. B. bei der TLS-Verschlüsselung und bei Proxys.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Wenn UseConnectionLogging vor UseHttps platziert wird, wird der verschlüsselte Datenverkehr protokolliert.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Wenn UseConnectionLogging nach UseHttps platziert wird, wird der entschlüsselte Datenverkehr protokolliert.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

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

Binden an einen TCP-SocketBind to a TCP socket

Die Listen-Methode wird an ein TCP-Socket gebunden, und ein Lambdaausdruck einer Option lässt die Konfiguration des X.509-Zertifikats zu:The Listen method binds to a TCP socket, and an options lambda permits X.509 certificate configuration:

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

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

Im Beispiel wird HTTPS für einen Endpunkt mit ListenOptions konfiguriert.The example configures HTTPS for an endpoint with ListenOptions. Verwenden Sie die gleiche API zum Konfigurieren anderer Kestrel-Einstellungen für bestimmte Endpunkte.Use the same API to configure other Kestrel settings for specific endpoints.

Unter Windows können selbstsignierte Zertifikate mit dem PowerShell-Cmdlet „New-SelfSignedCertificate“ erstellt werden.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Ein nicht unterstütztes Beispiel finden Sie unter UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

Unter macOS, Linux und Windows können Zertifikate mithilfe von OpenSSL erstellt werden.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Binden an einen Unix-SocketBind to a Unix socket

Wie in diesem Beispiel dargestellt, lauschen Sie an einem Unix-Socket mit ListenUnixSocket, um eine verbesserte Leistung mit Nginx zu erzielen:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
});
  • Legen Sie in der Nginx-Konfigurationsdatei den Eintrag server > location > proxy_pass auf http://unix:/tmp/{KESTREL SOCKET}:/; fest.In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} ist der Name des für ListenUnixSocket bereitgestellten Socket (zum Beispiel kestrel-test.sock im vorherigen Beispiel).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Stellen Sie sicher, dass der Socket von Nginx beschreibbar ist (z. B. chmod go+w /tmp/kestrel-test.sock).Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

Port 0Port 0

Wenn die Portnummer 0 angegeben wird, wird Kestrel dynamisch an einen verfügbaren Port gebunden.When the port number 0 is specified, Kestrel dynamically binds to an available port. Im folgenden Beispiel wird veranschaulicht, wie bestimmt werden kann, für welchen Port Kestrel zur Laufzeit eine Bindung erstellt hat:The following example shows how to determine which port Kestrel actually bound at runtime:

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

Wenn die App ausgeführt wird, gibt das Ausgabefenster der Konsole den dynamischen Port an, über den die App erreicht werden kann:When the app is run, the console window output indicates the dynamic port where the app can be reached:

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

EinschränkungenLimitations

Konfigurieren Sie Endpunkte mithilfe der folgenden Ansätze:Configure endpoints with the following approaches:

  • UseUrls
  • Befehlszeilenargument --urls--urls command-line argument
  • Hostkonfigurationsschlüssel urlsurls host configuration key
  • Umgebungsvariable ASPNETCORE_URLSASPNETCORE_URLS environment variable

Diese Methoden sind nützlich, wenn Ihr Code mit anderen Servern als Kestrel funktionieren soll.These methods are useful for making code work with servers other than Kestrel. Beachten Sie jedoch die folgenden Einschränkungen:However, be aware of the following limitations:

  • HTTPS kann nicht mit diesen Ansätzen verwendet werden, außer ein Standardzertifikat wird in der HTTPS-Endpunktkonfiguration angegeben (z.B. wenn Sie wie zuvor in diesem Artikel gezeigt die KestrelServerOptions-Konfiguration oder eine Konfigurationsdatei verwenden).HTTPS can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint configuration (for example, using KestrelServerOptions configuration or a configuration file as shown earlier in this topic).
  • Wenn die Ansätze Listen und UseUrls gleichzeitig verwendet werden, überschreiben die Listen-Endpunkte die UseUrls-Endpunkte.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

IIS-EndpunktkonfigurationIIS endpoint configuration

Bei der Verwendung von IIS werden die URL-Bindungen für IIS-Überschreibungsbindungen durch Listen oder UseUrls festgelegt.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Weitere Informationen finden Sie im Artikel ASP.NET Core-Modul.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

Die Protocols-Eigenschaft richtet die HTTP-Protokolle (HttpProtocols) ein, die für einen Verbindungsendpunkt oder für den Server aktiviert werden.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Weisen Sie der Protocols-Eigenschaft einen Wert aus der HttpProtocols-Enumeration zu.Assign a value to the Protocols property from the HttpProtocols enum.

HttpProtocols-EnumerationswertHttpProtocols enum value Zulässiges VerbindungsprotokollConnection protocol permitted
Http1 Nur HTTP/1.1.HTTP/1.1 only. Kann mit oder ohne TLS verwendet werden.Can be used with or without TLS.
Http2 Nur HTTP/2.HTTP/2 only. Kann nur ohne TLS verwendet werden, wenn der Client einen Vorabkenntnis-Modus unterstützt.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 und HTTP/2.HTTP/1.1 and HTTP/2. HTTP/2 erfordert eine TLS- und ALPN-Verbindung (Application-Layer Protocol Negotiation). Andernfalls wird für die Verbindung standardmäßig HTTP/1.1 verwendet.HTTP/2 requires a TLS and Application-Layer Protocol Negotiation (ALPN) connection; otherwise, the connection defaults to HTTP/1.1.

Das Standardprotokoll ist HTTP/1.1.The default protocol is HTTP/1.1.

TLS-Einschränkungen für HTTP/2:TLS restrictions for HTTP/2:

  • TLS Version 1.2 oder höherTLS version 1.2 or later
  • Erneute Aushandlung deaktiviertRenegotiation disabled
  • Komprimierung deaktiviertCompression disabled
  • Minimale Größen für Austausch von flüchtigen Schlüsseln:Minimum ephemeral key exchange sizes:
    • ECDHE (Elliptic Curve Diffie-Hellman) [RFC4492]: mindestens 224 BitsElliptic curve Diffie-Hellman (ECDHE) [RFC4492]: 224 bits minimum
    • DHE (Finite Field Diffie-Hellman) [TLS12]: mindestens 2048 BitsFinite field Diffie-Hellman (DHE) [TLS12]: 2048 bits minimum
  • Verschlüsselungssammlung nicht gesperrtCipher suite not blocked

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] mit der elliptischen P-256-Kurve [FIPS186] wird standardmäßig unterstützt.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

Das folgende Beispiel erlaubt HTTP/1.1- und HTTP/2-Verbindungen an Port 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Die Verbindungen werden durch TLS mit einem bereitgestellten Zertifikat geschützt:Connections are secured by TLS with a supplied certificate:

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

Erstellen Sie optional eine IConnectionAdapter-Implementierung, um TLS-Handshakes auf Verbindungsbasis für bestimmte Verschlüsselungen zu filtern:Optionally create an IConnectionAdapter implementation to filter TLS handshakes on a per-connection basis for specific ciphers:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.ConnectionAdapters.Add(new TlsFilterAdapter());
    });
});
private class TlsFilterAdapter : IConnectionAdapter
{
    public bool IsHttps => false;

    public Task<IAdaptedConnection> OnConnectionAsync(ConnectionAdapterContext context)
    {
        var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

        // Throw NotSupportedException for any cipher algorithm that the app doesn't
        // wish to support. Alternatively, define and compare
        // ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher
        // suites.
        //
        // No encryption is used with a CipherAlgorithmType.Null cipher algorithm.
        if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
        {
            throw new NotSupportedException("Prohibited cipher: " + tlsFeature.CipherAlgorithm);
        }

        return Task.FromResult<IAdaptedConnection>(new AdaptedConnection(context.ConnectionStream));
    }

    private class AdaptedConnection : IAdaptedConnection
    {
        public AdaptedConnection(Stream adaptedStream)
        {
            ConnectionStream = adaptedStream;
        }

        public Stream ConnectionStream { get; }

        public void Dispose()
        {
        }
    }
}

Festlegen des Protokolls aus der KonfigurationSet the protocol from configuration

CreateDefaultBuilder ruft serverOptions.Configure(context.Configuration.GetSection("Kestrel")) standardmäßig zum Laden der Kestrel-Konfiguration auf.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

Im folgenden Beispiel appsettings.json wird für alle Endpunkte von Kestrel ein Standardverbindungsprotokoll (HTTP/1.1 und HTTP/2) eingerichtet:In the following appsettings.json example, a default connection protocol (HTTP/1.1 and HTTP/2) is established for all of Kestrel's endpoints:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1AndHttp2"
    }
  }
}

Das folgende Beispiel einer Konfigurationsdatei richtet ein Verbindungsprotokoll für einen bestimmten Endpunkt ein:The following configuration file example establishes a connection protocol for a specific endpoint:

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

Protokolle, die in Code angegeben werden, setzen Werte außer Kraft, der durch die Konfiguration festgelegt werden.Protocols specified in code override values set by configuration.

TransportkonfigurationTransport configuration

Mit dem Release von ASP.NET Core 2.1 basiert der Standardtransport von Kestrel nicht mehr auf Libuv, sondern auf verwalteten Sockets.With the release of ASP.NET Core 2.1, Kestrel's default transport is no longer based on Libuv but instead based on managed sockets. Dies stellt einen Breaking Change für ASP.NET Core 2.0-Apps dar, die auf Version 2.1 upgraden, UseLibuv aufrufen und von einem der folgenden Pakete abhängig sind:This is a breaking change for ASP.NET Core 2.0 apps upgrading to 2.1 that call UseLibuv and depend on either of the following packages:

Für Projekte, die den Einsatz von Libuv erfordern:For projects that require the use of Libuv:

  • Fügen Sie für das Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv-Paket eine Abhängigkeit auf die Projektdatei der App hinzu:Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's project file:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Rufen Sie UseLibuv auf:Call UseLibuv:

    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }
    
        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseLibuv()
                .UseStartup<Startup>();
    }
    

URL-PräfixeURL prefixes

Bei der Verwendung von UseUrls, dem Befehlszeilenargument --urls, dem Hostkonfigurationsschlüssel urls oder der Umgebungsvariable ASPNETCORE_URLS können die URL-Präfixe in den folgenden Formaten vorliegen.When using UseUrls, --urls command-line argument, urls host configuration key, or ASPNETCORE_URLS environment variable, the URL prefixes can be in any of the following formats.

Nur HTTP-URL-Präfixe sind gültig.Only HTTP URL prefixes are valid. Kestrel unterstützt HTTPS nicht beim Konfigurieren von URL-Bindungen mit UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • IPv4-Adresse mit PortnummerIPv4 address with port number

    http://65.55.39.10:80/
    

    Bei 0.0.0.0 handelt es sich um einen Sonderfall, für den eine Bindung an alle IPv4-Adressen erfolgt.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • IPv6-Adresse mit PortnummerIPv6 address with port number

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

    [::] stellt das Äquivalent von IPv6 zu 0.0.0.0 für IPv4 dar.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Hostname mit PortnummerHost name with port number

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

    Hostnamen, * und + sind nicht spezifisch.Host names, *, and +, aren't special. Alle Elemente, die nicht als gültige IP-Adresse oder localhost erkannt werden, werden an alle IPv4- und IPv6-IP-Adressen gebunden.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Verwenden Sie HTTP.sys oder einen Reverseproxyserver zum Binden verschiedener Hostnamen an verschiedene ASP.NET Core-Apps auf demselben Port, z.B. IIS, Nginx oder Apache.To bind different host names to different ASP.NET Core apps on the same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.

    Warnung

    Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.Hosting in a reverse proxy configuration requires host filtering.

  • localhost-Hostname mit Portnummer oder Loopback-IP mit PortnummerHost localhost name with port number or loopback IP with port number

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

    Wenn localhost angegeben ist, versucht Kestrel, eine Bindung zu IPv4- und IPv6-Loopback-Schnittstellen zu erstellen.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Wenn der erforderliche Port von einem anderen Dienst auf einer der Loopback-Schnittstellen verwendet wird, tritt beim Starten von Kestrel ein Fehler auf.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Wenn eine der Loopback-Schnittstellen aus anderen Gründen nicht verfügbar ist (meistens durch die fehlende Unterstützung von IPv6), protokolliert Kestrel eine Warnung.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Host-FilterungHost filtering

Obwohl Kestrel die Konfiguration basierend auf Präfixe wie http://example.com:5000 unterstützt, ignoriert Kestrel den Hostnamen weitgehend.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. Der Host localhost ist ein Sonderfall, der für die Bindung an Loopback-Adressen verwendet wird.Host localhost is a special case used for binding to loopback addresses. Jeder Host, der keine explizite IP-Adresse ist, wird an alle öffentlichen IP-Adressen gebunden.Any host other than an explicit IP address binds to all public IP addresses. Host-Header werden nicht überprüft.Host headers aren't validated.

Verwenden Sie Middleware zum Filtern von Hosts, um dieses Problem zu umgehen.As a workaround, use Host Filtering Middleware. Middleware zum Filtern von Hosts wird im Paket Microsoft.AspNetCore.HostFiltering bereitgestellt, das im Metapaket Microsoft.AspNetCore.App enthalten ist (ASP.NET Core 2.1 oder 2.2).Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or 2.2). Die Middleware wird von CreateDefaultBuilder hinzugefügt, wodurch AddHostFiltering aufgerufen wird:The middleware is added by CreateDefaultBuilder, which calls 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>();
}

Die Middleware zum Filtern von Hosts ist standardmäßig deaktiviert.Host Filtering Middleware is disabled by default. Wenn Sie die Middleware aktivieren möchten, definieren Sie einen AllowedHosts-Schlüssel in appsettings.json/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. Der Wert ist eine durch Semikolons getrennte Liste von Hostnamen ohne Portnummern:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Hinweis

Middleware für weitergeleitete Header hat auch eine AllowedHosts-Option.Forwarded Headers Middleware also has an AllowedHosts option. Middleware für weitergeleitete Header und Middleware zum Filtern von Hosts besitzen ähnliche Funktionen für unterschiedliche Szenarios.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Legen Sie AllowedHosts mit Middleware für weitergeleitete Header fest, wenn der Host-Header beim Weiterleiten von Anforderungen mit einem Reverseproxyserver oder einem Lastenausgleichsmodul nicht beibehalten wird.Setting AllowedHosts with Forwarded Headers Middleware is appropriate when the Host header isn't preserved while forwarding requests with a reverse proxy server or load balancer. Legen Sie AllowedHosts mit Middleware zum Filtern von Hosts fest, wenn Kestrel als öffentlicher Edgeserver verwendet oder der Host-Header direkt weitergeleitet wird.Setting AllowedHosts with Host Filtering Middleware is appropriate when Kestrel is used as a public-facing edge server or when the Host header is directly forwarded.

Weitere Informationen zu Middleware für weitergeleitete Header finden Sie unter Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und Lastenausgleich.For more information on Forwarded Headers Middleware, see Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und Lastenausgleich.

Einführung in Kestrel, dem plattformübergreifenden Webserver für ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel ist der Webserver, der standardmäßig in ASP.NET Core-Projektvorlagen enthalten ist.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel unterstützt die folgenden Szenarios:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Nicht transparente Upgrades, die zum Aktivieren von WebSockets verwendet werdenOpaque upgrade used to enable WebSockets
  • Unix-Sockets für eine hohe Leistung im Hintergrund von NginxUnix sockets for high performance behind Nginx

Kestrel wird auf allen Plattformen und für alle Versionen unterstützt, die .NET Core unterstützt.Kestrel is supported on all platforms and versions that .NET Core supports.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Verwenden von Kestrel mit einem ReverseproxyWhen to use Kestrel with a reverse proxy

Kestrel kann eigenständig oder mit einem Reverseproxyserver wie z.B. Internet Information Services (IIS), Nginx oder Apache verwendet werden.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Ein Reverseproxyserver empfängt HTTP-Anforderungen aus dem Netzwerk und leitet diese an Kestrel weiter.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel bei Verwendung als Webserver mit direkter Internetverbindung:Kestrel used as an edge (Internet-facing) web server:

Kestrel kommuniziert direkt und ohne Reverseproxyserver mit dem Internet

Kestrel bei Verwendung in einer Reverseproxykonfiguration:Kestrel used in a reverse proxy configuration:

Kestrel kommuniziert indirekt mit dem Internet über einen Reverseproxyserver wie IIS, Nginx oder Apache

Jede der beiden Konfigurationen – mit oder ohne einen Reverseproxyserver – stellt eine unterstützte Hostingkonfiguration dar.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Bei Verwendung als Edgeserver ohne Reverseproxyserver unterstützt Kestrel die gemeinsame Nutzung der gleichen IP-Adresse und des gleichen Ports durch mehrere Prozesse nicht.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Wenn Kestrel für das Lauschen an einem Port konfiguriert ist, verarbeitet Kestrel den gesamten Datenverkehr für diesen Port unabhängig von den Host-Headern der Anforderungen.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Ein Reverseproxy, der Ports freigeben kann, kann Anforderungen an Kestrel über eine eindeutige IP und einen eindeutigen Port weiterleiten.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Auch wenn kein Reverseproxyserver erforderlich ist, kann die Verwendung eines solchen empfehlenswert sein.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Für einen Reverseproxy gilt Folgendes:A reverse proxy:

  • Er kann die verfügbar gemachten öffentlichen Oberflächen der von ihm gehosteten Apps einschränken.Can limit the exposed public surface area of the apps that it hosts.
  • Er stellt eine zusätzliche Ebene für Konfiguration und Schutz bereit.Provide an additional layer of configuration and defense.
  • Er lässt sich besser in die vorhandene Infrastruktur integrieren.Might integrate better with existing infrastructure.
  • Er vereinfacht die Konfiguration von Lastenausgleich und sicherer Kommunikation (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Nur der Reverseproxyserver erfordert ein X.509-Zertifikat, und dieser Server kann mit den Servern der App im internen Netzwerk über einfaches HTTP kommunizieren.Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

Warnung

Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.Hosting in a reverse proxy configuration requires host filtering.

Verwenden von Kestrel in ASP.NET Core-AppsHow to use Kestrel in ASP.NET Core apps

Das Paket Microsoft.AspNetCore.Server.Kestrel ist im Metapaket Microsoft.AspNetCore.App enthalten.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

ASP.NET Core-Projektvorlagen verwenden Kestrel standardmäßig.ASP.NET Core project templates use Kestrel by default. Der Vorlagencode in Program.cs ruft CreateDefaultBuilder auf, wodurch UseKestrel im Hintergrund aufgerufen wird.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

Um zusätzliche Konfiguration nach dem Aufruf von CreateDefaultBuilder bereitzustellen, rufen Sie UseKestrel auf:To provide additional configuration after calling CreateDefaultBuilder, call UseKestrel:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            // Set properties and call methods on serverOptions
        });

Weitere Informationen zum CreateDefaultBuilder und zum Erstellen des Hosts finden Sie im Abschnitt Einrichten eines Hosts von ASP.NET Core-Webhost.For more information on CreateDefaultBuilder and building the host, see the Set up a host section of ASP.NET Core-Webhost.

Kestrel-OptionenKestrel options

Der Kestrel-Webserver verfügt über einschränkende Konfigurationsoptionen, die besonders nützlich bei Bereitstellungen mit Internetzugriff sind.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Legen Sie Einschränkungen für die Limits-Eigenschaft der KestrelServerOptions-Klasse fest.Set constraints on the Limits property of the KestrelServerOptions class. Die Limits-Eigenschaft enthält eine Instanz der KestrelServerLimits-Klasse.The Limits property holds an instance of the KestrelServerLimits class.

In den folgenden Beispielen wird der Microsoft.AspNetCore.Server.Kestrel.Core-Namespace verwendet:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Kestrel-Optionen, die in den folgenden Beispielen in C#-Code konfiguriert sind, können auch mit einem Konfigurationsanbieter festgelegt werden.Kestrel options, which are configured in C# code in the following examples, can also be set using a configuration provider. Beispielsweise kann der Dateikonfigurationsanbieter die Kestrel-Konfiguration aus einer appsettings.json- oder appsettings.{Umgebung}.json-Datei laden:For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

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

Verwenden Sie einen der folgenden Ansätze:Use one of the following approaches:

  • Konfigurieren Sie Kestrel in Startup.ConfigureServices:Configure Kestrel in Startup.ConfigureServices:

    1. Fügen Sie eine Instanz von IConfiguration in die Startup-Klasse ein.Inject an instance of IConfiguration into the Startup class. Im folgenden Beispiel wird davon ausgegangen, dass die eingefügte Konfiguration der Configuration-Eigenschaft zugewiesen wird.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. Laden Sie in Startup.ConfigureServices den Abschnitt Kestrel der Konfiguration in die Konfiguration von Kestrel:In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:

      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)
          {
              ...
          }
      }
      
  • Konfigurieren Sie Kestrel beim Erstellen des Hosts:Configure Kestrel when building the host:

    Laden Sie in Program.cs den Abschnitt Kestrel der Konfiguration in die Konfiguration von Kestrel:In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

    // using Microsoft.Extensions.DependencyInjection;
    
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureServices((context, services) =>
            {
                services.Configure<KestrelServerOptions>(
                    context.Configuration.GetSection("Kestrel"));
            })
            .UseStartup<Startup>();
    

Beide vorangehenden Ansätze funktionieren mit jedem Konfigurationsanbieter.Both of the preceding approaches work with any configuration provider.

Keep-Alive-TimeoutKeep-alive timeout

KeepAliveTimeout

Ruft das Keep-Alive-Timeout ab oder legt es fest.Gets or sets the keep-alive timeout. Standardwert: 2 Minuten.Defaults to 2 minutes.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
        });

Maximale Anzahl der ClientverbindungenMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Die maximale Anzahl von gleichzeitig geöffneten TCP-Verbindungen kann mithilfe von folgendem Code für die gesamte App festgelegt werden:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxConcurrentConnections = 100;
        });

Es gibt einen separaten Grenzwert für Verbindungen, die von HTTP oder HTTPS auf ein anderes Protokoll aktualisiert wurden (z.B. auf eine WebSockets-Anforderung).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Nachdem eine Verbindung aktualisiert wurde, zählt diese nicht mehr für den MaxConcurrentConnections-Grenzwert.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
        });

Die maximale Anzahl von Verbindungen ist standardmäßig nicht begrenzt (NULL).The maximum number of connections is unlimited (null) by default.

Maximale Größe des AnforderungstextsMaximum request body size

MaxRequestBodySize

Die maximale Größe des Anforderungstexts beträgt standardmäßig 30.000.000 Byte, also ungefähr 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Die empfohlene Methode zur Außerkraftsetzung des Grenzwerts in einer ASP.NET Core-MVC-App besteht im Verwenden des RequestSizeLimitAttribute-Attributs in einer Aktionsmethode:The recommended approach to override the limit in an ASP.NET Core MVC app is to use the RequestSizeLimitAttribute attribute on an action method:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Im folgenden Beispiel wird veranschaulicht, wie die Einschränkungen auf jeder Anforderung für die App konfiguriert werden:Here's an example that shows how to configure the constraint for the app on every request:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
        });

Außer Kraft setzen der Einstellung für eine bestimmte Anforderung in Middleware:Override the setting on a specific request in 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));
    }

Eine Ausnahme wird ausgelöst, wenn die App den Grenzwert einer Anforderung konfiguriert, nachdem die App bereits mit dem Lesen der Anforderung begonnen hat.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Es gibt eine IsReadOnly-Eigenschaft, die angibt, wenn sich die MaxRequestBodySize-Eigenschaft im schreibgeschützten Zustand befindet, also wenn der Grenzwert nicht mehr konfiguriert werden kann.There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

Wenn eine App prozessextern hinter dem ASP.NET Core-Modul ausgeführt wird, ist das Größenlimit von Kestrel für Anforderungstext deaktiviert, weil IIS dieses Limit bereits festlegt.When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit is disabled because IIS already sets the limit.

Minimale Datenrate des AnforderungstextsMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel überprüft sekündlich, ob Daten mit der angegebenen Rate in Bytes/Sekunde eingehen.Kestrel checks every second if data is arriving at the specified rate in bytes/second. 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ährenddessen nicht überprüft.If the rate drops below the minimum, the connection is timed out. The grace period is the amount of time that Kestrel gives the client to increase its send rate up to the minimum; the rate isn't checked during that time. Diese Toleranzperiode beugt dem Trennen von Verbindungen vor, die Daten aufgrund eines langsamen TCP-Starts anfänglich mit einer niedrigen Rate senden.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

Die mindestens erforderliche Rate beträgt standardmäßig 240 Bytes/Sekunde mit einer Toleranzperiode von 5 Sekunden.The default minimum rate is 240 bytes/second with a 5 second grace period.

Für die Antwort gilt ebenfalls eine mindestens erforderliche Rate.A minimum rate also applies to the response. Der Code zum Festlegen des Grenzwerts für Anforderung und Antwort ist abgesehen von RequestBody oder Response in den Namen von Eigenschaften und Schnittstelle identisch.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

In diesem Beispiel wird veranschaulicht, wie Sie die mindestens erforderlichen Datenraten in Program.cs konfigurieren:Here's an example that shows how to configure the minimum data rates in Program.cs:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MinRequestBodyDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
            serverOptions.Limits.MinResponseDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
        });

Timeout für AnforderungsheaderRequest headers timeout

RequestHeadersTimeout

Ruft die maximale Zeitspanne ab, während der der Server Anforderungsheader empfängt, oder legt diese fest.Gets or sets the maximum amount of time the server spends receiving request headers. Der Standardwert beträgt 30 Sekunden.Defaults to 30 seconds.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
        });

Synchrone E/A-VorgängeSynchronous I/O

AllowSynchronousIO steuert, ob für Anforderung und Antwort synchrone E/A-Vorgänge zulässig sind.AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. Der Standardwert ist true.The default value is true.

Warnung

Sehr viele blockierende synchrone E/A-Vorgänge können zu einem Ressourcenmangel im Threadpool führen, wodurch die App nicht mehr reagiert.A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Aktivieren Sie AllowSynchronousIO nur bei Verwendung einer Bibliothek, die asynchrone E/A-Vorgänge nicht unterstützt.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous I/O.

Das folgende Beispiel deaktiviert synchrone E/A-Vorgänge:The following example disables synchronous I/O:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.AllowSynchronousIO = false;
        });

Weitere Informationen zu anderen Kestrel-Optionen und -Einschränkungen finden Sie unter:For information about other Kestrel options and limits, see:

EndpunktkonfigurationEndpoint configuration

Standardmäßig wird ASP.NET Core an Folgendes gebunden:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (wenn ein lokales Entwicklungszertifikat vorhanden ist)https://localhost:5001 (when a local development certificate is present)

Verwenden Sie Folgendes zum Angeben der URLs:Specify URLs using the:

  • Die Umgebungsvariable ASPNETCORE_URLSASPNETCORE_URLS environment variable.
  • Das Befehlszeilenargument --urls--urls command-line argument.
  • Den Hostkonfigurationsschlüssel urlsurls host configuration key.
  • Die Erweiterungsmethode UseUrlsUseUrls extension method.

Der Wert, der mit diesen Ansätzen angegeben wird, kann mindestens ein HTTP- oder HTTPS-Endpunkt sein (HTTPS wenn ein Standardzertifikat verfügbar ist).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Konfigurieren Sie den Wert als eine durch Semikolons getrennte Liste (z.B. "Urls": "http://localhost:8000;http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Weitere Informationen zu diesen Ansätzen finden Sie unter Server-URLs und Außerkraftsetzen der Konfiguration.For more information on these approaches, see Server URLs and Override configuration.

Ein Entwicklungszertifikat wird erstellt:A development certificate is created:

Einige Browser erfordern, dass Sie die explizite Berechtigung erteilen, dem lokalen Entwicklungszertifikat zu vertrauen.Some browsers require granting explicit permission to trust the local development certificate.

Projektvorlagen konfigurieren Apps, damit sie standardmäßig auf HTTPS ausgeführt werden und die HTTPS-Umleitung und HSTS-Unterstützung enthalten.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Rufen Sie die Listen- oder ListenUnixSocket-Methode unter KestrelServerOptions auf, um URL-Präfixe und Ports für Kestrel zu konfigurieren.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, das Befehlszeilenargument --urls, der Hostkonfigurationsschlüssel urls und die Umgebungsvariable ASPNETCORE_URLS funktionieren ebenfalls, verfügen jedoch über Einschränkungen, die im Verlauf dieses Abschnitts erläutert werden (Ein Standardzertifikat muss für die HTTPS-Endpunktkonfiguration verfügbar sein).UseUrls, the --urls command-line argument, urls host configuration key, and the ASPNETCORE_URLS environment variable also work but have the limitations noted later in this section (a default certificate must be available for HTTPS endpoint configuration).

KestrelServerOptions-Konfiguration:KestrelServerOptions configuration:

ConfigureEndpointDefaults(Action<ListenOptions>)ConfigureEndpointDefaults(Action<ListenOptions>)

Gibt die Konfiguration von Action zum Ausführen von jedem angegebenen Endpunkt an.Specifies a configuration Action to run for each specified endpoint. Mehrmalige Aufrufe von ConfigureEndpointDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });
        });

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureEndpointDefaults erstellt werden, werden die Standardwerte nicht angewendet.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Gibt die Konfiguration von Action zum Ausführen von jedem HTTPS-Endpunkt an.Specifies a configuration Action to run for each HTTPS endpoint. Mehrmalige Aufrufe von ConfigureHttpsDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                // certificate is an X509Certificate2
                listenOptions.ServerCertificate = certificate;
            });
        });

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureHttpsDefaults erstellt werden, werden die Standardwerte nicht angewendet.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Configure(IConfiguration)Configure(IConfiguration)

Erstellt ein Konfigurationsladeprogramm für das Einrichten von Kestrel, was IConfiguration als Eingabe erfordert.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. Die Konfiguration muss auf den Konfigurationsabschnitt für Kestrel festgelegt werden.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Konfiguriert Kestrel zur Verwendung von HTTPS.Configure Kestrel to use HTTPS.

ListenOptions.UseHttps-Erweiterungen:ListenOptions.UseHttps extensions:

  • UseHttps: Hiermit wird Kestrel zur Verwendung von HTTPS mit dem Standardzertifikat konfiguriert.UseHttps: Configure Kestrel to use HTTPS with the default certificate. Löst eine Ausnahme aus, wenn kein Standardzertifikat konfiguriert ist.Throws an exception if no default certificate is configured.
  • 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-Parameter:ListenOptions.UseHttps parameters:

  • filename entspricht dem Pfad und Dateinamen einer Zertifikatdatei relativ zu dem Verzeichnis, das die Inhaltsdateien der App enthält.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password ist das für den Zugriff auf die X.509-Zertifikatsdaten erforderliche Kennwort.password is the password required to access the X.509 certificate data.
  • configureOptions ist eine Action zum Konfigurieren von HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Gibt ListenOptions zurück.Returns the ListenOptions.
  • storeName ist der Zertifikatspeicher, aus dem das Zertifikat geladen wird.storeName is the certificate store from which to load the certificate.
  • subject ist der Name des Antragstellers für das Zertifikat.subject is the subject name for the certificate.
  • allowInvalid gibt an, ob ungültige Zertifikate berücksichtigt werden sollten, z.B. selbstsignierte Zertifikate.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location ist der Speicherort, aus dem das Zertifikat geladen wird.location is the store location to load the certificate from.
  • serverCertificate ist das X.509-Zertifikat.serverCertificate is the X.509 certificate.

In der Produktion muss HTTPS explizit konfiguriert sein.In production, HTTPS must be explicitly configured. Zumindest muss ein Standardzertifikat angegeben werden.At a minimum, a default certificate must be provided.

Die im Folgenden beschriebenen unterstützten Konfigurationen:Supported configurations described next:

  • Keine KonfigurationNo configuration
  • Ersetzen des Standardzertifikats aus der KonfigurationReplace the default certificate from configuration
  • Ändern des Standards im CodeChange the defaults in code

Keine KonfigurationNo configuration

Kestrel überwacht http://localhost:5000 und https://localhost:5001 (wenn ein Standardzertifikat verfügbar ist).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Ersetzen des Standardzertifikats aus der KonfigurationReplace the default certificate from configuration

CreateDefaultBuilder ruft Configure(context.Configuration.GetSection("Kestrel")) standardmäßig zum Laden der Kestrel-Konfiguration auf.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Ein Standardkonfigurationsschema für HTTPS-App-Einstellungen ist für Kestrel verfügbar.A default HTTPS app settings configuration schema is available for Kestrel. Konfigurieren Sie mehrere Endpunkte, einschließlich der zu verwendenden URLs und Zertifikate aus einer Datei auf dem Datenträger oder einem Zertifikatspeicher.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

Die Vorgehensweise im folgenden appsettings.json-Beispiel:In the following appsettings.json example:

  • Legen Sie AllowInvalid auf true fest, um die Verwendung von ungültigen Zertifikaten zu erlauben (z.B. selbstsignierte Zertifikate).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Jeder HTTPS-Endpunkt, der kein Zertifikat angibt (im folgenden Beispiel HttpsDefaultCert), greift auf das unter Zertifikate > Standard festgelegte Zertifikat oder das Entwicklungszertifikat zurück.Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls back to the cert defined under Certificates > Default or the development certificate.
{
  "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>"
      }
    }
  }
}

Alternativ zur Verwendung von Pfad und Kennwort für alle Zertifikatknoten können Sie das Zertifikat mithilfe von Zertifikatspeicherfeldern angeben.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Das Zertifikat unter Zertifikate > Standard kann beispielweise wie folgt angegeben werden:For example, the Certificates > Default certificate can be specified as:

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

Schema-Hinweise:Schema notes:

  • Bei den Namen der Endpunkte wird die Groß-/Kleinschreibung nicht beachtet.Endpoints names are case-insensitive. Zum Beispiel sind HTTPS und Https gültig.For example, HTTPS and Https are valid.
  • Der Parameter Url ist für jeden Endpunkt erforderlich.The Url parameter is required for each endpoint. Das Format für diesen Parameter ist identisch mit dem allgemeinen Konfigurationsparameter Urls, mit der Ausnahme, dass er auf einen einzelnen Wert begrenzt ist.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Diese Endpunkte ersetzen die in der allgemeinen Urls-Konfiguration festgelegten Endpunkte, anstatt zu ihnen hinzuzufügen.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Endpunkte, die über Listen in Code definiert werden, werden den im Konfigurationsabschnitt definierten Endpunkten hinzugefügt.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • Der Certificate-Abschnitt ist optional.The Certificate section is optional. Wenn der Certificate-Abschnitt nicht angegeben ist, werden die in früheren Szenarios definierten Standardwerte verwendet.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Wenn keine Standardwerte verfügbar sind, löst der Server eine Ausnahme aus und startet nicht.If no defaults are available, the server throws an exception and fails to start.
  • Der Certificate-Abschnitt unterstützt die Zertifikate PfadKennwort und SubjectStore (Antragsteller–Speicher).The Certificate section supports both PathPassword and SubjectStore certificates.
  • Auf diese Weise kann eine beliebige Anzahl von Endpunkten definiert werden, solange Sie keine Portkonflikte verursachen.Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) gibt KestrelConfigurationLoader mit der Methode .Endpoint(string name, listenOptions => { }) zurück, die dazu verwendet werden kann, die Einstellungen eines Endpunkts zu ergänzen:options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

Auf KestrelServerOptions.ConfigurationLoader kann direkt zugegriffen werden, um die Iteration auf dem vorhandenen Ladeprogramm fortzusetzen, etwa auf dem von CreateDefaultBuilder bereitgestellten Ladeprogramm.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • Der Konfigurationsabschnitt ist für jeden Endpunkt in den Optionen der Methode Endpoint verfügbar, sodass benutzerdefinierte Einstellungen gelesen werden können.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Mehrere Konfigurationen können durch erneutes Aufrufen von options.Configure(context.Configuration.GetSection("{SECTION}")) mit einem anderen Abschnitt geladen werden.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Sofern Load nicht in einer vorherigen Instanz explizit aufgerufen wird, wird nur die letzte Konfiguration verwendet.Only the last configuration is used, unless Load is explicitly called on prior instances. Das Metapaket ruft Load nicht auf, sodass der Abschnitt mit der Standardkonfiguration ersetzt werden kann.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader spiegelt die API-Familie Listen von KestrelServerOptions als Endpoint-Überladungen, weshalb Code und Konfigurationsendpunkte am selben Ort konfiguriert werden können.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Diese Überladungen verwenden keine Namen und nutzen nur Standardeinstellungen aus der Konfiguration.These overloads don't use names and only consume default settings from configuration.

Ändern des Standards im CodeChange the defaults in code

ConfigureEndpointDefaults und ConfigureHttpsDefaults können zum Ändern der Standardeinstellungen für ListenOptions und HttpsConnectionAdapterOptions verwendet werden, einschließlich der Standardzertifikate, die im vorherigen Szenario festgelegt wurden.ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. ConfigureEndpointDefaults und ConfigureHttpsDefaults sollten aufgerufen werden, bevor Endpunkte konfiguriert werden.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });

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

Kestrel-Unterstützung für SNIKestrel support for SNI

Die Servernamensanzeige (SNI) kann zum Hosten mehrerer Domänen auf der gleichen IP-Adresse und dem gleichen Port verwendet werden.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Damit die Servernamensanzeige funktioniert, sendet der Client während des TLS-Handshakes den Hostnamen für die sichere Sitzung an den Server, sodass der Server das richtige Zertifikat bereitstellen kann.For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. Der Client verwendet das beigestellte Zertifikat für die verschlüsselte Kommunikation mit dem Server während der sicheren Sitzung nach dem TLS-Handshake.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel unterstützt die Servernamensanzeige über den ServerCertificateSelector-Rückruf.Kestrel supports SNI via the ServerCertificateSelector callback. Der Rückruf wird für jede Verbindung einmal aufgerufen, um der App zu ermöglichen, den Hostnamen zu überprüfen und das entsprechende Zertifikat auszuwählen.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Für die Unterstützung der Servernamensanzeige benötigen Sie Folgendes:SNI support requires:

  • Wird auf dem Zielframework netcoreapp2.1 oder höher ausgeführt.Running on target framework netcoreapp2.1 or later. In net461 oder höher, wird der Rückruf aufgerufen, name ist aber immer null.On net461 or later, the callback is invoked but the name is always null. name ist auch null, wenn der Client den Hostnamenparameter nicht im TLS-Handshake angibt.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Alle Websites werden in derselben Kestrel-Instanz ausgeführt.All websites run on the same Kestrel instance. Kestrel unterstützt ohne Reverseproxy keine gemeinsame IP-Adresse und keinen gemeinsamen Port für mehrere Instanzen.Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, 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;
                    };
                });
            });
        })
        .Build();

VerbindungsprotokollierungConnection logging

Rufen Sie UseConnectionLogging auf, um Protokolle auf Debugebene für die Kommunikation auf Byteebene für eine Verbindung auszugeben.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. Die Verbindungsprotokollierung ist beim Beheben von Problemen bei der Low-Level-Kommunikation hilfreich, wie z. B. bei der TLS-Verschlüsselung und bei Proxys.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Wenn UseConnectionLogging vor UseHttps platziert wird, wird der verschlüsselte Datenverkehr protokolliert.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Wenn UseConnectionLogging nach UseHttps platziert wird, wird der entschlüsselte Datenverkehr protokolliert.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

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

Binden an einen TCP-SocketBind to a TCP socket

Die Listen-Methode wird an ein TCP-Socket gebunden, und ein Lambdaausdruck einer Option lässt die Konfiguration des X.509-Zertifikats zu:The Listen method binds to a TCP socket, and an options lambda permits X.509 certificate configuration:

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

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

Im Beispiel wird HTTPS für einen Endpunkt mit ListenOptions konfiguriert.The example configures HTTPS for an endpoint with ListenOptions. Verwenden Sie die gleiche API zum Konfigurieren anderer Kestrel-Einstellungen für bestimmte Endpunkte.Use the same API to configure other Kestrel settings for specific endpoints.

Unter Windows können selbstsignierte Zertifikate mit dem PowerShell-Cmdlet „New-SelfSignedCertificate“ erstellt werden.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Ein nicht unterstütztes Beispiel finden Sie unter UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

Unter macOS, Linux und Windows können Zertifikate mithilfe von OpenSSL erstellt werden.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Binden an einen Unix-SocketBind to a Unix socket

Wie in diesem Beispiel dargestellt, lauschen Sie an einem Unix-Socket mit ListenUnixSocket, um eine verbesserte Leistung mit Nginx zu erzielen:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testpassword");
            });
        });
  • Legen Sie in der Nginx-Konfigurationsdatei den Eintrag server > location > proxy_pass auf http://unix:/tmp/{KESTREL SOCKET}:/; fest.In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} ist der Name des für ListenUnixSocket bereitgestellten Socket (zum Beispiel kestrel-test.sock im vorherigen Beispiel).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Stellen Sie sicher, dass der Socket von Nginx beschreibbar ist (z. B. chmod go+w /tmp/kestrel-test.sock).Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

Port 0Port 0

Wenn die Portnummer 0 angegeben wird, wird Kestrel dynamisch an einen verfügbaren Port gebunden.When the port number 0 is specified, Kestrel dynamically binds to an available port. Im folgenden Beispiel wird veranschaulicht, wie bestimmt werden kann, für welchen Port Kestrel zur Laufzeit eine Bindung erstellt hat:The following example shows how to determine which port Kestrel actually bound at runtime:

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

Wenn die App ausgeführt wird, gibt das Ausgabefenster der Konsole den dynamischen Port an, über den die App erreicht werden kann:When the app is run, the console window output indicates the dynamic port where the app can be reached:

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

EinschränkungenLimitations

Konfigurieren Sie Endpunkte mithilfe der folgenden Ansätze:Configure endpoints with the following approaches:

  • UseUrls
  • Befehlszeilenargument --urls--urls command-line argument
  • Hostkonfigurationsschlüssel urlsurls host configuration key
  • Umgebungsvariable ASPNETCORE_URLSASPNETCORE_URLS environment variable

Diese Methoden sind nützlich, wenn Ihr Code mit anderen Servern als Kestrel funktionieren soll.These methods are useful for making code work with servers other than Kestrel. Beachten Sie jedoch die folgenden Einschränkungen:However, be aware of the following limitations:

  • HTTPS kann nicht mit diesen Ansätzen verwendet werden, außer ein Standardzertifikat wird in der HTTPS-Endpunktkonfiguration angegeben (z.B. wenn Sie wie zuvor in diesem Artikel gezeigt die KestrelServerOptions-Konfiguration oder eine Konfigurationsdatei verwenden).HTTPS can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint configuration (for example, using KestrelServerOptions configuration or a configuration file as shown earlier in this topic).
  • Wenn die Ansätze Listen und UseUrls gleichzeitig verwendet werden, überschreiben die Listen-Endpunkte die UseUrls-Endpunkte.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

IIS-EndpunktkonfigurationIIS endpoint configuration

Bei der Verwendung von IIS werden die URL-Bindungen für IIS-Überschreibungsbindungen durch Listen oder UseUrls festgelegt.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Weitere Informationen finden Sie im Artikel ASP.NET Core-Modul.For more information, see the ASP.NET Core Module topic.

TransportkonfigurationTransport configuration

Mit dem Release von ASP.NET Core 2.1 basiert der Standardtransport von Kestrel nicht mehr auf Libuv, sondern auf verwalteten Sockets.With the release of ASP.NET Core 2.1, Kestrel's default transport is no longer based on Libuv but instead based on managed sockets. Dies stellt einen Breaking Change für ASP.NET Core 2.0-Apps dar, die auf Version 2.1 upgraden, UseLibuv aufrufen und von einem der folgenden Pakete abhängig sind:This is a breaking change for ASP.NET Core 2.0 apps upgrading to 2.1 that call UseLibuv and depend on either of the following packages:

Für Projekte, die den Einsatz von Libuv erfordern:For projects that require the use of Libuv:

  • Fügen Sie für das Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv-Paket eine Abhängigkeit auf die Projektdatei der App hinzu:Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's project file:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Rufen Sie UseLibuv auf:Call UseLibuv:

    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }
    
        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseLibuv()
                .UseStartup<Startup>();
    }
    

URL-PräfixeURL prefixes

Bei der Verwendung von UseUrls, dem Befehlszeilenargument --urls, dem Hostkonfigurationsschlüssel urls oder der Umgebungsvariable ASPNETCORE_URLS können die URL-Präfixe in den folgenden Formaten vorliegen.When using UseUrls, --urls command-line argument, urls host configuration key, or ASPNETCORE_URLS environment variable, the URL prefixes can be in any of the following formats.

Nur HTTP-URL-Präfixe sind gültig.Only HTTP URL prefixes are valid. Kestrel unterstützt HTTPS nicht beim Konfigurieren von URL-Bindungen mit UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • IPv4-Adresse mit PortnummerIPv4 address with port number

    http://65.55.39.10:80/
    

    Bei 0.0.0.0 handelt es sich um einen Sonderfall, für den eine Bindung an alle IPv4-Adressen erfolgt.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • IPv6-Adresse mit PortnummerIPv6 address with port number

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

    [::] stellt das Äquivalent von IPv6 zu 0.0.0.0 für IPv4 dar.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Hostname mit PortnummerHost name with port number

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

    Hostnamen, * und + sind nicht spezifisch.Host names, *, and +, aren't special. Alle Elemente, die nicht als gültige IP-Adresse oder localhost erkannt werden, werden an alle IPv4- und IPv6-IP-Adressen gebunden.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Verwenden Sie HTTP.sys oder einen Reverseproxyserver zum Binden verschiedener Hostnamen an verschiedene ASP.NET Core-Apps auf demselben Port, z.B. IIS, Nginx oder Apache.To bind different host names to different ASP.NET Core apps on the same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.

    Warnung

    Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.Hosting in a reverse proxy configuration requires host filtering.

  • localhost-Hostname mit Portnummer oder Loopback-IP mit PortnummerHost localhost name with port number or loopback IP with port number

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

    Wenn localhost angegeben ist, versucht Kestrel, eine Bindung zu IPv4- und IPv6-Loopback-Schnittstellen zu erstellen.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Wenn der erforderliche Port von einem anderen Dienst auf einer der Loopback-Schnittstellen verwendet wird, tritt beim Starten von Kestrel ein Fehler auf.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Wenn eine der Loopback-Schnittstellen aus anderen Gründen nicht verfügbar ist (meistens durch die fehlende Unterstützung von IPv6), protokolliert Kestrel eine Warnung.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Host-FilterungHost filtering

Obwohl Kestrel die Konfiguration basierend auf Präfixe wie http://example.com:5000 unterstützt, ignoriert Kestrel den Hostnamen weitgehend.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. Der Host localhost ist ein Sonderfall, der für die Bindung an Loopback-Adressen verwendet wird.Host localhost is a special case used for binding to loopback addresses. Jeder Host, der keine explizite IP-Adresse ist, wird an alle öffentlichen IP-Adressen gebunden.Any host other than an explicit IP address binds to all public IP addresses. Host-Header werden nicht überprüft.Host headers aren't validated.

Verwenden Sie Middleware zum Filtern von Hosts, um dieses Problem zu umgehen.As a workaround, use Host Filtering Middleware. Middleware zum Filtern von Hosts wird im Paket Microsoft.AspNetCore.HostFiltering bereitgestellt, das im Metapaket Microsoft.AspNetCore.App enthalten ist (ASP.NET Core 2.1 oder 2.2).Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or 2.2). Die Middleware wird von CreateDefaultBuilder hinzugefügt, wodurch AddHostFiltering aufgerufen wird:The middleware is added by CreateDefaultBuilder, which calls 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>();
}

Die Middleware zum Filtern von Hosts ist standardmäßig deaktiviert.Host Filtering Middleware is disabled by default. Wenn Sie die Middleware aktivieren möchten, definieren Sie einen AllowedHosts-Schlüssel in appsettings.json/appsettings.<EnvironmentName>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. Der Wert ist eine durch Semikolons getrennte Liste von Hostnamen ohne Portnummern:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Hinweis

Middleware für weitergeleitete Header hat auch eine AllowedHosts-Option.Forwarded Headers Middleware also has an AllowedHosts option. Middleware für weitergeleitete Header und Middleware zum Filtern von Hosts besitzen ähnliche Funktionen für unterschiedliche Szenarios.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Legen Sie AllowedHosts mit Middleware für weitergeleitete Header fest, wenn der Host-Header beim Weiterleiten von Anforderungen mit einem Reverseproxyserver oder einem Lastenausgleichsmodul nicht beibehalten wird.Setting AllowedHosts with Forwarded Headers Middleware is appropriate when the Host header isn't preserved while forwarding requests with a reverse proxy server or load balancer. Legen Sie AllowedHosts mit Middleware zum Filtern von Hosts fest, wenn Kestrel als öffentlicher Edgeserver verwendet oder der Host-Header direkt weitergeleitet wird.Setting AllowedHosts with Host Filtering Middleware is appropriate when Kestrel is used as a public-facing edge server or when the Host header is directly forwarded.

Weitere Informationen zu Middleware für weitergeleitete Header finden Sie unter Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und Lastenausgleich.For more information on Forwarded Headers Middleware, see Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und Lastenausgleich.

Leeren von HTTP/1.1-AnforderungenHTTP/1.1 request draining

Das Öffnen von HTTP-Verbindungen ist zeitaufwendig.Opening HTTP connections is time consuming. Bei HTTPS ist es zudem ressourcenintensiv.For HTTPS, it's also resource intensive. Daher versucht Kestrel, Verbindungen gemäß dem HTTP/1.1-Protokoll wiederzuverwenden.Therefore, Kestrel tries to reuse connections per the HTTP/1.1 protocol. Ein Anforderungstext muss vollständig genutzt worden sein, damit die Verbindung wiederverwendet werden kann.A request body must be fully consumed to allow the connection to be reused. Die App nutzt nicht immer den Anforderungstext, z. B. bei einer POST-Anforderung, bei der der Server eine Umleitung oder 404-Antwort zurückgibt.The app doesn't always consume the request body, such as a POST requests where the server returns a redirect or 404 response. Im Fall der POST-Umleitung:In the POST-redirect case:

  • Der Client hat möglicherweise bereits einen Teil der POST-Daten gesendet.The client may already have sent part of the POST data.
  • Der Server schreibt die 301-Antwort.The server writes the 301 response.
  • Die Verbindung kann erst dann für eine neue Anforderung verwendet werden, wenn die POST-Daten im vorherigen Anforderungstext vollständig gelesen wurden.The connection can't be used for a new request until the POST data from the previous request body has been fully read.
  • Kestrel versucht, den Anforderungstext zu leeren.Kestrel tries to drain the request body. Leeren des Anforderungstexts bedeutet, die Daten zu lesen und zu verwerfen, ohne sie zu verarbeiten.Draining the request body means reading and discarding the data without processing it.

Beim Leerungsvorgang wird ein Kompromiss zwischen der Möglichkeit der Wiederverwendung der Verbindung und der Dauer gefunden, die zum Leeren der verbleibenden Daten benötigt wird:The draining process makes a tradoff between allowing the connection to be reused and the time it takes to drain any remaining data:

  • Für das Leeren gilt ein Zeitlimit von fünf Sekunden, das nicht konfigurierbar ist.Draining has a timeout of five seconds, which isn't configurable.
  • Wenn vor dem Zeitlimit nicht alle durch den Header Content-Length oder Transfer-Encoding angegebenen Daten gelesen wurden, wird die Verbindung geschlossen.If all of the data specified by the Content-Length or Transfer-Encoding header hasn't been read before the timeout, the connection is closed.

Mitunter möchten Sie die Anforderung sofort beenden, entweder bevor oder nachdem die Antwort geschrieben wurde.Sometimes you may want to terminate the request immediately, before or after writing the response. Beispielsweise können für Clients restriktive Datenobergrenzen gelten, sodass das Begrenzen hochgeladener Daten Priorität haben kann.For example, clients may have restrictive data caps, so limiting uploaded data might be a priority. Um in solchen Fällen eine Anforderung zu beenden, rufen Sie HttpContext.abort in einem Controller, eine Razor Page oder Middleware auf.In such cases to terminate a request, call HttpContext.Abort from a controller, Razor Page, or middleware.

Gegen den Aufruf von Abort gibt es Vorbehalte:There are caveats to calling Abort:

  • Das Erstellen neuer Verbindungen kann langsam und aufwendig sein.Creating new connections can be slow and expensive.
  • Es gibt keine Garantie, dass der Client die Antwort gelesen hat, bevor die Verbindung geschlossen wird.There's no guarantee that the client has read the response before the connection closes.
  • Das Aufrufen von Abort sollte selten erfolgen und schweren Fehlerfällen und nicht gewöhnlichen Fehlern vorbehalten sein.Calling Abort should be rare and reserved for severe error cases, not common errors.
    • Rufen Sie Abort nur dann auf, wenn ein konkretes Problem gelöst werden muss.Only call Abort when a specific problem needs to be solved. Rufen Sie beispielsweise Abort auf, wenn böswillige Clients versuchen, Daten per POST abzurufen, oder wenn es einen Fehler im Clientcode gibt, der umfangreiche oder zahlreiche Anforderungen verursacht.For example, call Abort if malicious clients are trying to POST data or when there's a bug in client code that causes large or numerous requests.
    • Rufen Sie Abort nicht für gewöhnliche Fehlersituationen auf, wie z. B. HTTP 404 (Nicht gefunden).Don't call Abort for common error situations, such as HTTP 404 (Not Found).

Durch den Aufruf von HttpResponse.CompleteAsync vor dem Aufruf von Abort wird sichergestellt, dass der Server das Schreiben der Antwort abgeschlossen hat.Calling HttpResponse.CompleteAsync before calling Abort ensures that the server has completed writing the response. Das Clientverhalten ist jedoch nicht vorhersagbar, und es kann sein, dass die Antwort nicht gelesen wird, bevor die Verbindung abgebrochen wird.However, client behavior isn't predictable and they may not read the response before the connection is aborted.

Dieser Prozess bei HTTP/2 ist anders, da das Protokoll den Abbruch einzelner Anforderungsströme ohne Schließen der Verbindung unterstützt.This process is different for HTTP/2 because the protocol supports aborting individual request streams without closing the connection. Das fünfsekündige Zeitlimit für das Leeren gilt nicht.The five second drain timeout doesn't apply. Wenn nach dem Fertigstellen einer Antwort ungelesene Anforderungstextdaten vorhanden sind, sendet der Server einen HTTP/2-RST-Datenrahmen.If there's any unread request body data after completing a response, then the server sends an HTTP/2 RST frame. Zusätzliche Datenrahmen im Anforderungstext werden ignoriert.Additional request body data frames are ignored.

Wenn möglich, ist es für Clients besser, den Anforderungsheader Expect: 100-continue zu verwenden und auf die Antwort des Servers zu warten, bevor mit dem Senden des Anforderungstexts begonnen wird.If possible, it's better for clients to utilize the Expect: 100-continue request header and wait for the server to respond before starting to send the request body. Das gibt dem Client die Gelegenheit, die Antwort zu prüfen und abzubrechen, bevor nicht benötigte Daten gesendet werden.That gives the client an opportunity to examine the response and abort before sending unneeded data.

Zusätzliche RessourcenAdditional resources