Implementacja serwera sieci Web Kestrel w ASP.NET CoreKestrel web server implementation in ASP.NET Core

Autorzy Dykstra, Krzysztof Rossi StephenBy Tom Dykstra, Chris Ross, and Stephen Halter

Kestrel to Międzyplatformowy serwer sieci Web dla ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel to serwer sieci Web, który jest domyślnie uwzględniony w szablonach projektu ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel obsługuje następujące scenariusze:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Nieprzezroczyste uaktualnienie używane do włączania obsługi obiektów WebSocketsOpaque upgrade used to enable WebSockets
  • Gniazda systemu UNIX w celu zapewnienia wysokiej wydajności w tle NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (z wyjątkiem macOS † )HTTP/2 (except on macOS†)

†Protokół HTTP/2 będzie obsługiwany w przypadku macOS w przyszłej wersji.†HTTP/2 will be supported on macOS in a future release.

Kestrel jest obsługiwana na wszystkich platformach i wersjach obsługiwanych przez platformę .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Wyświetl lub pobierz przykładowy kod (jak pobrać)View or download sample code (how to download)

Obsługa protokołu HTTP/2HTTP/2 support

Protokół HTTP/2 jest dostępny dla aplikacji ASP.NET Core, jeśli spełnione są następujące wymagania podstawowe:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • System operacyjny†Operating system†
    • Windows Server 2016/Windows 10 lub nowszy‡Windows Server 2016/Windows 10 or later‡
    • Linux z OpenSSL 1.0.2 lub nowszym (na przykład Ubuntu 16,04 lub nowszy)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Platforma docelowa: .NET Core 2,2 lub nowszyTarget framework: .NET Core 2.2 or later
  • Połączenie negocjowania protokołu warstwy aplikacji (ClientHello alpn)Application-Layer Protocol Negotiation (ALPN) connection
  • Połączenie TLS 1,2 lub nowszeTLS 1.2 or later connection

†Protokół HTTP/2 będzie obsługiwany w przypadku macOS w przyszłej wersji.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel ma ograniczoną obsługę protokołu HTTP/2 w systemie Windows Server 2012 R2 i Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Obsługa jest ograniczona, ponieważ lista obsługiwanych mechanizmów szyfrowania TLS dostępnych w tych systemach operacyjnych jest ograniczona.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Do zabezpieczenia połączeń TLS może być wymagany certyfikat wygenerowany przy użyciu algorytmu podpisu cyfrowego (ECDSA) krzywej eliptycznej.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

W przypadku nawiązania połączenia HTTP/2 raporty HttpRequest. Protocol HTTP/2 .If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

Protokół HTTP/2 jest domyślnie wyłączony.HTTP/2 is disabled by default. Więcej informacji na temat konfiguracji można znaleźć w sekcjach Kestrel Options and ListenOptions. Protocols .For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Kiedy używać Kestrel z zwrotnym serwerem proxyWhen to use Kestrel with a reverse proxy

Kestrel może być używana przez siebie lub z odwrotnym serwerem proxy , takich jak Internet Information Services (IIS), Nginxlub Apache.Kestrel can be used by itself or with a reverse proxy server , such as Internet Information Services (IIS), Nginx, or Apache. Odwrotny serwer proxy odbiera żądania HTTP z sieci i przekazuje je do usługi Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel używany jako serwer sieci Web z krawędzią (dostępną z Internetu):Kestrel used as an edge (Internet-facing) web server:

Kestrel komunikuje się bezpośrednio z Internetem bez serwera proxy zwrotnego

Kestrel używany w konfiguracji zwrotnego serwera proxy:Kestrel used in a reverse proxy configuration:

Kestrel komunikuje się pośrednio z Internetem za pomocą odwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache

Konfiguracja, z serwerem proxy odwrotnych lub bez niego, jest obsługiwaną konfiguracją hostingu.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Kestrel używany jako serwer graniczny bez serwera proxy odwrotnego nie obsługuje udostępniania tego samego adresu IP i portu między wieloma procesami.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Gdy Kestrel jest skonfigurowany do nasłuchiwania na porcie, Kestrel obsługuje cały ruch dla tego portu bez względu na nagłówki żądań Host .When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Zwrotny serwer proxy, który może udostępniać porty, ma możliwość przekazywania żądań do Kestrel na unikatowym adresie IP i porcie.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Nawet jeśli odwrotny serwer proxy nie jest wymagany, może to być dobry wybór przy użyciu odwrotnego serwera proxy.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Zwrotny serwer proxy:A reverse proxy:

  • Może ograniczać uwidoczniony obszar publicznej powierzchni aplikacji, które obsługuje.Can limit the exposed public surface area of the apps that it hosts.
  • Zapewnienie dodatkowej warstwy konfiguracji i obrony.Provide an additional layer of configuration and defense.
  • Integracja z istniejącą infrastrukturą może być lepsza.Might integrate better with existing infrastructure.
  • Uprość Równoważenie obciążenia i konfigurację komunikacji zabezpieczonej (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Tylko serwer zwrotny proxy wymaga certyfikatu X. 509, a serwer może komunikować się z serwerami aplikacji w sieci wewnętrznej przy użyciu zwykłego protokołu HTTP.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.

Ostrzeżenie

Hostowanie w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.Hosting in a reverse proxy configuration requires host filtering.

Kestrel w aplikacjach ASP.NET CoreKestrel in ASP.NET Core apps

Szablony projektów ASP.NET Core domyślnie używają Kestrel.ASP.NET Core project templates use Kestrel by default. W program.cs ConfigureWebHostDefaults Metoda wywołuje UseKestrel :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>();
        });

Więcej informacji na temat tworzenia hosta znajduje się w sekcji Konfigurowanie ustawień hosta i domyślnego konstruktora w temacie Host ogólny .NET w ASP.NET Core .For more information on building the host, see the Set up a host and Default builder settings sections of Host ogólny .NET w ASP.NET Core.

Aby zapewnić dodatkową konfigurację po wywołaniu ConfigureWebHostDefaults , użyj 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>();
        });

Opcje KestrelKestrel options

Serwer sieci Web Kestrel ma opcje konfiguracji ograniczeń, które są szczególnie przydatne w przypadku wdrożeń mających dostęp do Internetu.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Ustaw ograniczenia Limits właściwości KestrelServerOptions klasy.Set constraints on the Limits property of the KestrelServerOptions class. LimitsWłaściwość przechowuje wystąpienie KestrelServerLimits klasy.The Limits property holds an instance of the KestrelServerLimits class.

W poniższych przykładach użyto Microsoft.AspNetCore.Server.Kestrel.Core przestrzeni nazw:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

W przykładach przedstawionych w dalszej części tego artykułu opcje Kestrel są konfigurowane w kodzie C#.In examples shown later in this article, Kestrel options are configured in C# code. Opcje Kestrel można również ustawić za pomocą dostawcy konfiguracji.Kestrel options can also be set using a configuration provider. Na przykład dostawca konfiguracji plików może załadować konfigurację Kestrel z appsettings.json lub appSettings. { Environment} plik JSON :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
  }
}

Uwaga

KestrelServerOptionskonfigurację punktu końcowego można konfigurować z poziomu dostawców konfiguracji.KestrelServerOptions and endpoint configuration are configurable from configuration providers. Pozostała konfiguracja Kestrel musi być skonfigurowana w kodzie C#.Remaining Kestrel configuration must be configured in C# code.

Skorzystaj z jednej z następujących metod:Use one of the following approaches:

  • Skonfiguruj Kestrel w Startup.ConfigureServices :Configure Kestrel in Startup.ConfigureServices:

    1. Wstrzyknąć wystąpienie IConfiguration do Startup klasy.Inject an instance of IConfiguration into the Startup class. W poniższym przykładzie przyjęto założenie, że wprowadzona konfiguracja jest przypisana do Configuration właściwości.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. W programie Startup.ConfigureServices Załaduj Kestrel sekcję Konfiguracja do konfiguracji programu 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)
          {
              ...
          }
      }
      
  • Skonfiguruj Kestrel podczas kompilowania hosta:Configure Kestrel when building the host:

    W programie program.cs Załaduj Kestrel sekcję Konfiguracja do konfiguracji programu 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>();
            });
    

Obie powyższe podejścia współpracują z dowolnym dostawcą konfiguracji.Both of the preceding approaches work with any configuration provider.

Limit czasu utrzymywania aktywnościKeep-alive timeout

KeepAliveTimeout

Pobiera lub ustawia limit czasu utrzymywania aktywności.Gets or sets the keep-alive timeout. Wartość domyślna to 2 minuty.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);
})

Maksymalna liczba połączeń klientaMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maksymalna liczba współbieżnych otwartych połączeń TCP można ustawić dla całej aplikacji przy użyciu następującego kodu: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);
})

Istnieje oddzielny limit połączeń, które zostały uaktualnione z protokołu HTTP lub HTTPS do innego protokołu (na przykład w żądaniu usługi WebSockets).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Po uaktualnieniu połączenia nie jest ono wliczane do MaxConcurrentConnections limitu.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);
})

Maksymalna liczba połączeń jest domyślnie nieograniczona (null).The maximum number of connections is unlimited (null) by default.

Maksymalny rozmiar treści żądaniaMaximum request body size

MaxRequestBodySize

Domyślny maksymalny rozmiar treści żądania to 30 000 000 bajtów, czyli około 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Zalecanym podejściem do zastąpienia limitu w aplikacji ASP.NET Core MVC jest użycie RequestSizeLimitAttribute atrybutu dla metody akcji: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()

Oto przykład, który pokazuje, jak skonfigurować ograniczenie dla aplikacji w każdym żądaniu: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);
})

Zastąp ustawienie określonego żądania w oprogramowaniu pośredniczącym: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));
    }

Wyjątek jest generowany, jeśli aplikacja skonfiguruje limit żądania po rozpoczęciu uruchamiania aplikacji w celu odczytania żądania.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Istnieje IsReadOnly Właściwość, która wskazuje MaxRequestBodySize , czy właściwość jest w stanie tylko do odczytu, co oznacza, że jest zbyt późno, aby skonfigurować limit.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.

Gdy aplikacja jest uruchamiana poza procesem modułu ASP.NET Core, limit rozmiaru treści żądania Kestrel jest wyłączony, ponieważ program IIS już ustawia limit.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.

Minimalna stawka danych treści żądaniaMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel sprawdza co sekundę, jeśli dane są odbierane z określoną szybkością w bajtach na sekundę.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Jeśli szybkość spadnie poniżej wartości minimalnej, upłynął limit czasu połączenia. Okres prolongaty to czas, przez który Kestrel nadaje klientowi zwiększenie jego szybkości wysyłania do minimum; Ta częstotliwość nie jest sprawdzana w tym czasie.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. Okres prolongaty pozwala uniknąć porzucania połączeń, które początkowo wysyłają dane z niską szybkością.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

Domyślna stawka minimalna to 240 bajtów na sekundę z 5-sekundowym okresem prolongaty.The default minimum rate is 240 bytes/second with a 5 second grace period.

Minimalna stawka dotyczy także odpowiedzi.A minimum rate also applies to the response. Kod określający limit żądań i limit odpowiedzi jest taki sam, z wyjątkiem RequestBody Response właściwości i nazwy interfejsów.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.

Oto przykład pokazujący sposób konfigurowania minimalnych stawek danych w program.cs :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);
})

Przesłoń minimalne limity szybkości dla żądania w oprogramowaniu pośredniczącym: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));
    }

IHttpMinResponseDataRateFeatureOdwołania w poprzednim przykładzie nie występują w HttpContext.Features żądaniach HTTP/2, ponieważ Modyfikowanie limitów szybkości dla poszczególnych żądań jest ogólnie nieobsługiwane w przypadku protokołu HTTP/2 z powodu obsługi żądania multipleksowania żądań.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. Jednak IHttpMinRequestBodyDataRateFeature nadal występuje HttpContext.Features dla żądań HTTP/2, ponieważ limit liczby odczytów nadal można wyłączyć całkowicie dla każdego żądania przez ustawienie IHttpMinRequestBodyDataRateFeature.MinDataRate null nawet dla żądania HTTP/2.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. Próba odczytania IHttpMinRequestBodyDataRateFeature.MinDataRate lub próby ustawienia jej na wartość inną niż null spowoduje NotSupportedException zgłoszenie żądania HTTP/2.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.

Limity szybkości dla całego serwera skonfigurowane za pośrednictwem KestrelServerOptions.Limits nadal mają zastosowanie do połączeń HTTP/1. x i http/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Limit czasu nagłówków żądańRequest headers timeout

RequestHeadersTimeout

Pobiera lub ustawia maksymalny czas, przez jaki serwer spędza nagłówki żądania.Gets or sets the maximum amount of time the server spends receiving request headers. Wartość domyślna to 30 sekund.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);
})

Maksymalna liczba strumieni na połączenieMaximum streams per connection

Http2.MaxStreamsPerConnection ogranicza liczbę współbieżnych strumieni żądań na połączenie HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Odrzucone strumienie są nadmiarowe.Excess streams are refused.

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

Wartość domyślna to 100.The default value is 100.

Rozmiar tabeli nagłówkaHeader table size

Dekoder HPACK dekompresuje nagłówki HTTP dla połączeń HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize ogranicza rozmiar tabeli kompresji nagłówka używanej przez dekoder HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. Wartość jest podawana w oktetach i musi być większa od zera (0).The value is provided in octets and must be greater than zero (0).

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

Wartość domyślna to 4096.The default value is 4096.

Maksymalny rozmiar ramkiMaximum frame size

Http2.MaxFrameSize wskazuje maksymalny dozwolony rozmiar ładunku ramki połączenia HTTP/2 odebranego lub wysłanego przez serwer.Http2.MaxFrameSize indicates the maximum allowed size of an HTTP/2 connection frame payload received or sent by the server. Wartość jest podawana w oktetach i musi należeć do przedziału od 2 ^ 14 (16 384) do 2 ^ 24-1 (16 777 215).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;
});

Wartość domyślna to 2 ^ 14 (16 384).The default value is 2^14 (16,384).

Maksymalny rozmiar nagłówka żądaniaMaximum request header size

Http2.MaxRequestHeaderFieldSize wskazuje maksymalny dozwolony rozmiar w oktetach wartości nagłówka żądania.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Ten limit dotyczy zarówno nazwy, jak i wartości w skompresowanych i nieskompresowanych reprezentacji.This limit applies to both name and value in their compressed and uncompressed representations. Wartość musi być większa od zera (0).The value must be greater than zero (0).

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

Wartość domyślna to 8 192.The default value is 8,192.

Początkowy rozmiar okna połączeniaInitial connection window size

Http2.InitialConnectionWindowSize wskazuje maksymalne dane dotyczące treści żądania w bajtach, które są agregowane w buforach serwera w ramach wszystkich żądań (strumieni) na połączenie.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Żądania są również ograniczone przez Http2.InitialStreamWindowSize .Requests are also limited by Http2.InitialStreamWindowSize. Wartość musi być większa lub równa 65 535 i mniejsza niż 2 ^ 31 (2 147 483 648).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;
});

Wartość domyślna to 128 KB (131 072).The default value is 128 KB (131,072).

Rozmiar początkowego okna strumieniaInitial stream window size

Http2.InitialStreamWindowSize wskazuje maksymalne dane dotyczące treści żądania w bajtach bufory serwera w ramach żądania (Stream).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Żądania są również ograniczone przez Http2.InitialConnectionWindowSize .Requests are also limited by Http2.InitialConnectionWindowSize. Wartość musi być większa lub równa 65 535 i mniejsza niż 2 ^ 31 (2 147 483 648).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;
});

Wartość domyślna to 96 KB (98 304).The default value is 96 KB (98,304).

Konfiguracja polecenia ping Keep Alive protokołu HTTP/2HTTP/2 keep alive ping configuration

Kestrel można skonfigurować do wysyłania poleceń ping protokołu HTTP/2 do podłączonych klientów.Kestrel can be configured to send HTTP/2 pings to connected clients. Polecenia ping protokołu HTTP/2 współpracują z wieloma celami:HTTP/2 pings serve multiple purposes:

  • Utrzymywanie bezczynnych połączeń.Keep idle connections alive. Niektórzy klienci i serwery proxy zamykają połączenia, które są w stanie bezczynności.Some clients and proxy servers close connections that are idle. Polecenia ping protokołu HTTP/2 są uznawane za działania w ramach połączenia i uniemożliwiają zamknięcie połączenia w trybie bezczynności.HTTP/2 pings are considered as activity on a connection and prevent the connection from being closed as idle.
  • Zamknij połączenia w złej kondycji.Close unhealthy connections. Połączenia, w których klient nie odpowiada na polecenie "Keep Alive" w skonfigurowanym czasie, są zamykane przez serwer.Connections where the client doesn't respond to the keep alive ping in the configured time are closed by the server.

Dostępne są dwie opcje konfiguracji związane z poleceniami "Keep Alive" protokołu HTTP/2:There are two configuration options related to HTTP/2 keep alive pings:

  • Http2.KeepAlivePingInterval to element TimeSpan , który konfiguruje wewnętrznie polecenie ping.Http2.KeepAlivePingInterval is a TimeSpan that configures the ping internal. Serwer wysyła polecenie ping do klienta, jeśli nie otrzyma żadnej ramki przez ten okres.The server sends a keep alive ping to the client if it doesn't receive any frames for this period of time. Polecenia ping utrzymywania aktywności są wyłączone, gdy ta opcja jest ustawiona na TimeSpan.MaxValue .Keep alive pings are disabled when this option is set to TimeSpan.MaxValue. Wartość domyślna to TimeSpan.MaxValue.The default value is TimeSpan.MaxValue.
  • Http2.KeepAlivePingTimeout``TimeSpanumożliwia skonfigurowanie limitu czasu polecenia ping.Http2.KeepAlivePingTimeout is a TimeSpan that configures the ping timeout. Jeśli serwer nie odbiera żadnych ramek, takich jak odpowiedzi ping, podczas tego limitu czasu połączenie jest zamknięte.If the server doesn't receive any frames, such as a response ping, during this timeout then the connection is closed. Limit czasu utrzymywania aktywności jest wyłączony, gdy ta opcja jest ustawiona na TimeSpan.MaxValue .Keep alive timeout is disabled when this option is set to TimeSpan.MaxValue. Wartość domyślna to 20 sekund.The default value is 20 seconds.
webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.KeepAlivePingInterval = TimeSpan.FromSeconds(30);
    serverOptions.Limits.Http2.KeepAlivePingTimeout = TimeSpan.FromSeconds(60);
});

PrzyczepTrailers

Przyczepy HTTP są podobne do nagłówków HTTP, z tą różnicą, że są wysyłane po wysłaniu treści odpowiedzi.HTTP Trailers are similar to HTTP Headers, except they are sent after the response body is sent. W przypadku usług IIS i HTTP.SYS obsługiwane są tylko przyczepy z odpowiedzią HTTP/2.For IIS and HTTP.SYS, only HTTP/2 response trailers are supported.

if (httpContext.Response.SupportsTrailers())
{
    httpContext.Response.DeclareTrailer("trailername"); 

    // Write body
    httpContext.Response.WriteAsync("Hello world");

    httpContext.Response.AppendTrailer("trailername", "TrailerValue");
}

W poprzednim przykładowym kodzie:In the preceding example code:

  • SupportsTrailers zapewnia, że przyczepy są obsługiwane na potrzeby odpowiedzi.SupportsTrailers ensures that trailers are supported for the response.
  • DeclareTrailer Dodaje nazwę danej przyczepy do Trailer nagłówka odpowiedzi.DeclareTrailer adds the given trailer name to the Trailer response header. Deklarowanie przyczep z odpowiedzią jest opcjonalne, ale zalecane.Declaring a response's trailers is optional, but recommended. Jeśli DeclareTrailer jest wywoływana, musi być przed wysłaniem nagłówków odpowiedzi.If DeclareTrailer is called, it must be before the response headers are sent.
  • AppendTrailer dołącza przyczepę.AppendTrailer appends the trailer.

ResetReset

Wartość Resetuj umożliwia serwerowi zresetowanie żądania HTTP/2 z określonym kodem błędu.Reset allows for the server to reset a HTTP/2 request with a specified error code. Żądanie resetowania jest uznawane za przerwane.A reset request is considered aborted.

var resetFeature = httpContext.Features.Get<IHttpResetFeature>();
resetFeature.Reset(errorCode: 2);

Reset w poprzednim przykładzie kodu określa INTERNAL_ERROR Kod błędu.Reset in the preceding code example specifies the INTERNAL_ERROR error code. Więcej informacji o kodach błędów protokołu HTTP/2 znajduje się w sekcji kod błędu specyfikacji protokołu HTTP/2.For more information about HTTP/2 error codes, visit the HTTP/2 specification error code section.

Synchroniczne operacje we/wySynchronous I/O

AllowSynchronousIO Określa, czy synchroniczna operacja we/wy jest dozwolona dla żądania i odpowiedzi.AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. Wartość domyślna to false.The default value is false.

Ostrzeżenie

Duża liczba blokowania synchronicznych operacji we/wy może prowadzić do zablokowania puli wątków, co sprawia, że aplikacja nie odpowiada.A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Włączaj tylko AllowSynchronousIO w przypadku korzystania z biblioteki, która nie obsługuje asynchronicznych operacji we/wy.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous I/O.

Poniższy przykład umożliwia synchroniczne we/wy:The following example enables synchronous I/O:

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

Aby uzyskać informacje o innych opcjach i ograniczeniach Kestrel, zobacz:For information about other Kestrel options and limits, see:

Konfiguracja punktu końcowegoEndpoint configuration

Domyślnie ASP.NET Core wiąże się z:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (gdy obecny jest lokalny certyfikat programistyczny)https://localhost:5001 (when a local development certificate is present)

Określ adresy URL przy użyciu:Specify URLs using the:

  • ASPNETCORE_URLS Zmienna środowiskowa.ASPNETCORE_URLS environment variable.
  • --urls argument wiersza polecenia.--urls command-line argument.
  • urls klucz konfiguracji hosta.urls host configuration key.
  • UseUrls Metoda rozszerzenia.UseUrls extension method.

Wartość podana przy użyciu tych metod może być jednym lub większą liczbą punktów końcowych HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001" ).Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Aby uzyskać więcej informacji na temat tych metod, zobacz adresy URL serwera i Zastąp konfigurację.For more information on these approaches, see Server URLs and Override configuration.

Tworzony jest certyfikat programistyczny:A development certificate is created:

Niektóre przeglądarki wymagają przyznania jawnego uprawnienia do zaufania do lokalnego certyfikatu deweloperskiego.Some browsers require granting explicit permission to trust the local development certificate.

Szablony projektu konfigurują aplikacje do uruchamiania domyślnie przy użyciu protokołu HTTPS i obejmują przekierowania https i obsługę HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Wywołanie Listen lub ListenUnixSocket metody w KestrelServerOptions celu skonfigurowania prefiksów i portów adresów URL dla Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, --urls argument wiersza polecenia, urls klucz konfiguracji hosta i ASPNETCORE_URLS zmienna środowiskowa również działają, ale mają ograniczenia wymienione w dalszej części tej sekcji (certyfikat domyślny musi być dostępny dla konfiguracji punktu końcowego HTTPS).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 skonfigurowaćKestrelServerOptions configuration:

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

Określa konfigurację Action do uruchomienia dla każdego określonego punktu końcowego.Specifies a configuration Action to run for each specified endpoint. Wywołanie ConfigureEndpointDefaults wielokrotne zastępuje przed Action ostatnimi Action parametrami.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

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

Uwaga

Punkty końcowe utworzone przez wywołanie Listen przed wywołaniem ConfigureEndpointDefaults nie mają zastosowania wartości domyślnych.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

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

Określa konfigurację Action do uruchomienia dla każdego punktu końcowego HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Wywołanie ConfigureHttpsDefaults wielokrotne zastępuje przed Action ostatnimi Action parametrami.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;
    });
});

Uwaga

Punkty końcowe utworzone przez wywołanie Listen przed wywołaniem ConfigureHttpsDefaults nie mają zastosowania wartości domyślnych.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Konfiguruj (IConfiguration)Configure(IConfiguration)

Tworzy moduł ładujący konfigurację na potrzeby konfigurowania Kestrel, które pobiera IConfiguration jako dane wejściowe.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. Konfiguracja musi być objęta zakresem sekcji konfiguracji dla Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Skonfiguruj Kestrel do korzystania z protokołu HTTPS.Configure Kestrel to use HTTPS.

ListenOptions.UseHttps rozszerzeniaListenOptions.UseHttps extensions:

  • UseHttps: Skonfiguruj Kestrel do używania protokołu HTTPS z domyślnym certyfikatem.UseHttps: Configure Kestrel to use HTTPS with the default certificate. Zgłasza wyjątek, jeśli nie został skonfigurowany żaden certyfikat domyślny.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 wejścioweListenOptions.UseHttps parameters:

  • filename jest ścieżką i nazwą pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X. 509.password is the password required to access the X.509 certificate data.
  • configureOptions jest Action do skonfigurowania HttpsConnectionAdapterOptions .configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Zwraca wartość ListenOptions .Returns the ListenOptions.
  • storeName to magazyn certyfikatów, z którego ma zostać załadowany certyfikat.storeName is the certificate store from which to load the certificate.
  • subject to nazwa podmiotu certyfikatu.subject is the subject name for the certificate.
  • allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location jest lokalizacją magazynu, z której ma zostać załadowany certyfikat.location is the store location to load the certificate from.
  • serverCertificate jest certyfikatem X. 509.serverCertificate is the X.509 certificate.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS.In production, HTTPS must be explicitly configured. Należy podać co najmniej certyfikat domyślny.At a minimum, a default certificate must be provided.

Obsługiwane konfiguracje opisane dalej:Supported configurations described next:

  • Brak konfiguracjiNo configuration
  • Zastąp domyślny certyfikat z konfiguracjiReplace the default certificate from configuration
  • Zmień wartości domyślne w kodzieChange the defaults in code

Brak konfiguracjiNo configuration

Kestrel nasłuchuje w systemie http://localhost:5000 i https://localhost:5001 (Jeśli domyślny certyfikat jest dostępny).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Zastąp domyślny certyfikat z konfiguracjiReplace the default certificate from configuration

CreateDefaultBuilder wywołania Configure(context.Configuration.GetSection("Kestrel")) domyślnie do ładowania konfiguracji Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Konfigurowanie wielu punktów końcowych, w tym adresów URL i certyfikatów do użycia, z pliku znajdującego się na dysku lub z magazynu certyfikatów.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

W poniższym appsettings.json przykładzie:In the following appsettings.json example:

  • Ustaw AllowInvalid na, true Aby zezwolić na korzystanie z nieprawidłowych certyfikatów (na przykład certyfikatów z podpisem własnym).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Wszystkie punkty końcowe HTTPS, które nie określają certyfikatu ( HttpsDefaultCert w poniższym przykładzie) powracają do certyfikatu zdefiniowanego w obszarze Certyfikaty > domyślne lub certyfikat programistyczny.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>"
      }
    }
  }
}

Alternatywą dla korzystania z ścieżki i hasła dla dowolnego węzła certyfikatu jest określenie certyfikatu przy użyciu pól magazynu certyfikatów.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Certyfikat domyślny można na przykład > Default określić jako: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>"
}

Uwagi dotyczące schematu:Schema notes:

  • W nazwach punktów końcowych nie jest rozróżniana wielkość liter.Endpoints names are case-insensitive. Na przykład HTTPS i Https są prawidłowe.For example, HTTPS and Https are valid.
  • UrlParametr jest wymagany dla każdego punktu końcowego.The Url parameter is required for each endpoint. Format tego parametru jest taki sam jak parametr konfiguracji najwyższego poziomu, Urls z tą różnicą, że jest ograniczony do pojedynczej wartości.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego poziomu Urls zamiast dodawać je do nich.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Punkty końcowe zdefiniowane w kodzie za pośrednictwem Listen łączą się z punktami końcowymi zdefiniowanymi w sekcji konfiguracji.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • CertificateSekcja jest opcjonalna.The Certificate section is optional. Jeśli Certificate sekcja nie jest określona, używane są wartości domyślne zdefiniowane we wcześniejszych scenariuszach.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Jeśli żadne wartości domyślne nie są dostępne, serwer zgłasza wyjątek i nie może się uruchomić.If no defaults are available, the server throws an exception and fails to start.
  • CertificateSekcja obsługuje zarówno hasło ścieżkiPassword , jak i certyfikaty magazynu podmiotuStore .The Certificate section supports both PathPassword and SubjectStore certificates.
  • W ten sposób można zdefiniować dowolną liczbę punktów końcowych, dopóki nie spowoduje to konfliktów portów.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}")) zwraca KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) metodę, która może służyć do uzupełniania skonfigurowanych ustawień punktu końcowego: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;
        });
});

KestrelServerOptions.ConfigurationLoader można uzyskać bezpośredni dostęp do kontynuowania iteracji w istniejącym module ładującym, takim jak dostarczony przez CreateDefaultBuilder .KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach w Endpoint metodzie, aby można było odczytać ustawienia niestandardowe.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Można załadować wiele konfiguracji, wywołując options.Configure(context.Configuration.GetSection("{SECTION}")) ponownie z inną sekcją.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Używana jest tylko Ostatnia konfiguracja, chyba że Load jest jawnie wywoływana w poprzednich wystąpieniach.Only the last configuration is used, unless Load is explicitly called on prior instances. Pakiet nie wywołuje metody, Load Aby można było zastąpić sekcję konfiguracji domyślnej.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader odzwierciedla Listen rodzinę interfejsów API z programu KestrelServerOptions jako Endpoint przeciążenia, dlatego punkty końcowe kodu i konfiguracji można skonfigurować w tym samym miejscu.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.These overloads don't use names and only consume default settings from configuration.

Zmień wartości domyślne w kodzieChange the defaults in code

ConfigureEndpointDefaults i ConfigureHttpsDefaults może służyć do zmiany ustawień domyślnych dla ListenOptions i HttpsConnectionAdapterOptions , w tym przesłanianie domyślnego certyfikatu określonego w poprzednim scenariuszu.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 i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem punktów końcowych.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;
    });
});

Obsługa usługi Kestrel dla SNIKestrel support for SNI

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i porcie.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Aby SNI działał, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uzgadniania TLS, aby serwer mógł zapewnić prawidłowy certyfikat.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. Klient korzysta z dostarczonego certyfikatu w celu zaszyfrowania komunikacji z serwerem podczas bezpiecznej sesji, która następuje po uzgadnianiu protokołu TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel obsługuje SNI za pośrednictwem ServerCertificateSelector wywołania zwrotnego.Kestrel supports SNI via the ServerCertificateSelector callback. Wywołanie zwrotne jest wywoływane jednokrotnie dla każdego połączenia, aby umożliwić aplikacji inspekcję nazwy hosta i wybieranie odpowiedniego certyfikatu.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Obsługa SNI wymaga:SNI support requires:

  • Uruchomiona w środowisku docelowym netcoreapp2.1 lub nowszym.Running on target framework netcoreapp2.1 or later. W dniu net461 lub później wywołanie zwrotne jest wywoływane, ale name jest zawsze null .On net461 or later, the callback is invoked but the name is always null. nameJest również, null Jeśli klient nie poda parametru nazwy hosta w UZGADNIANIU protokołu TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Wszystkie witryny sieci Web działają na tym samym wystąpieniu Kestrel.All websites run on the same Kestrel instance. Kestrel nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera proxy.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;
            };
        });
    });
});

Rejestrowanie połączeńConnection logging

Wywołanie UseConnectionLogging do emisji dzienników na poziomie debugowania dla komunikacji na poziomie bajtów w ramach połączenia.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. Rejestrowanie połączeń ułatwia rozwiązywanie problemów z komunikacją na niskim poziomie, na przykład podczas szyfrowania TLS i za serwerami proxy.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Jeśli UseConnectionLogging jest umieszczona przed UseHttps , szyfrowany ruch jest rejestrowany.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Jeśli UseConnectionLogging jest umieszczony po UseHttps , odszyfrowany ruch jest rejestrowany.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

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

Powiąż z gniazdem TCPBind to a TCP socket

ListenMetoda wiąże się z gniazdem TCP, a opcja lambda zezwala na konfigurację certyfikatu X. 509: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>();
        });

Przykład konfiguruje HTTPS dla punktu końcowego za pomocą ListenOptions .The example configures HTTPS for an endpoint with ListenOptions. Użyj tego samego interfejsu API, aby skonfigurować inne ustawienia Kestrel dla określonych punktów końcowych.Use the same API to configure other Kestrel settings for specific endpoints.

W systemie Windows certyfikaty z podpisem własnym można tworzyć za pomocą polecenia cmdlet Programu PowerShell new-SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Aby zapoznać się z nieobsługiwionym przykładem, zobacz UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows certyfikaty można tworzyć za pomocą funkcji OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Powiąż z gniazdem systemu UNIXBind to a Unix socket

Nasłuchiwanie w gnieździe systemu UNIX za pomocą ListenUnixSocket programu w celu zwiększenia wydajności za pomocą usługi Nginx, jak pokazano w tym przykładzie: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");
        });
})
  • W pliku konfiguracji Nginx Ustaw server > location > proxy_pass pozycję na http://unix:/tmp/{KESTREL SOCKET}:/; .In the Nginx configuration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} jest nazwą gniazda, na ListenUnixSocket przykład kestrel-test.sock w powyższym przykładzie).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład 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

Gdy numer portu 0 jest określony, Kestrel dynamicznie wiąże się z dostępnym portem.When the port number 0 is specified, Kestrel dynamically binds to an available port. W poniższym przykładzie pokazano, jak określić, który port Kestrel faktycznie powiązany w czasie wykonywania: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>");
    });
}

Po uruchomieniu aplikacji dane wyjściowe okna konsoli wskazują port dynamiczny, w którym można uzyskać dostęp do aplikacji: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

OgraniczeniaLimitations

Skonfiguruj punkty końcowe przy użyciu następujących metod:Configure endpoints with the following approaches:

  • UseUrls
  • --urls argument wiersza polecenia--urls command-line argument
  • urls klucz konfiguracji hostaurls host configuration key
  • ASPNETCORE_URLS Zmienna środowiskowaASPNETCORE_URLS environment variable

Te metody są przydatne do tworzenia kodu w pracy z serwerami innymi niż Kestrel.These methods are useful for making code work with servers other than Kestrel. Należy jednak pamiętać o następujących ograniczeniach:However, be aware of the following limitations:

  • Nie można użyć protokołu HTTPS z tymi metodami, chyba że w konfiguracji punktu końcowego HTTPS jest podany certyfikat domyślny (na przykład przy użyciu KestrelServerOptions konfiguracji lub pliku konfiguracji, jak pokazano wcześniej w tym temacie).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).
  • Gdy oba Listen podejścia i UseUrls są używane jednocześnie, Listen punkty końcowe zastępują UseUrls punkty końcowe.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Konfiguracja punktu końcowego usług IISIIS endpoint configuration

W przypadku korzystania z usług IIS powiązania URL dla powiązań przesłonięć usług IIS są ustawiane przez Listen lub UseUrls .When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Aby uzyskać więcej informacji, zobacz temat ASP.NET Core Module .For more information, see the ASP.NET Core Module topic.

ListenOptions. ProtocolsListenOptions.Protocols

ProtocolsWłaściwość ustanawia protokoły HTTP ( HttpProtocols ) włączone w punkcie końcowym połączenia lub dla serwera.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Przypisz wartość do Protocols właściwości z HttpProtocols wyliczenia.Assign a value to the Protocols property from the HttpProtocols enum.

HttpProtocols wartość wyliczeniaHttpProtocols enum value Dozwolony protokół połączeniaConnection protocol permitted
Http1 Tylko HTTP/1.1.HTTP/1.1 only. Może być używany z protokołem TLS lub bez niego.Can be used with or without TLS.
Http2 Tylko HTTP/2.HTTP/2 only. Mogą być używane bez protokołu TLS tylko wtedy, gdy klient obsługuje poprzedni tryb wiedzy.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 i HTTP/2.HTTP/1.1 and HTTP/2. Protokół HTTP/2 wymaga od klienta wyboru protokołu HTTP/2 w uzgadnianiu negocjowania protokołu TLS aplikacji (ClientHello alpn) . w przeciwnym razie wartość domyślna połączenia to HTTP/1.1.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.

Wartość domyślna ListenOptions.Protocols dla każdego punktu końcowego to HttpProtocols.Http1AndHttp2 .The default ListenOptions.Protocols value for any endpoint is HttpProtocols.Http1AndHttp2.

Ograniczenia protokołu TLS dla protokołu HTTP/2:TLS restrictions for HTTP/2:

  • TLS w wersji 1,2 lub nowszejTLS version 1.2 or later
  • Ponowne negocjowanie wyłączoneRenegotiation disabled
  • Kompresja wyłączonaCompression disabled
  • Minimalne rozmiary tymczasowych kluczy wymiany:Minimum ephemeral key exchange sizes:
    • Krzywa eliptyczna Diffie-Hellman (ECDHE) [ RFC4492 ] : minimum 224 bitówElliptic curve Diffie-Hellman (ECDHE) [RFC4492]: 224 bits minimum
    • Ograniczone pole Diffie-Hellman (DHE) [ TLS12 ] : minimum 2048 bitówFinite field Diffie-Hellman (DHE) [TLS12]: 2048 bits minimum
  • Mechanizm szyfrowania jest niedozwolony.Cipher suite not prohibited.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256[TLS-ECDHE] z krzywą eliptyczna P-256 [ FIPS186 ] jest domyślnie obsługiwana.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

Poniższy przykład umożliwia nawiązywanie połączeń HTTP/1.1 i HTTP/2 na porcie 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Połączenia są zabezpieczone przez protokół TLS przy użyciu podanego certyfikatu:Connections are secured by TLS with a supplied certificate:

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

Używaj oprogramowania pośredniczącego do filtrowania uzgadniania protokołu TLS dla poszczególnych połączeń dla określonych szyfrów, jeśli jest to wymagane.Use Connection Middleware to filter TLS handshakes on a per-connection basis for specific ciphers if required.

Poniższy przykład zgłasza NotSupportedException dowolny algorytm szyfrowania, który nie jest obsługiwany przez aplikację.The following example throws NotSupportedException for any cipher algorithm that the app doesn't support. Alternatywnie można zdefiniować i porównać ITlsHandshakeFeature. CipherAlgorithm z listą akceptowalnych mechanizmów szyfrowania.Alternatively, define and compare ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher suites.

Nie jest używane szyfrowanie z algorytmem szyfrowania CipherAlgorithmType. null .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();
            });
        }
    }
}

Filtrowanie połączeń można również skonfigurować za pomocą wyrażenia IConnectionBuilder lambda: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();
        });
    });
});

W systemie Linux CipherSuitesPolicy można używać do filtrowania uzgadniania protokołu TLS dla poszczególnych połączeń: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,
                    // ...
                });
        };
    });
});

Ustawianie protokołu z konfiguracjiSet the protocol from configuration

CreateDefaultBuilder wywołania serverOptions.Configure(context.Configuration.GetSection("Kestrel")) domyślnie do ładowania konfiguracji Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

W poniższym appsettings.json przykładzie jako domyślny protokół połączenia dla wszystkich punktów końcowych jest przychodzący ruch HTTP/1.1:The following appsettings.json example establishes HTTP/1.1 as the default connection protocol for all endpoints:

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

Poniższy appsettings.json przykład ustanawia protokół połączeń HTTP/1.1 dla określonego punktu końcowego: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"
      }
    }
  }
}

Protokoły określone w wartościach zastąpienia kodu ustawione przez konfigurację.Protocols specified in code override values set by configuration.

Konfiguracja transportuTransport configuration

Dla projektów, które wymagają użycia Libuv ( UseLibuv ):For projects that require the use of Libuv (UseLibuv):

  • Dodaj zależność dla pakietu Microsoft. AspNetCore. Server. Kestrel. transport. Libuv do pliku projektu aplikacji: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}" />
    
  • Wywołaj UseLibuv IWebHostBuilder :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>();
                 });
    }
    

Prefiksy adresów URLURL prefixes

W przypadku użycia UseUrls , --urls argumentu wiersza polecenia, urls klucza konfiguracji hosta lub ASPNETCORE_URLS zmiennej środowiskowej prefiksy adresów URL mogą znajdować się w jednym z następujących formatów.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.

Tylko prefiksy adresów URL HTTP są prawidłowe.Only HTTP URL prefixes are valid. Kestrel nie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy użyciu programu UseUrls .Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Adres IPv4 z numerem portuIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 jest szczególnym przypadkiem, który wiąże się ze wszystkimi adresami IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Adres IPv6 z numerem portuIPv6 address with port number

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

    [::] jest odpowiednikiem IPv6 dla protokołu IPv4 0.0.0.0 .[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nazwa hosta z numerem portuHost name with port number

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

    Nazwy hostów, * i + , nie są specjalne.Host names, *, and +, aren't special. Wszystkie nie są rozpoznawane jako prawidłowy adres IP lub są localhost powiązane ze wszystkimi IP IPv4 i IPv6.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core aplikacjami na tym samym porcie, użyj HTTP.sys lub zwrotnego serwera proxy, takiego jak IIS, Nginx lub 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.

    Ostrzeżenie

    Hostowanie w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.Hosting in a reverse proxy configuration requires host filtering.

  • localhostNazwa hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portuHost localhost name with port number or loopback IP with port number

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

    Gdy localhost jest określony, Kestrel próbuje powiązać z interfejsami sprzężenia zwrotnego IPv4 i IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Jeśli żądany port jest używany przez inną usługę w dowolnym interfejsie sprzężenia zwrotnego, uruchomienie Kestrel nie powiedzie się.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Jeśli którykolwiek z innych przyczyn interfejsu sprzężenia zwrotnego jest niedostępny (najczęściej jest to spowodowane tym, że protokół IPv6 nie jest obsługiwany), Kestrel rejestruje ostrzeżenie.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtrowanie hostówHost filtering

Program Kestrel obsługuje konfigurację na podstawie prefiksów, takich jak http://example.com:5000 , Kestrel w znacznym stopniu ignoruje nazwę hosta.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. Host localhost jest specjalnym przypadkiem używanym do tworzenia powiązań z adresami sprzężenia zwrotnego.Host localhost is a special case used for binding to loopback addresses. Każdy host poza jawnym adresem IP tworzy powiązanie ze wszystkimi publicznymi adresami IP.Any host other than an explicit IP address binds to all public IP addresses. Host nagłówki nie są sprawdzane.Host headers aren't validated.

Aby obejść ten sposób, użyj oprogramowania pośredniczącego filtrowania hosta.As a workaround, use Host Filtering Middleware. Oprogramowanie pośredniczące do filtrowania hosta jest dostarczane przez pakiet Microsoft. AspNetCore. HostFiltering , który jest niejawnie dostarczany dla ASP.NET Core aplikacji.Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is implicitly provided for ASP.NET Core apps. Oprogramowanie pośredniczące jest dodawane przez CreateDefaultBuilder program, który wywołuje AddHostFiltering następujące wywołania: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>();
}

Programowe filtrowanie hosta jest domyślnie wyłączone.Host Filtering Middleware is disabled by default. Aby włączyć oprogramowanie pośredniczące, zdefiniuj AllowedHosts klucz w appsettings.json / appSettings. <EnvironmentName> kod JSON .To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json . Wartość to rozdzielana średnikami lista nazw hostów bez numerów portów:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json :appsettings.json :

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

Uwaga

Przekierowane nagłówki oprogramowania również mają AllowedHosts opcję.Forwarded Headers Middleware also has an AllowedHosts option. Przekazane nagłówki — oprogramowanie pośredniczące i filtrowanie hostów oprogramowanie pośredniczące ma podobną funkcjonalność dla różnych scenariuszy.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Ustawienie AllowedHosts z przekierowanymi nagłówkami — oprogramowanie pośredniczące jest odpowiednie, gdy Host nagłówek nie jest zachowywany podczas przekazywania żądań z odwrotnym serwerem proxy lub modułem równoważenia obciążenia.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. Ustawienie AllowedHosts przy użyciu oprogramowania pośredniczącego filtrowania hosta jest odpowiednie, gdy Kestrel jest używany jako publiczny serwer graniczny lub gdy Host nagłówek jest bezpośrednio przekazywany.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.

Aby uzyskać więcej informacji na temat przekierowanych nagłówków, należy zapoznać się z tematem Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia .For more information on Forwarded Headers Middleware, see Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia.

Kestrel to Międzyplatformowy serwer sieci Web dla ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel to serwer sieci Web, który jest domyślnie uwzględniony w szablonach projektu ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel obsługuje następujące scenariusze:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Nieprzezroczyste uaktualnienie używane do włączania obsługi obiektów WebSocketsOpaque upgrade used to enable WebSockets
  • Gniazda systemu UNIX w celu zapewnienia wysokiej wydajności w tle NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (z wyjątkiem macOS † )HTTP/2 (except on macOS†)

†Protokół HTTP/2 będzie obsługiwany w przypadku macOS w przyszłej wersji.†HTTP/2 will be supported on macOS in a future release.

Kestrel jest obsługiwana na wszystkich platformach i wersjach obsługiwanych przez platformę .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Wyświetl lub pobierz przykładowy kod (jak pobrać)View or download sample code (how to download)

Obsługa protokołu HTTP/2HTTP/2 support

Protokół HTTP/2 jest dostępny dla aplikacji ASP.NET Core, jeśli spełnione są następujące wymagania podstawowe:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • System operacyjny†Operating system†
    • Windows Server 2016/Windows 10 lub nowszy‡Windows Server 2016/Windows 10 or later‡
    • Linux z OpenSSL 1.0.2 lub nowszym (na przykład Ubuntu 16,04 lub nowszy)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Platforma docelowa: .NET Core 2,2 lub nowszyTarget framework: .NET Core 2.2 or later
  • Połączenie negocjowania protokołu warstwy aplikacji (ClientHello alpn)Application-Layer Protocol Negotiation (ALPN) connection
  • Połączenie TLS 1,2 lub nowszeTLS 1.2 or later connection

†Protokół HTTP/2 będzie obsługiwany w przypadku macOS w przyszłej wersji.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel ma ograniczoną obsługę protokołu HTTP/2 w systemie Windows Server 2012 R2 i Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Obsługa jest ograniczona, ponieważ lista obsługiwanych mechanizmów szyfrowania TLS dostępnych w tych systemach operacyjnych jest ograniczona.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Do zabezpieczenia połączeń TLS może być wymagany certyfikat wygenerowany przy użyciu algorytmu podpisu cyfrowego (ECDSA) krzywej eliptycznej.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

W przypadku nawiązania połączenia HTTP/2 raporty HttpRequest. Protocol HTTP/2 .If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

Protokół HTTP/2 jest domyślnie wyłączony.HTTP/2 is disabled by default. Więcej informacji na temat konfiguracji można znaleźć w sekcjach Kestrel Options and ListenOptions. Protocols .For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Kiedy używać Kestrel z zwrotnym serwerem proxyWhen to use Kestrel with a reverse proxy

Kestrel może być używana przez siebie lub z odwrotnym serwerem proxy , takich jak Internet Information Services (IIS), Nginxlub Apache.Kestrel can be used by itself or with a reverse proxy server , such as Internet Information Services (IIS), Nginx, or Apache. Odwrotny serwer proxy odbiera żądania HTTP z sieci i przekazuje je do usługi Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel używany jako serwer sieci Web z krawędzią (dostępną z Internetu):Kestrel used as an edge (Internet-facing) web server:

Kestrel komunikuje się bezpośrednio z Internetem bez serwera proxy zwrotnego

Kestrel używany w konfiguracji zwrotnego serwera proxy:Kestrel used in a reverse proxy configuration:

Kestrel komunikuje się pośrednio z Internetem za pomocą odwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache

Konfiguracja, z serwerem proxy odwrotnych lub bez niego, jest obsługiwaną konfiguracją hostingu.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Kestrel używany jako serwer graniczny bez serwera proxy odwrotnego nie obsługuje udostępniania tego samego adresu IP i portu między wieloma procesami.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Gdy Kestrel jest skonfigurowany do nasłuchiwania na porcie, Kestrel obsługuje cały ruch dla tego portu bez względu na nagłówki żądań Host .When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Zwrotny serwer proxy, który może udostępniać porty, ma możliwość przekazywania żądań do Kestrel na unikatowym adresie IP i porcie.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Nawet jeśli odwrotny serwer proxy nie jest wymagany, może to być dobry wybór przy użyciu odwrotnego serwera proxy.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Zwrotny serwer proxy:A reverse proxy:

  • Może ograniczać uwidoczniony obszar publicznej powierzchni aplikacji, które obsługuje.Can limit the exposed public surface area of the apps that it hosts.
  • Zapewnienie dodatkowej warstwy konfiguracji i obrony.Provide an additional layer of configuration and defense.
  • Integracja z istniejącą infrastrukturą może być lepsza.Might integrate better with existing infrastructure.
  • Uprość Równoważenie obciążenia i konfigurację komunikacji zabezpieczonej (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Tylko serwer zwrotny proxy wymaga certyfikatu X. 509, a serwer może komunikować się z serwerami aplikacji w sieci wewnętrznej przy użyciu zwykłego protokołu HTTP.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.

Ostrzeżenie

Hostowanie w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.Hosting in a reverse proxy configuration requires host filtering.

Jak używać Kestrel w aplikacjach ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

Pakiet Microsoft. AspNetCore. Server. Kestrel jest zawarty w pakiecie Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

Szablony projektów ASP.NET Core domyślnie używają Kestrel.ASP.NET Core project templates use Kestrel by default. W program.cs , kod szablonu wywołuje CreateDefaultBuilder , który wywołuje się w UseKestrel tle.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>();

Więcej informacji na temat CreateDefaultBuilder i kompilowanie hosta znajduje się w sekcji Konfigurowanie hosta w temacie ASP.NET Core hosta sieci Web .For more information on CreateDefaultBuilder and building the host, see the Set up a host section of ASP.NET Core hosta sieci Web.

Aby zapewnić dodatkową konfigurację po wywołaniu CreateDefaultBuilder , użyj 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
        });

Jeśli aplikacja nie wywoła połączenia CreateDefaultBuilder w celu skonfigurowania hosta, wywołaj UseKestrel przed wywołaniem ConfigureKestrel :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();
}

Opcje KestrelKestrel options

Serwer sieci Web Kestrel ma opcje konfiguracji ograniczeń, które są szczególnie przydatne w przypadku wdrożeń mających dostęp do Internetu.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Ustaw ograniczenia Limits właściwości KestrelServerOptions klasy.Set constraints on the Limits property of the KestrelServerOptions class. LimitsWłaściwość przechowuje wystąpienie KestrelServerLimits klasy.The Limits property holds an instance of the KestrelServerLimits class.

W poniższych przykładach użyto Microsoft.AspNetCore.Server.Kestrel.Core przestrzeni nazw:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Opcje Kestrel, które są konfigurowane w kodzie C# w poniższych przykładach, można również ustawić za pomocą dostawcy konfiguracji.Kestrel options, which are configured in C# code in the following examples, can also be set using a configuration provider. Na przykład dostawca konfiguracji plików może załadować konfigurację Kestrel z appsettings.json lub appSettings. { Environment} plik JSON :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
    }
  }
}

Skorzystaj z jednej z następujących metod:Use one of the following approaches:

  • Skonfiguruj Kestrel w Startup.ConfigureServices :Configure Kestrel in Startup.ConfigureServices:

    1. Wstrzyknąć wystąpienie IConfiguration do Startup klasy.Inject an instance of IConfiguration into the Startup class. W poniższym przykładzie przyjęto założenie, że wprowadzona konfiguracja jest przypisana do Configuration właściwości.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. W programie Startup.ConfigureServices Załaduj Kestrel sekcję Konfiguracja do konfiguracji programu 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)
          {
              ...
          }
      }
      
  • Skonfiguruj Kestrel podczas kompilowania hosta:Configure Kestrel when building the host:

    W programie program.cs Załaduj Kestrel sekcję Konfiguracja do konfiguracji programu 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>();
    

Obie powyższe podejścia współpracują z dowolnym dostawcą konfiguracji.Both of the preceding approaches work with any configuration provider.

Limit czasu utrzymywania aktywnościKeep-alive timeout

KeepAliveTimeout

Pobiera lub ustawia limit czasu utrzymywania aktywności.Gets or sets the keep-alive timeout. Wartość domyślna to 2 minuty.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);
});

Maksymalna liczba połączeń klientaMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maksymalna liczba współbieżnych otwartych połączeń TCP można ustawić dla całej aplikacji przy użyciu następującego kodu: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);
});

Istnieje oddzielny limit połączeń, które zostały uaktualnione z protokołu HTTP lub HTTPS do innego protokołu (na przykład w żądaniu usługi WebSockets).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Po uaktualnieniu połączenia nie jest ono wliczane do MaxConcurrentConnections limitu.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);
});

Maksymalna liczba połączeń jest domyślnie nieograniczona (null).The maximum number of connections is unlimited (null) by default.

Maksymalny rozmiar treści żądaniaMaximum request body size

MaxRequestBodySize

Domyślny maksymalny rozmiar treści żądania to 30 000 000 bajtów, czyli około 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Zalecanym podejściem do zastąpienia limitu w aplikacji ASP.NET Core MVC jest użycie RequestSizeLimitAttribute atrybutu dla metody akcji: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()

Oto przykład, który pokazuje, jak skonfigurować ograniczenie dla aplikacji w każdym żądaniu: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);
});

Zastąp ustawienie określonego żądania w oprogramowaniu pośredniczącym: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));
    }

Wyjątek jest generowany, jeśli aplikacja skonfiguruje limit żądania po rozpoczęciu uruchamiania aplikacji w celu odczytania żądania.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Istnieje IsReadOnly Właściwość, która wskazuje MaxRequestBodySize , czy właściwość jest w stanie tylko do odczytu, co oznacza, że jest zbyt późno, aby skonfigurować limit.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.

Gdy aplikacja jest uruchamiana poza procesem modułu ASP.NET Core, limit rozmiaru treści żądania Kestrel jest wyłączony, ponieważ program IIS już ustawia limit.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.

Minimalna stawka danych treści żądaniaMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel sprawdza co sekundę, jeśli dane są odbierane z określoną szybkością w bajtach na sekundę.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Jeśli szybkość spadnie poniżej wartości minimalnej, upłynął limit czasu połączenia. Okres prolongaty to czas, przez który Kestrel nadaje klientowi zwiększenie jego szybkości wysyłania do minimum; Ta częstotliwość nie jest sprawdzana w tym czasie.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. Okres prolongaty pozwala uniknąć porzucania połączeń, które początkowo wysyłają dane z niską szybkością.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

Domyślna stawka minimalna to 240 bajtów na sekundę z 5-sekundowym okresem prolongaty.The default minimum rate is 240 bytes/second with a 5 second grace period.

Minimalna stawka dotyczy także odpowiedzi.A minimum rate also applies to the response. Kod określający limit żądań i limit odpowiedzi jest taki sam, z wyjątkiem RequestBody Response właściwości i nazwy interfejsów.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.

Oto przykład pokazujący sposób konfigurowania minimalnych stawek danych w program.cs :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);
});

Przesłoń minimalne limity szybkości dla żądania w oprogramowaniu pośredniczącym: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));
    }

Funkcja rate, do której odwołuje się poprzednia próba, nie jest dostępna w HttpContext.Features przypadku żądań HTTP/2, ponieważ Modyfikowanie limitów szybkości dla poszczególnych żądań nie jest obsługiwane w przypadku protokołu HTTP/2 ze względu na obsługę multipleksera żądania.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. Limity szybkości dla całego serwera skonfigurowane za pośrednictwem KestrelServerOptions.Limits nadal mają zastosowanie do połączeń HTTP/1. x i http/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Limit czasu nagłówków żądańRequest headers timeout

RequestHeadersTimeout

Pobiera lub ustawia maksymalny czas, przez jaki serwer spędza nagłówki żądania.Gets or sets the maximum amount of time the server spends receiving request headers. Wartość domyślna to 30 sekund.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);
});

Maksymalna liczba strumieni na połączenieMaximum streams per connection

Http2.MaxStreamsPerConnection ogranicza liczbę współbieżnych strumieni żądań na połączenie HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. Odrzucone strumienie są nadmiarowe.Excess streams are refused.

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

Wartość domyślna to 100.The default value is 100.

Rozmiar tabeli nagłówkaHeader table size

Dekoder HPACK dekompresuje nagłówki HTTP dla połączeń HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize ogranicza rozmiar tabeli kompresji nagłówka używanej przez dekoder HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. Wartość jest podawana w oktetach i musi być większa od zera (0).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;
        });

Wartość domyślna to 4096.The default value is 4096.

Maksymalny rozmiar ramkiMaximum frame size

Http2.MaxFrameSize wskazuje maksymalny rozmiar ładunku ramki połączenia HTTP/2 do odebrania.Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. Wartość jest podawana w oktetach i musi należeć do przedziału od 2 ^ 14 (16 384) do 2 ^ 24-1 (16 777 215).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;
        });

Wartość domyślna to 2 ^ 14 (16 384).The default value is 2^14 (16,384).

Maksymalny rozmiar nagłówka żądaniaMaximum request header size

Http2.MaxRequestHeaderFieldSize wskazuje maksymalny dozwolony rozmiar w oktetach wartości nagłówka żądania.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Ten limit dotyczy zarówno nazwy, jak i wartości razem w skompresowanych i nieskompresowanych reprezentacji.This limit applies to both name and value together in their compressed and uncompressed representations. Wartość musi być większa od zera (0).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;
        });

Wartość domyślna to 8 192.The default value is 8,192.

Początkowy rozmiar okna połączeniaInitial connection window size

Http2.InitialConnectionWindowSize wskazuje maksymalne dane dotyczące treści żądania w bajtach, które są agregowane w buforach serwera w ramach wszystkich żądań (strumieni) na połączenie.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Żądania są również ograniczone przez Http2.InitialStreamWindowSize .Requests are also limited by Http2.InitialStreamWindowSize. Wartość musi być większa lub równa 65 535 i mniejsza niż 2 ^ 31 (2 147 483 648).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;
        });

Wartość domyślna to 128 KB (131 072).The default value is 128 KB (131,072).

Rozmiar początkowego okna strumieniaInitial stream window size

Http2.InitialStreamWindowSize wskazuje maksymalne dane dotyczące treści żądania w bajtach bufory serwera w ramach żądania (Stream).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Żądania są również ograniczone przez Http2.InitialStreamWindowSize .Requests are also limited by Http2.InitialStreamWindowSize. Wartość musi być większa lub równa 65 535 i mniejsza niż 2 ^ 31 (2 147 483 648).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;
        });

Wartość domyślna to 96 KB (98 304).The default value is 96 KB (98,304).

Synchroniczne operacje we/wySynchronous I/O

AllowSynchronousIO Określa, czy synchroniczna operacja we/wy jest dozwolona dla żądania i odpowiedzi.AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. Wartość domyślna to true .The default value is true.

Ostrzeżenie

Duża liczba blokowania synchronicznych operacji we/wy może prowadzić do zablokowania puli wątków, co sprawia, że aplikacja nie odpowiada.A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Włączaj tylko AllowSynchronousIO w przypadku korzystania z biblioteki, która nie obsługuje asynchronicznych operacji we/wy.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous I/O.

Poniższy przykład umożliwia synchroniczne we/wy:The following example enables synchronous I/O:

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

Aby uzyskać informacje o innych opcjach i ograniczeniach Kestrel, zobacz:For information about other Kestrel options and limits, see:

Konfiguracja punktu końcowegoEndpoint configuration

Domyślnie ASP.NET Core wiąże się z:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (gdy obecny jest lokalny certyfikat programistyczny)https://localhost:5001 (when a local development certificate is present)

Określ adresy URL przy użyciu:Specify URLs using the:

  • ASPNETCORE_URLS Zmienna środowiskowa.ASPNETCORE_URLS environment variable.
  • --urls argument wiersza polecenia.--urls command-line argument.
  • urls klucz konfiguracji hosta.urls host configuration key.
  • UseUrls Metoda rozszerzenia.UseUrls extension method.

Wartość podana przy użyciu tych metod może być jednym lub większą liczbą punktów końcowych HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001" ).Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Aby uzyskać więcej informacji na temat tych metod, zobacz adresy URL serwera i Zastąp konfigurację.For more information on these approaches, see Server URLs and Override configuration.

Tworzony jest certyfikat programistyczny:A development certificate is created:

Niektóre przeglądarki wymagają przyznania jawnego uprawnienia do zaufania do lokalnego certyfikatu deweloperskiego.Some browsers require granting explicit permission to trust the local development certificate.

Szablony projektu konfigurują aplikacje do uruchamiania domyślnie przy użyciu protokołu HTTPS i obejmują przekierowania https i obsługę HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Wywołanie Listen lub ListenUnixSocket metody w KestrelServerOptions celu skonfigurowania prefiksów i portów adresów URL dla Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, --urls argument wiersza polecenia, urls klucz konfiguracji hosta i ASPNETCORE_URLS zmienna środowiskowa również działają, ale mają ograniczenia wymienione w dalszej części tej sekcji (certyfikat domyślny musi być dostępny dla konfiguracji punktu końcowego HTTPS).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 skonfigurowaćKestrelServerOptions configuration:

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

Określa konfigurację Action do uruchomienia dla każdego określonego punktu końcowego.Specifies a configuration Action to run for each specified endpoint. Wywołanie ConfigureEndpointDefaults wielokrotne zastępuje przed Action ostatnimi Action parametrami.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
            });
        });

Uwaga

Punkty końcowe utworzone przez wywołanie Listen przed wywołaniem ConfigureEndpointDefaults nie mają zastosowania wartości domyślnych.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

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

Określa konfigurację Action do uruchomienia dla każdego punktu końcowego HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Wywołanie ConfigureHttpsDefaults wielokrotne zastępuje przed Action ostatnimi Action parametrami.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;
            });
        });

Uwaga

Punkty końcowe utworzone przez wywołanie Listen przed wywołaniem ConfigureHttpsDefaults nie mają zastosowania wartości domyślnych.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Konfiguruj (IConfiguration)Configure(IConfiguration)

Tworzy moduł ładujący konfigurację na potrzeby konfigurowania Kestrel, które pobiera IConfiguration jako dane wejściowe.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. Konfiguracja musi być objęta zakresem sekcji konfiguracji dla Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Skonfiguruj Kestrel do korzystania z protokołu HTTPS.Configure Kestrel to use HTTPS.

ListenOptions.UseHttps rozszerzeniaListenOptions.UseHttps extensions:

  • UseHttps: Skonfiguruj Kestrel do używania protokołu HTTPS z domyślnym certyfikatem.UseHttps: Configure Kestrel to use HTTPS with the default certificate. Zgłasza wyjątek, jeśli nie został skonfigurowany żaden certyfikat domyślny.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 wejścioweListenOptions.UseHttps parameters:

  • filename jest ścieżką i nazwą pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X. 509.password is the password required to access the X.509 certificate data.
  • configureOptions jest Action do skonfigurowania HttpsConnectionAdapterOptions .configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Zwraca wartość ListenOptions .Returns the ListenOptions.
  • storeName to magazyn certyfikatów, z którego ma zostać załadowany certyfikat.storeName is the certificate store from which to load the certificate.
  • subject to nazwa podmiotu certyfikatu.subject is the subject name for the certificate.
  • allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location jest lokalizacją magazynu, z której ma zostać załadowany certyfikat.location is the store location to load the certificate from.
  • serverCertificate jest certyfikatem X. 509.serverCertificate is the X.509 certificate.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS.In production, HTTPS must be explicitly configured. Należy podać co najmniej certyfikat domyślny.At a minimum, a default certificate must be provided.

Obsługiwane konfiguracje opisane dalej:Supported configurations described next:

  • Brak konfiguracjiNo configuration
  • Zastąp domyślny certyfikat z konfiguracjiReplace the default certificate from configuration
  • Zmień wartości domyślne w kodzieChange the defaults in code

Brak konfiguracjiNo configuration

Kestrel nasłuchuje w systemie http://localhost:5000 i https://localhost:5001 (Jeśli domyślny certyfikat jest dostępny).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Zastąp domyślny certyfikat z konfiguracjiReplace the default certificate from configuration

CreateDefaultBuilder wywołania Configure(context.Configuration.GetSection("Kestrel")) domyślnie do ładowania konfiguracji Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Konfigurowanie wielu punktów końcowych, w tym adresów URL i certyfikatów do użycia, z pliku znajdującego się na dysku lub z magazynu certyfikatów.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

W poniższym appsettings.json przykładzie:In the following appsettings.json example:

  • Ustaw AllowInvalid na, true Aby zezwolić na korzystanie z nieprawidłowych certyfikatów (na przykład certyfikatów z podpisem własnym).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Wszystkie punkty końcowe HTTPS, które nie określają certyfikatu ( HttpsDefaultCert w poniższym przykładzie) powracają do certyfikatu zdefiniowanego w obszarze Certyfikaty > domyślne lub certyfikat programistyczny.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>"
      }
    }
  }
}

Alternatywą dla korzystania z ścieżki i hasła dla dowolnego węzła certyfikatu jest określenie certyfikatu przy użyciu pól magazynu certyfikatów.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Certyfikat domyślny można na przykład > Default określić jako: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>"
}

Uwagi dotyczące schematu:Schema notes:

  • W nazwach punktów końcowych nie jest rozróżniana wielkość liter.Endpoints names are case-insensitive. Na przykład HTTPS i Https są prawidłowe.For example, HTTPS and Https are valid.
  • UrlParametr jest wymagany dla każdego punktu końcowego.The Url parameter is required for each endpoint. Format tego parametru jest taki sam jak parametr konfiguracji najwyższego poziomu, Urls z tą różnicą, że jest ograniczony do pojedynczej wartości.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego poziomu Urls zamiast dodawać je do nich.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Punkty końcowe zdefiniowane w kodzie za pośrednictwem Listen łączą się z punktami końcowymi zdefiniowanymi w sekcji konfiguracji.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • CertificateSekcja jest opcjonalna.The Certificate section is optional. Jeśli Certificate sekcja nie jest określona, używane są wartości domyślne zdefiniowane we wcześniejszych scenariuszach.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Jeśli żadne wartości domyślne nie są dostępne, serwer zgłasza wyjątek i nie może się uruchomić.If no defaults are available, the server throws an exception and fails to start.
  • CertificateSekcja obsługuje zarówno hasło ścieżkiPassword , jak i certyfikaty magazynu podmiotuStore .The Certificate section supports both PathPassword and SubjectStore certificates.
  • W ten sposób można zdefiniować dowolną liczbę punktów końcowych, dopóki nie spowoduje to konfliktów portów.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}")) zwraca KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) metodę, która może służyć do uzupełniania skonfigurowanych ustawień punktu końcowego: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;
                });
        });

KestrelServerOptions.ConfigurationLoader można uzyskać bezpośredni dostęp do kontynuowania iteracji w istniejącym module ładującym, takim jak dostarczony przez CreateDefaultBuilder .KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach w Endpoint metodzie, aby można było odczytać ustawienia niestandardowe.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Można załadować wiele konfiguracji, wywołując options.Configure(context.Configuration.GetSection("{SECTION}")) ponownie z inną sekcją.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Używana jest tylko Ostatnia konfiguracja, chyba że Load jest jawnie wywoływana w poprzednich wystąpieniach.Only the last configuration is used, unless Load is explicitly called on prior instances. Pakiet nie wywołuje metody, Load Aby można było zastąpić sekcję konfiguracji domyślnej.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader odzwierciedla Listen rodzinę interfejsów API z programu KestrelServerOptions jako Endpoint przeciążenia, dlatego punkty końcowe kodu i konfiguracji można skonfigurować w tym samym miejscu.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.These overloads don't use names and only consume default settings from configuration.

Zmień wartości domyślne w kodzieChange the defaults in code

ConfigureEndpointDefaults i ConfigureHttpsDefaults może służyć do zmiany ustawień domyślnych dla ListenOptions i HttpsConnectionAdapterOptions , w tym przesłanianie domyślnego certyfikatu określonego w poprzednim scenariuszu.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 i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem punktów końcowych.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;
            });
        });

Obsługa usługi Kestrel dla SNIKestrel support for SNI

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i porcie.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Aby SNI działał, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uzgadniania TLS, aby serwer mógł zapewnić prawidłowy certyfikat.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. Klient korzysta z dostarczonego certyfikatu w celu zaszyfrowania komunikacji z serwerem podczas bezpiecznej sesji, która następuje po uzgadnianiu protokołu TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel obsługuje SNI za pośrednictwem ServerCertificateSelector wywołania zwrotnego.Kestrel supports SNI via the ServerCertificateSelector callback. Wywołanie zwrotne jest wywoływane jednokrotnie dla każdego połączenia, aby umożliwić aplikacji inspekcję nazwy hosta i wybieranie odpowiedniego certyfikatu.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Obsługa SNI wymaga:SNI support requires:

  • Uruchomiona w środowisku docelowym netcoreapp2.1 lub nowszym.Running on target framework netcoreapp2.1 or later. W dniu net461 lub później wywołanie zwrotne jest wywoływane, ale name jest zawsze null .On net461 or later, the callback is invoked but the name is always null. nameJest również, null Jeśli klient nie poda parametru nazwy hosta w UZGADNIANIU protokołu TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Wszystkie witryny sieci Web działają na tym samym wystąpieniu Kestrel.All websites run on the same Kestrel instance. Kestrel nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera proxy.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;
                    };
                });
            });
        });

Rejestrowanie połączeńConnection logging

Wywołanie UseConnectionLogging do emisji dzienników na poziomie debugowania dla komunikacji na poziomie bajtów w ramach połączenia.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. Rejestrowanie połączeń ułatwia rozwiązywanie problemów z komunikacją na niskim poziomie, na przykład podczas szyfrowania TLS i za serwerami proxy.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Jeśli UseConnectionLogging jest umieszczona przed UseHttps , szyfrowany ruch jest rejestrowany.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Jeśli UseConnectionLogging jest umieszczony po UseHttps , odszyfrowany ruch jest rejestrowany.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

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

Powiąż z gniazdem TCPBind to a TCP socket

ListenMetoda wiąże się z gniazdem TCP, a opcja lambda zezwala na konfigurację certyfikatu X. 509: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");
            });
        });

Przykład konfiguruje HTTPS dla punktu końcowego za pomocą ListenOptions .The example configures HTTPS for an endpoint with ListenOptions. Użyj tego samego interfejsu API, aby skonfigurować inne ustawienia Kestrel dla określonych punktów końcowych.Use the same API to configure other Kestrel settings for specific endpoints.

W systemie Windows certyfikaty z podpisem własnym można tworzyć za pomocą polecenia cmdlet Programu PowerShell new-SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Aby zapoznać się z nieobsługiwionym przykładem, zobacz UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows certyfikaty można tworzyć za pomocą funkcji OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Powiąż z gniazdem systemu UNIXBind to a Unix socket

Nasłuchiwanie w gnieździe systemu UNIX za pomocą ListenUnixSocket programu w celu zwiększenia wydajności za pomocą usługi Nginx, jak pokazano w tym przykładzie: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");
    });
});
  • W pliku Nginx confiuguration Ustaw server > location > proxy_pass pozycję na http://unix:/tmp/{KESTREL SOCKET}:/; .In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} jest nazwą gniazda, na ListenUnixSocket przykład kestrel-test.sock w powyższym przykładzie).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład 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

Gdy numer portu 0 jest określony, Kestrel dynamicznie wiąże się z dostępnym portem.When the port number 0 is specified, Kestrel dynamically binds to an available port. W poniższym przykładzie pokazano, jak określić, który port Kestrel faktycznie powiązany w czasie wykonywania: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>");
    });
}

Po uruchomieniu aplikacji dane wyjściowe okna konsoli wskazują port dynamiczny, w którym można uzyskać dostęp do aplikacji: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

OgraniczeniaLimitations

Skonfiguruj punkty końcowe przy użyciu następujących metod:Configure endpoints with the following approaches:

  • UseUrls
  • --urls argument wiersza polecenia--urls command-line argument
  • urls klucz konfiguracji hostaurls host configuration key
  • ASPNETCORE_URLS Zmienna środowiskowaASPNETCORE_URLS environment variable

Te metody są przydatne do tworzenia kodu w pracy z serwerami innymi niż Kestrel.These methods are useful for making code work with servers other than Kestrel. Należy jednak pamiętać o następujących ograniczeniach:However, be aware of the following limitations:

  • Nie można użyć protokołu HTTPS z tymi metodami, chyba że w konfiguracji punktu końcowego HTTPS jest podany certyfikat domyślny (na przykład przy użyciu KestrelServerOptions konfiguracji lub pliku konfiguracji, jak pokazano wcześniej w tym temacie).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).
  • Gdy oba Listen podejścia i UseUrls są używane jednocześnie, Listen punkty końcowe zastępują UseUrls punkty końcowe.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Konfiguracja punktu końcowego usług IISIIS endpoint configuration

W przypadku korzystania z usług IIS powiązania URL dla powiązań przesłonięć usług IIS są ustawiane przez Listen lub UseUrls .When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Aby uzyskać więcej informacji, zobacz temat ASP.NET Core Module .For more information, see the ASP.NET Core Module topic.

ListenOptions. ProtocolsListenOptions.Protocols

ProtocolsWłaściwość ustanawia protokoły HTTP ( HttpProtocols ) włączone w punkcie końcowym połączenia lub dla serwera.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Przypisz wartość do Protocols właściwości z HttpProtocols wyliczenia.Assign a value to the Protocols property from the HttpProtocols enum.

HttpProtocols wartość wyliczeniaHttpProtocols enum value Dozwolony protokół połączeniaConnection protocol permitted
Http1 Tylko HTTP/1.1.HTTP/1.1 only. Może być używany z protokołem TLS lub bez niego.Can be used with or without TLS.
Http2 Tylko HTTP/2.HTTP/2 only. Mogą być używane bez protokołu TLS tylko wtedy, gdy klient obsługuje poprzedni tryb wiedzy.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 i HTTP/2.HTTP/1.1 and HTTP/2. Protokół HTTP/2 wymaga połączenia protokołów TLS i warstwy aplikacji (ClientHello alpn) . w przeciwnym razie wartość domyślna połączenia to HTTP/1.1.HTTP/2 requires a TLS and Application-Layer Protocol Negotiation (ALPN) connection; otherwise, the connection defaults to HTTP/1.1.

Domyślnym protokołem jest HTTP/1.1.The default protocol is HTTP/1.1.

Ograniczenia protokołu TLS dla protokołu HTTP/2:TLS restrictions for HTTP/2:

  • TLS w wersji 1,2 lub nowszejTLS version 1.2 or later
  • Ponowne negocjowanie wyłączoneRenegotiation disabled
  • Kompresja wyłączonaCompression disabled
  • Minimalne rozmiary tymczasowych kluczy wymiany:Minimum ephemeral key exchange sizes:
    • Krzywa eliptyczna Diffie-Hellman (ECDHE) [ RFC4492 ] : minimum 224 bitówElliptic curve Diffie-Hellman (ECDHE) [RFC4492]: 224 bits minimum
    • Ograniczone pole Diffie-Hellman (DHE) [ TLS12 ] : minimum 2048 bitówFinite field Diffie-Hellman (DHE) [TLS12]: 2048 bits minimum
  • Nie zablokowano pakietu szyfrowaniaCipher suite not blocked

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256[TLS-ECDHE] z krzywą eliptyczna P-256 [ FIPS186 ] jest domyślnie obsługiwana.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

Poniższy przykład umożliwia nawiązywanie połączeń HTTP/1.1 i HTTP/2 na porcie 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Połączenia są zabezpieczone przez protokół TLS przy użyciu podanego certyfikatu: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");
    });
});

Opcjonalnie można utworzyć IConnectionAdapter implementację do filtrowania uzgadniania protokołu TLS dla poszczególnych połączeń dla określonych szyfrów: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()
        {
        }
    }
}

Ustawianie protokołu z konfiguracjiSet the protocol from configuration

CreateDefaultBuilder wywołania serverOptions.Configure(context.Configuration.GetSection("Kestrel")) domyślnie do ładowania konfiguracji Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

W poniższym appsettings.json przykładzie jest ustanowiony domyślny protokół połączeń (http/1.1 i http/2) dla wszystkich punktów końcowych Kestrel: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"
    }
  }
}

Poniższy przykład pliku konfiguracji ustanawia protokół połączenia dla określonego punktu końcowego:The following configuration file example establishes a connection protocol for a specific endpoint:

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

Protokoły określone w wartościach zastąpienia kodu ustawione przez konfigurację.Protocols specified in code override values set by configuration.

Konfiguracja transportuTransport configuration

W wersji ASP.NET Core 2,1 Kestrel domyślny transport nie jest już oparty na Libuv, ale zamiast w oparciu o zarządzane gniazda.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. Jest to istotna zmiana dla aplikacji ASP.NET Core 2,0 uaktualniana do 2,1, które wywołują UseLibuv i zależą od jednego z następujących pakietów: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:

Dla projektów, które wymagają użycia Libuv:For projects that require the use of Libuv:

  • Dodaj zależność dla pakietu Microsoft. AspNetCore. Server. Kestrel. transport. Libuv do pliku projektu aplikacji: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}" />
    
  • Wywołanie UseLibuv :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>();
    }
    

Prefiksy adresów URLURL prefixes

W przypadku użycia UseUrls , --urls argumentu wiersza polecenia, urls klucza konfiguracji hosta lub ASPNETCORE_URLS zmiennej środowiskowej prefiksy adresów URL mogą znajdować się w jednym z następujących formatów.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.

Tylko prefiksy adresów URL HTTP są prawidłowe.Only HTTP URL prefixes are valid. Kestrel nie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy użyciu programu UseUrls .Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Adres IPv4 z numerem portuIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 jest szczególnym przypadkiem, który wiąże się ze wszystkimi adresami IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Adres IPv6 z numerem portuIPv6 address with port number

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

    [::] jest odpowiednikiem IPv6 dla protokołu IPv4 0.0.0.0 .[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nazwa hosta z numerem portuHost name with port number

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

    Nazwy hostów, * i + , nie są specjalne.Host names, *, and +, aren't special. Wszystkie nie są rozpoznawane jako prawidłowy adres IP lub są localhost powiązane ze wszystkimi IP IPv4 i IPv6.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core aplikacjami na tym samym porcie, użyj HTTP.sys lub zwrotnego serwera proxy, takiego jak IIS, Nginx lub 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.

    Ostrzeżenie

    Hostowanie w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.Hosting in a reverse proxy configuration requires host filtering.

  • localhostNazwa hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portuHost localhost name with port number or loopback IP with port number

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

    Gdy localhost jest określony, Kestrel próbuje powiązać z interfejsami sprzężenia zwrotnego IPv4 i IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Jeśli żądany port jest używany przez inną usługę w dowolnym interfejsie sprzężenia zwrotnego, uruchomienie Kestrel nie powiedzie się.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Jeśli którykolwiek z innych przyczyn interfejsu sprzężenia zwrotnego jest niedostępny (najczęściej jest to spowodowane tym, że protokół IPv6 nie jest obsługiwany), Kestrel rejestruje ostrzeżenie.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtrowanie hostówHost filtering

Program Kestrel obsługuje konfigurację na podstawie prefiksów, takich jak http://example.com:5000 , Kestrel w znacznym stopniu ignoruje nazwę hosta.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. Host localhost jest specjalnym przypadkiem używanym do tworzenia powiązań z adresami sprzężenia zwrotnego.Host localhost is a special case used for binding to loopback addresses. Każdy host poza jawnym adresem IP tworzy powiązanie ze wszystkimi publicznymi adresami IP.Any host other than an explicit IP address binds to all public IP addresses. Host nagłówki nie są sprawdzane.Host headers aren't validated.

Aby obejść ten sposób, użyj oprogramowania pośredniczącego filtrowania hosta.As a workaround, use Host Filtering Middleware. Oprogramowanie pośredniczące do filtrowania hosta jest dostarczane przez pakiet Microsoft. AspNetCore. HostFiltering , który jest zawarty w pakiecie Microsoft. AspNetCore. App (ASP.NET Core 2,1 lub 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). Oprogramowanie pośredniczące jest dodawane przez CreateDefaultBuilder program, który wywołuje AddHostFiltering następujące wywołania: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>();
}

Programowe filtrowanie hosta jest domyślnie wyłączone.Host Filtering Middleware is disabled by default. Aby włączyć oprogramowanie pośredniczące, zdefiniuj AllowedHosts klucz w appsettings.json / appSettings. <EnvironmentName> kod JSON .To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json . Wartość to rozdzielana średnikami lista nazw hostów bez numerów portów:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json :appsettings.json :

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

Uwaga

Przekierowane nagłówki oprogramowania również mają AllowedHosts opcję.Forwarded Headers Middleware also has an AllowedHosts option. Przekazane nagłówki — oprogramowanie pośredniczące i filtrowanie hostów oprogramowanie pośredniczące ma podobną funkcjonalność dla różnych scenariuszy.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Ustawienie AllowedHosts z przekierowanymi nagłówkami — oprogramowanie pośredniczące jest odpowiednie, gdy Host nagłówek nie jest zachowywany podczas przekazywania żądań z odwrotnym serwerem proxy lub modułem równoważenia obciążenia.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. Ustawienie AllowedHosts przy użyciu oprogramowania pośredniczącego filtrowania hosta jest odpowiednie, gdy Kestrel jest używany jako publiczny serwer graniczny lub gdy Host nagłówek jest bezpośrednio przekazywany.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.

Aby uzyskać więcej informacji na temat przekierowanych nagłówków, należy zapoznać się z tematem Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia .For more information on Forwarded Headers Middleware, see Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia.

Kestrel to Międzyplatformowy serwer sieci Web dla ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel to serwer sieci Web, który jest domyślnie uwzględniony w szablonach projektu ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel obsługuje następujące scenariusze:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Nieprzezroczyste uaktualnienie używane do włączania obsługi obiektów WebSocketsOpaque upgrade used to enable WebSockets
  • Gniazda systemu UNIX w celu zapewnienia wysokiej wydajności w tle NginxUnix sockets for high performance behind Nginx

Kestrel jest obsługiwana na wszystkich platformach i wersjach obsługiwanych przez platformę .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Wyświetl lub pobierz przykładowy kod (jak pobrać)View or download sample code (how to download)

Kiedy używać Kestrel z zwrotnym serwerem proxyWhen to use Kestrel with a reverse proxy

Kestrel może być używana przez siebie lub z odwrotnym serwerem proxy , takich jak Internet Information Services (IIS), Nginxlub Apache.Kestrel can be used by itself or with a reverse proxy server , such as Internet Information Services (IIS), Nginx, or Apache. Odwrotny serwer proxy odbiera żądania HTTP z sieci i przekazuje je do usługi Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel używany jako serwer sieci Web z krawędzią (dostępną z Internetu):Kestrel used as an edge (Internet-facing) web server:

Kestrel komunikuje się bezpośrednio z Internetem bez serwera proxy zwrotnego

Kestrel używany w konfiguracji zwrotnego serwera proxy:Kestrel used in a reverse proxy configuration:

Kestrel komunikuje się pośrednio z Internetem za pomocą odwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache

Konfiguracja, z serwerem proxy odwrotnych lub bez niego, jest obsługiwaną konfiguracją hostingu.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Kestrel używany jako serwer graniczny bez serwera proxy odwrotnego nie obsługuje udostępniania tego samego adresu IP i portu między wieloma procesami.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Gdy Kestrel jest skonfigurowany do nasłuchiwania na porcie, Kestrel obsługuje cały ruch dla tego portu bez względu na nagłówki żądań Host .When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Zwrotny serwer proxy, który może udostępniać porty, ma możliwość przekazywania żądań do Kestrel na unikatowym adresie IP i porcie.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Nawet jeśli odwrotny serwer proxy nie jest wymagany, może to być dobry wybór przy użyciu odwrotnego serwera proxy.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Zwrotny serwer proxy:A reverse proxy:

  • Może ograniczać uwidoczniony obszar publicznej powierzchni aplikacji, które obsługuje.Can limit the exposed public surface area of the apps that it hosts.
  • Zapewnienie dodatkowej warstwy konfiguracji i obrony.Provide an additional layer of configuration and defense.
  • Integracja z istniejącą infrastrukturą może być lepsza.Might integrate better with existing infrastructure.
  • Uprość Równoważenie obciążenia i konfigurację komunikacji zabezpieczonej (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Tylko serwer zwrotny proxy wymaga certyfikatu X. 509, a serwer może komunikować się z serwerami aplikacji w sieci wewnętrznej przy użyciu zwykłego protokołu HTTP.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.

Ostrzeżenie

Hostowanie w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.Hosting in a reverse proxy configuration requires host filtering.

Jak używać Kestrel w aplikacjach ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

Pakiet Microsoft. AspNetCore. Server. Kestrel jest zawarty w pakiecie Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

Szablony projektów ASP.NET Core domyślnie używają Kestrel.ASP.NET Core project templates use Kestrel by default. W program.cs , kod szablonu wywołuje CreateDefaultBuilder , który wywołuje się w UseKestrel tle.In Program.cs , the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

Aby zapewnić dodatkową konfigurację po wywołaniu CreateDefaultBuilder , wywołaj UseKestrel :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
        });

Więcej informacji na temat CreateDefaultBuilder i kompilowanie hosta znajduje się w sekcji Konfigurowanie hosta w temacie ASP.NET Core hosta sieci Web .For more information on CreateDefaultBuilder and building the host, see the Set up a host section of ASP.NET Core hosta sieci Web.

Opcje KestrelKestrel options

Serwer sieci Web Kestrel ma opcje konfiguracji ograniczeń, które są szczególnie przydatne w przypadku wdrożeń mających dostęp do Internetu.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Ustaw ograniczenia Limits właściwości KestrelServerOptions klasy.Set constraints on the Limits property of the KestrelServerOptions class. LimitsWłaściwość przechowuje wystąpienie KestrelServerLimits klasy.The Limits property holds an instance of the KestrelServerLimits class.

W poniższych przykładach użyto Microsoft.AspNetCore.Server.Kestrel.Core przestrzeni nazw:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Opcje Kestrel, które są konfigurowane w kodzie C# w poniższych przykładach, można również ustawić za pomocą dostawcy konfiguracji.Kestrel options, which are configured in C# code in the following examples, can also be set using a configuration provider. Na przykład dostawca konfiguracji plików może załadować konfigurację Kestrel z appsettings.json lub appSettings. { Environment} plik JSON :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
    }
  }
}

Skorzystaj z jednej z następujących metod:Use one of the following approaches:

  • Skonfiguruj Kestrel w Startup.ConfigureServices :Configure Kestrel in Startup.ConfigureServices:

    1. Wstrzyknąć wystąpienie IConfiguration do Startup klasy.Inject an instance of IConfiguration into the Startup class. W poniższym przykładzie przyjęto założenie, że wprowadzona konfiguracja jest przypisana do Configuration właściwości.The following example assumes that the injected configuration is assigned to the Configuration property.

    2. W programie Startup.ConfigureServices Załaduj Kestrel sekcję Konfiguracja do konfiguracji programu 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)
          {
              ...
          }
      }
      
  • Skonfiguruj Kestrel podczas kompilowania hosta:Configure Kestrel when building the host:

    W programie program.cs Załaduj Kestrel sekcję Konfiguracja do konfiguracji programu 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>();
    

Obie powyższe podejścia współpracują z dowolnym dostawcą konfiguracji.Both of the preceding approaches work with any configuration provider.

Limit czasu utrzymywania aktywnościKeep-alive timeout

KeepAliveTimeout

Pobiera lub ustawia limit czasu utrzymywania aktywności.Gets or sets the keep-alive timeout. Wartość domyślna to 2 minuty.Defaults to 2 minutes.

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

Maksymalna liczba połączeń klientaMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maksymalna liczba współbieżnych otwartych połączeń TCP można ustawić dla całej aplikacji przy użyciu następującego kodu: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;
        });

Istnieje oddzielny limit połączeń, które zostały uaktualnione z protokołu HTTP lub HTTPS do innego protokołu (na przykład w żądaniu usługi WebSockets).There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). Po uaktualnieniu połączenia nie jest ono wliczane do MaxConcurrentConnections limitu.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;
        });

Maksymalna liczba połączeń jest domyślnie nieograniczona (null).The maximum number of connections is unlimited (null) by default.

Maksymalny rozmiar treści żądaniaMaximum request body size

MaxRequestBodySize

Domyślny maksymalny rozmiar treści żądania to 30 000 000 bajtów, czyli około 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Zalecanym podejściem do zastąpienia limitu w aplikacji ASP.NET Core MVC jest użycie RequestSizeLimitAttribute atrybutu dla metody akcji: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()

Oto przykład, który pokazuje, jak skonfigurować ograniczenie dla aplikacji w każdym żądaniu: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;
        });

Zastąp ustawienie określonego żądania w oprogramowaniu pośredniczącym: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));
    }

Wyjątek jest generowany, jeśli aplikacja skonfiguruje limit żądania po rozpoczęciu uruchamiania aplikacji w celu odczytania żądania.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Istnieje IsReadOnly Właściwość, która wskazuje MaxRequestBodySize , czy właściwość jest w stanie tylko do odczytu, co oznacza, że jest zbyt późno, aby skonfigurować limit.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.

Gdy aplikacja jest uruchamiana poza procesem modułu ASP.NET Core, limit rozmiaru treści żądania Kestrel jest wyłączony, ponieważ program IIS już ustawia limit.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.

Minimalna stawka danych treści żądaniaMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel sprawdza co sekundę, jeśli dane są odbierane z określoną szybkością w bajtach na sekundę.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Jeśli szybkość spadnie poniżej wartości minimalnej, upłynął limit czasu połączenia. Okres prolongaty to czas, przez który Kestrel nadaje klientowi zwiększenie jego szybkości wysyłania do minimum; Ta częstotliwość nie jest sprawdzana w tym czasie.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. Okres prolongaty pozwala uniknąć porzucania połączeń, które początkowo wysyłają dane z niską szybkością.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

Domyślna stawka minimalna to 240 bajtów na sekundę z 5-sekundowym okresem prolongaty.The default minimum rate is 240 bytes/second with a 5 second grace period.

Minimalna stawka dotyczy także odpowiedzi.A minimum rate also applies to the response. Kod określający limit żądań i limit odpowiedzi jest taki sam, z wyjątkiem RequestBody Response właściwości i nazwy interfejsów.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.

Oto przykład pokazujący sposób konfigurowania minimalnych stawek danych w program.cs :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));
        });

Limit czasu nagłówków żądańRequest headers timeout

RequestHeadersTimeout

Pobiera lub ustawia maksymalny czas, przez jaki serwer spędza nagłówki żądania.Gets or sets the maximum amount of time the server spends receiving request headers. Wartość domyślna to 30 sekund.Defaults to 30 seconds.

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

Synchroniczne operacje we/wySynchronous I/O

AllowSynchronousIO Określa, czy synchroniczna operacja we/wy jest dozwolona dla żądania i odpowiedzi.AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. Wartość domyślna to true .The default value is true.

Ostrzeżenie

Duża liczba blokowania synchronicznych operacji we/wy może prowadzić do zablokowania puli wątków, co sprawia, że aplikacja nie odpowiada.A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Włączaj tylko AllowSynchronousIO w przypadku korzystania z biblioteki, która nie obsługuje asynchronicznych operacji we/wy.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous I/O.

Poniższy przykład wyłącza synchroniczne we/wy:The following example disables synchronous I/O:

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

Aby uzyskać informacje o innych opcjach i ograniczeniach Kestrel, zobacz:For information about other Kestrel options and limits, see:

Konfiguracja punktu końcowegoEndpoint configuration

Domyślnie ASP.NET Core wiąże się z:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (gdy obecny jest lokalny certyfikat programistyczny)https://localhost:5001 (when a local development certificate is present)

Określ adresy URL przy użyciu:Specify URLs using the:

  • ASPNETCORE_URLS Zmienna środowiskowa.ASPNETCORE_URLS environment variable.
  • --urls argument wiersza polecenia.--urls command-line argument.
  • urls klucz konfiguracji hosta.urls host configuration key.
  • UseUrls Metoda rozszerzenia.UseUrls extension method.

Wartość podana przy użyciu tych metod może być jednym lub większą liczbą punktów końcowych HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001" ).Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Aby uzyskać więcej informacji na temat tych metod, zobacz adresy URL serwera i Zastąp konfigurację.For more information on these approaches, see Server URLs and Override configuration.

Tworzony jest certyfikat programistyczny:A development certificate is created:

Niektóre przeglądarki wymagają przyznania jawnego uprawnienia do zaufania do lokalnego certyfikatu deweloperskiego.Some browsers require granting explicit permission to trust the local development certificate.

Szablony projektu konfigurują aplikacje do uruchamiania domyślnie przy użyciu protokołu HTTPS i obejmują przekierowania https i obsługę HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Wywołanie Listen lub ListenUnixSocket metody w KestrelServerOptions celu skonfigurowania prefiksów i portów adresów URL dla Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls, --urls argument wiersza polecenia, urls klucz konfiguracji hosta i ASPNETCORE_URLS zmienna środowiskowa również działają, ale mają ograniczenia wymienione w dalszej części tej sekcji (certyfikat domyślny musi być dostępny dla konfiguracji punktu końcowego HTTPS).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 skonfigurowaćKestrelServerOptions configuration:

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

Określa konfigurację Action do uruchomienia dla każdego określonego punktu końcowego.Specifies a configuration Action to run for each specified endpoint. Wywołanie ConfigureEndpointDefaults wielokrotne zastępuje przed Action ostatnimi Action parametrami.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
            });
        });

Uwaga

Punkty końcowe utworzone przez wywołanie Listen przed wywołaniem ConfigureEndpointDefaults nie mają zastosowania wartości domyślnych.Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

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

Określa konfigurację Action do uruchomienia dla każdego punktu końcowego HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Wywołanie ConfigureHttpsDefaults wielokrotne zastępuje przed Action ostatnimi Action parametrami.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;
            });
        });

Uwaga

Punkty końcowe utworzone przez wywołanie Listen przed wywołaniem ConfigureHttpsDefaults nie mają zastosowania wartości domyślnych.Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Konfiguruj (IConfiguration)Configure(IConfiguration)

Tworzy moduł ładujący konfigurację na potrzeby konfigurowania Kestrel, które pobiera IConfiguration jako dane wejściowe.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. Konfiguracja musi być objęta zakresem sekcji konfiguracji dla Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Skonfiguruj Kestrel do korzystania z protokołu HTTPS.Configure Kestrel to use HTTPS.

ListenOptions.UseHttps rozszerzeniaListenOptions.UseHttps extensions:

  • UseHttps: Skonfiguruj Kestrel do używania protokołu HTTPS z domyślnym certyfikatem.UseHttps: Configure Kestrel to use HTTPS with the default certificate. Zgłasza wyjątek, jeśli nie został skonfigurowany żaden certyfikat domyślny.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 wejścioweListenOptions.UseHttps parameters:

  • filename jest ścieżką i nazwą pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X. 509.password is the password required to access the X.509 certificate data.
  • configureOptions jest Action do skonfigurowania HttpsConnectionAdapterOptions .configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Zwraca wartość ListenOptions .Returns the ListenOptions.
  • storeName to magazyn certyfikatów, z którego ma zostać załadowany certyfikat.storeName is the certificate store from which to load the certificate.
  • subject to nazwa podmiotu certyfikatu.subject is the subject name for the certificate.
  • allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location jest lokalizacją magazynu, z której ma zostać załadowany certyfikat.location is the store location to load the certificate from.
  • serverCertificate jest certyfikatem X. 509.serverCertificate is the X.509 certificate.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS.In production, HTTPS must be explicitly configured. Należy podać co najmniej certyfikat domyślny.At a minimum, a default certificate must be provided.

Obsługiwane konfiguracje opisane dalej:Supported configurations described next:

  • Brak konfiguracjiNo configuration
  • Zastąp domyślny certyfikat z konfiguracjiReplace the default certificate from configuration
  • Zmień wartości domyślne w kodzieChange the defaults in code

Brak konfiguracjiNo configuration

Kestrel nasłuchuje w systemie http://localhost:5000 i https://localhost:5001 (Jeśli domyślny certyfikat jest dostępny).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Zastąp domyślny certyfikat z konfiguracjiReplace the default certificate from configuration

CreateDefaultBuilder wywołania Configure(context.Configuration.GetSection("Kestrel")) domyślnie do ładowania konfiguracji Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla Kestrel.A default HTTPS app settings configuration schema is available for Kestrel. Konfigurowanie wielu punktów końcowych, w tym adresów URL i certyfikatów do użycia, z pliku znajdującego się na dysku lub z magazynu certyfikatów.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

W poniższym appsettings.json przykładzie:In the following appsettings.json example:

  • Ustaw AllowInvalid na, true Aby zezwolić na korzystanie z nieprawidłowych certyfikatów (na przykład certyfikatów z podpisem własnym).Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Wszystkie punkty końcowe HTTPS, które nie określają certyfikatu ( HttpsDefaultCert w poniższym przykładzie) powracają do certyfikatu zdefiniowanego w obszarze Certyfikaty > domyślne lub certyfikat programistyczny.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>"
      }
    }
  }
}

Alternatywą dla korzystania z ścieżki i hasła dla dowolnego węzła certyfikatu jest określenie certyfikatu przy użyciu pól magazynu certyfikatów.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Certyfikat domyślny można na przykład > Default określić jako: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>"
}

Uwagi dotyczące schematu:Schema notes:

  • W nazwach punktów końcowych nie jest rozróżniana wielkość liter.Endpoints names are case-insensitive. Na przykład HTTPS i Https są prawidłowe.For example, HTTPS and Https are valid.
  • UrlParametr jest wymagany dla każdego punktu końcowego.The Url parameter is required for each endpoint. Format tego parametru jest taki sam jak parametr konfiguracji najwyższego poziomu, Urls z tą różnicą, że jest ograniczony do pojedynczej wartości.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego poziomu Urls zamiast dodawać je do nich.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Punkty końcowe zdefiniowane w kodzie za pośrednictwem Listen łączą się z punktami końcowymi zdefiniowanymi w sekcji konfiguracji.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • CertificateSekcja jest opcjonalna.The Certificate section is optional. Jeśli Certificate sekcja nie jest określona, używane są wartości domyślne zdefiniowane we wcześniejszych scenariuszach.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Jeśli żadne wartości domyślne nie są dostępne, serwer zgłasza wyjątek i nie może się uruchomić.If no defaults are available, the server throws an exception and fails to start.
  • CertificateSekcja obsługuje zarówno hasło ścieżkiPassword , jak i certyfikaty magazynu podmiotuStore .The Certificate section supports both PathPassword and SubjectStore certificates.
  • W ten sposób można zdefiniować dowolną liczbę punktów końcowych, dopóki nie spowoduje to konfliktów portów.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}")) zwraca KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) metodę, która może służyć do uzupełniania skonfigurowanych ustawień punktu końcowego: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;
                });
        });

KestrelServerOptions.ConfigurationLoader można uzyskać bezpośredni dostęp do kontynuowania iteracji w istniejącym module ładującym, takim jak dostarczony przez CreateDefaultBuilder .KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach w Endpoint metodzie, aby można było odczytać ustawienia niestandardowe.The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
  • Można załadować wiele konfiguracji, wywołując options.Configure(context.Configuration.GetSection("{SECTION}")) ponownie z inną sekcją.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Używana jest tylko Ostatnia konfiguracja, chyba że Load jest jawnie wywoływana w poprzednich wystąpieniach.Only the last configuration is used, unless Load is explicitly called on prior instances. Pakiet nie wywołuje metody, Load Aby można było zastąpić sekcję konfiguracji domyślnej.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader odzwierciedla Listen rodzinę interfejsów API z programu KestrelServerOptions jako Endpoint przeciążenia, dlatego punkty końcowe kodu i konfiguracji można skonfigurować w tym samym miejscu.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.These overloads don't use names and only consume default settings from configuration.

Zmień wartości domyślne w kodzieChange the defaults in code

ConfigureEndpointDefaults i ConfigureHttpsDefaults może służyć do zmiany ustawień domyślnych dla ListenOptions i HttpsConnectionAdapterOptions , w tym przesłanianie domyślnego certyfikatu określonego w poprzednim scenariuszu.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 i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem punktów końcowych.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;
            });
        });

Obsługa usługi Kestrel dla SNIKestrel support for SNI

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i porcie.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Aby SNI działał, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uzgadniania TLS, aby serwer mógł zapewnić prawidłowy certyfikat.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. Klient korzysta z dostarczonego certyfikatu w celu zaszyfrowania komunikacji z serwerem podczas bezpiecznej sesji, która następuje po uzgadnianiu protokołu TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel obsługuje SNI za pośrednictwem ServerCertificateSelector wywołania zwrotnego.Kestrel supports SNI via the ServerCertificateSelector callback. Wywołanie zwrotne jest wywoływane jednokrotnie dla każdego połączenia, aby umożliwić aplikacji inspekcję nazwy hosta i wybieranie odpowiedniego certyfikatu.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Obsługa SNI wymaga:SNI support requires:

  • Uruchomiona w środowisku docelowym netcoreapp2.1 lub nowszym.Running on target framework netcoreapp2.1 or later. W dniu net461 lub później wywołanie zwrotne jest wywoływane, ale name jest zawsze null .On net461 or later, the callback is invoked but the name is always null. nameJest również, null Jeśli klient nie poda parametru nazwy hosta w UZGADNIANIU protokołu TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Wszystkie witryny sieci Web działają na tym samym wystąpieniu Kestrel.All websites run on the same Kestrel instance. Kestrel nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera proxy.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();

Rejestrowanie połączeńConnection logging

Wywołanie UseConnectionLogging do emisji dzienników na poziomie debugowania dla komunikacji na poziomie bajtów w ramach połączenia.Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. Rejestrowanie połączeń ułatwia rozwiązywanie problemów z komunikacją na niskim poziomie, na przykład podczas szyfrowania TLS i za serwerami proxy.Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. Jeśli UseConnectionLogging jest umieszczona przed UseHttps , szyfrowany ruch jest rejestrowany.If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. Jeśli UseConnectionLogging jest umieszczony po UseHttps , odszyfrowany ruch jest rejestrowany.If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

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

Powiąż z gniazdem TCPBind to a TCP socket

ListenMetoda wiąże się z gniazdem TCP, a opcja lambda zezwala na konfigurację certyfikatu X. 509: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");
            });
        });

Przykład konfiguruje HTTPS dla punktu końcowego za pomocą ListenOptions .The example configures HTTPS for an endpoint with ListenOptions. Użyj tego samego interfejsu API, aby skonfigurować inne ustawienia Kestrel dla określonych punktów końcowych.Use the same API to configure other Kestrel settings for specific endpoints.

W systemie Windows certyfikaty z podpisem własnym można tworzyć za pomocą polecenia cmdlet Programu PowerShell new-SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Aby zapoznać się z nieobsługiwionym przykładem, zobacz UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows certyfikaty można tworzyć za pomocą funkcji OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Powiąż z gniazdem systemu UNIXBind to a Unix socket

Nasłuchiwanie w gnieździe systemu UNIX za pomocą ListenUnixSocket programu w celu zwiększenia wydajności za pomocą usługi Nginx, jak pokazano w tym przykładzie: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");
            });
        });
  • W pliku Nginx confiuguration Ustaw server > location > proxy_pass pozycję na http://unix:/tmp/{KESTREL SOCKET}:/; .In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} jest nazwą gniazda, na ListenUnixSocket przykład kestrel-test.sock w powyższym przykładzie).{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład 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

Gdy numer portu 0 jest określony, Kestrel dynamicznie wiąże się z dostępnym portem.When the port number 0 is specified, Kestrel dynamically binds to an available port. W poniższym przykładzie pokazano, jak określić, który port Kestrel faktycznie powiązany w czasie wykonywania: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>");
    });
}

Po uruchomieniu aplikacji dane wyjściowe okna konsoli wskazują port dynamiczny, w którym można uzyskać dostęp do aplikacji: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

OgraniczeniaLimitations

Skonfiguruj punkty końcowe przy użyciu następujących metod:Configure endpoints with the following approaches:

  • UseUrls
  • --urls argument wiersza polecenia--urls command-line argument
  • urls klucz konfiguracji hostaurls host configuration key
  • ASPNETCORE_URLS Zmienna środowiskowaASPNETCORE_URLS environment variable

Te metody są przydatne do tworzenia kodu w pracy z serwerami innymi niż Kestrel.These methods are useful for making code work with servers other than Kestrel. Należy jednak pamiętać o następujących ograniczeniach:However, be aware of the following limitations:

  • Nie można użyć protokołu HTTPS z tymi metodami, chyba że w konfiguracji punktu końcowego HTTPS jest podany certyfikat domyślny (na przykład przy użyciu KestrelServerOptions konfiguracji lub pliku konfiguracji, jak pokazano wcześniej w tym temacie).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).
  • Gdy oba Listen podejścia i UseUrls są używane jednocześnie, Listen punkty końcowe zastępują UseUrls punkty końcowe.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Konfiguracja punktu końcowego usług IISIIS endpoint configuration

W przypadku korzystania z usług IIS powiązania URL dla powiązań przesłonięć usług IIS są ustawiane przez Listen lub UseUrls .When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Aby uzyskać więcej informacji, zobacz temat ASP.NET Core Module .For more information, see the ASP.NET Core Module topic.

Konfiguracja transportuTransport configuration

W wersji ASP.NET Core 2,1 Kestrel domyślny transport nie jest już oparty na Libuv, ale zamiast w oparciu o zarządzane gniazda.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. Jest to istotna zmiana dla aplikacji ASP.NET Core 2,0 uaktualniana do 2,1, które wywołują UseLibuv i zależą od jednego z następujących pakietów: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:

Dla projektów, które wymagają użycia Libuv:For projects that require the use of Libuv:

  • Dodaj zależność dla pakietu Microsoft. AspNetCore. Server. Kestrel. transport. Libuv do pliku projektu aplikacji: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}" />
    
  • Wywołanie UseLibuv :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>();
    }
    

Prefiksy adresów URLURL prefixes

W przypadku użycia UseUrls , --urls argumentu wiersza polecenia, urls klucza konfiguracji hosta lub ASPNETCORE_URLS zmiennej środowiskowej prefiksy adresów URL mogą znajdować się w jednym z następujących formatów.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.

Tylko prefiksy adresów URL HTTP są prawidłowe.Only HTTP URL prefixes are valid. Kestrel nie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy użyciu programu UseUrls .Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Adres IPv4 z numerem portuIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 jest szczególnym przypadkiem, który wiąże się ze wszystkimi adresami IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Adres IPv6 z numerem portuIPv6 address with port number

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

    [::] jest odpowiednikiem IPv6 dla protokołu IPv4 0.0.0.0 .[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nazwa hosta z numerem portuHost name with port number

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

    Nazwy hostów, * i + , nie są specjalne.Host names, *, and +, aren't special. Wszystkie nie są rozpoznawane jako prawidłowy adres IP lub są localhost powiązane ze wszystkimi IP IPv4 i IPv6.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core aplikacjami na tym samym porcie, użyj HTTP.sys lub zwrotnego serwera proxy, takiego jak IIS, Nginx lub 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.

    Ostrzeżenie

    Hostowanie w konfiguracji zwrotnego serwera proxy wymaga filtrowania hosta.Hosting in a reverse proxy configuration requires host filtering.

  • localhostNazwa hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portuHost localhost name with port number or loopback IP with port number

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

    Gdy localhost jest określony, Kestrel próbuje powiązać z interfejsami sprzężenia zwrotnego IPv4 i IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Jeśli żądany port jest używany przez inną usługę w dowolnym interfejsie sprzężenia zwrotnego, uruchomienie Kestrel nie powiedzie się.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Jeśli którykolwiek z innych przyczyn interfejsu sprzężenia zwrotnego jest niedostępny (najczęściej jest to spowodowane tym, że protokół IPv6 nie jest obsługiwany), Kestrel rejestruje ostrzeżenie.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtrowanie hostówHost filtering

Program Kestrel obsługuje konfigurację na podstawie prefiksów, takich jak http://example.com:5000 , Kestrel w znacznym stopniu ignoruje nazwę hosta.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. Host localhost jest specjalnym przypadkiem używanym do tworzenia powiązań z adresami sprzężenia zwrotnego.Host localhost is a special case used for binding to loopback addresses. Każdy host poza jawnym adresem IP tworzy powiązanie ze wszystkimi publicznymi adresami IP.Any host other than an explicit IP address binds to all public IP addresses. Host nagłówki nie są sprawdzane.Host headers aren't validated.

Aby obejść ten sposób, użyj oprogramowania pośredniczącego filtrowania hosta.As a workaround, use Host Filtering Middleware. Oprogramowanie pośredniczące do filtrowania hosta jest dostarczane przez pakiet Microsoft. AspNetCore. HostFiltering , który jest zawarty w pakiecie Microsoft. AspNetCore. App (ASP.NET Core 2,1 lub 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). Oprogramowanie pośredniczące jest dodawane przez CreateDefaultBuilder program, który wywołuje AddHostFiltering następujące wywołania: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>();
}

Programowe filtrowanie hosta jest domyślnie wyłączone.Host Filtering Middleware is disabled by default. Aby włączyć oprogramowanie pośredniczące, zdefiniuj AllowedHosts klucz w appsettings.json / appSettings. <EnvironmentName> kod JSON .To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json . Wartość to rozdzielana średnikami lista nazw hostów bez numerów portów:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json :appsettings.json :

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

Uwaga

Przekierowane nagłówki oprogramowania również mają AllowedHosts opcję.Forwarded Headers Middleware also has an AllowedHosts option. Przekazane nagłówki — oprogramowanie pośredniczące i filtrowanie hostów oprogramowanie pośredniczące ma podobną funkcjonalność dla różnych scenariuszy.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. Ustawienie AllowedHosts z przekierowanymi nagłówkami — oprogramowanie pośredniczące jest odpowiednie, gdy Host nagłówek nie jest zachowywany podczas przekazywania żądań z odwrotnym serwerem proxy lub modułem równoważenia obciążenia.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. Ustawienie AllowedHosts przy użyciu oprogramowania pośredniczącego filtrowania hosta jest odpowiednie, gdy Kestrel jest używany jako publiczny serwer graniczny lub gdy Host nagłówek jest bezpośrednio przekazywany.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.

Aby uzyskać więcej informacji na temat przekierowanych nagłówków, należy zapoznać się z tematem Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia .For more information on Forwarded Headers Middleware, see Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia.

Opróżnianie żądań HTTP/1.1HTTP/1.1 request draining

Otwieranie połączeń HTTP jest czasochłonne.Opening HTTP connections is time consuming. W przypadku protokołu HTTPS jest to również czasochłonne zasoby.For HTTPS, it's also resource intensive. W związku z tym Kestrel próbuje ponownie użyć połączeń zgodnie z protokołem HTTP/1.1.Therefore, Kestrel tries to reuse connections per the HTTP/1.1 protocol. Treść żądania musi być w pełni zużyta, aby umożliwić ponowne użycie połączenia.A request body must be fully consumed to allow the connection to be reused. Aplikacja nie zawsze zużywa treści żądania, na przykład żądania, w POST których serwer zwraca przekierowanie lub odpowiedź 404.The app doesn't always consume the request body, such as a POST requests where the server returns a redirect or 404 response. W POST przypadku przekierowania — przypadek:In the POST-redirect case:

  • Klient mógł już wysłać część POST danych.The client may already have sent part of the POST data.
  • Serwer zapisuje odpowiedź 301.The server writes the 301 response.
  • Nie można użyć połączenia dla nowego żądania, dopóki POST dane z poprzedniej treści żądania nie zostały w pełni odczytane.The connection can't be used for a new request until the POST data from the previous request body has been fully read.
  • Kestrel próbuje opróżnić treść żądania.Kestrel tries to drain the request body. Opróżnianie treści żądania oznacza odczytywanie i odrzucanie danych bez przetwarzania.Draining the request body means reading and discarding the data without processing it.

Proces opróżniania polega na tym, że tradoff między zezwoleniem na ponowne użycie połączenia i czasem potrzebny do opróżnienia pozostałych danych:The draining process makes a tradoff between allowing the connection to be reused and the time it takes to drain any remaining data:

  • Opróżnianie ma przekroczenie limitu czasu wynoszącego pięć sekund, co nie jest możliwe do skonfigurowania.Draining has a timeout of five seconds, which isn't configurable.
  • Jeśli wszystkie dane określone przez Content-Length Transfer-Encoding nagłówek lub nie zostały odczytane przed upływem limitu czasu, połączenie zostanie zamknięte.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.

Czasami możesz chcieć natychmiast przerwać żądanie przed zapisaniem odpowiedzi lub po jej zapisaniu.Sometimes you may want to terminate the request immediately, before or after writing the response. Na przykład klienci mogą mieć restrykcyjne limity danych, więc ograniczenie przekazywania danych może być priorytetem.For example, clients may have restrictive data caps, so limiting uploaded data might be a priority. W takich przypadkach aby zakończyć żądanie, należy wywołać metodę HttpContext. Abort z kontrolera, Razor strony lub oprogramowania pośredniczącego.In such cases to terminate a request, call HttpContext.Abort from a controller, Razor Page, or middleware.

Istnieją zastrzeżenia dotyczące wywoływania Abort :There are caveats to calling Abort:

  • Tworzenie nowych połączeń może być powolne i kosztowne.Creating new connections can be slow and expensive.
  • Nie ma gwarancji, że klient odczytał odpowiedź przed zamknięciem połączenia.There's no guarantee that the client has read the response before the connection closes.
  • Wywołanie Abort powinno być rzadkie i zarezerwowane dla poważnych przypadków błędów, a nie typowych błędów.Calling Abort should be rare and reserved for severe error cases, not common errors.
    • Należy wywołać tylko Abort wtedy, gdy określony problem musi zostać rozwiązany.Only call Abort when a specific problem needs to be solved. Na przykład Wywołaj, Abort czy złośliwi klienci próbują uzyskać POST dane, czy w kodzie klienta występuje usterka powodująca duże lub liczne żądania.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.
    • Nie wywołuj Abort w przypadku typowych sytuacji błędów, takich jak HTTP 404 (nie znaleziono).Don't call Abort for common error situations, such as HTTP 404 (Not Found).

Wywołanie metody HttpResponse. CompleteAsync przed wywołaniem Abort gwarantuje, że serwer zakończył zapisywanie odpowiedzi.Calling HttpResponse.CompleteAsync before calling Abort ensures that the server has completed writing the response. Zachowanie klienta nie jest jednak przewidywalne i może nie odczytać odpowiedzi przed przerwaniem połączenia.However, client behavior isn't predictable and they may not read the response before the connection is aborted.

Ten proces jest inny w przypadku protokołu HTTP/2, ponieważ protokół obsługuje przerywanie pojedynczych strumieni żądań bez zamykania połączenia.This process is different for HTTP/2 because the protocol supports aborting individual request streams without closing the connection. Nie ma zastosowania pięć sekund limitu czasu opróżniania.The five second drain timeout doesn't apply. Jeśli po zakończeniu odpowiedzi istnieją nieodczytane dane treści żądania, serwer wysyła ramkę protokołu HTTP/2.If there's any unread request body data after completing a response, then the server sends an HTTP/2 RST frame. Dodatkowe ramki danych treści żądania są ignorowane.Additional request body data frames are ignored.

Jeśli to możliwe, lepiej, aby klienci używali oczekiwanego nagłówka żądania: 100-Continue i poczekać na odpowiedź serwera przed rozpoczęciem wysyłania treści żądania.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. Dzięki temu Klient może przeanalizować odpowiedź i przerwać przed wysłaniem niepotrzebnych danych.That gives the client an opportunity to examine the response and abort before sending unneeded data.

Dodatkowe zasobyAdditional resources